sbus is simple message bus based on unix domain, sequenced-packet sockets.
Features:
Support for multi-user buses.
No state-keeping required in clients.
Supports all send(2)/recv(2) flags.
Almost full setsockopt(2)/getsockopt(2)/fcntl(2)/ioctl(2) support:
No send-time timestamps
Increasing message size limit may cause problems
Supports select(2)/poll(2)/epoll(7).
Support for routing keys with wildcards.
Support for secret communication.
Reliable and ordered communication.
Non-features:
No IP or cluster support, should be implemented as a separate service.
No support for overly large messages, should be implemented at application level.
No persistence support, should be implemented as a separate service.
No support for automatic unsubscriptions.
No support for reply-to keys, should be implemented at application level.
No support for shared queues, should be implemented as a separate service.
No file descriptor passing support, not network-compatible, should be
implemented as a separate service or at application level.
No support for server-verified credentials, can be implemented at
application level by using '!/cred/' routing keys.
No acknowledgement of when messages have been processes, can be
implemented at application level by sending yourself a message
and wait for it to return.
No remote procedure call support.
Routing keys:
Routing keys are used to filter received messages. A routing key
may contain any byte other than the NUL, whoever there are three
bytes with special meaning: '*', '/', and '!'. '*' should not be
in routing keys, but only in routing key patterns, it matches until
the next '/' or end if there are not more '/'s. Additionally if a
routing key pattern ends with '/' that '/' will match to a '/' and
any subsequent byte. For example 'a/*/c/' will match 'a/b/c/' and
'a/b/c/d/e' but not 'a/b/c' or 'a/c/d'. And empty routing key
pattern shall match everything. The token '!' is reserved, a client
should never use '!' for any other purpose than specified in the
protocol, unless it has an other byte than a '/' next to it. The
server may choose to disconnect a client using '!' in an invalid
way or simply ignore such messages.
Protocol:
Communication is done over unix domain, sequenced-packet sockets.
Each packet is interpreted as a complete message. A packet cannot
contain multiple message, and a message cannot be split over
multiple packets. There are 4 types of messages:
Subscribe:
Send a routing key pattern to the server for the client.
The server shall send all messages with matching routing
keys to this client. The server shall store the key even
if there is already an identical routing key pattern
registered for the client.
Messages of this type shall match the regular expression
^SUB \([^\x00]*\)\(\x00.*\)\?$
where \1 is the routing key pattern, \2 is ignored.
Unsubscribe:
Tell the server to remove a routing key pattern for the
client. The server may choose to disconnect the client
if it sends a routing key pattern that is not registered
for the client.
Messages of this type shall match the regular expression
^UNSUB \([^\x00]*\)\(\x00.*\)\?$
where \1 is the routing key pattern, \2 is ignored.
Publish:
Publish a message on the bus. The server shall send a
copy of packet to all clients with a matching routing
key pattern, including the client that sent the packet
if and only if that client has a matching routing key
pattern. The server may not send a copy of the packet
to any clients without a matching routing key pattern.
Messages of this type shall match the regular expression
^MSG \([^\x00]*\)\x00\(.*\)$
where \1 is the routing key for the message and \2
is the message payload.
Control message:
Send a control message to the server. The server may
also send control message to clients. The server will
never forward control message it receives, and no
subscriptions are required to receive the messages.
Messages of this type shall match the regular expression
^CMSG \([^\x00]*\)\(\x00\(.*\)\)$
where \1 is the routing key for the message and \3
is the message payload. \2 may be om be omitted if
sent by the client.
Secret messages:
Routing keys starting with '!/cred/' can only be subscribed to
by clients with matching credentials. These routing keys must
match regular expression
^!/cred/\([0-9]*\)/\([0-9]*\)/\([0-9]*\)/\(.*\)$
where \1 is the group ID, \2 is the user ID, \3 is the process
ID, and \4 the rest of routing key which may also use this
pattern a process it communicates. Client can only subscribe
to the routing key \1, \2, and \3 match it's credentials.
If \1, \2, or \3 are empty, they will match the clients it's
credentials when subscribing. However, the server will not
accept '*' for \1, \2, or \3, or truncated routing keys.
However, due to network support, these routing keys may need
to be prefixed with the credentials for the servers the message
goes through, or use the credentials of the a program running
on a different master machine. Therefore, a client cannot
simply just use its GID, UID, and PID, but must ask what's its
credentials are by sending an empty control message (CMSG) with
the routing key '!/cred/whoami'. The server will reply with a
control message with the same routing key and the message will
be the credentials, for example '!/cred/100/1000/1111' or
'!/cred/100/1000/1111/!/cred/1000/1000/19211'. Note, the server
will never send control messages it receives from other clients,
so the received control message is guaranteed to come from the
server.
Example of how two client can prove their identities to each oter:
A: Send A's credentials to B.
B: Send B's credentials with routing key private to A.
A: Send a random message with routing key private to B.
B: Send back the message with routing key private to A.
Flood control:
The following control messages can be sent to the server to
choose the server behaviour when messages cannot be delivered
without blocking. All control messages are optional and server
may choose to ignore them at any time, even if previously
honoured. Most recently sent control message that precedence.
^CMSG blocking/soft/queue\(\x00.*\)*$
Delivering is preferable, the server should queue up
message that cannot be sent.
^CMSG blocking/soft/discard\(\x00.*\)*$
Delivering is unimportant, the server should discard
message that cannot be sent.
^CMSG blocking/soft/block\(\x00.*\)*$
Delivering is important, the server may block communication
to guarantee that messages are delivered.
^CMSG blocking/soft/error\(\x00.*\)*$
The server may treat a client as misbehaving if message
cannot be sent.
^CMSG blocking/hard/discard\(\x00.*\)*$
If the server has queued up too many message it should
start discarding new message instead of queuing them.
^CMSG blocking/hard/block\(\x00.*\)*$
If the server has queued up too many message it should
start blocking communication until it can start queuing
messages again.
^CMSG blocking/hard/error\(\x00.*\)*$
If the server has queued up too many message it should
start treating clients that are blocking as misbehaving.
^CMSG order/queue\(\x00.*\)*$
If the client is blocking it is preferable that messages
are sent in order.
^CMSG order/stack\(\x00.*\)*$
If the client is blocking it is preferable that messages
are sent in reverse order.
^CMSG order/random\(\x00.*\)*$
If the client is blocking it is preferable that messages
are sent in such order that memory is freed up as fast
as possible.
Echos:
By default, if a client sends a message with a routing key it is
subscribed to, that client will receive that message. The server
may however choose to implement control messages for selecting
whether this happens. Disabling echoing is useful for implementing
slave servers that only send messages upwords in the server
hierarchy when necessary. The control messages for controlling
echoing are
^CMSG echo/off\(\x00.*\)*$
Disable echoing.
^CMSG echo/on\(\x00.*\)*$
Reenable echoing.
