aboutsummaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
-rw-r--r--CHANGELOG.md4
-rw-r--r--docs/operations.md17
-rw-r--r--src/transport/wire.rs47
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() {