diff --git a/quest/m1/README.md b/quest/m1/README.md index 13b46b1670d..78e6b415aa3 100644 --- a/quest/m1/README.md +++ b/quest/m1/README.md @@ -178,7 +178,6 @@ per-frame CPU growth since #5926. - [One Ed25519 public key type with one z-base-32 codec](/quest/m1/mesh-key-codec.md) - `moq_auth::mesh::EndpointId` is merged into `moq_crypto::sign::PublicKey` - [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 -- [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/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 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..22bbb22bba7 100644 --- a/rs/moq-stats/MIGRATE.md +++ b/rs/moq-stats/MIGRATE.md @@ -4,6 +4,15 @@ 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`. +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. + ### `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..b1ab9a7c032 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, }; @@ -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,8 +621,8 @@ impl Shape for Keyed { /// traffic, and each `(tier, label)`'s sessions. #[derive(Default)] struct Grouped { - /// The track instance the last frame came from. - epoch: Option, + /// The group counter epoch the last frame came from. + epoch: Option, totals: Keyed, paths: Keyed, labels: 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,8 +1211,8 @@ 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 { + /// [`NodeBroadcast`] at the same path resumes that group's counters. + 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; @@ -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() @@ -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. + // Regressing counters reset within the same instance, even 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..9e8d610d5fe --- /dev/null +++ b/rs/moq-stats/src/epoch.rs @@ -0,0 +1,57 @@ +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, 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..1aa06c1f058 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 @@ -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; @@ -48,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). @@ -123,16 +126,14 @@ pub struct Prefix { pub children: BTreeMap, } -/// One frame off a group track: one instance of the track, and its counters. -#[serde_with::serde_as] +/// 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 { /// 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..7f5538c7ad2 100644 --- a/rs/moq-stats/src/produce.rs +++ b/rs/moq-stats/src/produce.rs @@ -8,12 +8,12 @@ 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 _; 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 @@ -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, @@ -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. @@ -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, } @@ -833,9 +831,8 @@ 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. - epoch: crate::mint_epoch(), + // A new counter run: readers keep its counters apart from an earlier epoch's. + epoch: Epoch::mint(), tiers: Frame::default(), }, live: false, @@ -1557,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" ); } } @@ -1638,7 +1635,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}; @@ -1941,7 +1938,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 +1947,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 +1966,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 +1977,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 +1987,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 +2014,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 +2225,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 +2829,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)], }, @@ -3072,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); @@ -3117,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,