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:
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 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.
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 theauth
parameter is omitted, an uncontrolled access in open mode is assumed.label
is an optional label for the connection. This will be used in server log entries for debugging purposes and for identifying the connection in administrative requests.
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:
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 theping
message, if there was one, or will be omitted if the originalping
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, protocol:?STR,
wait:?INT, monitor:?BOOL, tag:?STR }
This message queries the Broker about the availability of some kind of service.
where:
service
is the name of the type of service the requestor is seeking.protocol
is the name of the communications protocol by which the requestor wishes to access the service. This parameter is optional, and defaults to"tcp"
if omitted.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. This parameter 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 parameter is optional and defaults to false if omitted. A value of true is invalid if thewait
parameter was specified with a value of 0.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.
← { 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 originalfind
request.tag
echoes the tag from thefind
request, if there was one, or will be omitted if the originalfind
also omitted it.
{ type:"servicedesc", service:STR, hostport:?STR,
protocol:?STR, label:?STR, auth:?AUTHDESC,
provider:?INT, failure:?STR }
where:
service
is the service type name of the service.hostport
is a"hostname:portnumber"
string indicating the host and port at which the service is being offered. This field will be absent if the service was not available.protocol
is the name of the communications protocol over which the service is being offered. This field 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 at the service provider's discretion).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 theauth
request. This field will be absent if the service was not available or if the service provider did not share authorization information with the broker (in the latter case, it is the responsibility of the service requestor and the service provider to cooperate out-of-band to coordinate authorization arrangements).provider
is a simple integer provider ID associated with the server providing the service, independent of the particular service(s) being offered. These provider IDs are assigned by the Broker itself. The provider ID enables a client to determine if multiple different services all come from the same provider. This field 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 field will only be present in the event of failure, in which case the other optional fields described above will be absent.
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:
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 thefind
request, except that the client should not provide aprovider
property as this will be assigned by the Broker. Thelabel
,auth
, andprotocol
properties are optional at the client's discretion, but theservice
andhostport
properties are mandatory.
wontserve
→ { to:"client", op:"wontserve", services:[STR] }
This message informs the Broker that the sender 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 awontserve
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.
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:
kill
is an optional flag that if true orders an abrupt termination. Normally, the client would empty its message queues, checkpoint any active state, and perform an orderly shutdown. However, if thekill
flag is true, the client should exit immediately without stopping to clean things up. The value defaults to false if the parameter is omitted.
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 parameter 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.
← { 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. If there are no providers of the requested service, this array will be empty.
{ type:"loaddesc", label:?STR, load:FLOAT, provider:INT }
where:
label
is a printable label for the service provider being described. This field will be absent if the service provider did not label itself.load
is the 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.
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:
service
is the optional name of a type of 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.
← { 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 thefind
request.on
is a boolean flag indicating whether the service described is currently being offered. In the reply to theservicedesc
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 thewatch
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 this parameter is 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 thekill
flag is true, they will exit immediately without stopping to clean things up. The value defaults to false if the parameter is omitted.
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:
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 this parameter is omitted, the Broker's current send/don't send setting for service notifications 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 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 for load notifications will be left unchanged.
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.