nodedb_types/
wire_version.rs

1// SPDX-License-Identifier: Apache-2.0
2
3//! Single source of truth for the `WIRE_FORMAT_VERSION` constant
4//! shared between every crate that needs to stamp or interpret it.
5//!
6//! This is the *cluster-wide* wire format version, distinct from:
7//! - `nodedb_cluster::wire::WIRE_VERSION` (the binary frame layout
8//!   version of the `VShardEnvelope`),
9//! - the RPC frame header version in
10//!   `nodedb_cluster::rpc_codec::header` (a private constant of that
11//!   module).
12//!
13//! # DO NOT BUMP THIS BEFORE 1.0
14//!
15//! It stays at `1` until the first stable release. Read this before
16//! changing it — the reflex to bump on any wire-shape change is wrong here:
17//!
18//! - **There is nothing to be compatible with.** Pre-1.0 there are no
19//!   deployed clusters, so there is no older peer a new build must talk to.
20//! - **A bump cannot buy a rolling upgrade.** `MIN_WIRE_FORMAT_VERSION ==
21//!   WIRE_FORMAT_VERSION` (floor == ceiling), so a node rejects *any* peer
22//!   whose version differs. Mixed-version clusters cannot form at all, which
23//!   makes every `wire_version >= V` feature gate dead code: inside a cluster
24//!   that exists, all nodes are provably on this exact version. Adding such a
25//!   gate is unreachable-branch hardening, not safety.
26//! - **This value is NOT persisted.** It is stamped on `NodeInfo` for the
27//!   handshake and drives `ClusterVersionView`, nothing more. The version
28//!   written into stored raft-log and metadata entries is
29//!   `nodedb_cluster::wire_version::WireVersion::CURRENT`, which is separate
30//!   and independent. Changing the constant here therefore cannot orphan or
31//!   corrupt anything already on disk.
32//!
33//! So: adding a new enum variant, RPC, or payload field needs NO bump. Every
34//! node in a working cluster runs the same build by construction. Ratcheting
35//! this pre-1.0 only invents a stop-the-world upgrade requirement that does
36//! not otherwise exist, and would leave 1.0 shipping as "wire version 20" for
37//! no reason.
38//!
39//! After 1.0, when real deployments exist and a genuine compatibility window
40//! is introduced, this becomes meaningful — bump it then, deliberately, and
41//! only alongside an actual `MIN_WIRE_FORMAT_VERSION < WIRE_FORMAT_VERSION`
42//! support window.
43
44/// Cluster-wide wire format version. Stamped on every `NodeInfo` and
45/// returned by `nodedb::version::WIRE_FORMAT_VERSION` (a re-export).
46///
47/// WARNING: pinned at 1 until 1.0. See the module docs above before changing.
48pub const WIRE_FORMAT_VERSION: u16 = 1;
49
50/// Minimum wire format version this build can read. Equal to
51/// `WIRE_FORMAT_VERSION`: floor == ceiling, no backward compat window.
52pub const MIN_WIRE_FORMAT_VERSION: u16 = WIRE_FORMAT_VERSION;
53
54// Compile-time invariants — these constants must satisfy:
55//   - MIN_WIRE_FORMAT_VERSION <= WIRE_FORMAT_VERSION
56//   - WIRE_FORMAT_VERSION > 0
57const _: () = assert!(MIN_WIRE_FORMAT_VERSION <= WIRE_FORMAT_VERSION);
58const _: () = assert!(WIRE_FORMAT_VERSION > 0);
nodedb_types/wire_version.rs

nodedb_types/
wire_version.rs
