Skip to content

feat(ingest): report each pushed stream's usage under its publisher's key - #614

Open
okdaichi wants to merge 3 commits into
ccr-2161bc2c-wkewvo-optin-secondsfrom
ccr-2161bc2c-wkewvo-ingest-usage
Open

okdaichi wants to merge 3 commits into
ccr-2161bc2c-wkewvo-optin-secondsfrom
ccr-2161bc2c-wkewvo-ingest-usage

Conversation

@okdaichi

Copy link
Copy Markdown
Collaborator

Description

Step 3 of usage metering, stacked on #613 (which is stacked on #608). Merge those first; GitHub then retargets this PR to main.

A stream pushed over RTMP or RTSP reaches the relay over the ingest's own session, under the ingest's key, so the relay can't bill it to its publisher. With QUMO_USAGE_URL and QUMO_AUTH_KEYS, qumo rtmp and qumo rtsp-push now report each stream themselves, under the kid of the token that granted the push. This is the rule used for all metering: usage goes to the kid of the tenant token the server itself verified.

Each stream sends, through internal/meter (#608):

  • a session_open;
  • a usage record every 30 s;
  • a session_close.

The records carry:

  • ingest.media_bytes (usage.IngestMediaBytes): the media the ingest took in, the payload of every frame without the protocol around it;
  • gateway.opt_in_seconds.abr and .hls: how long the ingest kept the broadcast opted into each egress on the publisher's behalf.

Related Issue

Follows #608 and #613. Step 4 (hls) comes next.

Changes

  • ingest.PublishAuthorizer returns a Permission: the lapse, as before, plus the kid of the key that granted the push. The verifying authorizer fills it from auth.Grant.KeyID().
  • ingest.Session:
    • counts the media pushed into it (PushVideo, PushAudio, PushAudioFrames);
    • counts its opt-in time (Usage).
  • meterStream:
    • reports one stream: open, every 30 s, then close;
    • does nothing without a meter or without a kid (auth off).
  • Wiring:
    • RTMPConfig.Meter and RTSPConfig.Meter.
    • An RTSP ANNOUNCE that replaces a session closes the old session's report.
    • QUMO_USAGE_URL is read by the ingest commands and refused without QUMO_AUTH_KEYS.
    • The meter sends what is left after the server shuts down.
    • The startup banner shows the usage URL.
  • optin.Clock: the opt-in clock from feat(relay): report how long each publishing session kept broadcasts opted into HLS and ABR #613 moved from internal/relay to internal/optin; the relay and the ingest both use it.
  • Docs: cli/rtmp.md and cli/rtsp-push.md (a Usage section and the QUMO_USAGE_URL row), and configuration (an opt-in through ingest is billed by the ingest, not by the relay). CHANGELOG (Added).

RTSP pull (qumo rtsp) presents no publisher token, so it reports nothing; the operator configures that stream.

Testing

  • Unit:
    • Session.Usage counts the payload bytes of every push method and the opt-in time.
    • meterStream: an open, then a close under the kid with the media bytes and the opt-in seconds; nothing without a meter or a kid.
    • The RTMP server reports a granted stream under the granting key and a refused one not at all.
    • authorizeAny and publishAuthorizer return the kid of the credential that granted the push.
    • Ingest, optin and relay tests pass with -race.
  • Integration: TestIngest_ReportsUsage runs ffmpeg → RTMP ingest with two tokens (broadcast and ABR opt-in) checked against a key set.
    • The session_close is under the tenant's kid, carries ingest.media_bytes > 0, and carries gateway.opt_in_seconds.abr between 2 and 6 after a 2.2 s opt-in.
    • The test fails with the RTMP metering switched off.
  • Suites: go test ./... passes; golangci-lint reports 0 issues; the whole internal/integration suite passes (176 s).

Checklist

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

Generated by Claude Code

claude and others added 3 commits November 18, 2026 11:54
… key

With QUMO_USAGE_URL and QUMO_AUTH_KEYS, qumo rtmp and qumo rtsp-push send
each stream to the usage URL as a relay sends a publishing session: an
open, usage every 30 s and a close, under the kid of the token that
granted the push, with the media the ingest took in (ingest.media_bytes)
and how long it kept the broadcast opted into each egress. The relay only
sees the ingest's own session, so a stream pushed over RTMP or RTSP is
billed to its publisher here.

- ingest.PublishAuthorizer returns a Permission: the lapse, and the kid
  of the key that granted it.
- Session counts the media pushed into it and its opt-in time (Usage).
- The opt-in clock moved from the relay to internal/optin (optin.Clock),
  which both use.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01KPWMJL7PH3rPhK5UTGavaB
…hare the whole-seconds rule

TestRTMPServer_Meter flushed the meter once the broadcast was announced,
but the stream's usage report opens after that, so the sink often got
nothing. It now flushes until the open arrives.

TestMeterStream runs its stream in a synctest bubble instead of sleeping
for real time.

The rule turning opt-in time into whole-second metrics was written in
both auth and ingest; optin.AddSeconds is now the one copy.

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