Field Constraints and Value Ranges ​

Request Fields (C→S) ​

• There is no infinite wait or lease. Official clients round sub-second values up, validate the range, and return an explicit input error before sending instead of clamping an out-of-range value. The default lease is 30 seconds.
• In the official client API, wait is the whole acquire limit from call entry through the local queue, definitely-unsent connection retries, the write, and the response. The client creates one monotonic operation deadline, and immediately before sending the writer puts the u8 ceiling of the remaining seconds into the frame's wait. A late connection or definitely-unsent failover therefore cannot restart the server wait from the beginning. At the deadline, a request still queued times out definitely unsent; if even one byte may have been sent, the exact session is closed and the result is Indeterminate. Only an original wait=0 uses wire 0, and that immediate attempt has a separate finite I/O deadline so a stalled transport cannot block forever. If a correlated A from just before the deadline is discovered late at the Ticket delivery gate, the server waiter is already resolved: keep the session open, compensate the known exact token, and return Indeterminate. Correlated T/B remain definitive non-acquisitions.
• For an original wait=0, wire and server behavior remain one immediate, non-queued attempt. Within its separate five-second transport deadline, a definitely-unsent failure may select another connection and retry with the same owner. Once any byte may have been sent, the acquire is never retransmitted.
• The official client API requires min_work_budget, which is not carried on the wire. It must cover critical work + expected pause + DB commit/rollback completion, be in 0..250 seconds, and not exceed the normalized lease. Violations fail before any frame is sent with an UnsupportedDuration/InsufficientLease-class error.
• Key length is measured in bytes, not characters — Korean is 3 bytes per character in UTF-8, so at most 42 characters.
• owner is only a response correlation ID, not authority. Reusing it does not return an active token or renew a lease. Concurrent in-flight requests from one client must still use distinct non-zero values so responses remain unambiguous. Official clients fail closed if their local counter reaches zero or wraps.
• bad_key covers an empty key, one over 128 bytes, one containing whitespace or a newline, and invalid UTF-8, all alike. Official clients additionally never send \r — a key ending in \r would silently become a different key.
• Explicit release and compensating release for an already-known token have one absolute 5-second deadline from call/enqueue time, including reconnects and retries. R confirms success; N means already gone or not the current token. No observed response is never assumed to mean success. A full bounded compensation queue falls back to the lease-expiry safety net.

Response Fields (S→C) ​

The server never issues token 0. Single mode uses a counter for the current process lifetime; cluster mode uses a consensus-replicated counter and fails closed before overflow. Wall clock or randomness is not claimed to provide monotonicity across restart.

Fixed-Header Lengths ​

The fixed-length binary run that follows the op. These bytes may contain 0x0A, so a parser must consume exactly this many before it starts scanning for the newline.

Too few bytes yields E bad_request.

Frame Size ​

The 192B limit sits comfortably above the largest possible frame (146B), so a client that follows the spec can never hit it. After a structurally malformed or oversized frame, framing is no longer trusted and the connection is closed.

Auth Handshake ​

See Auth Handshake for the full procedure.

Server-Side Limits ​

Values a client never sets directly, but which still shape its behaviour.

The read buffer (4096B), response batch (64), 5-second progress timeout for a started client frame, and the single-mode expiry sweep (5 seconds) are compile-time constants, not environment variables. Cluster expiry uses a token-validating deadline min-heap rather than a full scan. For the full list of configurable values and their valid ranges, see Configuration (Env Vars).

Acquire, new-key, and total-waiter admission closes at 90% of each hard limit and reopens only after usage falls below 75%. A new acquire can therefore get B before the hard limit; capacity reserved for release and Raft recovery is separate from this hysteresis.

Violation → Response Summary ​

For every error reason and its connection handling, see Response · Error E.