aboutsummaryrefslogtreecommitdiffstats
path: root/src/transport/wire.rs
diff options
context:
space:
mode:
Diffstat (limited to 'src/transport/wire.rs')
-rw-r--r--src/transport/wire.rs206
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.