PROTOCOL

infod3 protocol v0

	The infod3 protocol is a client-server protocol. The server
	maintains a key/value store, and connected client may
	add, update and delete entries. Clients can also subscribe to
	changes in the store by key pattern, and receive immediate
	updates. Coherent updates are supported through transactions.

	Three variants of the protocol are defined.  A required binary
	form, an optional self-framed binary form and an optional text form.

Overview

	A client may send the following commands to the server:

		HELLO <v><text>
		SUB <pattern>
		UNSUB <pattern>
		READ <key>
		WRITE <key> [<value>]
		BEGIN
		COMMIT
		PING <id>

	The server may send the following messages to the client:

		VERSION <v><text>
		INFO <key> [<value>]
		PONG <id>
		ERROR <text>

	The client MAY close the connection at any time.
	Most server messages are sent in response to a client command.
	Error messages MAY be sent by the server at any time.

	The size of any key-value pair is limited to 65535 bytes,
	including the NUL byte separator between the key and value.
	The key portion MUST NOT contain a NUL byte.

Client Commands

	Command messages sent from the client are described next.

	HELLO <v> <text>

	    The client indicates the protocol version it wishes to talk.
	    The server MUST respond with a VERSION message indicating
	    its capability.
	    This document describes version 0 of the protocol.
	    A HELLO also optionally identifies the client to the
	    server in the text portion. A server may log this as an
	    indication of the client software's state.
	    If sent at all, the HELLO command SHOULD be the first sent
	    message.
	    A client need not wait for the VERSION response
	    before sending subsquent commands compatible with version 0.

	SUB <pattern>
	UNSUB <pattern>

	    Manages subscriptions in the current client's channel.
	    Every client connection is associated with a set of active
	    subscriptions. The pattern syntax is documented below.

	    When a new subscription is received, the server MUST
	    send INFO messages for every existing matching key.
	    From then on until canceled by a matching UNSUB, the
	    server MUST send INFO messages to the subscribed client
	    whenever a matching key's value is changed.
	    A server MAY place a limit on the number of subscriptions.

	READ <key>

	    The server MUST respond with an INFO message for the key.

	WRITE <key> [<value>]

	    The server MUST update the key's value.
	    It MUST not respond with an INFO message, unless a
	    matching subscription is active.

	PING <id>

	    The server MUST respond with a matching PONG. This
	    can be used for client synchronization.

	BEGIN
	COMMIT

	    When a BEGIN message is sent to a server, it MUST
	    begin recording subsequent commands up to the next matching
	    COMMIT. When the COMMIT is received, all recorded
	    commands are performed atomically and exclusive to any
	    other client. This is intended to be allowed to query
	    multiple keys coherently.

	    A server MUST ignore any COMMIT without a matching BEGIN.
	    A server MAY place a limit on the number of commands
	    it can record.

Server messages

	VERSION <v> <text>

	    This is the response to a HELLO command. The server
	    indicates the highest compatible version number it can
	    talk. It MUST be equal to or less than the HELLO's version.
	    The <text> MAY be the empty string, othewise it should
	    describe the server.

	INFO <key> [<value>]

	    INFO messages MUST only be sent from the server
	    as a result of READ or SUB commands.
	    The <value> MUST be absent only when the key does not
	    exist on the server.

	PONG <id>

	    A PONG message MUST only be sent in response to a PING
	    commands.

	ERROR <int> <text>

	    An ERROR message MAY be sent by the server at any time.
	    The text is for human consumption and a client should
	    log the message.
	    The server MAY close the connection immediately after
	    sending an ERROR message.

	    The integer 0-255 represent an error group. The error groups
	    are currently:

		100	Unknown or malformed message
		101	Bad message parameter
		102	Buffer overflow
		103     Bad command state
		255	Internal server error

	    A client recieving error 255 SHOULD disconnect and retry later.
	    A client MUST NOT retry on errors 100 through 103.

Patterns

	Subscription patterns are matched against existing and future keys.
	A pattern is a UTF-8 string with some characters (metachars)
	having special meaning:

		( | ) * ? \

	The pattern is matched from left-to-right against each candidate key,
	succeding when the pattern matches the entire key. The pattern fails
	immediately when an element of the pattern fails to match.

	The elements of a pattern are:

		c	Any regular character (non-metachar) matches itself.

		*c	The * matches the shortest substring (including
			empty string) up to and then including the next
			regular character c.

		?	A ? matches any single character.

		*	A * at the end of a pattern or followed by | or )
			greedily matches the rest of the key string.
			Patterns containing ** or *( are invalid.
			The pattern *? is equivalent to ?.

		(x|y|...)
			A group matches the first matching branch of x y etc.
			Once a branch is matched, subsequent branches are
			ignored and matching continues after the closing ).
			Parenthesised groups can be nested up to four deep.

		\c	Matches exactly the character c which may be
			a metachar. (Note that quoted backslashes may
			appear as \134 in the text protocol.)

	The greedy nature of * means that the pattern "iface.*.mtu" will
	find key "iface.eth0.mtu" but miss "iface.bridge0.port1.mtu".
	However, pattern "iface.*" will get both.

	Overlong or invalid UTF-8 characters in either pattern or key text
	MAY be treated as unmatchable. NULs MUST NOT appear in key or pattern.

Binary form of messages

	Binary messages are of the form

	    +----+------/ /------+
	    | ID |    payload    |
	    +----+------/ /------+

	"Self-framed" binary messages are of the form

	    +----+----+----+------/ /------+
	    | ID |  length |    payload    |
	    +----+----+----+------/ /------+

	    The length is in network endian format
	    and defines the number of bytes in the unpadded payload.

	Message IDs and their payload structure

		0x00 HELLO       <v> <text>
		0x01 SUB         <pattern>
		0x02 UNSUB       <pattern>
		0x03 READ        <key>
		0x04 WRITE       <key> [0x00 <value>]
		0x05 BEGIN
		0x06 COMMIT
		0x07 PING        <value>

		0x80 VERSION     <v> <text>
		0x81 INFO        <key> [0x00 <value>]
		0x82 PONG        <value>
		0x83 ERROR       <i> <text>

		0x0A <reserved>
		0x0D <reserved>
		0x20 <reserved>
		0x40-0x7E <reserved>

	The <v> version is a single byte. It is 0x00 for this version.

	The READ message MUST NOT contain a NUL (0x00 byte) in its <key>.
	The WRITE and INFO messages MUST NOT contain a NUL when the
	message indicates a key deletion. This distinguishes key deletion
	from an empty value.

	Each of <key>, <pattern> and <text> are in UTF-8.
	Each <value> is binary and need not be interpreted as UTF-8.
	Keys sent by a client SHOULD be in normalized UTF-8, although the
	server MUST NOT normalize or otherwise correct the key form.

	If a server sends an ERROR message in binary mode, it MUST
	immediately close the connection.

	The maximum size of the payload is 65535 bytes. This makes the
	maximum size of a self-framed binary message 65538 bytes.

	A binary client need not send a HELLO message if it
	is going to use version 0 messages.

	A server SHOULD switch to text protocol on a stream socket
	if the first received byte from the client is one of

		0x0A 0x0D 0x20 or 0x40-0x7E.

	Some message IDs have been reserved for this purpose.

Text form of messages

	The text form of a client channel consists of
	lines terminated with <cr> and/or <lf>. Command words sent
	by the client MUST be interpreted case insensitively.
	and redundant space characters <sp> are permitted.
	Blank lines MUST be ignored by the server.

	A server MUST switch from text to binary mode if it receives
	an initial binary HELLO message commencing with 0x00.

	The server MUST always emit command IDs in uppercase
	and send minimal single space characters <sp>.
	The server MUST always terminate lines with <cr><lf>.
	A server MUST NOT send blank lines consisting of just <cr><lf>.

	An abbreviated syntax for the messages and commands follows:

	    <sp>* HELLO [<sp>+ <int> [<sp>+ <text>]] <sp>* <crlf>
	    <sp>* SUB <sp>+ <pattern> <sp>* <crlf>
	    <sp>* UNSUB <sp>+ <pattern> <sp>* <crlf>
	    <sp>* READ <sp>+ <key> <sp>* <crlf>
	    <sp>* WRITE <sp>+ <key> [<sp>+ <value>] <sp>* <crlf>
	    <sp>* BEGIN <sp>* <crlf>
	    <sp>* COMMIT <sp>* <crlf>
	    <sp>* PING [<sp>+ <ident>] <sp>* <crlf>

	    VERSION <sp> <int> [<sp> <text>] <cr> <lf>
	    INFO <sp> <key> [<sp> <value>] <cr> <lf>
	    PONG <sp> [<ident>] <cr> <lf>
	    ERROR <sp> <int> <sp> <text> <cr> <lf>

	where <int> is an unsigned decimal integer smaller than 256.
	The server MUST NOT generate leading 0s except for the value 0.
	
	If the client omits the HELLO message, the server MUST NOT send
	a VERSION response. However, the server MAY then assume any version
	that is compatible with version 0.

    Human clients

	A server MAY accept the pseudo-command HELP with the text protocol
	and SHOULD reply with human-oriented response text.

	A server MUST accept single letter aliases for all
	commands, except HELLO, namely: s (SUB), u (UNSUB), r (READ),
	w (WRITE), b (BEGIN), c (COMMIT) and p (PING).
	Client programs using the text protocol SHOULD not abbreviate
	commands.

    String quoting

	<ident>, <pattern>, <key>, <value> and <text> strings are encoded in
	the following quoting system:

		- If the string has no length, it MUST be encoded as ""
		- If the string contains only UTF-8 characters, excluding
			<sp> <cr> <lf>
		  and does not begin with ", then it MAY be encoded
		  directly without quoting and without any special meaning
		  for " or \.
		- Otherwise the string MUST be enclosed in " with the
		  following bytes octal escaped as \ooo:

			<lf>	\012
			<cr>	\015
			"	\042
			\	\134

	The server MUST accept all quoted \ooo octal sequences.
	The server MUST generate these five octal sequences
	instead of their unescaped byte form:

		\000 \012 \015 \042 \134

	The server MUST NOT accept non-octal escapes. That is, a
	backslash in a quoted string not followed by three octal
	digits MUST be rejected by the server using error code 101.

	The server MUST quote every strings it sends.

	If the server sends an ERROR message in response to a malformed
	command, it MAY close the connection.

    Maximum line length

        In the worst case, a compliant server will emit a line consisting of
	262152 bytes. This corresponds to:
	  - the longest word "VERSION" (7 bytes)
	  - space (1)
	  - the number "255" (3)
	  - space (1)
	  - a quoted strings of all octal escapes (1 + 65534 * 4 + 1)
	  - the trailing <cr><lf> (2)

Security

	Identity and access control is not discussed in this document.