aboutsummaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorMattias Andrée <maandree@kth.se>2017-10-21 20:18:36 +0200
committerMattias Andrée <maandree@kth.se>2017-10-21 20:40:58 +0200
commit507a01865c80546aa0d75b5fb07043abe82d3487 (patch)
tree0cd8f6956c5e681878d422b247dbe3eb428ddb2a
parentLIBSBUS_BUFFER_SIZE: use UL suffix (diff)
downloadsbus-507a01865c80546aa0d75b5fb07043abe82d3487.tar.gz
sbus-507a01865c80546aa0d75b5fb07043abe82d3487.tar.bz2
sbus-507a01865c80546aa0d75b5fb07043abe82d3487.tar.xz
Add README
Signed-off-by: Mattias Andrée <maandree@kth.se>
-rw-r--r--README72
1 files changed, 72 insertions, 0 deletions
diff --git a/README b/README
new file mode 100644
index 0000000..57732c8
--- /dev/null
+++ b/README
@@ -0,0 +1,72 @@
+sbus is simple message bus based on unix domain, sequenced-packet sockets.
+
+Features:
+ Support for multi-user buses.
+ No support state-keeping in clients.
+ Supports all send(2)/recv(2) flags.
+ Support for routing keys with wildcards.
+
+Non-features:
+ No IP or cluster support, should be implemented as a separate service.
+ No support for overly larged 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.
+
+Routing keys:
+ Routing keys are used to filter received messages. A routing key
+ may contain any byte, whoever there are two bytes with special
+ meaning: '*' and '.'. '*' should not be used in routin 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 routiung key
+ pattern shall match everything.
+
+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 3 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.