1 Connections

The goal of a connector is to provide specific patterns of communication among channels of instances of roles.

A connector in Kumori has two ports: a client port and a server port. Those ports are not explicitly represented, instead they determine what sort of channels can connect to each port: only client channels from roles can connect to the client port of a connector. Likewise, the connector can only connect to server channels through its server port.

There are two types of supported connectors, part of the built-in library:

• Load Balancer connectors. With the simple standard load balancing semantics. Components linked to the connector through a client channel can resolve that channel name to obtain the IP of the connector. When initiating communications through that IP, the connector spreads load evenly to the set of server channels connected through its server ports.

• Complete/Full connectors. Providing full visibility to roles with client channels connected to the client port about the set of server channels the server port connects to. A component code can find all endpoints associated to the server channels the connector is linked to by resolving its client channel name. If SRV records are retrieved, it will obtain the pair IP:port of each one of the server channels connected.

Connector are defined within a service using the connect keyword, being able to declare multiple connections inside the same block, each one with a different name. This is the type alias definition:

type LoadBalancer struct {
    from struct { target string, channel string } | []struct { target string, channel string }
    to struct { target string, channel string } | []struct { target string, channel string }

    meta? any
}

type FullConnector ReducedFullConnector | CompleteFullConnector

alias ReducedFullConnector struct {
    target string
    channel string
    meta? any
}

alias CompleteFullConnector struct {
    from struct { target string, channel string } | []struct { target string, channel string }
    to struct { target string, channel string } | []struct { target string, channel string }

    meta? any
}

The LoadBalancer connector type allows to define either a single or multiple from and to clauses, each one specifying a target role and channel. This allows for more complex load balancing scenarios where multiple roles can connect to the connector as clients or servers.

The FullConnector type has two variants: ReducedFullConnector and CompleteFullConnector. The ReducedFullConnector variant allows to define a single target role and channel, while the CompleteFullConnector variant allows to define single or multiple from and to clauses, similar to the LoadBalancer connector.

[!NOTE] The meta field is an optional field that can hold any additional metadata associated with the connector. The metadata will be made available to the source role instances.

In both connectors, the target field specifies the name of the role being connected. To reference the current service as a target, you can use the special keyword self. The channel field indicates the name of the channel within the target role that is being connected.

When declaring a connector, you can specify its type by using either kumori.LoadBalancer or kumori.FullConnector, followed by the configuration block. Here are examples of both types of connectors:

connect {
    webAppToDatabase kumori.LoadBalancer({
        from {
            target  "webAppRole"
            channel "tcp"
        }

        to {
            target  "databaseRole"
            channel "tcp"
        }
    })

    selfToCache kumori.LoadBalancer({
        from {
            target  "self"
            channel "http"
        }

        to {
            target  "cacheRole"
            channel "http"
        }
    })

    apiToCache kumori.FullConnector({
        target  "cacheRole"
        channel "udp"
    })
}

[!NOTE] The use of the kumori prefix for connectors indicates the need to import the "kumori" built-in library to access these connector types.

1.1 Example with multiple from-to clauses

As explained, the LoadBalancer and CompleteFullConnector types allow to define multiple from and to clauses. Here is an example of a load balancer connector that connects multiple client roles to multiple server roles:

connect {
    multiRoleLoadBalancer kumori.LoadBalancer({
        from [
            { target "clientRole1", channel: "http" },
            { target "clientRole2", channel: "http" }
        ]

        to [
            { target "serverRole1", channel: "http" },
            { target "serverRole2", channel: "http" }
        ]
    })
}