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_versionbeing declared first is what makespostcard::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 toOkunder a derived impl. So position cannot be the obligation there, and it is discharged instead by the explicit check inEnvelope’s hand-writtenDeserialize, 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.
- Postcard
Error - What postcard reported, carried without making postcard’s own error type a part of this crate’s public API.
- Pull
Request - Asks the far side for one round trip’s worth of what it holds.
- Resume
Token - Where the far side should resume a pull from, as the far side minted it.
Enums§
- Codec
Error - Why envelope bytes could not be read or written.
- Route
- Which of
SyncPeer’s two exchanges a buffer belongs to. - Wire
Error - 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.