The Broker Protocol

The Broker communicates using text lines sent over a TCP-connections. The broker interferes as little as possible in the format of what is sent between modules - that is up to the designers of the modules to specify.

This document describes version 1.0 (the first public release) of the Broker Protocol.

Terminology

The terms client and server can get confusing because, in a sense, there is only one server (the Broker) and all other processes are clients of the Broker. However, in this documentation, another distinction will be made.

A module (client of the broker) will be referred to as a server if there can only be one (named) instance of the module connected at any one time, and client if there can be several clients active at once.

For example, there can currently only be one speech recognition server connected to the broker at any time, and it is called 'Recognizer'. However, there can be several demonstration programs using the recognizer at once, and they are assigned unique names when they connect to the broker, such as RecognizerClient@kanin.speech.kth.se:3213 (The host and TCP port number are appended to the client's base name, yielding a unique name).

The Protocol

This is version 1.0 of the Broker protocol. A goal has been to keep it as small as possible. The intent is that both brokers and modules can be implemented by third parties on any platform and interoperate by following this protocol.

Connection

As the first thing after connecting to the broker, a server must send a line of the form:

SERVER <name>

where <name> is the name of the server. Values such as <name> must be enclosed in quotes (") if they contain spaces, and quote characters must be preceded by a backslash (\) if they are part of the name.
Keywords such as SERVER are not case sensitive.

A client must start a session by sending a line like:

CLIENT <baseName>

Where <name> is the base name of the client. The client must then wait for a message from the server like:

NAME <uniqueName>

Where <uniqueName> is the name the client must use in future calls to the broker.

Thus, after this point any module, whether client or server, has a name to use in future calls.

Session

During a session, a module may call functions of other modules, and receive calls from other modules.
There are two types of calls: procedure calls (CALL PROC) which do not return any result or error codes to the caller, and function calls (CALL FUNC) which will return with either a result or an error to the caller.
Parameters can be specified in two ways: either in one line or on several lines. This is specified with the INLINE or MULTILINE keywords.

There are thus four varieties of function calls:

CALL PROC <calledName> INLINE parameters

CALL PROC <calledName> MULTILINE

parameters

END_MULTILINE

CALL FUNC <callerName> <callerCallId> <calledName> INLINE parameters

CALL FUNC <callerName> <callerCallId> <calledName> MULTILINE

parameters

END_MULTILINE

<calledName> is the name of the module to be called.
parameters can be any data terminated by a newline. In the MULTILINE case it may be any number of lines not equal to "END_MULTILINE". It is recommended but not required that they only contain characters from the ISO 8859-1 character set.
<callerName> is the name of the module making the call.
<callerCallId> is specified by the caller so that it can identify which function call a return value or result belongs to (a module may make many concurrent function calls.)

After receiving a function call (CALL FUNC), a module must respond by sending either a result or an error (failure to do so may cause a client program to wait forever for the reply). A module will also receive these messages from the Broker in response to calls it has made.

RETURN <callerName> <callerCallId> INLINE parameters

RETURN <callerName> <callerCallId> MULTILINE

parameters

END_MULTILINE

ERROR <callerName> <callerCallId> message

message is an error message.

Closing a session

When a module's connection to the broker is to be closed, either by initiative from the Broker (because it is shutting down), or by the module itself, a CLOSE message must be sent:

CLOSE

After sending the CLOSE, the sending party may close the socket connection.
A robust module implementation should support a socket being closed without a preceding CLOSE message, perhaps due to a crashed module at the other end, or a network failure.

Lacking Features and Possible Future Extensions

It may be desirable to have a PING message to which the other component must immediatly reply to make sure the component at the other end is functioning properly, and to estimate round-trip time of a network connection.
There is no security functionality at all - if authentication, digital signatures etc are neccessary, then that must be implemented on a server level, to achieve the goal of keeping the Broker itself as simple as possible.
Other suggestions are welcome!

An Example Session

Prev: Chosen Architecture, Up: The Broker, Next: Implementing Modules