aboutsummaryrefslogtreecommitdiffstats
path: root/src/transport
diff options
context:
space:
mode:
authortv <tv@krebsco.de>2026-11-19 13:33:51 +0000
committertv <tv@krebsco.de>2026-11-19 14:39:52 +0100
commit7a5aeb02024ddff71ba60f40913555cd21a633ad (patch)
treed3d0f1bafd3d39dab02c89a902162c829d6c79f7 /src/transport
parent03105d40322dff9c18f0571872ab0f643aded0f7 (diff)
transport: SPEAKS, which wire versions a node speaks and what it knows
Before each HELLO and each HELLO_REPLY, a node sends SPEAKS: the oldest and the newest wire version it speaks, and the ID of the newest revision of the federation it knows. It stands outside the wire versions, its first byte 0, which no version is, laid out as no build changes: that byte, the oldest, the newest, then 32 bytes of the revision's ID where there is one; a reader takes those and leaves whatever follows, which a later build may add. So a peer on another build reads it too, and nodes on different builds can say what they run, which a rollout needs. A build from before it takes it for a message of another wire version and logs that once of the peer (version=0), reading the rest of the peer's messages as before: SPEAKS rolls out node by node, with no change of VERSION. The node keeps what each peer said last (`swarm::speaking`, at most 4096 peers). It counts as `hello` traffic. `OLDEST`, the oldest version this build reads, is `VERSION` for now: a range for a later build to widen. operations.md also says what is so of the other-version warning now: every transport logs it once per peer at warn, not Mycelium alone.
Diffstat (limited to 'src/transport')
-rw-r--r--src/transport/mod.rs19
-rw-r--r--src/transport/traffic.rs6
-rw-r--r--src/transport/wire.rs71
3 files changed, 92 insertions, 4 deletions
diff --git a/src/transport/mod.rs b/src/transport/mod.rs
index ad45ce9..7bc6ae0 100644
--- a/src/transport/mod.rs
+++ b/src/transport/mod.rs
@@ -254,6 +254,20 @@ pub(crate) enum ParsedMessage {
Disconnect(NeighbourAnswer),
/// Changes the sender refused, of those the recipient brought (`swarm::refusals`).
Refusals(RefusalsMessage),
+ /// What the sender's build speaks and knows, in a layout no build changes
+ /// (`wire::SPEAKS`, `swarm::speaking`).
+ Speaks(Speaks),
+}
+
+/// SPEAKS: the wire versions the sender speaks, the oldest and the newest, and the
+/// newest revision of the federation it knows, by ID, where it is built with the
+/// federation. Sent with every handshake, in a layout no build changes (`wire::SPEAKS`):
+/// a build that doesn't know it ignores it, as a message of another wire version.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub(crate) struct Speaks {
+ pub(crate) oldest: u8,
+ pub(crate) newest: u8,
+ pub(crate) revision: Option<[u8; 32]>,
}
/// REFUSALS: changes the sender refused by the swarm's rules (`access::screen`), of
@@ -417,6 +431,7 @@ pub(crate) enum MessageKind {
NeighbourReply,
Disconnect,
Refusals,
+ Speaks,
}
impl ParsedMessage {
@@ -440,6 +455,7 @@ impl ParsedMessage {
ParsedMessage::NeighbourReply(_) => MessageKind::NeighbourReply,
ParsedMessage::Disconnect(_) => MessageKind::Disconnect,
ParsedMessage::Refusals(_) => MessageKind::Refusals,
+ ParsedMessage::Speaks(_) => MessageKind::Speaks,
}
}
@@ -469,7 +485,8 @@ impl ParsedMessage {
ParsedMessage::Who(_)
| ParsedMessage::Me(_)
| ParsedMessage::Ping(_)
- | ParsedMessage::Pong { .. } => None,
+ | ParsedMessage::Pong { .. }
+ | ParsedMessage::Speaks(_) => None,
}
}
}
diff --git a/src/transport/traffic.rs b/src/transport/traffic.rs
index 5ff588e..89217c3 100644
--- a/src/transport/traffic.rs
+++ b/src/transport/traffic.rs
@@ -40,6 +40,7 @@ impl Counter {
#[derive(Debug, Default, Clone, Copy, Serialize)]
#[serde(rename_all = "camelCase")]
pub(crate) struct ByKind {
+ /// HELLO and SPEAKS, which goes with each handshake.
pub(crate) hello: Counter,
pub(crate) hello_reply: Counter,
pub(crate) sync: Counter,
@@ -84,7 +85,7 @@ impl ByKind {
fn get(&self, kind: MessageKind) -> &Counter {
match kind {
- MessageKind::Hello => &self.hello,
+ MessageKind::Hello | MessageKind::Speaks => &self.hello,
MessageKind::HelloReply => &self.hello_reply,
MessageKind::Sync => &self.sync,
MessageKind::Status => &self.status,
@@ -103,7 +104,7 @@ impl ByKind {
fn get_mut(&mut self, kind: MessageKind) -> &mut Counter {
match kind {
- MessageKind::Hello => &mut self.hello,
+ MessageKind::Hello | MessageKind::Speaks => &mut self.hello,
MessageKind::HelloReply => &mut self.hello_reply,
MessageKind::Sync => &mut self.sync,
MessageKind::Status => &mut self.status,
@@ -366,6 +367,7 @@ fn names(kind: MessageKind) -> (&'static str, &'static str) {
MessageKind::NeighbourReply => ("NEIGHBOUR_REPLY", "hyparview"),
MessageKind::Disconnect => ("DISCONNECT", "hyparview"),
MessageKind::Refusals => ("REFUSALS", "refusals"),
+ MessageKind::Speaks => ("SPEAKS", "hello"),
}
}
diff --git a/src/transport/wire.rs b/src/transport/wire.rs
index 0270e6c..abaa408 100644
--- a/src/transport/wire.rs
+++ b/src/transport/wire.rs
@@ -7,6 +7,11 @@
//! 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
//! 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.
use thiserror::Error;
@@ -16,6 +21,19 @@ use super::{EncodedMessage, MessageKind, ParsedMessage};
/// to a message type or a codec (`golden_bytes` fails then).
pub(crate) const VERSION: u8 = 52;
+/// The oldest version this build speaks: the messages of every version from it to
+/// `VERSION` it reads. Its SPEAKS says so.
+pub(crate) const OLDEST: u8 = VERSION;
+
+/// The first byte of a SPEAKS, which no version is. Its layout, never to change: that
+/// byte, the oldest version the sender speaks, the newest, then the 32 bytes of the ID
+/// of the newest revision of the federation it knows, where it knows one. A reader takes
+/// 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);
+
/// What the second byte of a payload says.
fn tag(kind: MessageKind) -> u8 {
match kind {
@@ -37,6 +55,8 @@ fn tag(kind: MessageKind) -> u8 {
MessageKind::NeighbourReply => 17,
MessageKind::Disconnect => 18,
MessageKind::Refusals => 20,
+ // None: a SPEAKS has no second byte (`SPEAKS`).
+ MessageKind::Speaks => u8::MAX,
}
}
@@ -75,6 +95,11 @@ pub(crate) fn encoded(peer: &str, message: &ParsedMessage) -> anyhow::Result<Enc
/// The payload of `message`.
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];
+ payload.extend(speaks.revision.iter().flatten());
+ return Ok(payload);
+ }
let mut payload = vec![VERSION, tag(message.kind())];
match message {
ParsedMessage::Hello(hello) => rmp_serde::encode::write(&mut payload, hello)?,
@@ -99,6 +124,7 @@ pub(crate) fn encode(message: &ParsedMessage) -> Result<Vec<u8>, WireError> {
rmp_serde::encode::write(&mut payload, answer)?
}
ParsedMessage::Refusals(message) => rmp_serde::encode::write(&mut payload, message)?,
+ ParsedMessage::Speaks(_) => unreachable!("encoded above"),
}
Ok(payload)
}
@@ -138,7 +164,17 @@ impl OtherVersions {
pub(crate) fn decode(payload: &[u8]) -> Result<ParsedMessage, WireError> {
let (&version, payload) = payload.split_first().ok_or(WireError::Empty)?;
- if version != VERSION {
+ if version == SPEAKS {
+ let [oldest, newest, rest @ ..] = payload else {
+ return Err(WireError::Empty);
+ };
+ return Ok(ParsedMessage::Speaks(super::Speaks {
+ oldest: *oldest,
+ newest: *newest,
+ 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)?;
@@ -729,6 +765,39 @@ mod tests {
crate::transport::Hex(bytes).to_string()
}
+ /// A SPEAKS is laid out as no build changes: its version byte, the oldest and newest
+ /// version, the revision's ID where there is one; what follows is left.
+ #[test]
+ fn speaks_keeps_its_layout() {
+ let speaks = super::super::Speaks {
+ oldest: 50,
+ newest: 52,
+ revision: Some([7; 32]),
+ };
+ let bytes = encode(&ParsedMessage::Speaks(speaks)).unwrap();
+ assert_eq!(hex(&bytes), format!("003234{}", "07".repeat(32)));
+ let without = super::super::Speaks {
+ revision: None,
+ ..speaks
+ };
+ assert_eq!(
+ hex(&encode(&ParsedMessage::Speaks(without)).unwrap()),
+ "003234"
+ );
+ for (payload, read) in [
+ (bytes.clone(), speaks),
+ ([bytes.as_slice(), b"later"].concat(), speaks),
+ (vec![0, 50, 52], without),
+ (vec![0, 50, 52, 1, 2], without),
+ ] {
+ match decode(&payload) {
+ Ok(ParsedMessage::Speaks(decoded)) => assert_eq!(decoded, read),
+ other => panic!("{other:?}"),
+ }
+ }
+ assert!(decode(&[0, 50]).is_err());
+ }
+
/// The exact bytes of a few messages. If this fails after a change to a message type
/// or a codec, the change is a new wire format: bump `VERSION` and take the new bytes.
#[test]