Skip to content

feat(relay): report how long each publishing session kept broadcasts opted into HLS and ABR - #613

Open
okdaichi wants to merge 2 commits into
ccr-2161bc2c-wkewvo-meterfrom
ccr-2161bc2c-wkewvo-optin-seconds
Open

okdaichi wants to merge 2 commits into
ccr-2161bc2c-wkewvo-meterfrom
ccr-2161bc2c-wkewvo-optin-seconds

Conversation

@okdaichi

Copy link
Copy Markdown
Collaborator

Description

Step 2 of usage metering, stacked on #608. Merge #608 first; GitHub then retargets this PR to main.

A publishing session's usage and session_close records now carry opt-in seconds:

  • gateway.opt_in_seconds.abr and gateway.opt_in_seconds.hls
  • the whole seconds the session's announcements beneath /.abr/ and /.hls/ lasted on the relay, added up over its broadcasts (two broadcasts opted into ABR for a minute each are 120)

A control plane can then bill ABR or HLS by the time it was used, under the tenant's key. This follows the rule agreed for metering: usage goes to the kid of the tenant token the server itself verified. The relay verifies the ticket that lets the session announce the opt-in, so the relay meters it. qumo abr never needs to know whose broadcast it transcodes.

Why only paid opt-ins are counted:

  • gomoqt's announcement reader drops an announcement the session's grant doesn't cover, so an opt-in the key doesn't hold never reaches the relay.
  • When a ticket is revoked or replaced, gomoqt rescopes the reader and ends the announcements outside the new grant, so the clock stops then.

Related Issue

Follows #608 (step 1: internal/meter). Steps 3 (ingest) and 4 (hls) come next.

Changes

  • internal/relay:
    • optInClock counts each checked session's opt-in announcements while they last. Per egress it keeps the time of ended announcements plus live × (now − last change).
    • It skips an announcement that has already ended. For an ended announcement gomoqt runs AfterFunc later on another goroutine, which would otherwise count the time until then.
    • The lease sends the totals with each revalidate, and reportEnd with the end (auth.Request.OptIns).
    • Unchecked sessions (relay peers, auth off) count nothing, so an opt-in forwarded between relays is billed once, at the edge.
  • internal/auth:
    • A publisher's records carry the opt-in seconds, whole seconds only, and only for egresses with at least one second.
    • A publisher with opt-in time is reported even if it moved no bytes.
    • A viewer's total carries none: a viewer can't announce.
  • usage.OptInSeconds(optIn) names the metric.
  • optin.Of names the egress a path opts into; internal/ingest now uses it instead of its own copy.
  • Docs: configuration (usage reports), cli/abr.md, CHANGELOG (Added).

Records of sessions that opted nothing in are unchanged, so a receiver that doesn't bill opt-ins sees what it saw before.

Testing

  • Unit:
    • optInClock: live and ended announcements, two egresses, a path that is not an opt-in, an announcement that ended before it was tracked, a nil clock (-race).
    • The usage reporter: whole seconds, sub-second time left out, opt-in time without bytes reported, a viewer's total without it, and the close record carrying the final time.
    • optin.Of and usage.OptInSeconds.
  • Integration: TestRelay_ReportsOptInSeconds runs a paid tenant against a relay with a usage sink.
    • The tenant publishes a broadcast, opts it into ABR on a ticket, holds the opt-in for 2.2 s, then leaves.
    • The end report carries ≥ 2 s of ABR, and the session_close record under the tenant's kid carries gateway.opt_in_seconds.abr between 2 and 5.
    • The test fails with the relay's tracking switched off.
  • Suites: go test ./... passes; golangci-lint reports 0 issues; the internal/integration suite passes.
  • Not run here: TestServer_DualStackBind_ReachableOverIPv6 fails in this container only because it has no IPv6 loopback; CI has one.

Checklist

  • Comments added for complex logic
  • Documentation updated if needed
  • Tests added/updated

Generated by Claude Code

…opted into HLS and ABR

A publishing session's usage and session_close records now carry
gateway.opt_in_seconds.abr and .hls (usage.OptInSeconds): the whole
seconds its announcements beneath /.abr/ and /.hls/ lasted on the relay,
added up over its broadcasts. Only an opt-in the session's grant covers
reaches the relay, and moqt ends one a revoked ticket no longer covers, so
the time is billed to the key that holds the opt-in. qumo abr never needs
to know whose broadcast it transcodes.

- relay: optInClock counts each checked session's opt-in announcements
  while they last; the lease sends its totals with each revalidate and
  reportEnd with the end (auth.Request.OptIns).
- auth: a publisher's records carry them; a viewer's total does not.
- optin.Of names the egress a path opts into; ingest uses it too.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01KPWMJL7PH3rPhK5UTGavaB
A publisher that opted anything in sent a usage record at every revalidate,
even with no bytes moved and under a whole second opted in. It now reports
only when a metric is positive, as before #613 for bytes.

The opt-in clock reads time.Now itself; its tests run in a synctest bubble
instead of passing a fake clock through the constructor. TestOf uses
subtests; two doc comments are rewrapped.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01KPWMJNAzsnsiqRPREa2JqY
okdaichi added a commit that referenced this pull request Nov 18, 2026
The opt-in clock now lives in internal/optin: NewClock takes no clock and
its tests run in a synctest bubble, as in #613.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01KPWMJNAzsnsiqRPREa2JqY

This branch has not been deployed

No deployments
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.

2 participants