Skip to main content

Module wire

Module wire 

Expand description

The versioned envelope every replication message travels in.

§What is here

The envelope, per ADR-0016 §11 — FORMAT_VERSION, Envelope, its hand-written Deserialize impl and WireError — and, since #114, the message set at the end of the file.

Envelope is generic in T and is not an enum of message kinds, and the message set did not make it one. Each message is its own type, wrapped as Envelope<PushBatch>, Envelope<Ack>, Envelope<PullRequest> or Envelope<Pulled<ResumeToken>>: an enum of kinds inside the versioned type would make adding a kind a shape change, and so a version bump every peer not yet redeployed refuses. Which message a buffer holds is the transport’s to say — the route, or the request it answers (ADR-0097). SyncError is still not extended.

§The obligation, and why it is discharged differently in each format

WF-8 says a receiver must read and check the version before any part of the message is decoded. That single sentence has two spellings, because the two formats this workspace encodes into do not agree on what “first” means.

  • In a positional format — postcard — fields are written in declaration order and nothing else is recoverable, so format_version being declared first is what makes postcard::take_from_bytes::<u16> on the front of the buffer yield it. That is a property of the struct declaration, which is why the field order below is load-bearing rather than cosmetic.
  • In a self-describing format — JSON — key order carries no meaning at all. Measured: {"message":null,"format_version":999} decodes to Ok under a derived impl. So position cannot be the obligation there, and it is discharged instead by the explicit check in Envelope’s hand-written Deserialize, before the message is touched.

The measurements behind both statements are in experiments/wire-format/tests/w6_envelope_varint.rs and decorative_envelope_witness.rs.

Structs§

Envelope
A replication message, wrapped with the wire format version that produced it.
PostcardError
What postcard reported, carried without making postcard’s own error type a part of this crate’s public API.
PullRequest
Asks the far side for one round trip’s worth of what it holds.
ResumeToken
Where the far side should resume a pull from, as the far side minted it.

Enums§

CodecError
Why envelope bytes could not be read or written.
Route
Which of SyncPeer’s two exchanges a buffer belongs to.
WireError
Why a wire-level decode was refused.

Constants§

FORMAT_VERSION
The version stamped on every envelope this build encodes, and the only one it decodes.

Functions§

check_format_version
Checks a version read off the wire against the one this build speaks.