feat(moq-net): usage stats in the model (BroadcastInfo-carried, origin-attributed)

[kixelated]

Implements the design in rs/moq-net/DESIGN-stats.md (PR #1894), which supersedes the with_meter / set_meter approach on #1873. Per-broadcast usage sinks live in BroadcastInfo, are set at construction, and ride the immutable Arc<BroadcastInfo> down to every track, group, and frame. Usage is atomics, so the model bumps through a shared &Arc<Usage> with no mutation, no setter, and no Arc::make_mut.

This takes over #1873 (which should be closed in favor of this).

What changed

The design's three phases, each landed as its own commit:

1. The model carries usage stats. New model/usage.rs: Usage (groups/frames/bytes payload + opened/closed lifecycle atomics) and BroadcastStats (one Usage per direction). BroadcastInfo gains a stats field; Arc<BroadcastInfo> + Arc<TrackInfo> are threaded through Broadcast/Track/Group; payload bumps move into the model (ingress at create_group/append_frame, egress as the consumer reads). The stats-layer BroadcastStats is renamed BroadcastHandle.

2. Origin attributes egress, ingress baked at construction. The lite/IETF subscriber loops build the broadcast with stats.producer already set. The per-session OriginConsumer::with_egress provider stamps each BroadcastConsumer it yields (announce stream, request_broadcast, dynamic accept) with that session's egress sink, so per-tier egress survives with zero mutation. The handler/gateway per-frame/byte/group bumps are deleted; the stats layer reads the shared Arc<Usage> instead of vending payload guards.

3. Model-tracked live viewer/publisher counts. A Live refcount over each sink: a BroadcastConsumer is one live viewer while it has ≥1 outstanding TrackConsumer (the token rides into the TrackSubscriber, so a subscription counts for its whole life); a broadcast with ≥1 live TrackProducer is one publisher (the publisher token rides the shared broadcast state, so the relay's dynamic-accept ingress path is covered). SessionBroadcasts is gone; the publish loop maps opened - closed onto the existing broadcasts / broadcasts_closed fields, so the published schema is unchanged.

Semantics

• Egress is per-consumer (N viewers count N times); ingress is single-writer (counts once). A relay counts both directions without double-counting either.
• The lite fetch path is metered through the model: a fetch re-serves an existing group, so it bumps frames/bytes but not groups.
• The model counts raw (decompressed) bytes vs. the old post-compression wire bytes. Only the hang catalog track sets compress, so the difference is noise; a follow-up will cache compressed bytes so the count is the wire size again. (Confirmed acceptable.)

Testing

cargo test -p moq-net passes (400 lib + 4 integration), including new model tests for ingress-once/egress-per-viewer, origin egress-stamping, and live viewer/publisher counts. clippy/doc/fmt clean; dependent crates (moq-mux, hang, moq-relay, moq-native, moq-srt, moq-json, moq-ffi) compile.

Note: this environment's egress policy blocks the kixelated/nvidia-video-codec-sdk git fork and the sandbox has no IPv6, so the full workspace just check and the moq-native end-to-end relay suite can't run here. CI's nix run is the source of truth for those.

Cross-package sync

• js/net: not mirrored. The stats aggregator / usage sinks are relay-side Rust only; the browser client has no equivalent. No doc/concept wire change (this is API, not wire).

Breaking changes (target dev)

Public API in rs/moq-net: BroadcastInfo gains stats; Broadcast{Producer,Consumer,Dynamic} carry Arc<BroadcastInfo>; GroupProducer::new takes Arc<TrackInfo> + Arc<BroadcastInfo> (was Option<Timescale>); the stats-layer BroadcastStats is renamed BroadcastHandle; SessionBroadcasts / BroadcastSubscription and the publisher_broadcasts / subscriber_broadcasts / per-track frame/bytes/group methods are removed; Counters swaps its payload + broadcasts atoms for a shared Arc<Usage>. TrackProducer::new(name, info) keeps its signature (standalone tracks get a shared no-op broadcast).

Follow-ups

• Wire moq-rtc (WHIP/WHEP) and moq-rtmp through the same origin egress / ingress-at-construction seam (the mechanism exists; their origins just need with_egress and an ingress-baked broadcast).
• Cache compressed bytes in the model so the byte count is the wire size for compressed tracks.

🤖 Generated with Claude Code

(Written by Claude)