Protocol — Client ↔ Server ​

The full spec of every byte exchanged on the client port (default 5225). It consists of the auth handshake, performed once right after connecting, followed by the binary frame lock protocol. Every official client implements this specification identically, byte for byte.

Each message page's Structure shows the field layout, and Example shows the actual bytes sent (values change with refresh).

Byte notation: op is shown as an ASCII character (e.g. A); wait and lease are u8 binary values, while token and owner are u64 big-endian binary values. They are shown in hex (e.g. wait=5 → 05). key and addr are UTF-8 text, and reason is ASCII text — all of these are variable-length, shown as N in the structure. The trailing \n (newline) terminates the frame as 0A. Fields are sent back-to-back with no delimiter.

The fixed headers (wait, lease, token, owner) are binary values that may contain 0x0A — so a parser must consume the op's fixed-header length by byte count first, before scanning for the newline. The lengths are: requests A=10B / R=8B; responses A=16B / T·B·R·N=8B / M·L·E=0B.

Table of Contents ​

• Transport layer
• Auth handshake — shared with the cluster's Raft port, so it lives on the Protocol (Common) page
• Requests
  • A · Acquire
  • R · Release
• Responses
  • A · Acquired
  • T · Timed Out
  • B · Busy
  • R · Released
  • N · Not Found
  • E · Error
  • M · Moved
  • L · Leader Notice
• Field constraints
• Request × key-state matrix
• Fencing token
• Reply matching rules
• Example session

The server-to-server cluster consensus (Raft) protocol is covered on a separate page.