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
| Transport | Use it for |
|---|---|
standard | The default. Plain TCP, one command per line ending in \n. Use this from application code and with nc. |
telnet | Same as standard, but requests end in \r\n as a telnet client sends them. |
http | Read 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:
| Transport | Request terminator | Response 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 |
http | Not applicable: one command per request. | Not applicable |
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:
| Request | Equivalent command |
|---|---|
GET /<id> | r<id>, or an SSE stream on a broadcast slot (below) |
POST /<id> with the value as the body | w<id><value> |
- Any other path shape, including
/+00,/-01and/1, is rejected with400. - A trailing
\nor\r\nin aPOSTbody is stripped. A body longer than 36 bytes is rejected with400. - Methods other than
GETandPOSTget405. - Authentication uses HTTP Basic Auth on every request, instead of
uandp. A request without credentials is anonymous. s,d,u,pandqhave no HTTP equivalent, so multicast groups can't be joined over HTTP.- Every request is its own connection, so no HTTP client can own a
timeout_memoryslot across two writes. Usestandardortelnetfor leases.
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.
| Status | When |
|---|---|
200 | Success, with the value as the body. |
400 | A 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>. |
401 | Basic Auth credentials were sent but don't match a configured user. |
403 | Permission error: 006 WRITE_PERMISSION or 008 READ_PERMISSION. |
404 | The slot is not configured (005 MISSING_SLOT). |
405 | A method other than GET or POST. |
503 | The node is not the cluster leader (000 NOT_LEADER). |
504 | The 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:
| Limit | Value |
|---|---|
| Time to send the request headers | 5 seconds |
| Time for the whole request | 10 seconds |
| Time to write a response | 10 seconds |
| Idle keep-alive connection | Closed after 60 seconds |
| Request headers | At 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.