diff options
| author | tv <tv@krebsco.de> | 2026-11-19 16:13:53 +0000 |
|---|---|---|
| committer | tv <tv@krebsco.de> | 2026-11-19 17:35:42 +0100 |
| commit | 866c6a402e65f9102e63cebdf5a50c0a3f526260 (patch) | |
| tree | 8e3051bdebb3f136dee5bbcda1ad6de723b2f171 | |
| parent | 180e5ad1d1d144f5e9f9168094a0ec0417b64a61 (diff) | |
wire: a peer on another version is named older or newer, with what to upgrade
A node meeting messages of a wire version it doesn't speak logged
`Peer speaks another wire version (another build)`, with the versions
as fields only. It says now, in the message, which build is the newer
and which node to upgrade: this one, where the peer's is newer
(`upgrade this node to talk with it`), else the peer's
(`upgrade that node`), with the peer's version and the ones this build
speaks. Its fields are the peer's version and the oldest and newest this
build speaks.
| -rw-r--r-- | CHANGELOG.md | 4 | ||||
| -rw-r--r-- | docs/operations.md | 17 | ||||
| -rw-r--r-- | src/transport/wire.rs | 47 |
3 files changed, 55 insertions, 13 deletions
diff --git a/CHANGELOG.md b/CHANGELOG.md index ffc0c13..37d1015 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,6 +7,10 @@ it from the release before ([`docs/operations.md`](docs/operations.md), ## Unreleased +* A node meeting a peer on another wire version names both versions in its warning, and + which node to upgrade ([`docs/operations.md`](docs/operations.md), + [Upgrading](docs/operations.md#upgrading); [`src/transport/wire.rs`](src/transport/wire.rs)). + ## 0.0.1 (2026-11-19) The first release to keep this log; a flag day from anything before it. What it holds: diff --git a/docs/operations.md b/docs/operations.md index efc6b04..d100a49 100644 --- a/docs/operations.md +++ b/docs/operations.md @@ -128,13 +128,15 @@ A node upgrades by restarting with its files. What to know: * **The wire format.** Each change to it bumps a version byte, and nodes ignore messages of another version. Across such a change, upgraded nodes and the others don't talk: the swarm is split until every node is upgraded, both sides go on - writing, and they merge then. Each logs it (`Peer speaks another wire version - (another build); ignoring its messages`, warn, once per peer). With each handshake, a + writing, and they merge then. Each logs it, at warn, once per peer, naming both + versions and the node to upgrade (`Peer speaks another wire version: a newer build + (wire version 53; this one speaks 52): upgrade this node to talk with it; ignoring its + messages`, or of an older build, `upgrade that node`). With each handshake, a node says which versions it speaks, and the newest revision of the federation it knows (SPEAKS, outside the versions; [`peers.md`](peers.md), - [Handshake and join](peers.md#handshake-and-join)); a build from before SPEAKS logs it - as that warning, `version=0`, once of the peer, and reads the peer's other messages - where they are of its version. + [Handshake and join](peers.md#handshake-and-join)); a build from before SPEAKS, before + 0.0.1, logs it as another wire version, `version=0`, once of the peer, and reads the + peer's other messages where they are of its version. A node speaks one version, so every change of the format is a major release; before 1.0.0, take every upgrade as one, and upgrade all nodes close together. * **Automerge.** A remake needs every node to build the same snapshot, byte for byte, @@ -280,9 +282,8 @@ And from the log, at warn or error: * `Couldn't write the state file`, `Couldn't rewrite the document file`: a full or read-only disk; * `The … file is readable by others than its owner; chmod 600 it`; -* `Peer speaks another wire version (another build); ignoring its messages`: a node on - another build; with `version=0`, only a newer build's SPEAKS, which this build doesn't - read. +* `Peer speaks another wire version: …; ignoring its messages`: a node on another + build; the message names both versions, and whether to upgrade this node or that one. ## What a node uses diff --git a/src/transport/wire.rs b/src/transport/wire.rs index abaa408..0b661dd 100644 --- a/src/transport/wire.rs +++ b/src/transport/wire.rs @@ -135,9 +135,9 @@ pub(crate) fn encode(message: &ParsedMessage) -> Result<Vec<u8>, WireError> { 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, -/// instead of silently retrying their HELLOs for good. Bounded: anyone can send us -/// anything. +/// 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>>); @@ -155,13 +155,36 @@ impl OtherVersions { tracing::warn!( from = %super::Addressed(scheme, &sender), version, - ours = VERSION, - "Peer speaks another wire version (another build); ignoring its messages" + oldest = OLDEST, + newest = VERSION, + "Peer speaks another wire version: {}; ignoring its messages", + other_build(version) ); } } } +/// 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}") + }; + if version > VERSION { + format!( + "a newer build (wire version {version}; 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" + ) + } +} + pub(crate) fn decode(payload: &[u8]) -> Result<ParsedMessage, WireError> { let (&version, payload) = payload.split_first().ok_or(WireError::Empty)?; if version == SPEAKS { @@ -616,6 +639,20 @@ mod tests { assert!(other.0.lock().unwrap().len() <= MAX_OTHER_VERSIONS); } + /// 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); + 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); + assert!(older.contains("upgrade that node"), "{older}"); + } + /// Every kind decodes to what was encoded: re-encoded, the same bytes. #[test] fn every_kind_round_trips() { |
