Skip to content

Key session stats by a grant label instead of the auth root - #5731

Merged
kixelated merged 12 commits into
mainfrom
quest/m2/grant-label
Oct 18, 2026
Merged

kixelated merged 12 commits into
mainfrom
quest/m2/grant-label

Conversation

@kixelated

@kixelated kixelated commented Oct 16, 2026 •

Copy link
Copy Markdown
Collaborator

Problem

Authorization roots currently do two jobs: scope what a session may access and key its session statistics. Most sessions share a broad root (often /), so per-root stats say little, and a narrowly scoped credential splits one project's usage across credential roots. Per-credential bytes only reach an auth decider through Lease::close, once a session ends.

Approach

  • Add an optional literal label to Rust and JavaScript auth grants. Grant::validate and GrantSchema refuse a label that is not a literal path.
  • Session stats are keyed by the label instead of the auth root. The root is used only for auth; it no longer appears in any stats row, key, or track name. A grant without a label records under the empty label, never under its root.
  • The relay Token carries the label (PathOwned, empty when the grant names none) and hands it to session and HTTP request stats (cluster.rs, web.rs, moq-cli).
  • [<tier>/]sessions.json is keyed by label, <label>/presence.json replaces <root>/presence.json, and --stats-depth groups sessions by the label's leading segments, the same way it grouped by root. Presence requests and their group check follow the label path.
  • Report per-label sent_bytes and received_bytes (payload this node sent to and received from those sessions) beside presence.
  • Each session counts its own bytes in session-local atomics, so a write touches no shared row. Each (tier, label) row holds its live sessions (keyed by identity) and their counters at arrival under one lock, plus a folded total for sessions that left. A read sums them under that lock and folds in sessions no handle can write through anymore, so a readout never goes down. A retag cuts the session's counters with a single load under the old row's lock, then joins the new row from that cut, so a concurrent write counts exactly once.
  • Session::set_tier(tier) becomes Session::retag(tier, label), called from Lease::ended and Refresh when a re-checked grant changes tier or label. Earlier bytes stay under the old label; later ones, including through meters handed out before the retag, go to the new one.
  • A label row is pruned by Registry::report only once no session holds it and no meter outliving its session can still write to it.
  • Excluded stats paths count toward neither the per-path rows nor the session's label.
  • Docs updated: doc/concept/stats.md, doc/bin/relay/auth.md, doc/bin/relay/config.md, doc/bin/inspect.md, doc/lib/rs/moq-auth.md, doc/lib/js/auth.md, the moq-stats crate docs, rs/moq-net/MIGRATE.md, and the demo stats dashboard (demo/web/src/stats.{ts,html}). Retires quest/m2/grant-label.md.

Impact

  • Stats wire (breaking): [<tier>/]sessions.json entries are keyed by stats label rather than auth root, and presence tracks are requested as <label>/presence.json rather than <root>/presence.json. At --stats-depth 1 or more, sessions group under their label's leading segments rather than their root's. Unlabeled sessions and the relay's own refusals appear under the empty label ("", and presence.json), as unscoped refusals did under the empty root. Presence JSON (sessions.json, presence.json, totals.json) also gains additive sent_bytes and received_bytes. The traffic, totals, and requested prefix (<path>/traffic.json) tracks stay keyed by broadcast path and are unchanged apart from those byte fields.
  • Auth HTTP JSON: an optional label on the grant. Old grants remain valid. An older relay ignores the field; access is unchanged.
  • Public Rust API (breaking):
    • stats::Handle::session(label), stats::Handle::request(label), stats::Handle::refuse(label, reason), and stats::Handle::wire(label, counters) take the stats label where they took the auth root.
    • stats::Session::set_tier(tier) is replaced by stats::Session::retag(tier, label).
    • stats::SessionEntry::root is renamed label.
    • moq_stats presence helpers and readers (presence_track, consume::Consumer::presence, aggregate::Consumer::presence) take a label; the signatures are unchanged.
  • Public Rust API (additive): moq_auth::Grant::label, moq_auth::Error::InvalidLabel, moq_net::stats::Presence::{sent_bytes, received_bytes}, moq_relay::auth::Token::label.
  • Public JS API: GrantSchema gains optional label. The demo dashboard's sessions table now lists labels.
  • No MoQ wire change and no authorization change.
  • Cost: each payload write adds one relaxed atomic increment on a session-local counter. A report folds each label's live sessions, so its cost scales with live session count (see benchmarks below).

Decisions

From the maintainer:

  • ✅ Root is for auth only. Stats are keyed and grouped by label; root drops out of stats rows, keys, and track names. No consumer besides moq.pro (and the demo dashboard, updated here) read it.
  • ✅ [<tier>/]sessions.json is keyed by label and a per-label presence track replaces <root>/presence.json. No separate labels.json and no per-root sums.
  • ✅ --stats-depth groups and presence requests follow the label path the way they followed the root path. Labels are literal paths, so they fit that model unchanged.
  • ✅ Unlabeled sessions and refusals count under the empty label, the way unscoped refusals counted under the empty root. There is no fallback to the root. (Chosen by the agent as suggested.)
  • ✅ The label must be a literal path.

Settled by the quest plan:

  • ✅ The grant field is named label and sits beside tier.
  • ✅ set_tier generalizes into one (tier, label) retag rather than a second method.
  • ✅ Presence gains sent_bytes / received_bytes.

Made during iteration (by the agent, unattended; challenge any of them):

  • ✅ Token::label is a PathOwned, empty when the grant names none, rather than an Option: the empty path is already the stats key for "no label", like the default tier.
  • ✅ Rebuilt the byte fold under a per-row lock. The previous version had two bugs a regression test now covers: retagging A to B and back to A counted the session's live bytes twice on A, and a readout could dip while a session retagged or dropped, which stats readers treat as a counter reset.
  • ✅ Datagram payload bytes count toward the label, like stream payload.
  • ✅ An excluded stats path counts toward no label, matching the per-path rows.
  • ✅ A label row stays open while a meter outlives its session, so late bytes are not lost.
  • ✅ A row keys its live sessions by session identity, so a retag leaves in constant time instead of scanning co-labeled sessions. (From the Codex review.)
  • ✅ moq-stats aggregation treats a drop in sent_bytes or received_bytes as a reset, like the other presence counters, so merged byte totals never go backward. (From the Codex review.)
  • ✅ A changed grant from an embedder (lease::Producer::update) or a refreshed credential is held to Grant::validate, like the admitting grant, so a malformed label cannot retag a live session. An update that admits nothing ends as Narrowed; one past its expiry ends as Expired. (From the Codex review.)
  • ✅ Wire counters (wire_tx / wire_rx, from feat(stats): collect owned transport wire counters #5773) follow the session's label like its other presence fields: a retag flushes the old (tier, label) row before the session moves, and stats::Handle::wire takes a label. (Merge with main.)
  • ✅ Admission builds the token from the exact grant snapshot it validated, and protocol setup holds the grant it re-reads to Grant::validate, so an update racing either step cannot install an unchecked label (an_invalid_label_added_before_protocol_setup_is_refused). (From the Codex review.)

Verification

  • just fix
  • just check
  • cargo test -p moq-net --lib stats (wire_deltas_follow_label_and_tier_changes retags tier and label together; new: retag_back_counts_bytes_once, retag_moves_presence_between_labels_on_one_tier, session_bytes_outlive_the_session, excluded_paths_skip_session_bytes)
  • cargo test -p moq-stats (new: byte_only_regression_begins_another_segment)
  • cargo test -p moq-relay --lib auth (new: an_invalid_label_at_revalidation_ends_the_lease, an_invalid_label_added_before_protocol_setup_is_refused; the token test asserts an absent label is the empty label, not the root)
  • cargo test -p moq-relay --test integration (a_moved_tier_retags_the_live_session moves tier and label and asserts per-label presence and bytes end to end; refusals and HTTP requests without a label land under the empty label)
  • cargo bench -p moq-net --features fuzz --bench stats -- stats/ --sample-size 10 --warm-up-time 1 --measurement-time 1 on a shared, loaded machine: write path 3.7 ns path-only vs 7.5 ns with session bytes; retag about 300 ns per move, flat from 1 to 10,000 sessions per label and 1 to 100 labels; session report 69 ns (1 label x 1 session), 4.1 us (100x1), 9.0 us (100x10), 41 us (1000x1), 96 us (1000x10)

CI notes for the latest head: TS validation fails the same way on main's nightly (8bcbc7dfd, an mp2 audio hole in the TS round trip), and io_uring's acme::tests::failed_validations_stop_short_of_the_rate_limit hung once at its 30s bound where it normally passes in about 6s. That test points validations at a port it bound and released, so a concurrently running test can reuse the port and the mock's TLS dial waits forever; it is untouched here and tracked as a follow-up.

(Written by Claude Opus 5.5)

🤖 Generated with Claude Code

kixelated and others added 3 commits October 16, 2026 21:09
Co-Authored-By: OpenAI Codex <noreply@openai.com>
Co-Authored-By: OpenAI Codex <noreply@openai.com>
Retagging a session from A to B and back counted its live bytes twice on
A, and a readout could dip while a session retagged or dropped, which
stats readers treat as a counter reset. Each label row now holds its live
sessions and folded total under one lock, and a retag cuts the session's
counters with a single load under the old row's lock.

Also counts datagram payload toward the label, skips excluded paths,
keeps a row open while a meter outlives its session, keys moq-cli
session stats by label, and updates stale "auth root" wording.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@kixelated
kixelated force-pushed the quest/m2/grant-label branch from c348b56 to 14f7a2e Compare October 17, 2026 04:40
@kixelated
kixelated marked this pull request as ready for review October 17, 2026 04:40
@chatgpt-codex-connector

chatgpt-codex-connector Bot commented Oct 17, 2026 •

Copy link
Copy Markdown

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review Status Commit Review trigger
📝 Code Review ✅ Completed 2026-10-18T04:10:02.155310Z 591be53 New commits
ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

@coderabbitai

coderabbitai Bot commented Oct 17, 2026 •

Copy link
Copy Markdown
Contributor

Warning

Review limit reached

You've used all free OSS reviews for now. Wait for the free limit to reset to keep reviewing this public repository.

Next included review available in 30 minutes.

Check out review usage here.

View limit details

Limit details: You’ve used all 4 included reviews currently available.

Learn how review limits work.

Review configuration:

⚙️ Run configuration
  • Configuration used: Organization UI
  • Review profile: CHILL
  • Plan: Advanced
  • Run ID: b425b609-f14f-4c85-90b7-50a130bd634e
📥 Commits

Reviewing files that changed from the base of the PR and between e65cc1f and 591be53.

📒 Files selected for processing: 34
  • demo/web/src/stats.html
  • demo/web/src/stats.ts
  • doc/bin/inspect.md
  • doc/bin/relay/auth.md
  • doc/bin/relay/config.md
  • doc/concept/stats.md
  • doc/lib/js/auth.md
  • doc/lib/rs/moq-auth.md
  • js/auth/src/contract.test.ts
  • js/auth/src/contract.ts
  • js/auth/src/interop.test.ts
  • quest/m2/README.md
  • quest/m2/grant-label.md
  • rs/moq-auth/src/error.rs
  • rs/moq-auth/src/grant.rs
  • rs/moq-cli/src/main.rs
  • rs/moq-net/Cargo.toml
  • rs/moq-net/MIGRATE.md
  • rs/moq-net/benches/stats.rs
  • rs/moq-net/src/fuzz.rs
  • rs/moq-net/src/stats.rs
  • rs/moq-relay/src/auth.rs
  • rs/moq-relay/src/auth/refresh.rs
  • rs/moq-relay/src/cluster.rs
  • rs/moq-relay/src/web.rs
  • rs/moq-relay/tests/integration/auth_embedder.rs
  • rs/moq-relay/tests/integration/auth_lifetime.rs
  • rs/moq-relay/tests/integration/session_revalidate.rs
  • rs/moq-stats/benches/producer_tick.rs
  • rs/moq-stats/src/aggregate.rs
  • rs/moq-stats/src/consume.rs
  • rs/moq-stats/src/lib.rs
  • rs/moq-stats/src/produce.rs
  • rs/moq-stats/src/produce_bench.rs
  • Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

Comment @coderabbitai help to get the list of available commands.

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 14f7a2ee49

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Comment thread rs/moq-relay/src/auth.rs Resolved
An embedder's lease update skipped Grant::validate, so a malformed
stats label (or any other contract violation) could retag a live
session. Both the lease and refresh paths now validate a changed grant
first; one that admits nothing ends as Narrowed and one already past
its expiry as Expired.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: ba22e46563

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Comment thread rs/moq-net/src/stats.rs Resolved
A retag searched the row's live sessions linearly under its lock, so
moving N co-labeled sessions cost O(N^2). Key them by session identity
instead, and add a retag benchmark swept over labels and sessions per
label: each move stays near 150 ns from 1 to 10,000 sessions.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: d39917116b

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Comment thread rs/moq-net/src/stats.rs Resolved
kixelated and others added 2 commits October 16, 2026 23:06
Presence::regressed skipped sent_bytes and received_bytes, so a source
whose byte counters restarted while its other presence counters had
caught up replaced its earlier contribution instead of starting a new
segment, and merged byte totals could go backward.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@kixelated
kixelated marked this pull request as draft October 17, 2026 14:49
Session stats rows are keyed by (tier, root, label). `root` stays the
auth root and `SessionEntry::label` carries the optional grant label,
with no fallback to the root. A new per-tier `labels.json` track sums
labeled rows by label; `sessions.json` and `presence.json` stay keyed by
root and sum across labels. The producer folds an ended row into its
key's sum while the key lives on, so a sum never dips.

`Handle::session` and `Handle::request` take `label: Option<PathOwned>`,
and `Session::retag` moves tier and label without touching the root.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@kixelated
kixelated marked this pull request as ready for review October 17, 2026 15:33

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 17fe326086

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Comment thread rs/moq-relay/src/auth.rs Resolved
`Auth::admit` validated one snapshot of the decider's grant and then
re-read it for the token, so an embedder update in between could install
an unchecked label. Admission now builds the token from the snapshot it
checked; a later update still arrives as a change and is re-checked.
`Refresh::new` likewise holds the grant it reads at protocol setup to
`Grant::validate`, not only the rate check.

Also notes in the stats docs that a label spanning groups appears on
each group's track.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@kixelated
kixelated marked this pull request as draft October 17, 2026 15:49
@kixelated
kixelated marked this pull request as ready for review October 17, 2026 15:49
The auth root is for auth only. Session stats rows, `sessions.json`,
presence tracks, and `--stats-depth` groups are keyed by the grant's
stats label, and `SessionEntry::root` is renamed `label`. A grant
without a label, and the relay's own refusals, record under the empty
label; there is no fallback to the root.

This drops the parallel `labels.json` track and the per-root sums.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@kixelated kixelated changed the title Label live session stats independently of auth scope Key session stats by a grant label instead of the auth root Oct 17, 2026
@kixelated
kixelated marked this pull request as draft October 17, 2026 16:52
@kixelated
kixelated marked this pull request as ready for review October 17, 2026 16:52
Resolves #5811's prefix tracks against label-keyed presence: presence
tracks and requests take the stats label, prefix tracks keep the
broadcast path.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@kixelated
kixelated marked this pull request as draft October 17, 2026 17:10
@kixelated
kixelated marked this pull request as ready for review October 17, 2026 17:11
Wire counters from #5773 follow the session's label and tier on retag.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@kixelated

Copy link
Copy Markdown
Collaborator Author

Merging at 591be53: main merged, all checks green (TS validation and io_uring included), Codex reviewed this head with no findings. The earlier TS validation and acme failures were main-side flakes, unrelated to this PR.

Decision taken while merging main: #5773's wire counters follow the label too (stats::Handle::wire(label, counters), flushed into the old row on retag), recorded under Decisions in the description.

(Written by Claude Opus 5.5)

@kixelated
kixelated added this pull request to the merge queue Oct 18, 2026
Merged via the queue into main with commit 8489270 Oct 18, 2026
16 checks passed
@kixelated
kixelated deleted the quest/m2/grant-label branch October 18, 2026 04:40
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant