Elko: Broker Protocols

The Elko Broker Protocols

The Broker

The Broker is an Elko server that allows a cluster of Elko servers of various kinds to find out information about each other's available services (and thus establish interconnectivity) without having to be preconfigured to know about one another. It also shields the various servers from order of startup issues. Finally, it provides a place to stand for monitoring and administering an Elko server farm as a whole.

A Broker understands two different JSON message protocols. These correspond to the two kinds of actors who may wish to communicate with a Broker: clients offering or seeking services, and administrators. Each of the ports that a Broker listens for connections on can be configured to support either or both of these protocols.

Each of these protocols is associated with a particular object ref to which messages should be addressed:

Common Protocols

While there are two different message protocols, they share a common set of messages pertaining to connection housekeeping. These messages may be targeted at either of the two protocol objects described above.

auth

→ { to:REF, op:"auth", auth:?AUTHDESC, label:?STR}

This message begins a new session with the Broker, providing whatever authorization credentials as may be appropriate (according to the Broker's server configuration) to gain access to services.

An auth message must be the first message sent to client or admin on any new connection to the Broker. Any other message to these objects will result in immediate termination of the connection.

If the auth operation fails, the connection will be terminated by the Broker. Otherwise, the client is thereafter free to send messages according to the protocol of the REF that was authorized.

Authorization information

The auth parameter of the auth message describes a bundle of authorization information to authorize access. Its general form is:

{ type:"auth", mode:STR, code:?STR, id:?STR }

where:

disconnect

→ { to:REF, op:"disconnect" }

This message requests the server to terminate its connection to the sender. The connection to the server is broken.

ping

→ { to:REF, op:"ping", tag:?STR }

This message tests connectivity to the server.

If the message is successfully received by the server, it will reply with:

← { to:REF, op:"pong", tag:?STR }

debug

→ { to:REF, op:"debug", msg:STR }

This message delivers debugging information to the server. If the server is configured to permit this, the string given in the msg parameter will be written to the server's log. If the server is not configured to permit this, this message will simply be ignored.

Client Protocol

The Broker client protocol is used by servers that are seeking services from other servers, offering services to other servers, or both.

find

→ { to:"client", op:"find", service:STR, protocol:?STR, wait:?INT, monitor:?BOOL, tag:?STR }

This message queries the Broker about the availability of some kind of service.

where:

The Broker will reply with a message of the form:

← { to:"client", op:"find", desc:[SERVICEDESC], tag:?STR }

where:

A service descriptor takes the form:

{ type:"servicedesc", service:STR, hostport:?STR, protocol:?STR, label:?STR, auth:?AUTHDESC, provider:?INT, failure:?STR }

where:

If the wait parameter of the original find request was 0, the reply will be immediate, delivering either service information or a "no such service" failure. If the wait parameter was non-zero, then the Broker will withhold its reply until some service provider contacts it offering the service, or the wait period times out, or the Broker becomes unable for some other reason to be able to offer service information.

If the monitor parameter of the original find request was true (in which case the wait parameter was, by definition, non-zero), the Broker will send a new find response message each time an additional service provider registers an instance of the requested service with the Broker. This stream of service notifications will continue until the requested wait period has elapsed, or indefinitely if the wait parameter was negative.

willserve

→ { to:"client", op:"willserve", services:[SERVICEDESC] }

This message informs the Broker that the sender is offering to provide one or more services.

where:

wontserve

→ { to:"client", op:"wontserve", services:[STR] }

This message informs the Broker that the sender is ceasing to provide one or more services.

where:

load

→ { to:"client", op:"load", factor:FLOAT }

This message informs the Broker of sender's current load.

where:

reinit

← { to:"client", op:"reinit" }

This message is a directive from the Broker to the client, instructing the client to reinitialize itself. The exact meaning of "reinitialize" is specific to the kind of client it is, but the spirit of the request is that the client should restore itself to something resembling the condition it was in when it first started up. In particular, the client can obey this request by shutting down, which terminates the connection, restarting, and restablishing its relationship with the Broker.

shutdown

← { to:"client", op:"shutdown", kill:?BOOL }

This message is a directive from the Broker to the client, instructing the client to shut itself down.

where:

Admin Protocol

The Broker admin protocol is used to administer the Broker and, indirectly, the entire collection of clients it is in contact with.

loaddesc

→ { to:"admin", op:"loaddesc", service:?STR }

This message requests the Broker to send information about the load of registered services.

where:

The Broker will reply with a message of the form:

← { to:"admin", op:"loaddesc", desc:[LOADDESC] }

where:

A load descriptor takes the form:

{ type:"loaddesc", label:?STR, load:FLOAT, provider:INT }

where:

reinit

→ { to:"admin", op:"reinit", server:?STR, self:?BOOL }

This message instructs the Broker to reinitialize zero or more of the provider servers it knows about and, optionally, itself.

where:

If any provider servers are to be reinitialized, each will be sent a corresponding reinit message (see client message descriptions above) on its client connection.

servicedesc

→ { to:"admin", op:"servicedesc", service:?STR }

This message requests the Broker to send information about currently registered services.

where:

The Broker will reply with a message of the form:

← { to:"admin", op:"servicedesc", desc:[SERVICEDESC], on:BOOL }

where:

shutdown

→ { to:"admin", op:"shutdown", server:?STR, self:?BOOL, kill:?BOOL }

This message instructs the Broker to shut down zero or more of the provider servers it knows about and, optionally itself.

where:

If any provider servers are to be shut down, each will be sent a corresponding shutdown message (see client message descriptions above) on its client connection.

watch

→ { to:"admin", op:"watch", services:?BOOL, load:?BOOL }

This message requests the Broker to begin or cease providing ongoing updates as to the status of registered client service providers.

where:

If the services flag is true, the admin client will be sent a servicedesc message each time the Broker is notified by a service provider client about a service being offered or withdrawn. This message is exactly as described in the response to the admin servicedesc request above.

If the load flag is true, the admin client will be sent a loaddesc message each time the Broker is notified by a service provider client about a load change. This message is exactly as described in the response to the admin loaddesc request above.

Although both the services and load parameters are optional, in practice at least one of these parameters should be provided, as the request is otherwise a no-op.