Struct Envelope
pub struct Envelope<T> { /* private fields */ }Expand description
A replication message, wrapped with the wire format version that produced it.
Field order is part of the contract: format_version is declared first so
that a positional encoder writes it first. See the module documentation for
why that is only half of WF-8’s obligation.
use happenstance_sync::wire::{Envelope, FORMAT_VERSION};
let envelope = Envelope::new("hello");
assert_eq!(envelope.format_version(), FORMAT_VERSION);
let json = serde_json::to_string(&envelope)?;
assert_eq!(json, r#"{"format_version":3,"message":"hello"}"#);
let decoded: Envelope<String> = serde_json::from_str(&json)?;
assert_eq!(decoded.message(), "hello");A version this build does not implement is refused, and the message inside is never decoded:
use happenstance_sync::wire::{Envelope, WireError};
// What a peer one format version ahead would send.
let json = r#"{"format_version":999,"message":"hello"}"#;
let error = serde_json::from_str::<Envelope<String>>(json).unwrap_err();
assert!(error.to_string().contains(WireError::UNSUPPORTED_FORMAT_VERSION));Implementations§
§impl<T> Envelope<T>
impl<T> Envelope<T>
pub const fn new(message: T) -> Self
pub const fn new(message: T) -> Self
Wraps message and stamps FORMAT_VERSION.
There is deliberately no constructor that stamps an arbitrary version: a sender that can name a version it does not implement can send one, and nothing downstream could tell that from a peer that genuinely speaks it.
pub const fn format_version(&self) -> u16
pub const fn format_version(&self) -> u16
The version this envelope was encoded at.
Always FORMAT_VERSION — a decoded envelope carrying anything else
does not exist, because decoding refuses it.
pub fn into_message(self) -> T
pub fn into_message(self) -> T
Unwraps the envelope, discarding the version.
Trait Implementations§
impl<T: Copy> Copy for Envelope<T>
§impl<'de, T: Deserialize<'de>> Deserialize<'de> for Envelope<T>
The hand-written half of the format, and the reason this module exists.
impl<'de, T: Deserialize<'de>> Deserialize<'de> for Envelope<T>
The hand-written half of the format, and the reason this module exists.
Do not replace this with #[derive(Deserialize)]. The derive is a code
generator with no interception point: it reads every field into a local
Option and only then constructs the struct, so a derived Envelope<T>
decodes the message before anything examines the version — the partial decode
WF-8’s MUST NOT forbids. default, deny_unknown_fields and flatten are
the hooks the derive offers, and none of them is “stop here and decide”.
A derive plus a version check afterwards looks identical from outside and is
not: measured, it returns the same Err in both formats and produces
byte-identical postcard framing — [01 07] at version 1, [80 03 07] at 384,
the same take_from_bytes::<u16> value and the same [07] remainder. The
one observation that separates them is whether T::deserialize ran at all,
which is what wire::version_is_readable_before_the_message witnesses.