Crate commy_wire 

The Commy wire contract: the binary range frame and the error-code vocabulary.

The specification is in spec/, the language-neutral golden vectors are in vectors/, and every SDK runs the same vectors in its own CI. This crate is the Rust side of that contract and is tested against those exact files.

Structs

Authenticate

Client to server. Carries the protocol version.

ByteRange

A run of bytes inside a file, named without its data.

ConfirmLocal

Client to server: the nonce read from nonce_path, proving the same filesystem view.

ConfirmLocalAck

Server to client: the nonce matched; the server deletes the nonce file. A mismatch is an Error with PERMISSION_DENIED.

ErrorReply

Server to client: a request failed.

FlushAck

Server to client: the flush identified by request_id is applied; seq is the new sequence.

FlushEnd

Client to server, from a remote sender: the range frames for one flush are complete. The server assigns the flush one new seq, forwards it, and answers FlushAck.

GetServiceFilePath

Client to server: may this service file be mapped locally?

Loss

Server to a client: writes of its own were lost, and why. ranges are in old-file coordinates; empty means the whole file. A receiver treats an unknown kind as a loss of the whole file.

LossRange

A byte range inside a file.

RangeFrame

A run of bytes that changed in one service file. All integers are little-endian.

RangesChanged

Client to server, from a local sender (it wrote into the shared mapping): these ranges changed. No data travels; the server reads the latest bytes from the file when it forwards. Answered with FlushAck.

RangesUpdated

Server to a local receiver: these ranges of the file changed, at seq. No data; the receiver already sees the bytes through its own mapping.

Resync

Client to server: send the whole file again (no replay log in v1).

ResyncDone

Server to client: the last range frame of the snapshot has been sent.

RotateRequest

Client to server: replace a service’s file. new_size is required for RESIZE and forbidden for REVOCATION; revoke_client_id is the reverse. See RotateRequest::validate.

RotationAccepted

Server to client: the request was accepted. The rotation ends with RotationCommit.

RotationCommit

Server to every SDK on the service: the new file is live. new_file_id differs from old_file_id and is the handle for the new mapping; fetch it with GetServiceFilePath (local) or Resync (remote). After a revocation, each remaining SDK writes its unflushed ranges into the new file; after a resize, old-offset writes are never replayed.

RotationDrained

Client to server: everything written so far is flushed; seq is the last sequence flushed.

RotationPending

Server to every SDK on the service (resize only): the drain barrier is open. Stop issuing write guards, wait for outstanding ones, flush into the old file, then send RotationDrained within deadline_ms. An SDK that does not is dropped with a ROTATION_STRAGGLER Loss.

ServiceFilePath

Server to client: the file_id that range frames use for this service. path and nonce_path are both present (local mapping offered) or both absent (stay on WSS ranges). They are absent unless the service is open to local mapping and the caller holds a write grant on it.

Enums

ControlMessage

JSON control messages, sent as WebSocket text frames. Adjacently tagged ({"type": ..., "data": {...}}); unknown fields and unknown types are refused.

ErrorCode

The only spellings an error code may have on the wire, from server and SDKs alike.

FrameError

Why a binary frame was refused.

LossKind

What a program lost.

RotateReason

Why a service file is being replaced.

Constants

HEADER_LEN

Bytes before the payload: kind (1) + file_id (4) + seq (8) + offset (8) + len (4).

KIND_RANGE

First byte of a binary range frame.

MAX_PAYLOAD

Largest payload one frame may carry. A bigger change is split into several frames.

MAX_RANGES_PER_MESSAGE

Most ranges one RangesChanged or RangesUpdated may carry. A flush with more is split into several messages, each getting its own seq.

Functions

validate_ranges

Check a range list: 1 to MAX_RANGES_PER_MESSAGE ranges, none empty, none whose end overflows a u64, sorted by offset and not overlapping (adjacent is fine). A message that fails is answered INVALID_REQUEST (or dropped, when it came from the server).