The Elko Broker Protocols

By Chip Morningstar
August 18, 2009

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:

client for clients (which are typically themselves other kinds of servers) seeking or providing services.
admin for administrator messages.

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 opens a new connection to 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 on any connection to the Broker. Any other message will result in immediate termination of the connection.

If the auth message fails to successfully authorize the connection, the connection will be terminated by the Broker. Otherwise, the client is thereafter free to send messages according to the protocol (according to REF) that was authorized.

auth is a bundle of authorization information, as described below. The specific authorization information that is relevant depends on the configuration of the Broker server port being connected to. If omitted, an uncontrolled access in open mode is assumed.
label is an optional label for the connection. This will be used in log entries for debugging purposes and for identifying the connection in administrative requests.

Authorizaton information

The auth parameter of the auth message describes a bundle of authorization information to authorize access. It takes the form:


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

where:

mode is the requested authorization mode. Currently recognized authorization modes are "open" and "password". Other modes may be relevant in the future or when talking to other kinds of servers.
code is an authorization code, whose meaning varies depending on the authorization mode. In the case of open mode, it is irrelevant and should not be provided. In the case of password mode, it is a password string.
id is an optional identity string, whose meaning varies depending on the authorization mode. In the case of open mode, it is irrelevant and should not be provided. In the case of password mode, it may or may not be relevant depending on the configuration.

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.

tag is an optional string that may be anything of the client's choosing.

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


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

tag echoes the tag from the ping message, if there was one, or will be omitted if the original ping also omitted it.

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, wait:?INT,
          monitor:?BOOL, tag:?STR }

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

where:

service is the the name of the type of service the requestor is seeking.
wait is the time (in seconds) that the requestor is willing to wait for the service to become available. A value of 0 means that the requestor is not willing to wait at all. A negative value means that the requestor is willing to wait forever. It is optional, and defaults to 0 (don't wait) if omitted.
monitor is a boolean flag indicating that the requestor wishes to continue to be aprised of new services of the requested type as they become known to the Broker, even after the first reply has been returned. This is optional and defaults to false if omitted. A value of true is invalid if the wait parameter was specified with a non-zero value.
tag is an optional tag string that, if given, will be sent back with the response(s), to help the client match up requests and responses.

The Broker will reply with a message of the form:


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

where:

desc is an array of service descriptors, each of which describes one server offering the service being sought in the original find request.
tag echoes the tag from the find request, if there was one, or will be omitted if the original find also omitted it.

A service descriptor takes the form:


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

where:

service is service type name of the service.
hostport is a "hostname:portnumber" string indicating the host and port and which the service is being offered. This will be absent if the service was not available.
label is the descriptive label given by the service provider when it registered that the service was available. This will be absent if the service was not available or if the service provider did not provide a label string (which is optional).
auth is an authorization descriptor that indicates how one should authorize with the indicated service. The authorization descriptor is exactly as documented above in the description of the auth request. This will be absent if the service was not available.
provider is the optional provider ID associated with the server providing the service. This enables a client to determine if multiple different services all come from the same provider. These provider IDs are assigned by the Broker itself. This will be absent if the service was not available.
failure is an error message string indicating the reason why the Broker was unable to fulfill the request. Typically this will be "no such service", though other errors are possible in principle. This will only be present in the event of failure, in which case the other optional properties described above will be absent.

If the wait parameter to 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 other 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 to the original find request was true (in which case the wait parameter was, by definition, non-zero), the Broker will send a new response 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 client is offering to provide one or more services.

where:

services is an array of one or more service descriptors, each of which describes one service that the sender is offering to provide. The service descriptor is as described above in the descripion of the find request, except that the client should not provide a provider property as this will be assigned by the Broker. The label and auth properties are optional at the client's discretion, but the service and hostport properties are mandatory.

wontserve


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

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

where:

services is an array of the names of one or more service types indicating the services that the client will not be providing. Note that it is not an error for a client to send a wontserve message mentioning services that it was not (to the Broker's knowledge) offering in the first place.

load


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

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

where:

factor is the sender's current load factor. This may be any value, though all clients talking to a given Broker should all share a single, commensurable metric.

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:

service is the optional name of a service of interest. If this is provided, the reply will deliver load information about providers of the named service. If it is omitted, the reply will deliver load information about all service providers that the Broker knows about.

The Broker will reply with a message of the form:


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

where:

desc is an array of load descriptors, each of which describes the load associated with one service provider.

A load descriptor takes the form:


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

where:

label is a printable label for the service provider being described.
load is provider server's most recently reported load factor.
provider is the provider ID associated with the server providing the service.

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:

server is the optional label for a provider server to be reinitialized. Alternatively, the string "all" indicates that all provider servers that the Broker knows about are to be reinitialized. If omitted, no provider servers will be reinitialized.
self is an optional flag that if true directs that the Broker itself also be reinitialized. The value defaults to false if the parameter is omitted. Broker reinitialization, if requested, will take place after any provider server reinitializations.

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

servicedesc


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

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

where:

service is the optional name of a service of interest. If this is provided, the reply will deliver information about providers of the named service. If it is omitted, the reply will deliver information about all service providers that the Broker knows about.

The Broker will reply with a message of the form:


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

where:

desc is an array of service descriptors, each of which describes one service being offered by some service provider client. The service descriptors are exactly as described above in the discussion of the find request.
on is a boolean flag indicating whether the service described is currently being offered. In the reply to the servicedesc request, this flag will always be true, as this reply only describes services that are actually being offered. However, this message is also used when watching services via the watch request, described below, which will also deliver notifications about services ceasing to be offered.

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:

server is the optional label for a provider server to be shut down. Alternatively, the string "all" indicates that all provider servers that the Broker knows about are to be shut down. If omitted, no provider servers will be shut down.
self is an optional flag that if true directs that the Broker itself also be shut down. The value defaults to false if the parameter is omitted. Broker shutdown, if requested, will take place after any provider server shutdowns.
kill is an optional flag that if true orders an abrupt termination of the indicated server(s). Normally, servers will empty their message queues, checkpoint any active state, and perform an orderly shutdown. However, if the kill flag is true, they will exit immediately without stopping to clean things up. The value defaults to false if the parameter is omitted.

If any provider servers are to be shut down, each will be sent a corresponding shutdown message 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 register client service providers.

where:

services is an optional boolean flag indicating whether the sender wants to be notified about services coming or going. A value of true indicates that the sender wishes to begin receiving such notifications. A value of false indicates that the sender wishes to cease receiving such notifications. If omitted, the Broker's current send/don't send setting will be left unchanged.
load is an optional boolean flag indicating whether the sender wants to be receive load factor updates for service providers that the Broker knows about. A value of true indicates that the send wishes to begin receiving such notifications. A value of valse indicates that the sender wishes to cease receiving such notifications. If omitted, the Broker's current send/don't send setting for these notifications will be left unchanged.

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.

Elko: Broker Protocols

The Elko Broker Protocols

By Chip Morningstar August 18, 2009

The Broker

Common Protocols

auth

Authorizaton information

disconnect

ping

debug

Client Protocol

find

willserve

wontserve

load

Admin Protocol

loaddesc

reinit

servicedesc

shutdown

watch

By Chip Morningstar
August 18, 2009