The Msglite Protocol
The msglite protocol is easy for both computers and humans to read and compose. Take a look at this example:
C: > 5 1 someAddress
C: hello
C: < 1 someAddress
S: > 5 1 someAddress
S: helloIn this example, the client sends a message with the body of hello to the address someAddress. Presumably, no other client is awaiting messages on that address, so the message is queued.
The client then indicates readiness to receive a message on that same address, and the server sends the queued message to the client.
Conversations with msglite take the form of a series of so-called commands. Each command consists of a single line terminated by \r\n. Command lines start with a sigil indicating the type of command and containing 0 or more arguments separated by spaces.
In the case of message and query commands, the first argument of the command indicates the length of the message body. If the indicated length is greater than 0, the command line is followed by that many octets, followed by \r\n.
Clients may send the following commands to the msglite server:
> bodyLength timeoutSeconds toAddress [replyAddress]If bodyLength is greater than 0, the command is followed by bodyLength bytes followed by \r\n.
The msglite server won’t send any response to a message command.
< timeoutSeconds onAddress1 [onAddress2..onAddress8]Clients may specify up to 8 addresses to receive messages on.
If a message is already queued on any of the specified addresses, the server will immediately respond with a message command corresponding to that message. The server will only send one message per ready command, even if there is more than one message available on the specified addresses. Once a message has been sent, the client is no longer considered ready and must send another ready command to receive further messages.
If no messages are ready on any of the specified addresses, the client’s readiness will be queued. When a message becomes available on any of the specified addresses, the server will send a message command.
If no messages become available within the specified number of timeout seconds, the server will send a timeout command. Once a timeout command has been sent, the client is no longer considered ready and must send another ready command to receive further messages.
If two or more clients indicate readiness on the same address at the same time, they will receive messages in the order in which they became ready (FIFO order).
? bodyLength timeoutSeconds toAddressIf bodyLength is greater than 0, the command is followed by bodyLength bytes followed by \r\n.
Query commands act as a combination of a message and a ready command.
Msglite will send your message to the indicated address appending a single-use reply address which the recipient can use to respond to the query.
If a response becomes available before the indicated number of timeout seconds, msglite will send a message command with that response.
If no response becomes available within the indicated time, msglite will send a timeout command.
.The quit command will cause msglite to close the connection.
Msglite may send the following commands to clients:
Message commands sent from msglite to clients are formatted in the same way as message commands sent from clients to msglite. See the above description.
*Timeout commands are sent when a ready command or a query command times out.
- errorMessageErrors are only sent if clients send bad data. The errorMessage may contain spaces.