Docs / Protocol

Protocol

Every message is plain text: one command byte, a three-digit slot number, and an optional value. This page is the exact contract a client has to follow. Transport differences are on the Transports page.

Framing and limits#

These rules are exact and apply to every command below.

RuleValue
Request sizeAt least 4 bytes and at most 40 bytes, not counting the terminator. The only exception is q, which is exactly one byte.
Slot value sizeAt most 36 bytes.
Slot numberExactly three ASCII digits, 000 to 999. Signs, spaces and padding are rejected with exxx001, so r-01, r+01 and r 01 are all errors.
Trailing bytesOnly w takes bytes after the slot number. For r, s and d the request ends at the third digit, and anything after it is rejected with exxx001.
Unit of measurementBytes, not characters or Unicode code points. 36 ASCII characters fit, 18 two-byte characters (é) fit, and 9 four-byte emoji fit, but 36 two-byte characters are rejected with 001.
EncodingThe value is an opaque byte string. Ghoti never validates, normalises or transcodes it, and returns exactly the bytes it received.
Request terminatorA single \n on standard, \r\n on telnet. The http transport has no terminator: one command is one HTTP request.
Response terminatorAlways a single \n, on every transport, including telnet.
Requests in flightOne. Send a command, wait for its response, then send the next one.

Framing requests#

TCP is a byte stream and doesn't preserve write boundaries, so Ghoti doesn't assume that one read holds exactly one request. A request is the bytes up to and including its terminator, wherever the segment boundaries fall:

Framing responses#

Ghoti batches pending responses and async events, so a single read on the client can return several messages at once. Clients must split the incoming stream on \n and never assume that one read yields one message. For example, a write to a broadcast slot can arrive as a single segment holding both the async event and the confirmation, one per line:

< a004HelloWorld
< v0042/2/0

Commands#

CommandFormAnswered with
r readr + 3-digit slotv + slot + value, or e
w writew + 3-digit slot + value (up to 36 bytes)v + slot + value, or e
s subscribes + 3-digit slotv + slot + 1, or e
d deregisterd + 3-digit slotv + slot + 0, or e
u useru + usernamev + username, or e
p passwordp + passwordv + username, or e
q quitqNothing. The connection is closed.

Any other command byte is rejected with exxx001, and so is a slot number that is not exactly three ASCII digits. Only w takes bytes after the slot number, so r000JUNK is rejected with exxx001 rather than read as r000.

Current behaviour: j is accepted but never answered

The parser accepts j followed by a three-digit slot number, but the server has no handler for it and sends no response. A client that sends it waits forever for an answer. Don't send it.

Read: r#

Send r and a three-digit slot number. The response is v, the slot number, and the value:

> r000
< v0006396A64C-1C2C-4BFC-B8F1-034758018CAC

What a read returns, and whether it changes the slot, depends on the slot kind. See the slot reference.

Write: w#

Send w, the slot number and the value. Everything after the third digit, up to the terminator, is the value. On most slots the response echoes what was stored:

> w000HelloWorld
< v000HelloWorld

w000 with nothing after it writes an empty value. Broadcast and multicast slots answer a write with a received/sent/errors summary instead of the value.

Subscribe and deregister: s, d#

Multicast slots deliver events only to the connections in their group. s joins the group and d leaves it. The value in the response tells you whether the connection is now a member:

> s005
< v0051
> d005
< v0050

Sending s or d to a slot that doesn't manage a group returns error 010 (UNSUPPORTED_COMMAND). Both commands need read permission on the slot.

Login: u, p#

u sets the username on the connection and p checks the password. The exact rules are on the Authentication page.

Quit: q#

q closes the connection cleanly. It takes no slot number and no arguments, so the request is exactly one byte, and anything after it is rejected with exxx001. The server doesn't answer it.

Responses#

The first byte of every message identifies its type:

TypeFormExample
v valuev + slot + valuev000HelloWorld
e errore + slot (or xxx) + 3-digit code, optionally followed by an argumente000008, exxx003, exxx000node1
a async eventa + slot + dataa234HelloWorld

The answers to u and p are the exception: v followed directly by the username, with no slot number.

Errors that are not about a slot, such as a parse error or a login failure, use xxx in place of the slot number. Every code is listed in Error codes.

Treat any other leading byte as unknown: discard the message up to the next \n and keep reading rather than closing the connection. That keeps clients working if new response types are added.

Ordering#

Retries and idempotency#

A command can be retried safely only if it is idempotent, and this table is the authority on which commands are:

Command and slotSafe to retry
r on simple memory, timeout memory, broadcast, multicastYes
r on atomic counterNo, every read increments the counter
r on token bucket, leaky bucketNo, every read consumes from the bucket
r on tickerYes. A read applies the ticks that have elapsed since the last read, so its value depends on time, not on how many reads were sent
w on simple memory, timeout memory, atomic counter, tickerYes, the value is absolute
w on broadcast, multicastNo, every write sends the event again
s, dYes, both are idempotent
u, pA failed p closes the connection, so a retry means opening a new connection and starting the login again

A lost response can't be told apart from a command that was never executed. A client that needs at-most-once semantics for the non-idempotent commands has to reconcile the state itself, for example by reading the slot back where the slot kind allows it.

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