diff --git a/Cargo.lock b/Cargo.lock index 9657b52..a177314 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -4594,7 +4594,7 @@ checksum = "35fb2e5f958ec131621fdd531e9fc186ed768cbe395337403ae56c17a74c68ec" [[package]] name = "peerspeak" -version = "0.1.0" +version = "0.2.0" dependencies = [ "anyhow", "async-trait", diff --git a/Cargo.toml b/Cargo.toml index 1967184..739b7fe 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -1,6 +1,6 @@ [package] name = "peerspeak" -version = "0.1.0" +version = "0.2.0" edition = "2024" [lib] diff --git a/VERSIONING.md b/VERSIONING.md new file mode 100644 index 0000000..a28eb56 --- /dev/null +++ b/VERSIONING.md @@ -0,0 +1,139 @@ +# PeerSpeak Versioning Standard + +PeerSpeak is a full-mesh P2P voice app. Its "API contract" is not a library +surface — it is the **wire protocol** two nodes use to talk. So versioning here +tracks one question above all others: + +> **Can a node on build X talk to a node on build Y?** + +There are two distinct version layers. Keep them straight. + +--- + +## Layer 1 — Release version (`Cargo.toml`) + +The human-facing label you put on a build ("install this one"). + +**Scheme: SemVer, pre-1.0 (`0.MINOR.PATCH`).** + +While we are pre-1.0 (friends-only, no stability promise yet): + +| Change | Bump | Example | +| --- | --- | --- | +| **Breaking wire/protocol change** — peers on the old build can no longer interoperate; *everyone must update* | **MINOR** | `0.4.2 → 0.5.0` | +| Compatible change — bug fix, internal refactor, or a feature that does **not** change the wire (UI, local-only behavior, additive logic that old peers ignore safely) | **PATCH** | `0.4.2 → 0.4.3` | + +- **Reaching `1.0.0`:** when PeerSpeak is first shared beyond the trusted-friends + circle (a "public" release), and we are willing to commit to wire stability. + After 1.0, MAJOR = wire break, MINOR = compatible feature, PATCH = fix (normal + SemVer). +- Bump `version` in `Cargo.toml` as part of the change that warrants it, in the + same commit. The number in `Cargo.toml` is the source of truth; surface it in + the UI (e.g. an About/Settings line) so a user can read their build. + +**Rule of thumb:** if you find yourself writing "all peers must rebuild" or +"breaking gossip wire change" in a commit message (as S2 and W4 did), that is a +**MINOR** bump, and it must also bump the relevant protocol version in Layer 2. + +--- + +## Layer 2 — Protocol compatibility (the one that actually breaks calls) + +Wire incompatibility must **fail fast and legibly** — never as a silent +signature/decode error that looks like a bug or an attack. We achieve this by +embedding a protocol version into each transport plane, so incompatible peers +are rejected at connect/subscribe time instead of mid-conversation. + +PeerSpeak has **three independent planes**, each versioned **separately** — bump +only the plane whose wire format actually changed (audio rarely changes; gossip +changes often; they must not be forced to bump together). + +### ALPN naming convention + +All peerspeak ALPNs use the form **`peerspeak//`** where `` is that +plane's protocol version (an integer, starts at `1`). iroh refuses a connection +whose ALPN does not match exactly, so two peers on different `` for a plane +simply cannot open that connection → we map that to a clean "peer is running an +incompatible version" instead of garbage. + +| Plane | ALPN / mechanism | Bump when… | +| --- | --- | --- | +| **Audio** | ALPN `peerspeak/audio/` | the Opus/datagram framing, sequencing, or audio-handshake changes | +| **Friends/presence** | ALPN `peerspeak/friends/` | the `ControlMsg` / presence ping-pong shape changes | +| **Gossip** | *(see below — cannot use a custom ALPN)* | `GossipPayload` / `GossipMessage` / `PeerState` shape, signing, or freshness rules change | + +### Gossip is special + +The gossip plane runs over **iroh-gossip's own `GOSSIP_ALPN`**, which we do not +control, so we cannot version it via the ALPN. Instead, the gossip protocol +version is bound in **two** places: + +1. **Topic namespacing (primary, fail-fast):** the room's `topic_id` is a random + 32 bytes carried in the ticket, but the topic we actually *subscribe* to is + `protocol::versioned_topic(topic_id)` — a deterministic, dependency-free + transform that folds `GOSSIP_PROTO` into the bytes. Peers on different gossip + versions therefore derive **different subscription topics from the same ticket** + and never share a swarm — the same isolation a versioned ALPN gives the other + planes. The ticket format and the room identity (`topic_id`) are unchanged; only + the subscribed topic is namespaced. (The transform is for *isolation*, not + security — cryptographic separation is the signature domain below.) +2. **Signature domain (cryptographic separation):** the signing domain string + (`peerspeak-gossip-v`, bound into every signed payload) carries the version, + so two versions that somehow met on a topic would fail each other's verification + rather than misread it. + +Bumping the gossip version = bump `protocol::GOSSIP_PROTO` (drives +`versioned_topic`) **and** `protocol::GOSSIP_SIG_DOMAIN` together (a unit test in +`protocol.rs` asserts the domain string matches `GOSSIP_PROTO`, so they can't drift). + +### Single source of truth for protocol versions + +All protocol versions, ALPNs, the gossip signature domain, and `versioned_topic` +live in **`src/protocol.rs`**. Every call site derives from there (e.g. +`crate::protocol::AUDIO_ALPN`); **never hand-write an ALPN literal inline.** A +unit test asserts each ALPN/domain string matches its integer version so a bump +can't half-apply. + +--- + +## "I changed X — what do I bump?" (quick reference) + +| You changed… | Layer 2 (plane version) | Layer 1 (`Cargo.toml`) | +| --- | --- | --- | +| Opus framing / audio datagram layout | `peerspeak/audio/N` → `N+1` | MINOR | +| `ControlMsg` / presence shape | `peerspeak/friends/N` → `N+1` | MINOR | +| `GossipPayload`/`PeerState`/signing | `GOSSIP_PROTO_VERSION` + sig domain → next | MINOR | +| UI, local config, recording, a fix that doesn't touch any wire | nothing | PATCH | +| An *additive* gossip field that old peers safely ignore | judgement call — if old peers misbehave without it, treat as breaking (MINOR + gossip bump); if truly ignorable, PATCH | PATCH or MINOR | + +When in doubt about "is this additive-safe?", assume **breaking** and bump. A +false MINOR bump costs a coordinated rebuild; a false PATCH costs silent broken +calls in the field. + +--- + +## Release checklist (per build handed to anyone) + +1. Decide MINOR vs PATCH from the table above; bump `Cargo.toml`. +2. If MINOR for a wire reason, confirm the matching Layer-2 plane version(s) were + bumped in the same change. +3. Note the version + "breaking?" in the commit / handoff. +4. Tag the commit (`v0.x.y`) so a given binary maps to a known commit. +5. Rebuild **every** peer that must interoperate (e.g. dopedart, staged friend + releases) when the bump was a MINOR/wire break. + +--- + +## Current baseline (standard adopted + migrated, 2026-06-18, `0.2.0`) + +- `Cargo.toml`: **`0.2.0`** — the MINOR bump for the (deliberately breaking) + migration to this standard. **All peers must run ≥ `0.2.0` to interoperate** + (the ALPNs and gossip topics changed); the pre-standard `0.1.0`-era build + (e.g. an un-resynced dopedart) cannot talk to a `0.2.0` peer — by design, and it + now fails cleanly at the handshake instead of silently. +- Protocol versions (all at `1`): `peerspeak/audio/1`, `peerspeak/friends/1`, + gossip `peerspeak-gossip-v1` + `versioned_topic`. All sourced from + `src/protocol.rs`. +- **Remaining nicety (not blocking):** surface `env!("CARGO_PKG_VERSION")` in the + UI (an About/Settings line) and/or log it at startup, so a running build is + self-identifying in the field. Small follow-up. diff --git a/src/core/mod.rs b/src/core/mod.rs index c2029ba..2a6b58d 100644 --- a/src/core/mod.rs +++ b/src/core/mod.rs @@ -584,7 +584,7 @@ async fn build_net_stack( // report) is injected via `friends_handler`. let router = Router::builder(endpoint.clone()) .accept(iroh_gossip::net::GOSSIP_ALPN, gossip.clone()) - .accept(b"peerspeak-audio", audio_router.clone()) + .accept(crate::protocol::AUDIO_ALPN, audio_router.clone()) .accept( crate::presence_net::FRIENDS_ALPN, crate::presence_net::FriendsProtocol::new(friends_handler), diff --git a/src/lib.rs b/src/lib.rs index 64474ec..e6369ed 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -2,6 +2,7 @@ pub mod audio; pub mod codec; pub mod dsp; pub mod network; +pub mod protocol; pub mod core; pub mod app; pub mod config; diff --git a/src/network/gossip.rs b/src/network/gossip.rs index 6811970..23f0e8a 100644 --- a/src/network/gossip.rs +++ b/src/network/gossip.rs @@ -12,7 +12,7 @@ use serde::{Serialize, Deserialize}; /// Domain-separation tag mixed into every signed gossip payload so a signature /// can never be lifted out of this protocol/version into another context. -const GOSSIP_SIG_DOMAIN: &str = "peerspeak-gossip-v1"; +use crate::protocol::GOSSIP_SIG_DOMAIN; /// How far a payload's sender-stamped timestamp may differ from local time /// before it's rejected as stale (replayed) or implausibly future. Bounds the @@ -248,7 +248,11 @@ impl RoomState for IrohGossipState { crate::redact_for_log(ticket_str) )); let ticket = ticket_str.parse::()?; - let topic_id = TopicId::from_bytes(ticket.topic_id); + // Version-namespace the subscribed topic (VERSIONING.md): peers on a + // different gossip protocol version derive a different topic from the same + // ticket and never share a swarm. The raw ticket.topic_id stays the room + // identity (and what signatures bind, below). + let topic_id = TopicId::from_bytes(crate::protocol::versioned_topic(ticket.topic_id)); crate::log_msg(&format!( "Parsed ticket. host_id={}, host_addrs={}, topic={}", diff --git a/src/network/iroh_impl.rs b/src/network/iroh_impl.rs index 2267207..80dc871 100644 --- a/src/network/iroh_impl.rs +++ b/src/network/iroh_impl.rs @@ -9,7 +9,7 @@ use std::collections::{HashMap, HashSet}; use std::time::Duration; use async_trait::async_trait; -const AUDIO_ALPN: &[u8] = b"peerspeak-audio"; +use crate::protocol::AUDIO_ALPN; /// Per-peer datagram send queue depth. Audio is real-time, so a backlog is /// useless latency — keep it shallow and drop the oldest frame when full. diff --git a/src/presence_net.rs b/src/presence_net.rs index c30f8d8..72160de 100644 --- a/src/presence_net.rs +++ b/src/presence_net.rs @@ -31,7 +31,7 @@ use std::time::Duration; /// ALPN for the friends presence/control plane. Separate from the audio/gossip /// ALPNs so a control dial never lands on a bare room endpoint and vice versa. -pub const FRIENDS_ALPN: &[u8] = b"peerspeak/friends/0"; +pub const FRIENDS_ALPN: &[u8] = crate::protocol::FRIENDS_ALPN; /// Upper bound on a single control message — generous for a Pong carrying a /// member ticket (~300 chars), but rejects a peer trying to make us buffer a diff --git a/src/protocol.rs b/src/protocol.rs new file mode 100644 index 0000000..c229de1 --- /dev/null +++ b/src/protocol.rs @@ -0,0 +1,82 @@ +//! Single source of truth for PeerSpeak's on-wire protocol versions and the +//! per-plane ALPNs / gossip constants derived from them. +//! +//! See `VERSIONING.md`. The rule: each transport plane is versioned independently +//! (audio rarely changes, gossip changes often), and incompatible peers must fail +//! fast — never as a silent decode/signature error. iroh refuses a mismatched +//! ALPN at the QUIC handshake, so the audio/friends planes are self-isolating; +//! gossip can't use a custom ALPN (it rides iroh-gossip's `GOSSIP_ALPN`), so its +//! version is bound into the subscribed topic ([`versioned_topic`]) and the +//! signature domain ([`GOSSIP_SIG_DOMAIN`]). +//! +//! **Never hand-write an ALPN literal elsewhere — derive it here.** Bumping a +//! plane's protocol version is a breaking wire change → also bump `Cargo.toml` +//! MINOR (see `VERSIONING.md`). + +/// Audio datagram plane version (Opus framing / sequencing). Bump on any audio +/// wire change. Mirrored in [`AUDIO_ALPN`]. +pub const AUDIO_PROTO: u32 = 1; +/// Friends/presence plane version (`ControlMsg` ping-pong shape). Bump on any +/// change. Mirrored in [`FRIENDS_ALPN`]. +pub const FRIENDS_PROTO: u32 = 1; +/// Gossip plane version (`GossipPayload`/`GossipMessage`/`PeerState`, signing, +/// freshness). Bump on any change. Mirrored in [`GOSSIP_SIG_DOMAIN`] and folded +/// into [`versioned_topic`]. +pub const GOSSIP_PROTO: u32 = 1; + +/// ALPN for the audio datagram plane: `peerspeak/audio/`. +pub const AUDIO_ALPN: &[u8] = b"peerspeak/audio/1"; +/// ALPN for the friends/presence plane: `peerspeak/friends/`. +pub const FRIENDS_ALPN: &[u8] = b"peerspeak/friends/1"; +/// ed25519 gossip signature domain: `peerspeak-gossip-v`. Carries +/// the gossip protocol version into every signed payload — a version mismatch +/// fails verification (cryptographic separation between gossip versions). +pub const GOSSIP_SIG_DOMAIN: &str = "peerspeak-gossip-v1"; + +/// Version-namespace a room topic so peers on different gossip protocol versions +/// derive **different subscription topics from the same ticket** and therefore +/// never share a swarm — the gossip analog of a versioned ALPN. The room's raw +/// `topic_id` (random 32 bytes, carried in the ticket) is the room identity and +/// is unchanged; only the *subscribed* topic is namespaced. +/// +/// Deterministic and dependency-free; bijective for a fixed version, so distinct +/// rooms stay distinct after namespacing. This transform is for *isolation*, not +/// security — cryptographic separation between versions comes from +/// [`GOSSIP_SIG_DOMAIN`]. +pub fn versioned_topic(topic_id: [u8; 32]) -> [u8; 32] { + let v = GOSSIP_PROTO.to_le_bytes(); + let mut out = topic_id; + for (i, b) in out.iter_mut().enumerate() { + *b ^= v[i % v.len()]; + } + out +} + +#[cfg(test)] +mod tests { + use super::*; + + /// The ALPN/domain strings must stay in lock-step with the integer versions + /// so a version bump can't silently forget to update the wire string. + #[test] + fn alpns_match_their_proto_versions() { + assert_eq!(AUDIO_ALPN, format!("peerspeak/audio/{AUDIO_PROTO}").as_bytes()); + assert_eq!(FRIENDS_ALPN, format!("peerspeak/friends/{FRIENDS_PROTO}").as_bytes()); + assert_eq!(GOSSIP_SIG_DOMAIN, format!("peerspeak-gossip-v{GOSSIP_PROTO}")); + } + + #[test] + fn versioned_topic_is_deterministic_and_room_distinct() { + let a = [9u8; 32]; + let mut b = a; + b[5] = 10; + assert_eq!(versioned_topic(a), versioned_topic(a), "deterministic"); + assert_ne!(versioned_topic(a), versioned_topic(b), "distinct rooms stay distinct"); + } + + #[test] + fn versioned_topic_actually_namespaces_for_current_version() { + // Guards against a no-op transform: GOSSIP_PROTO=1 must change the topic. + assert_ne!(versioned_topic([0u8; 32]), [0u8; 32]); + } +}