Wire protocol
Each request starts with an ASCII header terminated by
\n; key and value bodies follow immediately, read by their
declared byte lengths. Bodies have no terminator and may contain
arbitrary bytes. One-byte commands keep overhead minimal while frames
stay readable during development.
Multiple requests per connection and pipelining are both supported. A
<key-length> of 0 is rejected for every
command; there is no dedicated key or value length limit beyond the
overall request-size limit (1 MiB per request on a node).
A — authenticate
A <secret-length>\n<secret>Responds O\n on success or E\n followed by
the server closing the connection. If the server has no auth secret
configured, A always succeeds. If it does, every other
command is rejected with E\n (and the connection closed)
until a matching A has been sent.
On/Od (node/discovery) instead of a bare
O — that one extra byte is how a client discovers what kind
of server it reached and adapts, with no configuration. Plain
A as documented here always works.G — get
G <key-length>\n<key>Responds with the value:
V <value-length>\n<value>or N\n when the key is missing or expired.
S — set
S <key-length> <value-length>\n<key><value>
S <key-length> <value-length> <ttl-seconds>\n<key><value>Responds S\n. Without a TTL the entry lives until
evicted (LRU under the memory bound) or deleted; with one it also
expires <ttl-seconds> after the write.
D — delete
D <key-length>\n<key>Responds D\n if the key existed, N\n
otherwise.
Other statuses you may see
| Reply | Meaning |
|---|---|
B\n | Busy. From a node: the connection limit is reached. From a discovery server: it is inside its startup grace after a restart, re-learning membership — retry shortly or try another replica. |
W\n | Wrong node (clusters only): per the node's own view of membership it does not own this key, so the client's routing table is stale. SDKs respond by refreshing the node list and retrying once. |
E\n | Error — authentication required or failed, or the request was malformed. Usually followed by the server closing the connection. |
Cluster-internal commands
Nodes, discovery servers, and SDKs additionally exchange membership
and migration frames — L (node list),
J/H/P (join, heartbeat,
announce), M/X/C (migrate,
cancel, complete). These are versioned with the server and not part of
the public caching API; the
ADRs
specify them in detail (0008 join/handoff, 0010 discovery HA,
0011 replication).
A complete session
$ printf 'S 4 5\nnameAliceG 4\nname' | nc 127.0.0.1 8356
S
V 5
AliceTwo pipelined requests — a set and a get — answered in order on one connection.