diff options
| author | tv <tv@krebsco.de> | 2026-11-19 17:44:03 +0000 |
|---|---|---|
| committer | tv <tv@krebsco.de> | 2026-11-19 19:26:01 +0100 |
| commit | 59e889254b1fda2dcc8e3e6d596635d1b77f589f (patch) | |
| tree | 2412dd262e7ae729498eb3300912395b601cd0b6 /src/transport/wire.rs | |
| parent | 180aba9ff89a4a294e284aa281d96adbcfe1b85b (diff) | |
transport: wire versions spoken side by side
A build speaks wire versions OLDEST to VERSION and writes each node the
newest both speak (wire::choose), as the node's SPEAKS says; the oldest
until it says. The identity layer keeps that per address (Book::speaks):
a SPEAKS from an address sets it for the address, and for every address
of the node proven there, and a new address of a node takes it over.
Paths encodes each message for an address in its version
(Transport::encode_in; Transport::encode is the newest).
So that two nodes know what the other speaks once they have proven
themselves to each other, before any other message goes between them, a
SPEAKS goes ahead of every WHO and ME, and WHO and ME are read in every
version from 52 on (wire::PROOFS): their tags and layout never change.
Without that, a node whose oldest version is past the other's couldn't
read its proofs, and the two would never get to the handshake that says
what each speaks. A SPEAKS naming no version this build speaks is logged
as a message of another version is, naming the node to upgrade, the
versions as ranges.
A 0.0.1 node takes a SPEAKS from an address not yet proven for any other
message from there: it drops it, and asks WHO.
This build speaks 52 alone, so nothing it sends changes but the SPEAKS
ahead of the proofs. A release adding a version encodes and decodes the
older ones from their own, frozen, types.
Diffstat (limited to 'src/transport/wire.rs')
| -rw-r--r-- | src/transport/wire.rs | 206 |
1 files changed, 167 insertions, 39 deletions
diff --git a/src/transport/wire.rs b/src/transport/wire.rs index 0b661dd..56883e8 100644 --- a/src/transport/wire.rs +++ b/src/transport/wire.rs @@ -3,15 +3,26 @@ //! arrays, fields in declaration order). The codecs below make hashes, IDs and bytes //! compact (MessagePack binaries, not arrays of numbers) and check their lengths. //! -//! The wire format may change freely until the first release: there is no compatibility -//! with older nodes to keep. But every change bumps `VERSION`, so nodes on different -//! builds tell each other apart instead of misreading each other's messages. The +//! Every change to a message type or a codec is a new version (`VERSION`), and a build +//! speaks several side by side, `OLDEST` to `VERSION`: it reads each, and writes to each +//! node the newest both speak (`choose`), as the node's SPEAKS says, or `OLDEST` until +//! then (`transport::identity`). So releases whose versions meet roll out node by node: +//! a release adds a version and keeps the older ones, and a later one leaves out the +//! oldest. The messages of an older version keep their own types, frozen, encoded and +//! decoded here beside the newest's (`golden_bytes` keeps the bytes of each). The //! transport's topic says which application a message is for, not which version. //! -//! One message stands outside the versions: SPEAKS (`SPEAKS`), its first byte the -//! version none is, laid out as no build changes, saying which versions a node speaks -//! and the newest revision of the federation it knows. A build from before it reads it -//! as a message of another version, and ignores it. +//! Two kinds of messages stand outside the versions, as they are what lets two builds +//! learn what the other speaks: +//! +//! * SPEAKS (`SPEAKS`), its first byte the version none is, laid out as no build changes, +//! saying which versions a node speaks and the newest revision of the federation it +//! knows. A build from before it reads it as a message of another version, and +//! ignores it. +//! * WHO and ME, the proofs of who is at an address (`PROOFS`), laid out in every +//! version as in the first: a build reads them whatever version they say they are in, +//! from that first on, so that two nodes prove themselves to each other before they +//! know what the other speaks. use thiserror::Error; @@ -31,8 +42,14 @@ pub(crate) const OLDEST: u8 = VERSION; /// those and leaves whatever follows, which a later build may add. pub(crate) const SPEAKS: u8 = 0; -// Whatever this build's versions, a SPEAKS reads as one. -const _: () = assert!(SPEAKS < OLDEST && OLDEST <= VERSION); +/// The first version with SPEAKS, as WHO and ME are laid out in every version: their +/// tags and fields never change (a change would be a new kind of message), and a build +/// reads them in any version from this one on, older or newer than its own. +pub(crate) const PROOFS: u8 = 52; + +// Whatever this build's versions, a SPEAKS reads as one, and it reads the proofs of +// every build that speaks one of its versions. +const _: () = assert!(SPEAKS < PROOFS && PROOFS <= OLDEST && OLDEST <= VERSION); /// What the second byte of a payload says. fn tag(kind: MessageKind) -> u8 { @@ -78,11 +95,15 @@ pub(crate) enum WireError { Decode(#[from] rmp_serde::decode::Error), } -/// `message` to `peer`, encoded as it goes on the wire alone (no envelope: libp2p, -/// Tor, the simulator); `peer` is its address too. +/// `message` to `peer`, encoded in wire `version` as it goes on the wire alone (no +/// envelope: libp2p, Tor, the simulator); `peer` is its address too. #[cfg_attr(not(any(feature = "libp2p", feature = "tor", test)), allow(dead_code))] -pub(crate) fn encoded(peer: &str, message: &ParsedMessage) -> anyhow::Result<EncodedMessage> { - let body = encode(message)?; +pub(crate) fn encoded_in( + peer: &str, + message: &ParsedMessage, + version: u8, +) -> anyhow::Result<EncodedMessage> { + let body = encode_in(message, version)?; Ok(EncodedMessage { peer: peer.to_owned(), address: peer.to_owned(), @@ -93,7 +114,31 @@ pub(crate) fn encoded(peer: &str, message: &ParsedMessage) -> anyhow::Result<Enc }) } -/// The payload of `message`. +/// The newest wire version a peer speaking `oldest` to `newest` (its SPEAKS) and this +/// build both speak: what this build writes to it. None where they share none. +pub(crate) fn choose(oldest: u8, newest: u8) -> Option<u8> { + let (low, high) = (oldest.max(OLDEST), newest.min(VERSION)); + (low <= high).then_some(high) +} + +/// The payload of `message` in wire `version`, one of `OLDEST..=VERSION`: of an older one, +/// as a build speaking only that one reads it. A SPEAKS is laid out alike in every one, +/// and so are WHO and ME (`PROOFS`), but for the version they say. +pub(crate) fn encode_in(message: &ParsedMessage, version: u8) -> Result<Vec<u8>, WireError> { + if matches!(message, ParsedMessage::Who(_) | ParsedMessage::Me(_)) && version >= PROOFS { + let mut payload = encode(message)?; + payload[0] = version; + return Ok(payload); + } + // Each older version this build still speaks is encoded here, from its own types, + // once its messages differ from the newest's; this build's are the newest's alone. + if version != VERSION && !matches!(message, ParsedMessage::Speaks(_)) { + return Err(WireError::Version(version)); + } + encode(message) +} + +/// The payload of `message`, in the newest wire version. pub(crate) fn encode(message: &ParsedMessage) -> Result<Vec<u8>, WireError> { if let ParsedMessage::Speaks(speaks) = message { let mut payload = vec![SPEAKS, speaks.oldest, speaks.newest]; @@ -134,16 +179,33 @@ pub(crate) fn encode(message: &ParsedMessage) -> Result<Vec<u8>, WireError> { /// (`OtherVersions`). const MAX_OTHER_VERSIONS: usize = 1024; -/// Senders whose messages are of another wire version (`WireError::Version`): each -/// logged once, at warn level, so two builds that don't speak to each other say so, and -/// which of them to upgrade, instead of silently retrying their HELLOs for good. Bounded: -/// anyone can send us anything. +/// Senders whose messages are of another wire version (`WireError::Version`), or whose +/// SPEAKS names none this build speaks: each logged once, at warn level, so two builds +/// that don't speak to each other say so, and which of them to upgrade, instead of +/// silently retrying their HELLOs for good. Bounded: anyone can send us anything. #[derive(Default)] pub(crate) struct OtherVersions(std::sync::Mutex<std::collections::HashSet<String>>); impl OtherVersions { /// A message from `sender` (on the transport `scheme`) was of `version`. pub(crate) fn note(&self, scheme: &'static str, sender: &str, version: u8) { + self.warn( + &super::Addressed(scheme, sender).to_string(), + version, + version, + ); + } + + /// A SPEAKS from `address` (as paths keep it) said its build speaks wire versions + /// `oldest` to `newest`: logged where this build speaks none of them, as a message of + /// another version is. The proofs between the two still go (`PROOFS`), nothing else. + pub(crate) fn speaks(&self, address: &str, oldest: u8, newest: u8) { + if choose(oldest, newest).is_none() { + self.warn(address, oldest, newest); + } + } + + fn warn(&self, from: &str, oldest: u8, newest: u8) { let mut known = self .0 .lock() @@ -151,36 +213,41 @@ impl OtherVersions { if known.len() >= MAX_OTHER_VERSIONS { known.clear(); } - if known.insert(sender.to_owned()) { + if known.insert(from.to_owned()) { tracing::warn!( - from = %super::Addressed(scheme, &sender), - version, + from = %from, + version = newest, oldest = OLDEST, newest = VERSION, "Peer speaks another wire version: {}; ignoring its messages", - other_build(version) + other_build(oldest, newest) ); } } } -/// Of a peer whose messages are of wire `version`, which this build doesn't speak, what -/// an operator does: upgrade this node where the peer's build is newer, the peer's where -/// it is older. -fn other_build(version: u8) -> String { - let ours = if OLDEST == VERSION { - VERSION.to_string() - } else { - format!("{OLDEST} to {VERSION}") +/// Of a peer speaking wire versions `oldest` to `newest`, none of which this build +/// speaks, what an operator does: upgrade this node where the peer's build is newer, the +/// peer's where it is older. +fn other_build(oldest: u8, newest: u8) -> String { + let versions = |oldest: u8, newest: u8| { + if oldest == newest { + format!("{oldest}") + } else { + format!("{oldest} to {newest}") + } }; - if version > VERSION { + let (theirs, ours) = (versions(oldest, newest), versions(OLDEST, VERSION)); + let plural = if oldest == newest { "" } else { "s" }; + if oldest > VERSION { format!( - "a newer build (wire version {version}; this one speaks {ours}): upgrade this node \ - to talk with it" + "a newer build (wire version{plural} {theirs}; this one speaks {ours}): upgrade this \ + node to talk with it" ) } else { format!( - "an older build (wire version {version}; this one speaks {ours}): upgrade that node" + "an older build (wire version{plural} {theirs}; this one speaks {ours}): upgrade that \ + node" ) } } @@ -197,11 +264,14 @@ pub(crate) fn decode(payload: &[u8]) -> Result<ParsedMessage, WireError> { revision: rest.get(..32).map(|id| id.try_into().expect("32 bytes")), })); } - if !(OLDEST..=VERSION).contains(&version) { - return Err(WireError::Version(version)); - } let (&kind, body) = payload.split_first().ok_or(WireError::Empty)?; let is = |wanted: MessageKind| kind == tag(wanted); + let proof = version >= PROOFS && (is(MessageKind::Who) || is(MessageKind::Me)); + // Each older version this build still speaks is decoded here, into its own types, + // once its messages differ from the newest's; this build's are the newest's alone. + if !(OLDEST..=VERSION).contains(&version) && !proof { + return Err(WireError::Version(version)); + } Ok(if is(MessageKind::Hello) { ParsedMessage::Hello(rmp_serde::from_slice(body)?) } else if is(MessageKind::HelloReply) { @@ -639,18 +709,76 @@ mod tests { assert!(other.0.lock().unwrap().len() <= MAX_OTHER_VERSIONS); } + /// A peer is written to in the newest version both speak, a version this build doesn't + /// speak never; in the newest one alone, while that is all it speaks. + #[test] + fn the_newest_version_both_speak_is_written() { + assert_eq!(choose(OLDEST, VERSION), Some(VERSION)); + assert_eq!(choose(1, VERSION + 5), Some(VERSION)); + assert_eq!(choose(OLDEST - 2, OLDEST - 1), None); + assert_eq!(choose(VERSION + 1, VERSION + 2), None); + let ping = ParsedMessage::Ping(7); + assert_eq!(encode_in(&ping, VERSION).unwrap(), encode(&ping).unwrap()); + assert!(encode_in(&ping, VERSION + 1).is_err()); + assert!(encoded_in("p", &ping, VERSION).is_ok()); + } + + /// WHO and ME are laid out alike in every version, as in the first with SPEAKS, and + /// read in any version from it on, older or newer than this build's: two builds prove + /// themselves to each other before either knows what the other speaks. These bytes + /// never change. + #[test] + fn proofs_are_read_in_every_version() { + let proof = IdentityProof { + key: [8; 32], + signature: [9; 64], + }; + let who = ParsedMessage::Who(proof.clone()); + let fields = format!("92c420{}c440{}", "08".repeat(32), "09".repeat(64)); + assert_eq!( + hex(&encode_in(&who, PROOFS).unwrap()), + format!("3406{fields}") + ); + let me = ParsedMessage::Me(proof); + assert_eq!( + hex(&encode_in(&me, PROOFS).unwrap()), + format!("3407{fields}") + ); + for version in [PROOFS, OLDEST, VERSION, VERSION + 1, u8::MAX] { + let who = encode_in(&who, version).unwrap(); + assert_eq!(who[0], version); + assert!( + matches!(decode(&who), Ok(ParsedMessage::Who(_))), + "{version}" + ); + let me = encode_in(&me, version).unwrap(); + assert!(matches!(decode(&me), Ok(ParsedMessage::Me(_))), "{version}"); + } + let mut before = encode(&who).unwrap(); + before[0] = PROOFS - 1; + assert!(matches!(decode(&before), Err(WireError::Version(_)))); + let mut ping = encode(&ParsedMessage::Ping(7)).unwrap(); + ping[0] = VERSION + 1; + assert!(matches!(decode(&ping), Err(WireError::Version(_)))); + } + /// The warning says which build is the older, the one to upgrade, and both versions. #[test] fn the_older_build_is_named() { - let newer = other_build(VERSION + 1); + let newer = other_build(VERSION + 1, VERSION + 1); assert!(newer.contains("upgrade this node"), "{newer}"); assert!( newer.contains(&format!("wire version {}", VERSION + 1)), "{newer}" ); assert!(newer.contains(&format!("speaks {VERSION}")), "{newer}"); - let older = other_build(OLDEST - 1); + let older = other_build(OLDEST - 1, OLDEST - 1); assert!(older.contains("upgrade that node"), "{older}"); + let newer = other_build(VERSION + 1, VERSION + 3); + assert!( + newer.contains(&format!("wire versions {} to {}", VERSION + 1, VERSION + 3)), + "{newer}" + ); } /// Every kind decodes to what was encoded: re-encoded, the same bytes. |
