Client Server Protocol

Client-Server Protocol

Connection Model

Stateless. No sessions, no prepared statements. Each request carries all context. Connections are reused for sequential pipelining - send request, get response, send next. Not multiplexed. One in-flight request per connection.

Two ports: client port for application traffic, replication port for cluster traffic. Wrong port = error 400. TCP_NODELAY on everything.

TLS

TLS 1.3 only. No fallback. kTLS offloads encryption to the kernel after the handshake, so io_uring reads/writes pass through without touching ciphertext in userspace. Session tickets are disabled (they desync kTLS sequence counters).

Two separate CAs: client CA on the client port, intracluster CA on the replication port. A client cert can't authenticate to the replication port. Replication always requires mTLS. Client port mTLS is configurable (default: require).

Hot-reload of certs is supported via configurable interval.

Identity & Auth

Identify is the mandatory first frame on every client connection, V4 and V5, whatever the server config. Any other first frame gets ProtocolError (response type 6) and the connection closes. Its body is discarded unparsed. Credentials in the Identify are optional unless the server requires them.

Two independent controls share the Identify round trip and nothing else:

• require_client_identity requires a verified RSA key pair (public_key + nonce + signature). An API key does not satisfy it: 10004.
• An api_keys.toml requires a valid API key. A key pair does not satisfy it: 10005. An API key presented to a server with no keys file: 10006.

Check order: signature (10001/10002), then the flag (10004), then API keys (10005/10006). So 10004 wins when both controls fail. Every rejected Identify closes the connection. Once identified, access level is stored on the connection for its lifetime. An API key grants access, not identity, and leaves write client_id unchecked.

The Identify also exchanges the compression dictionary: the client advertises known_dict_sha256 (seeded with the built-in), and the server ships bytes only on a mismatch. The dictionary ceiling is 1 MiB. Clients read the IdentifyResponse under ceiling + 128 (V4), not their response cap; the server's V5 write limit is 2 × ceiling + 128 because msgpack encodes the dictionary as an integer array. A non-Identify reply to Identify stays under the caller's cap. The server refuses to start with a larger dictionary.

API keys are stored as SHA-256 hashes only, never raw. Four slots: two ReadWrite, two ReadOnly.

API keys and client identity require TLS unless --insecure-allow-plaintext-auth is explicitly set (server exits at startup otherwise).

Access levels: ReadWrite (all operations) or ReadOnly (reads, details, lists only). Write/Delete/TrimStart/RegisterSchema on a ReadOnly connection = error 10007.

Pipelining

Sequential request-response loop. Server reads a request, processes it, sends response, reads next. Connection stays open until client timeout, server shutdown, or a Watch request.

Watch is connection-terminal. Once a Watch starts, the connection streams events until the client disconnects or filters empty out. No further regular requests.