From 0efbe3607d3b8dac25cecd265e5c1357f9f4d96e Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Tue, 3 Nov 2026 14:25:41 -0800 Subject: [PATCH 1/6] chore(quest): claim quest/m1/stats-epoch-type.md Quest-Claim: 7a573e32b650bb0f From ba7ba5bf621c0e7e76d1bdcf7dd3836b52fd2706 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Tue, 3 Nov 2026 14:28:19 -0800 Subject: [PATCH 2/6] refactor(stats)!: give group counter epochs their own type Separate group counter runs from broadcast instances without changing the JSON string contract. Use instance terminology in routing fixtures and stats node helpers. Co-Authored-By: GPT-6.1 Sol --- quest/m1/README.md | 1 - quest/m1/stats-epoch-type.md | 15 ----- .../integration/routing_contracts/handoff.rs | 2 +- .../integration/routing_contracts/mod.rs | 12 ++-- .../integration/routing_contracts/model.rs | 46 +++++++-------- rs/moq-stats/MIGRATE.md | 8 +++ rs/moq-stats/benches/aggregate.rs | 10 ++-- rs/moq-stats/src/aggregate.rs | 53 +++++++++-------- rs/moq-stats/src/epoch.rs | 59 +++++++++++++++++++ rs/moq-stats/src/lib.rs | 41 +++++++++---- rs/moq-stats/src/produce.rs | 38 ++++++------ 11 files changed, 177 insertions(+), 108 deletions(-) delete mode 100644 quest/m1/stats-epoch-type.md create mode 100644 rs/moq-stats/src/epoch.rs diff --git a/quest/m1/README.md b/quest/m1/README.md index 708a99de4e0..4e30d8782c9 100644 --- a/quest/m1/README.md +++ b/quest/m1/README.md @@ -185,7 +185,6 @@ per-frame CPU growth since #5926. - [Ordered reads can skip owed holes, and snapshot latest() does](/quest/m1/ordered-owed-holes.md) - moq-net's `Ordered` gains a read that skips past an owed hole to the newest buffered group, while keeping the reader's bounds - [A Rust relay never replays from group 0 to a lite-03/04 subscriber](/quest/m1/relay-inflight-replay.md) - A Rust relay or publisher serving a lite-03 or lite-04 SUBSCRIBE from a track copy that is still resolving starts at the newest group once the copy resolves - [The resume model passes its long run again](/quest/m1/resume-model-7542.md) - fix #7542's regression that drops groups a long-budget reader can still get -- [Stats name the route instance's epoch with a type](/quest/m1/stats-epoch-type.md) - `GroupFrame::epoch` gets a dedicated type and tests stop mislabelling the instance ## Related diff --git a/quest/m1/stats-epoch-type.md b/quest/m1/stats-epoch-type.md deleted file mode 100644 index 7852096a039..00000000000 --- a/quest/m1/stats-epoch-type.md +++ /dev/null @@ -1,15 +0,0 @@ -# [XS] Stats name the route instance's epoch with a type - -## Goal - -`moq_stats::GroupFrame::epoch` carries a dedicated type rather than a bare -integer, and the routing contract tests stop labelling the instance's value -`epoch` where they mean the instance, so the public stats API matches the -instance/epoch naming before the cut. - -## Plan - -Planned 2026-11-02 (maintainer, follow-up planning after the 2026-11-02 /quest-complete run), leftovers from [moq-dev/moq#7489](https://github.com/moq-dev/moq/pull/7489) -(routes carry an instance and a per-instance epoch). - -Public API: the `GroupFrame` field's type changes. diff --git a/rs/moq-net/tests/integration/routing_contracts/handoff.rs b/rs/moq-net/tests/integration/routing_contracts/handoff.rs index 2f11a6e8949..aebb1b455b4 100644 --- a/rs/moq-net/tests/integration/routing_contracts/handoff.rs +++ b/rs/moq-net/tests/integration/routing_contracts/handoff.rs @@ -688,7 +688,7 @@ fn only_a_wildcard_claim_overlaps_an_interest_below_it() { net.check().unwrap(); } -/// Two origins hold the same wildcard capability for one epoch, and a client +/// Two origins hold the same wildcard capability for one instance, and a client /// watches a region below it. Withdrawing one origin's wildcard ends only that /// origin's claim. The client's floor for `live/a/` certifies the wildcard above /// it, so a lagging relay's older copy of the withdrawn wildcard is refused diff --git a/rs/moq-net/tests/integration/routing_contracts/mod.rs b/rs/moq-net/tests/integration/routing_contracts/mod.rs index b968dcda11a..b39e9ded6ef 100644 --- a/rs/moq-net/tests/integration/routing_contracts/mod.rs +++ b/rs/moq-net/tests/integration/routing_contracts/mod.rs @@ -434,7 +434,7 @@ fn local_priorities_loop_path_only_requests() { /// The same ring with every relay subscribing at once. Each forwarded request /// joins the subscription its neighbor already opened, and no source feeds the -/// cycle. Joining by path or by epoch deadlocks; joining only a subscription to +/// cycle. Joining by path or by instance deadlocks; joining only a subscription to /// the same identity, or one within the request's bound, does not. #[test] fn aggregation_cycles_starve_without_a_forwarding_constraint() { @@ -445,7 +445,7 @@ fn aggregation_cycles_starve_without_a_forwarding_constraint() { "live/x", &all, Forward::Pinned, - Aggregate::Epoch + Aggregate::Instance ))); for (mode, aggregate) in [ (Forward::Pinned, Aggregate::Identity), @@ -464,7 +464,7 @@ fn aggregation_cycles_starve_without_a_forwarding_constraint() { /// publisher under the requester's announced one, with no Restart. Only a /// request naming the identity keeps the instance the requester announced. #[test] -fn epochless_reselection_splices_another_publisher() { +fn reselection_without_an_instance_splices_another_publisher() { let (edge, core, first, second) = (0, 1, 2, 3); let mut net = Net::new(Config::default(), 4); net.join(edge, core, 1); @@ -526,7 +526,7 @@ fn overlapping_wildcards_loop_where_specific_claims_are_unheard() { } /// A deterministic sweep over small random meshes: priorities, overlapping -/// wildcards, epochs, and claims some nodes have not heard. Pinned and bounded +/// wildcards, instances, and claims some nodes have not heard. Pinned and bounded /// requests never loop or deadlock; path-only requests and the wire-free /// downstream condition do. A pinned request always arrives, while a bounded /// one stalls where a transit hop has not heard the claim. @@ -621,8 +621,8 @@ fn random_mesh(rng: &mut XorShift) -> Net { net.join(origin, rng.next(RELAYS as u64) as usize, 1); net.originate(origin, origin as u64, 0); let prefix = prefixes[rng.next(3) as usize]; - let epoch = if rng.chance(50) { Some(1) } else { None }; - let claim = net.claim(origin as u64, prefix, rng.next(3), epoch); + let instance = if rng.chance(50) { Some(1) } else { None }; + let claim = net.claim(origin as u64, prefix, rng.next(3), instance); for relay in 0..RELAYS { if rng.chance(20) { net.hide(relay, claim); diff --git a/rs/moq-net/tests/integration/routing_contracts/model.rs b/rs/moq-net/tests/integration/routing_contracts/model.rs index 4a1cca63da1..18af0b52ca9 100644 --- a/rs/moq-net/tests/integration/routing_contracts/model.rs +++ b/rs/moq-net/tests/integration/routing_contracts/model.rs @@ -12,7 +12,7 @@ //! order on each directed session and can be held to replay them late. //! //! Claims come in two forms. The forwarding fixtures use global claims (an -//! identity serving a prefix, at a seed cost and optional epoch) known +//! identity serving a prefix, at a seed cost and optional instance) known //! everywhere unless a fixture hides one from a node, which stands in for //! scoping, interest, or a claim that has not arrived yet. The handoff fixtures //! use announcements instead: an origin versions its own claims, and they travel @@ -290,7 +290,7 @@ struct Pending { #[derive(Clone, Copy, Debug, PartialEq, Eq)] pub struct Item { pub seed: Metric, - pub epoch: Option, + pub instance: Option, pub since: Rev, } @@ -437,7 +437,7 @@ impl View { fn a_suffix_costs_the_same_however_its_interest_is_spelled() { let item = Item { seed: 0, - epoch: None, + instance: None, since: 1, }; let view = View { @@ -592,7 +592,7 @@ pub struct Claim { /// A trailing `/` claims the subtree; otherwise only the exact path. pub prefix: &'static str, pub seed: Metric, - pub epoch: Option, + pub instance: Option, } impl Claim { @@ -621,7 +621,7 @@ pub enum Forward { struct Carried { pinned: Option, bound: Option, - epoch: Option, + instance: Option, } #[derive(Clone, Debug, PartialEq, Eq)] @@ -636,8 +636,8 @@ pub enum Outcome { pub enum Aggregate { /// Any subscription for the path, as today. Path, - /// One serving the same explicit epoch. - Epoch, + /// One serving the same explicit instance. + Instance, /// One following a route to the same identity. Identity, /// One whose total is within the request's bound. @@ -654,7 +654,7 @@ struct Candidate { draining: bool, priority: i8, prefix: usize, - epoch: Option, + instance: Option, down_only: bool, } @@ -670,7 +670,7 @@ enum Up { struct Front { node: Node, id: Id, - epoch: Option, + instance: Option, total: Metric, /// Whether the route it follows is down-only. down_only: bool, @@ -903,7 +903,7 @@ impl Net { let claims = state.views.remove(&old).map(|view| view.items).unwrap_or_default(); self.originate(node, fnv("rotate", &[old]) & !QUALIFIED, 0); for (claim, item) in claims { - self.change(node, claim, Some((item.seed, item.epoch))); + self.change(node, claim, Some((item.seed, item.instance))); } for peer in peers { self.connect(node, peer); @@ -934,8 +934,8 @@ impl Net { } /// The origin at `node` starts or updates a claim, advancing its revision. - pub fn announce(&mut self, node: Node, claim: &'static str, seed: Metric, epoch: Option) { - self.change(node, claim, Some((seed, epoch))); + pub fn announce(&mut self, node: Node, claim: &'static str, seed: Metric, instance: Option) { + self.change(node, claim, Some((seed, instance))); } /// The origin at `node` withdraws a claim, advancing its revision. @@ -952,9 +952,9 @@ impl Net { return self.change(node, claim, attrs); } view.floors.insert("", rev); - let item = attrs.map(|(seed, epoch)| Item { + let item = attrs.map(|(seed, instance)| Item { seed, - epoch, + instance, since: view.items.get(claim).map_or(rev, |item| item.since), }); match item { @@ -1041,12 +1041,12 @@ impl Net { self.nodes[node].fd.remove(&id); } - pub fn claim(&mut self, id: Id, prefix: &'static str, seed: Metric, epoch: Option) -> usize { + pub fn claim(&mut self, id: Id, prefix: &'static str, seed: Metric, instance: Option) -> usize { self.claims.push(Claim { id, prefix, seed, - epoch, + instance, }); self.claims.len() - 1 } @@ -2053,7 +2053,7 @@ impl Net { draining: route.next.is_some_and(|next| self.draining.contains(&(node, next))), priority: route.next.map_or(0, |next| self.side(node, next).priority), prefix: claim.prefix.len(), - epoch: claim.epoch, + instance: claim.instance, down_only: route.down_only, }); } @@ -2077,7 +2077,7 @@ impl Net { }; ( Reverse(c.prefix), - Reverse(c.epoch), + Reverse(c.instance), c.draining, Reverse(c.priority), c.total, @@ -2099,7 +2099,7 @@ impl Net { draining: false, priority: 0, prefix: 0, - epoch: carried.epoch, + instance: carried.instance, down_only: route.down_only, }); } @@ -2135,7 +2135,7 @@ impl Net { Carried { pinned: (mode == Forward::Pinned).then_some(chosen.id), bound: (mode == Forward::Bounded).then_some(chosen.advertised + chosen.seed), - epoch: chosen.epoch, + instance: chosen.instance, } } else { carried @@ -2190,7 +2190,7 @@ impl Net { None => Front { node, id: 0, - epoch: None, + instance: None, total: 0, down_only: false, up: Up::Stalled, @@ -2198,7 +2198,7 @@ impl Net { Some(chosen) => Front { node, id: chosen.id, - epoch: chosen.epoch, + instance: chosen.instance, total: chosen.total, down_only: chosen.down_only, up: match chosen.next { @@ -2226,7 +2226,7 @@ impl Net { && !(exports_only && front.down_only) && match aggregate { Aggregate::Path => true, - Aggregate::Epoch => carried.epoch.is_some() && front.epoch == carried.epoch, + Aggregate::Instance => carried.instance.is_some() && front.instance == carried.instance, Aggregate::Identity => carried.pinned == Some(front.id), Aggregate::Bound => carried.bound.is_some_and(|bound| front.total <= bound), } diff --git a/rs/moq-stats/MIGRATE.md b/rs/moq-stats/MIGRATE.md index 7b4a1eda35e..308f07f2ba3 100644 --- a/rs/moq-stats/MIGRATE.md +++ b/rs/moq-stats/MIGRATE.md @@ -4,6 +4,14 @@ How to update your code for each breaking change, newest first. ## Unreleased +### Group counters have their own epoch type + +`GroupFrame::epoch` is `moq_stats::Epoch` instead of `moq_net::Instance`. +Use `Epoch` for stored group epochs; parse their text with `str::parse` or +`Epoch::try_from(String)`, and read it with `as_str` or `Display`. +Broadcast routes still use `moq_net::Instance`. Group JSON is unchanged: +producers mint UUIDv7 strings, and readers accept any nonempty epoch string. + ### `moq_net::Path` has no lifetime Functions that took `impl AsPath` take `impl Into`, so pass a `Path` rather than a string, and fields and returns that were `PathOwned` are `moq_net::Path`. See moq-net's migration for the rest. diff --git a/rs/moq-stats/benches/aggregate.rs b/rs/moq-stats/benches/aggregate.rs index 9f53ed1ac10..eb0117e0332 100644 --- a/rs/moq-stats/benches/aggregate.rs +++ b/rs/moq-stats/benches/aggregate.rs @@ -40,7 +40,7 @@ struct Body { /// default-tier egress. struct Node { source: moq_net::origin::Publication, - epoch: Instance, + instance: Instance, group: moq_json::snapshot::Producer, frame: Body, } @@ -48,9 +48,9 @@ struct Node { impl Node { fn new(origin: &origin::Producer, name: &str) -> Self { let source = origin.create_broadcast(format!(".stats/node/{name}").as_str()).unwrap(); - let epoch = Instance::random(); + let instance = Instance::random(); source - .announce(origin::Route::default().with_instance(epoch.clone(), 0)) + .announce(origin::Route::default().with_instance(instance.clone(), 0)) .unwrap(); let track = source .create_track( @@ -71,7 +71,7 @@ impl Node { }; Self { source, - epoch, + instance, group: moq_json::snapshot::Producer::new(track, config), frame, } @@ -144,7 +144,7 @@ async fn measure(live: usize, departed: usize, grace: Duration, state: State) -> } } node.source - .announce(origin::Route::default().with_instance(node.epoch.clone(), 0)) + .announce(origin::Route::default().with_instance(node.instance.clone(), 0)) .unwrap(); node.publish(1); total += 1; diff --git a/rs/moq-stats/src/aggregate.rs b/rs/moq-stats/src/aggregate.rs index 290c807b91b..088e3dcdb1f 100644 --- a/rs/moq-stats/src/aggregate.rs +++ b/rs/moq-stats/src/aggregate.rs @@ -18,7 +18,7 @@ use moq_net::track::Subscribing; use moq_net::{Instance, Path, broadcast, origin}; use crate::{ - Group, GroupFrame, Prefix, PrefixFrame, PresenceFrame, Result, Totals, TotalsFrame, Usage, group_track, + Epoch, Group, GroupFrame, Prefix, PrefixFrame, PresenceFrame, Result, Totals, TotalsFrame, Usage, group_track, parse_node_path, prefix_track, presence_track, totals_track, }; @@ -622,7 +622,7 @@ impl Shape for Keyed { #[derive(Default)] struct Grouped { /// The track instance the last frame came from. - epoch: Option, + epoch: Option, totals: Keyed, paths: Keyed, labels: Keyed, @@ -1212,7 +1212,7 @@ mod tests { /// The group epoch every hand-published group frame carries, so a new /// [`NodeBroadcast`] at the same path is the same track instance returning. - fn group_epoch() -> Instance { + fn group_epoch() -> Epoch { "01900000-0000-7000-8000-0000000000ff".parse().unwrap() } @@ -1430,10 +1430,10 @@ mod tests { } #[tokio::test(start_paused = true)] - async fn restarted_producer_adds_a_new_epoch() { - // A restarted node announces a new epoch with fresh counters. The new - // epoch adds to the old one's kept contribution instead of regressing - // the total, and the old epoch folds into the retired total once the + async fn restarted_producer_adds_a_new_instance() { + // A restarted node announces a new instance with fresh counters. The new + // instance adds to the old one's kept contribution instead of regressing + // the total, and the old instance folds into the retired total once the // grace elapses. let origin = produce_origin(); let node_a = node_producer(&origin, "a"); @@ -1457,19 +1457,19 @@ mod tests { let frame = read_monotonic_until(&mut traffic, "acme/room", 140, 170).await; assert_eq!(frame.get("acme/room").expect("entry").bytes, 170, "100 + 30 + 40"); - assert_eq!(traffic.inner.nodes.len(), 3, "the old epoch lingers for its grace"); + assert_eq!(traffic.inner.nodes.len(), 3, "the old instance lingers for its grace"); tokio::time::advance(GRACE).await; settle(&mut traffic).await; - assert_eq!(traffic.inner.nodes.len(), 2, "the old epoch folded"); + assert_eq!(traffic.inner.nodes.len(), 2, "the old instance folded"); assert_eq!(retired_bytes(&traffic, "acme/room"), Some(100)); } #[tokio::test(start_paused = true)] - async fn replaced_epoch_keeps_its_own_counters() { + async fn replaced_instance_keeps_its_own_counters() { // A node restarts while its old instance is still announced. The newer - // epoch replaces the old one at the same path; the old entry keeps its - // last contribution and never reads the new epoch, so nothing counts + // instance replaces the old one at the same path; the old entry keeps its + // last contribution and never reads the new instance, so nothing counts // twice while the old instance keeps publishing. let origin = produce_origin(); let old_a = node_producer(&origin, "a"); @@ -1496,7 +1496,7 @@ mod tests { assert_eq!(frame.get("acme/room").expect("entry").bytes, 170, "counted once"); } } - assert_eq!(traffic.inner.nodes.len(), 3, "one entry per epoch"); + assert_eq!(traffic.inner.nodes.len(), 3, "one entry per instance"); } #[test] @@ -1675,7 +1675,7 @@ mod tests { #[tokio::test(start_paused = true)] async fn churn_keeps_nodes_bounded() { - // Distinct nodes come and go, as epochs make every restart do. The + // Distinct nodes come and go, as instances make every restart do. The // node map holds only the live node plus those within their grace, while // the merged total stays exact and never regresses. const CHURN: u64 = 64; @@ -1931,7 +1931,7 @@ mod tests { } /// A hand-published node broadcast at `.stats/node/` with a plain - /// totals track and no epoch, so a new one at the same path is that node + /// totals track and no instance, so a new one at the same path is that node /// restarting without telling the reader. struct TotalsNode { _source: origin::Publication, @@ -2046,7 +2046,7 @@ mod tests { assert_eq!( merged.merged()[""], sample(7, 4), - "same epoch does not count old errors again" + "same instance does not count old errors again" ); merged .nodes @@ -2160,7 +2160,7 @@ mod tests { node.depart(); assert_eq!(merged.merged()[""], presence(5, 5)); - // The same epoch resumes with those sessions still open: they start + // The same instance resumes with those sessions still open: they start // again rather than un-end, so no counter goes down. let node = merged.nodes.get_mut(&key).expect("node"); node.observe(BTreeMap::from([(String::new(), presence(5, 3))])); @@ -2207,8 +2207,8 @@ mod tests { }) .await; - // The same publisher epoch returns with all three pairs still open. - node.source.announce(route).expect("reannounce epoch"); + // The same publisher instance returns with all three pairs still open. + node.source.announce(route).expect("reannounce instance"); let mut expected = raw; expected.announces_started = 7; expected.announces_ended = 5; @@ -2288,7 +2288,7 @@ mod tests { expected.subscriptions_ended = 7; assert_eq!(merged.merged()["room"], expected); - // A route without an epoch still resets, including after a resume. + // A route without an explicit instance still resets, including after a resume. let mut reset = Traffic::default(); reset.subscriptions_started = 1; reset.bytes = 10; @@ -2333,7 +2333,7 @@ mod tests { async fn presence_survives_join_leave_and_restart() { // One label held across nodes: a node joining adds its sessions, one // leaving closes its sessions but keeps its count, and a restarted node - // is a new epoch that adds to it. The merged count never goes down. + // is a new instance that adds to it. The merged count never goes down. let origin = produce_origin(); let node_a = node_producer(&origin, "a"); let _fa = feed(&node_a, Tier::default(), "acme", "acme/room", 8).await; @@ -2358,7 +2358,7 @@ mod tests { let frame = read_until(&mut presence.inner, grew, |frame| frame[""].active() == 1).await; assert_eq!(frame[""].sessions_started, 2); - // Restart: a new epoch at node b's path. + // Restart: a new instance at node b's path. let node_b = node_producer(&origin, "b"); let _fb = feed(&node_b, Tier::default(), "acme", "acme/room", 8).await; let frame = read_until(&mut presence.inner, grew, |frame| frame[""].active() == 2).await; @@ -2369,7 +2369,7 @@ mod tests { async fn prefix_survives_join_leave_and_restart() { // One prefix held across nodes: a node joining adds its traffic and its // children, one leaving closes its subscriptions and drops its children - // but keeps its rollup, and a restarted node is a new epoch that adds to + // but keeps its rollup, and a restarted node is a new instance that adds to // it. The merged rollup never goes down. let origin = produce_origin(); let node_a = node_producer(&origin, "a"); @@ -2404,7 +2404,7 @@ mod tests { assert_eq!(frame[""].publisher.subscriptions_started, 2); assert!(!frame[""].children.contains_key("other"), "{frame:?}"); - // Restart: a new epoch at node b's path. + // Restart: a new instance at node b's path. let node_b = node_producer(&origin, "b"); let _fb = feed(&node_b, Tier::default(), "acme", "acme/other", 3).await; let frame = read_until(&mut prefix.inner, grew, |frame| { @@ -2412,7 +2412,10 @@ mod tests { }) .await; assert_eq!(frame[""].publisher.subscriptions_started, 3); - assert_eq!(frame[""].children["other"].publisher.bytes, 3, "the new epoch's child"); + assert_eq!( + frame[""].children["other"].publisher.bytes, 3, + "the new instance's child" + ); } #[test] diff --git a/rs/moq-stats/src/epoch.rs b/rs/moq-stats/src/epoch.rs new file mode 100644 index 00000000000..299c57b6017 --- /dev/null +++ b/rs/moq-stats/src/epoch.rs @@ -0,0 +1,59 @@ +use std::{fmt, str::FromStr, sync::Arc}; + +/// Names one run of a group's counters, independently of its broadcast's instance. +#[derive( + Debug, Clone, PartialEq, Eq, PartialOrd, Ord, Hash, serde_with::SerializeDisplay, serde_with::DeserializeFromStr, +)] +pub struct Epoch(Arc); + +/// The group epoch is empty. +#[derive(Debug, Clone, Copy, PartialEq, Eq, thiserror::Error)] +#[error("invalid group epoch: empty")] +#[non_exhaustive] +pub struct InvalidEpoch; + +impl Epoch { + /// Mint a UUIDv7 so locally produced epochs sort by creation. + pub(crate) fn mint() -> Self { + Self(uuid::Uuid::now_v7().hyphenated().to_string().into()) + } + + /// The epoch's text. + pub fn as_str(&self) -> &str { + &self.0 + } +} + +impl FromStr for Epoch { + type Err = InvalidEpoch; + + fn from_str(text: &str) -> Result { + if text.is_empty() { + return Err(InvalidEpoch); + } + Ok(Self(text.into())) + } +} + +impl TryFrom for Epoch { + type Error = InvalidEpoch; + + fn try_from(text: String) -> Result { + if text.is_empty() { + return Err(InvalidEpoch); + } + Ok(Self(text.into())) + } +} + +impl fmt::Display for Epoch { + fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { + f.write_str(self.as_str()) + } +} + +impl AsRef for Epoch { + fn as_ref(&self) -> &str { + self.as_str() + } +} diff --git a/rs/moq-stats/src/lib.rs b/rs/moq-stats/src/lib.rs index 88f304e5b36..fa19e8871de 100644 --- a/rs/moq-stats/src/lib.rs +++ b/rs/moq-stats/src/lib.rs @@ -39,7 +39,10 @@ pub mod aggregate; pub mod consume; pub mod produce; +mod epoch; + pub use consume::Consumer; +pub use epoch::{Epoch, InvalidEpoch}; pub use produce::{Producer, Publisher}; use std::collections::BTreeMap; @@ -124,15 +127,13 @@ pub struct Prefix { } /// One frame off a group track: one instance of the track, and its counters. -#[serde_with::serde_as] #[derive(Debug, Clone, PartialEq, Eq, serde::Serialize, serde::Deserialize)] #[non_exhaustive] pub struct GroupFrame { /// Minted each time the group's track is created, as the text of a UUIDv7. Every /// counter in a frame with a new epoch starts from zero, so a reader keeps each /// epoch's counters apart rather than diffing across them. - #[serde_as(as = "serde_with::DisplayFromStr")] - pub epoch: Instance, + pub epoch: Epoch, /// Each tier's [`Group`] counters, keyed by tier label (`""` for the default /// tier). #[serde(default)] @@ -270,19 +271,35 @@ pub enum Error { /// A [`Result`](std::result::Result) using this crate's [`Error`]. pub type Result = std::result::Result; -/// A fresh [`GroupFrame::epoch`]: the text of a UUIDv7, so epochs sort by creation. -pub(crate) fn mint_epoch() -> Instance { - uuid::Uuid::now_v7() - .hyphenated() - .to_string() - .parse() - .expect("a UUID is never empty") -} - #[cfg(test)] mod tests { use super::*; + #[test] + fn group_epoch_wire_values() { + // Readers keep the text opaque, including values that are not UUIDs. + for text in ["0192f4e6-7b8a-7c3d-9e1f-2a3b4c5d6e7f", "legacy", "~minted", "é/\0"] { + let json = serde_json::json!({ "epoch": text, "tiers": {} }); + let frame: GroupFrame = serde_json::from_value(json.clone()).unwrap(); + assert_eq!(frame.epoch.as_str(), text); + assert_eq!(serde_json::to_value(frame).unwrap(), json); + assert_eq!(Epoch::try_from(text.to_string()).unwrap(), text.parse().unwrap()); + } + + for epoch in [ + serde_json::json!(""), + serde_json::json!(null), + serde_json::json!(1), + serde_json::json!([]), + serde_json::json!({}), + ] { + assert!(serde_json::from_value::(serde_json::json!({ "epoch": epoch })).is_err()); + } + assert!(serde_json::from_value::(serde_json::json!({})).is_err()); + assert!("".parse::().is_err()); + assert!(Epoch::try_from(String::new()).is_err()); + } + #[test] fn parse_node_path_variants() { let parse = diff --git a/rs/moq-stats/src/produce.rs b/rs/moq-stats/src/produce.rs index 955d1ddc6e1..2aae31c2421 100644 --- a/rs/moq-stats/src/produce.rs +++ b/rs/moq-stats/src/produce.rs @@ -13,7 +13,7 @@ use serde::Serialize; use tracing::Instrument as _; use crate::{ - Prefix, Totals, Usage, parse_prefix_track, parse_presence_track, prefix_track, presence_track, totals_track, + Epoch, Prefix, Totals, Usage, parse_prefix_track, parse_presence_track, prefix_track, presence_track, totals_track, }; /// Settings for a [`Producer`]. Construct with [`Config::new`] and chain @@ -793,11 +793,9 @@ struct GroupTrack { /// A group track's frame, byte-identical to a [`GroupFrame`](crate::GroupFrame) /// once sorted. -#[serde_with::serde_as] #[derive(Serialize)] struct GroupBody { - #[serde_as(as = "serde_with::DisplayFromStr")] - epoch: Instance, + epoch: Epoch, tiers: Frame, } @@ -835,7 +833,7 @@ impl GroupTrack { body: GroupBody { // A new instance of the name: readers keep its counters apart from // an earlier instance's. - epoch: crate::mint_epoch(), + epoch: Epoch::mint(), tiers: Frame::default(), }, live: false, @@ -1941,7 +1939,7 @@ mod tests { )) } - /// A producer restarted on the same origin ends its old epoch and announces + /// A producer restarted on the same origin ends its old instance and announces /// the same path under a new one. #[tokio::test(start_paused = true)] async fn restarted_producer_announces_a_new_instance() { @@ -1950,18 +1948,18 @@ mod tests { let first = node_producer(&origin); drive_tick().await; - let [(path, true, before)] = &take_epochs(&mut events)[..] else { + let [(path, true, before)] = &take_instances(&mut events)[..] else { panic!("expected one announce"); }; assert_eq!(path, ".stats/node/sjc"); drop(first); drive_tick().await; - assert_eq!(take_epochs(&mut events), [(path.clone(), false, before.clone())]); + assert_eq!(take_instances(&mut events), [(path.clone(), false, before.clone())]); let _second = node_producer(&origin); drive_tick().await; - let [(after_path, true, after)] = &take_epochs(&mut events)[..] else { + let [(after_path, true, after)] = &take_instances(&mut events)[..] else { panic!("expected one announce"); }; assert_eq!(after_path, path); @@ -1969,7 +1967,7 @@ mod tests { } /// A restart while the old instance is still announced (a route the mesh - /// has not withdrawn yet) takes the path at once: the newer epoch restarts + /// has not withdrawn yet) takes the path at once: the newer instance restarts /// it, so a reader re-requests the new broadcast instead of stalling on the /// old one, while the old subscription stays on the old instance. #[tokio::test(start_paused = true)] @@ -1980,7 +1978,7 @@ mod tests { let first = node_producer(&origin); let _f1 = feed(first.registry(), Tier::default(), "foo/bar", true, 1, 100).await; drive_tick().await; - let [(path, true, before)] = &take_epochs(&mut events)[..] else { + let [(path, true, before)] = &take_instances(&mut events)[..] else { panic!("expected one announce"); }; let stats = origin.consume().request(path.as_str(), None).await.expect("resolve"); @@ -1990,8 +1988,8 @@ mod tests { let second = node_producer(&origin); let _f2 = feed(second.registry(), Tier::default(), "foo/bar", true, 1, 30).await; drive_tick().await; - let [(started, true, after)] = &take_epochs(&mut events)[..] else { - panic!("expected the new epoch to restart the path"); + let [(started, true, after)] = &take_instances(&mut events)[..] else { + panic!("expected the new instance to restart the path"); }; assert_eq!(started, path); assert_ne!(after, before); @@ -2017,13 +2015,13 @@ mod tests { let _newer = node_producer(&origin); drive_tick().await; - let [(_, true, _)] = &take_epochs(&mut events)[..] else { + let [(_, true, _)] = &take_instances(&mut events)[..] else { panic!("expected the newer producer's announce"); }; publisher.run().await; drive_tick().await; - assert_eq!(take_epochs(&mut events), []); + assert_eq!(take_instances(&mut events), []); } /// Cancelling a running publisher ends its tracks deliberately, so a reader @@ -2228,13 +2226,13 @@ mod tests { } /// The announce events buffered so far in delivery order, as - /// `(path, active, epoch)`. Every stats route carries an epoch. - fn take_epochs(events: &mut announce::Consumer) -> Vec<(String, bool, Instance)> { + /// `(path, active, instance)`. Every stats route carries an instance. + fn take_instances(events: &mut announce::Consumer) -> Vec<(String, bool, Instance)> { use futures::FutureExt; let mut out = Vec::new(); while let Some(Some((update, active))) = next_update(events).now_or_never() { - let epoch = update.route.instance.expect("a stats route carries an instance"); - out.push((update.prefix.as_str().to_string(), active, epoch)); + let instance = update.route.instance.expect("a stats route carries an instance"); + out.push((update.prefix.as_str().to_string(), active, instance)); } out } @@ -2832,7 +2830,7 @@ mod tests { tier.paths.entries.push((Path::from_static("acme/live"), side)); tier.labels.entries.push((Path::from_static("acme"), presence)); let body = GroupBody { - epoch: crate::mint_epoch(), + epoch: Epoch::mint(), tiers: Frame { entries: vec![(Path::from_static(""), tier)], }, From c241da638c895569ee888de84cf0b74d1bad629a Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Tue, 3 Nov 2026 14:29:36 -0800 Subject: [PATCH 3/6] fix(stats): keep instance imports at their remaining consumers Co-Authored-By: GPT-6.1 Sol --- rs/moq-stats/src/lib.rs | 4 ++-- rs/moq-stats/src/produce.rs | 6 +++--- 2 files changed, 5 insertions(+), 5 deletions(-) diff --git a/rs/moq-stats/src/lib.rs b/rs/moq-stats/src/lib.rs index fa19e8871de..3ab6111444a 100644 --- a/rs/moq-stats/src/lib.rs +++ b/rs/moq-stats/src/lib.rs @@ -18,7 +18,7 @@ //! //! A [`Producer`] publishes one broadcast per node at `/node/` //! (default prefix `.stats`); parse announce paths back with -//! [`parse_node_path`]. Each announcement carries a fresh [`Instance`] on its +//! [`parse_node_path`]. Each announcement carries a fresh [`Instance`](moq_net::Instance) on its //! route, so a restarted node is a new broadcast at the same path; a reader //! tells them apart by the announced route's instance. The broadcast carries a //! `totals.json` track of each [`Tier`]'s [`Totals`] for the instance, and a @@ -51,7 +51,7 @@ use std::collections::BTreeMap; /// can depend on this crate alone. pub use moq_net::stats::{Failure, Failures, Handle, Presence, RefusalKind, Refusals, Registry, Role, Tier, Traffic}; -use moq_net::{Instance, Path}; +use moq_net::Path; /// One frame off the totals track: each tier's [`Totals`], keyed by tier label /// (`""` for the default tier). diff --git a/rs/moq-stats/src/produce.rs b/rs/moq-stats/src/produce.rs index 2aae31c2421..6b52e016a0f 100644 --- a/rs/moq-stats/src/produce.rs +++ b/rs/moq-stats/src/produce.rs @@ -8,7 +8,7 @@ use std::task::Poll; use kio::clock::Instant; use moq_net::stats::{Presence, Registry, Report, Tier, Traffic, TrafficEntry}; -use moq_net::{Instance, Path, broadcast, kio, origin, track}; +use moq_net::{Path, broadcast, kio, origin, track}; use serde::Serialize; use tracing::Instrument as _; @@ -32,7 +32,7 @@ pub struct Config { pub origin: Option, /// Top-level path stats are published under (default `.stats`). The full /// advertised path is `/node/` (or `/node` when - /// `node` is unset), announced under a fresh [`Instance`] each time. Also the + /// `node` is unset), announced under a fresh [`Instance`](moq_net::Instance) each time. Also the /// registry's exclude prefix, so serving a stats broadcast doesn't generate /// more stats. pub prefix: Path, @@ -1636,7 +1636,7 @@ mod tests { use std::collections::BTreeMap; use moq_net::stats::{Registry, Tier}; - use moq_net::{Timestamp, announce, broadcast, track}; + use moq_net::{Instance, Timestamp, announce, broadcast, track}; use super::*; use crate::{PrefixFrame, PresenceFrame, TotalsFrame}; From de3eea09e491fee555b29cc758f60cb6a063ec47 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Tue, 3 Nov 2026 14:40:57 -0800 Subject: [PATCH 4/6] refactor(stats): clarify counter runs and keep epochs unordered Co-Authored-By: GPT-6.1 Sol --- rs/moq-stats/src/aggregate.rs | 18 +++++++++--------- rs/moq-stats/src/epoch.rs | 4 +--- rs/moq-stats/src/lib.rs | 2 +- rs/moq-stats/src/produce.rs | 22 ++++++++++++---------- 4 files changed, 23 insertions(+), 23 deletions(-) diff --git a/rs/moq-stats/src/aggregate.rs b/rs/moq-stats/src/aggregate.rs index 088e3dcdb1f..b1ab9a7c032 100644 --- a/rs/moq-stats/src/aggregate.rs +++ b/rs/moq-stats/src/aggregate.rs @@ -90,8 +90,8 @@ impl Default for Config { /// the keys ever reported, not every node ever seen. Each route instance is its /// own node: a restarted producer announces a new instance whose counters add to /// the old one's kept contribution instead of regressing it, and a group -/// track's new instance, under a new [`GroupFrame::epoch`], adds to the old -/// instance's the same way. A reader stays pinned to its instance, so a +/// track's new [`GroupFrame::epoch`] adds to the old epoch's counters the same +/// way. A reader stays pinned to its broadcast instance, so a /// replacement never feeds it. A wire that carries no instance has its relay /// mint one per announcement, so a node reached through one announces anew each /// time it is announced again. @@ -621,7 +621,7 @@ impl Shape for Keyed { /// traffic, and each `(tier, label)`'s sessions. #[derive(Default)] struct Grouped { - /// The track instance the last frame came from. + /// The group counter epoch the last frame came from. epoch: Option, totals: Keyed, paths: Keyed, @@ -634,7 +634,7 @@ impl Shape for Grouped { const LISTED: bool = true; fn observe(&mut self, frame: GroupFrame) { - // A new instance counts from zero, whatever its counters read by the time + // A new epoch counts from zero, whatever its counters read by the time // this reader sees them. let reset = self.epoch.as_ref().is_some_and(|epoch| *epoch != frame.epoch); self.epoch = Some(frame.epoch); @@ -1211,7 +1211,7 @@ mod tests { } /// The group epoch every hand-published group frame carries, so a new - /// [`NodeBroadcast`] at the same path is the same track instance returning. + /// [`NodeBroadcast`] at the same path resumes that group's counters. fn group_epoch() -> Epoch { "01900000-0000-7000-8000-0000000000ff".parse().unwrap() } @@ -1886,9 +1886,9 @@ mod tests { #[tokio::test(start_paused = true)] async fn a_relisted_group_adds_its_new_epoch() { - // A group's track that lingers out and is listed again is a new instance - // counted from zero under a new epoch: the reader follows the listing to - // it, and its totals add to the old instance's instead of regressing. + // A group's track that lingers out and is listed again starts a new epoch + // counted from zero: the reader follows the listing to it, and its totals + // add to the old epoch's instead of regressing. let origin = produce_origin(); let node = crate::produce::spawned(Producer::new( produce::Config::new() @@ -2288,7 +2288,7 @@ mod tests { expected.subscriptions_ended = 7; assert_eq!(merged.merged()["room"], expected); - // A route without an explicit instance still resets, including after a resume. + // Regressing counters reset within the same instance, even after a resume. let mut reset = Traffic::default(); reset.subscriptions_started = 1; reset.bytes = 10; diff --git a/rs/moq-stats/src/epoch.rs b/rs/moq-stats/src/epoch.rs index 299c57b6017..9e8d610d5fe 100644 --- a/rs/moq-stats/src/epoch.rs +++ b/rs/moq-stats/src/epoch.rs @@ -1,9 +1,7 @@ use std::{fmt, str::FromStr, sync::Arc}; /// Names one run of a group's counters, independently of its broadcast's instance. -#[derive( - Debug, Clone, PartialEq, Eq, PartialOrd, Ord, Hash, serde_with::SerializeDisplay, serde_with::DeserializeFromStr, -)] +#[derive(Debug, Clone, PartialEq, Eq, Hash, serde_with::SerializeDisplay, serde_with::DeserializeFromStr)] pub struct Epoch(Arc); /// The group epoch is empty. diff --git a/rs/moq-stats/src/lib.rs b/rs/moq-stats/src/lib.rs index 3ab6111444a..1aa06c1f058 100644 --- a/rs/moq-stats/src/lib.rs +++ b/rs/moq-stats/src/lib.rs @@ -126,7 +126,7 @@ pub struct Prefix { pub children: BTreeMap, } -/// One frame off a group track: one instance of the track, and its counters. +/// One frame off a group track: its counter epoch and counters. #[derive(Debug, Clone, PartialEq, Eq, serde::Serialize, serde::Deserialize)] #[non_exhaustive] pub struct GroupFrame { diff --git a/rs/moq-stats/src/produce.rs b/rs/moq-stats/src/produce.rs index 6b52e016a0f..7f5538c7ad2 100644 --- a/rs/moq-stats/src/produce.rs +++ b/rs/moq-stats/src/produce.rs @@ -54,7 +54,7 @@ pub struct Config { /// first segment, and larger values include more leading segments. A /// group's track is listed while its group has live traffic, plus the /// [`Self::linger`], and a group returning after that is a new track - /// instance with a new [`GroupFrame::epoch`](crate::GroupFrame::epoch), + /// run with a new [`GroupFrame::epoch`](crate::GroupFrame::epoch), /// counted from zero. pub depth: usize, /// How long a group's track stays listed after its group's last entry @@ -661,7 +661,7 @@ fn tier_entry<'a, V: Default>(tiers: &'a mut HashMap, tier: &Tier) -> & } /// The always-present `totals.json` track and its per-tier sums. Never pruned -/// while the broadcast lives, so it is cumulative within the epoch. +/// while the broadcast lives, so it is cumulative within the broadcast instance. struct TotalsTrack { output: Output, sums: Cumulative, @@ -777,7 +777,7 @@ impl PrefixTrack { } /// One group's track: listed from the group's first entry until it lingers -/// empty, then finished. A return after that is a new instance under a new +/// empty, then finished. A return after that is a new run under a new /// epoch, counted from zero, so it holds no state for groups that left. struct GroupTrack { /// The track name, for logs. @@ -831,8 +831,7 @@ impl GroupTrack { name, snapshot: Snapshot::new(track, config()), body: GroupBody { - // A new instance of the name: readers keep its counters apart from - // an earlier instance's. + // A new counter run: readers keep its counters apart from an earlier epoch's. epoch: Epoch::mint(), tiers: Frame::default(), }, @@ -1555,7 +1554,7 @@ mod tests { assert_eq!( (total.wire_tx, total.wire_rx), (1_307, 2_614), - "epoch totals never reset on re-hold" + "broadcast totals never reset on re-hold" ); } } @@ -3070,9 +3069,9 @@ mod tests { ); } - /// A group that returns after its linger is a new track instance: a new + /// A group that returns after its linger starts a new counter run: a new /// epoch counted from zero, so a reader summing each epoch never counts the - /// old one twice, and group numbers that continue past the old instance's. + /// old one twice, and group numbers that continue past the old run's. #[tokio::test(start_paused = true)] async fn a_relisted_group_starts_a_new_epoch_from_zero() { let (producer, origin) = grouped_producer(Duration::ZERO); @@ -3115,14 +3114,17 @@ mod tests { .await .unwrap() .unwrap(); - assert!(second.epoch > first.epoch, "a returning group mints a new epoch"); + assert!( + second.epoch.as_str() > first.epoch.as_str(), + "a returning group mints a newer UUIDv7" + ); assert_eq!( second.tiers[""].sessions.sessions_started, 1, "a new epoch counts from zero" ); assert!( sequence(&broadcast).await > old_sequence, - "group numbers continue past the old instance" + "group numbers continue past the old run" ); assert_eq!( default_totals(&broadcast).await.sessions.sessions_started, From 2748fe9c4f8e76add627bea88a11e6794f7ef70c Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Tue, 3 Nov 2026 14:41:28 -0800 Subject: [PATCH 5/6] docs(stats): note that group epochs are unordered Co-Authored-By: GPT-6.1 Sol --- rs/moq-stats/MIGRATE.md | 1 + 1 file changed, 1 insertion(+) diff --git a/rs/moq-stats/MIGRATE.md b/rs/moq-stats/MIGRATE.md index 308f07f2ba3..22bbb22bba7 100644 --- a/rs/moq-stats/MIGRATE.md +++ b/rs/moq-stats/MIGRATE.md @@ -9,6 +9,7 @@ How to update your code for each breaking change, newest first. `GroupFrame::epoch` is `moq_stats::Epoch` instead of `moq_net::Instance`. Use `Epoch` for stored group epochs; parse their text with `str::parse` or `Epoch::try_from(String)`, and read it with `as_str` or `Display`. +Epochs are opaque identities with equality and hashing, without a temporal order. Broadcast routes still use `moq_net::Instance`. Group JSON is unchanged: producers mint UUIDv7 strings, and readers accept any nonempty epoch string. From f84f7ca8f9a2c136ec88150def81e4be6f2e1c9f Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Tue, 3 Nov 2026 16:58:01 -0800 Subject: [PATCH 6/6] docs(quest): name the renamed routing fixture and its instance key Co-Authored-By: Claude Opus 5.5 --- quest/m1/cluster-routing/routes/session.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/quest/m1/cluster-routing/routes/session.md b/quest/m1/cluster-routing/routes/session.md index ec2395ad365..3855c8f8e22 100644 --- a/quest/m1/cluster-routing/routes/session.md +++ b/quest/m1/cluster-routing/routes/session.md @@ -35,12 +35,12 @@ changes the contract decided ship with it. loop-free (RFC 8966 s2.7): a ring of same-epoch origins whose relays prioritize different links, and nested wildcards where a relay has not heard the specific claim, both cycle past requester exclusion; joining - another relay's subscription by path or epoch deadlocks; and without an - epoch a later hop splices another publisher under the requester's + another relay's subscription by path or instance deadlocks; and without an + instance a later hop splices another publisher under the requester's announcement with no Restart (`local_priorities_loop_path_only_requests`, `overlapping_wildcards_loop_where_specific_claims_are_unheard`, `aggregation_cycles_starve_without_a_forwarding_constraint`, - `epochless_reselection_splices_another_publisher`, + `reselection_without_an_instance_splices_another_publisher`, `sweep_forwarding_progress`). A relay therefore joins a forwarded request only to a subscription following its route to the same identity. When that identity becomes unreachable the forwarded request ends, and the first hop