Protocol overview

rifleDB speaks two protocols on the same paths: a Socket.IO connection for realtime use (what the SDK uses) and a REST API for everything else (curl, server code, other languages). This page is a map; the binding definitions are in architecture.md §4, §7 and §8, and the shared types, signing-string builders and pure ops live in @rifledb/protocol (packages/protocol/src).

Paths and values

• Paths are slash-separated segments of [A-Za-z0-9_~.-] (1–128 characters, not ./..), at most 16 deep and 512 characters. Top-level _ (system endpoints), system and users are reserved; segments starting with @ name actions.
• Values are JSON: no non-finite numbers, no __proto__/constructor/prototype keys, depth ≤ 8, ≤ 64 KB serialized (folders may set a lower maxValueBytes). Fast folders take only primitives and arrays of ≤ 256 primitives, ≤ 2 KB.
• Every stored value has a rev: one global, increasing sequence. Together with the server's epoch it identifies a version: ETags are "<epoch>:<rev>". The epoch changes on every server boot (INCR in Redis; a server with its own non-persistent in-memory store seeds it from the clock so it never repeats; architecture.md §3), so an ETag from before a restart no longer matches.

Realtime: Socket.IO at /v1/_ws

WebSocket transport only (long-polling is opt-in). Browsers must connect from an allowed origin (RIFLE_ALLOWED_ORIGINS); clients that send no Origin (Node) are admitted. Payloads are capped at 64 KB.

0. In the handshake the client may send auth: {slot: <32 random bytes, base64url>} (Socket.IO's auth option): a secret it keeps for its lifetime. One address may hold 64 connections at once; further handshakes are refused.
1. The server greets with hello {v: 1, epoch, nonce, serverTime, origin, limits, slot}. slot is 'p_' + b64url(sha256('rifle/slot/v1\n' + secret)).slice(0, 22) (random without a secret): the key segment this connection may write in a publicWrite: 'own' folder. The same secret gives the same slot on every connection, and nobody who only sees the slot can claim it.
2. The client signs rifle/ws-auth/v1\n<origin>\n<nonce>\n<serverTime>\n<kid> with each device or folder key and sends auth {proofs: [{kid, pub, sig}], register?}. Anonymous sessions skip this and can read public data and call public actions. The SDK re-authenticates after every reconnect.
3. Every client message is acknowledged: {ok: true, …} or {ok: false, code, msg, retryAfter?}.

Op ids make retries safe: a replayed id returns the original result (kept 5 minutes). Fast folders coalesce updates per path at hz per second (default 30) and send them as volatile messages, but deletes and each key's settled final value are always delivered.

sub acks carry seq: the server's sequence (highest rev assigned) when the snapshot was read. Every change with a rev at or below it is already in entries/dels, so a chg entry with rev <= seq arriving later is dropped — also for keys absent from the snapshot.

E_RATE acks carry retryAfter (ms) and, when the server knows it, scope: which limit refused.

REST: /v1/…

Preconditions: If-Match: "<epoch>:<rev>" writes only if the key is still at that version (412 otherwise); If-None-Match: * only if it does not exist. Validation and access checks run before anything is written: a refused request leaves no trace.

Signed requests

Requests that need an identity carry:

Rifle-Timestamp: <ms since epoch>
Rifle-Nonce: <≥16 random bytes, base64url>
Content-Digest: sha-256=:<base64 of sha256(body)>:      (with a body; RFC 9530)
Rifle-Signature: <kid>=<base64url Ed25519 signature>[, …] (up to 4 keys)
Rifle-Elevation: <token>                                 (optional, after a REST step-up)

over the string

rifle/http/v1\n<METHOD>\n<host>\n<path and query exactly as sent>\n<timestamp>\n<nonce>\n<Content-Digest or ->\n<sha256(elevation token) base64url or ->\n<kid>

The server checks, in this order: timestamp within ±60 s (401), nonce unused (409 E_REPLAY; nonces are kept 3 minutes), digest matches the raw body (422), Host is one of RIFLE_PUBLIC_HOSTS (403), signatures (401). The SDK's HTTP client and createRifleServer do all of this; e2e/tests/support.ts and server/smoke.ts show it in about 30 lines with WebCrypto.

Errors

RFC 9457 application/problem+json: {type, title, status, detail, code, retryAfter?, scope?} (scope on E_RATE as on the socket, when known), with Retry-After on 429 and WWW-Authenticate: Rifle-Signature on 401.

Other codes an action raises with abort answer 422; unexpected server errors 500 E_INTERNAL without details.

CORS: only RIFLE_ALLOWED_ORIGINS, ETag exposed, Rifle-* and Content-Digest headers allowed, never credentials (there are no cookies anywhere, so there is nothing to forge cross-site).