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.