Skip to main content

Module wire

offline_protocol_core

Module wire 

Source
Expand description

Compact binary wire codec for Message (wire format v1).

This is an additive second encoding alongside the canonical JSON representation — it does not replace it. JSON remains the permanent interoperability floor: every receiver still accepts JSON, and a binary frame is only ever produced for a peer known to support it. The two encodings are distinguished by the first byte alone (WIRE_V1_MAGIC vs. { = 0x7B), so no negotiation is required to decode.

§Why a frozen DTO

Message carries #[serde(default)] and #[serde(skip_serializing_if)] attributes plus validation-on-deserialize impls that a non-self-describing binary format (postcard) cannot honor field-for-field. Rather than serialize Message directly, this module defines WireMessageV1, a flat DTO with a fixed field order, and converts to/from Message through the validating constructors (UserId::new, LamportClock::from_value, …). That keeps the security checks the JSON path enforces (identifier caps, Lamport clamp) intact on the binary path.

§Evolution contract

postcard is positional: reordering, removing, retyping, or inserting a field silently corrupts decoding on peers running the previous layout. Therefore:

  • Never change WireMessageV1’s existing fields.
  • Additive, backward-compatible data goes into WireMessageV1::ext, a trailing (tag, bytes) list that old decoders read and ignore.
  • A change that cannot be expressed as an ext entry requires a new magic byte (0xF6 = v2) and out-of-band version negotiation.

The numeric enum mappings (priority_to_u8, content_type_to_u8) are likewise a frozen wire contract.

(WireMessageV1 and the two mapping helpers are deliberately private — the DTO is an encoding detail, not API surface — so they are named here in code spans rather than as intra-doc links, which rustdoc rejects for private items in public documentation.)

Constants§

WIRE_V1_MAGIC
Magic/version byte prefixed to every wire-format-v1 binary frame.
WIRE_VERSION_V1
Logical wire-format version advertised during capability negotiation, corresponding to WIRE_V1_MAGIC. Peers exchange the set of versions they can decode in their signed key package; a peer that lists this value can decode WIRE_V1_MAGIC frames, so it is safe to send it binary.