Docs / Protocol

Transports

The protocol is the same on every transport. The transport only changes how requests are framed and how responses reach the client. Pick one with the top-level protocol key.

protocol: standard   # standard (default), telnet or http
TransportUse it for
standardThe default. Plain TCP, one command per line ending in \n. Use this from application code and with nc.
telnetSame as standard, but requests end in \r\n as a telnet client sends them.
httpRead and write slots with GET and POST, and receive broadcast events in a browser or any client over Server-Sent Events.

A server runs one transport at a time, on addr.

Line endings#

Line endings are strict and differ per transport:

TransportRequest terminatorResponse terminator
standard\n only. The \r of a \r\n ending is kept as part of the request, so w000abc\r\n stores abc\r, and r000\r\n is rejected with exxx001 as a read with trailing bytes. Always send a bare \n.\n
telnet\r\n only. A request ending in a bare \n is rejected with exxx001.\n, not \r\n
httpNot applicable: one command per request.Not applicable
Connecting with telnet

A telnet client sends \r\n. Against the default standard transport, reads fail with exxx001 and written values keep a trailing \r. If you want to use telnet, set protocol: telnet. Otherwise use nc or another client that sends a bare \n.

standard and telnet#

Both transports are a long-lived TCP connection carrying the commands described in Protocol. The connection is the client's identity: it holds the logged-in user, timeout_memory ownership and multicast subscriptions, and it receives async events from broadcast and multicast slots.

Events are written to each connection with a 200 ms deadline. A connection that stops reading until its socket buffers fill up misses events, and those count as errors in the writer's received/sent/errors summary.

http#

protocol: http

Slots are addressed by path, where <id> is exactly three ASCII digits:

RequestEquivalent command
GET /<id>r<id>, or an SSE stream on a broadcast slot (below)
POST /<id> with the value as the bodyw<id><value>

Captured against the configuration shown, with slot_000 a simple_memory slot open to everyone and slot_002 restricted to my_service:

$ curl -s -X POST --data 'hello' localhost:9090/000
hello
$ curl -s localhost:9090/000
hello
$ curl -s localhost:9090/002
forbidden
$ curl -s localhost:9090/999
slot not configured
$ curl -s localhost:9090/1
slot must be a 3-digit number (e.g. GET /000)

HTTP status mapping#

The protocol response is translated into a status code. On 200 the body is the value, without the v and slot prefix.

StatusWhen
200Success, with the value as the body.
400A path that is not three digits, a body over 36 bytes, or any protocol error not listed below (for example 007 WRITE_FAILED). The body is error: <code>.
401Basic Auth credentials were sent but don't match a configured user.
403Permission error: 006 WRITE_PERMISSION or 008 READ_PERMISSION.
404The slot is not configured (005 MISSING_SLOT).
405A method other than GET or POST.
503The node is not the cluster leader (000 NOT_LEADER).
504The server didn't produce a response within 500 ms.

Server-Sent Events on broadcast slots#

A GET on a broadcast slot doesn't return the current value. It opens a persistent Server-Sent Events stream, and every later write to any broadcast slot is pushed to it as a data: line carrying the full async event. The server decides which slots stream from the configuration at startup.

$ curl -sN localhost:9090/001
data: a001deploy-42

That event came from a write in another terminal. Over HTTP, broadcast events go to the open SSE streams only, so the writer itself isn't counted:

$ curl -s -X POST --data 'deploy-42' localhost:9090/001
1/1/0

The stream is sent with Access-Control-Allow-Origin: *, so a page on another origin can subscribe with the browser's EventSource:

const events = new EventSource("http://localhost:9090/001");
events.onmessage = (e) => console.log(e.data); // "a001deploy-42"

The SSE data is the async event line, so it starts with a and the slot number. A stream opened on one broadcast slot receives the events of every broadcast slot, so check the slot number in the data.

Timeouts#

The HTTP server is bounded so that a slow or idle client can't hold resources for long:

LimitValue
Time to send the request headers5 seconds
Time for the whole request10 seconds
Time to write a response10 seconds
Idle keep-alive connectionClosed after 60 seconds
Request headersAt most 8 KiB

Every command is a single short request, so well-behaved clients never hit these limits.

Heartbeats#

SSE streams are the deliberate exception to the timeouts: a stream stays open for as long as the client keeps reading it, with no read or write timeout. When nothing has been written to a stream for 15 seconds, the server sends an SSE comment line, : keepalive, which SSE clients ignore. The check runs every 15 seconds, so a quiet stream carries a comment at least every 30 seconds and a busy one carries none. This stops proxies from closing an idle stream and lets the server notice a client that went away without closing the connection.

Backpressure#

A subscriber must keep reading. Each event is written with a 200 ms deadline, the same as on the standard transport. Once a subscriber's socket buffers are full because it stopped reading, the next event or heartbeat fails and the subscriber is disconnected. The event it missed counts as an error in the writer's received/sent/errors response, exactly like a stalled TCP subscriber.

Each SSE stream holds a connection for as long as it is open, so it counts against max_connections.

Found something out of date? Open an issue or edit this page.