bibeam_protocol/
frame.rs

1#![forbid(unsafe_code)]
2//! Wire-frame envelope shared by every `BiBeam` transport.
3//!
4//! Every message on the wire begins with [`MAGIC`] (`b"BIBM"`) followed by
5//! the one-byte [`VERSION`] tag. The remaining bytes are a postcard-encoded
6//! [`Frame`]. Keeping the prefix outside of the postcard payload lets the
7//! receiver reject mismatched protocol families before reaching for a
8//! serde-aware decoder.
9//!
10//! The three [`Frame`] variants now each carry their concrete payload:
11//!
12//! - [`Frame::Control`] carries the discovery / coordinator control
13//!   messages added in F-PROTO.3,
14//! - [`Frame::Tunnel`] carries the WG-sealed IP datagram added in
15//!   F-PROTO.4, and
16//! - [`Frame::Cohort`] carries the cohort lifecycle messages added in
17//!   F-PROTO.5.
18//!
19//! Codec helpers live in [`crate::codec`]; this module is wire-shape only.
20
21use serde::{Deserialize, Serialize};
22
23use crate::cohort::CohortMessage;
24use crate::control::ControlMessage;
25use crate::tunnel::Tunnel;
26
27/// Four-byte magic prefix written at the start of every `BiBeam` frame.
28///
29/// Spelled `BIBM` so a packet capture of any `BiBeam` flow is recognisable
30/// without consulting a decoder. The receiver MUST reject any buffer whose
31/// first four bytes do not match this constant.
32pub const MAGIC: [u8; 4] = *b"BIBM";
33
34/// Current wire-format version.
35///
36/// Incremented on any breaking change to the [`Frame`] layout or to the
37/// codec framing rules. A receiver MUST reject any buffer whose version
38/// byte does not match the version it speaks.
39pub const VERSION: u8 = 1;
40
41/// Top-level wire frame.
42///
43/// Each variant carries the payload introduced by its matching F-PROTO
44/// sub-item: [`Frame::Control`] holds a [`ControlMessage`] (F-PROTO.3),
45/// [`Frame::Tunnel`] holds a [`Tunnel`] datagram (F-PROTO.4), and
46/// [`Frame::Cohort`] holds a [`CohortMessage`] (F-PROTO.5).
47#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
48pub enum Frame {
49    /// Control-plane traffic carrying one [`ControlMessage`].
50    Control(ControlMessage),
51    /// Data-plane traffic carrying one [`Tunnel`] datagram.
52    Tunnel(Tunnel),
53    /// Cohort-plane traffic carrying one [`CohortMessage`].
54    Cohort(CohortMessage),
55}
bibeam_protocol/frame.rs

bibeam_protocol/
frame.rs
