Crate ssp2 

ssp2 — Syncular v2 wire codec (Rust POC)

A fresh implementation of the SSP2 envelope, the SSG2 rows-segment format, the §2.4 row codec, §8 realtime control messages, and the §11 canonical JSON debug rendering — built from SPEC.md alone (no reference to the v1 Rust tree or the v2 TypeScript implementations) to prove the written protocol contract is language-neutral. Conformance is pinned by the golden vectors in spec/vectors/.

Re-exports

pub use decode::decode_message;

pub use encode::encode_message;

pub use error::DecodeError;

pub use error::ErrorCode;

pub use model::Frame;

pub use model::Message;

pub use model::MsgKind;

pub use realtime::encode_presence_publish;

pub use realtime::parse_control;

pub use realtime::parse_control_value;

pub use realtime::render_control;

pub use realtime::ControlMessage;

pub use realtime::PresenceKind;

pub use render::render_message;

pub use render::render_rows_segment;

pub use segment::decode_rows_segment;

pub use segment::encode_rows_segment;

pub use segment::RowsSegment;

pub use segment::SegmentRow;

pub use stream::MessageStreamScanner;

pub use stream::ScannedMessage;

Modules

blob_ref

Canonical BlobRef documents (SPEC.md §5.9.1) — the value a blob_ref column (§2.4 tag 7) carries. Wire-shaped identically to json (a str), validated at decode against the pinned shape and key order; the raw string is preserved verbatim for re-encoding.

decode

SSP2 envelope decoding (SPEC.md §1.2), request/response frame grammar (§1.5, §1.6), and the closed decode-error boundary of §1.7: exactly the listed violations are rejected here, nothing more.

encode

Canonical SSP2 encoding (SPEC.md §1.2). Re-encoding a decoded message reproduces the input byte-for-byte: raw json strings, map entry order, and unknown frames are all preserved by the model.

error

Decode errors carrying the SPEC-named error codes (SPEC.md §1.7, §10).

model

Decoded SSP2 message model (SPEC.md §1.2, §1.5, §1.6, §4–§6).

primitives

Conventions primitives (SPEC.md “Conventions and primitive encodings”): little-endian fixed-width integers, str, bytes, opt, bool, json, canonical maps. Shared by the envelope codec and the SSG2 segment codec.

realtime

Realtime JSON control messages (SPEC.md §8). Server→client messages use {"event": …, "data": …}; the client ack uses {"type":"ack", …} (§8.2). Unknown events are tolerated and preserved verbatim (§8.1 forward-compat mirror of the frame-skip rule).

render

Canonical JSON debug rendering (SPEC.md §11.1). Non-contractual for the wire; contractual for golden vectors — rendered values must deep-equal the committed .json files when parsed as JSON.

segment

SSG2 rows segments (SPEC.md §5.2) and the §2.4 generated-row codec they embed. All structural decode failures are sync.invalid_request (§5.2 error-code rule); the column-table-vs-generated-schema comparison (sync.schema_mismatch) is the receiver’s job, not the codec’s.

stream

Incremental SSP2 message-stream scanner (SPEC.md §1.4, §8.7).

util

Small helpers: base64 (for §11 renderings) and UTF-16 code-unit ordering (Conventions: map keys are canonically sorted by code unit).