diff --git a/quest/m0/3588-anonymous-publisher-parked.md b/quest/m0/3588-anonymous-publisher-parked.md new file mode 100644 index 00000000000..28582fdc87b --- /dev/null +++ b/quest/m0/3588-anonymous-publisher-parked.md @@ -0,0 +1,58 @@ +# [M] moq-net: an anonymous publisher is parked behind its own minted id + +## Goal + +On main, when an anonymous publisher's session ends without a graceful +unannounce and another anonymous session announces the same path while the +front lingers, the newcomer takes the path over and a subscriber on any other +session gets its media. Today the newcomer is parked until the linger expires +and every subscriber gets 404 `dropped` meanwhile, which costs eight cells of +the nightly interop matrix and every reconnect on a released relay. Boundary: +a newcomer arriving while the old session is still open keeps waiting for it +to end, because a relay cannot tell an anonymous handoff from an anonymous +reflection, and evicting a live incumbent on a reflected announce is a loop. +Established ids keep taking over immediately, as today. Fix on main; dev +deleted the gate. + +## Plan + +#3042 mints `Origin::random()` for every accepted session that declares no +identity, so routes learned on it are not advertised back to it. That is all +`drafts/draft-lcurley-moq-cluster.md` asks of an assigned id, and the +reflection gate must keep counting it: a peer we advertised a live path to, +which then announces that path under the id we minted for it, is reflecting +our content. The defect is one step earlier. A new session is advertised the +lingering front before it announces anything, `AnnounceConsumerNotify::announce` +registers an `ExclusionGuard` for the freshly minted id in +`FrontState::excluded`, the peer's own announce is stamped `hops = [id]`, and +`attach_source` in `rs/moq-net/src/model/origin.rs` parks it as a reflection. +A front with no live route has nothing to reflect. + +- A lingering front, one whose `routes` are empty and whose linger is what + keeps it open, is not advertised to announce consumers that attach after + its last route left, and registers no exclusion for them. It is advertised + again the moment a route joins. Consumers that were advertised it while it + was live keep their guards, so a reflection from any of them stays parked + and the linger closes the front as today. The resolve path keeps + registering guards: a subscriber is a real reader. +- With no guard for the newcomer, its announce is untainted and the existing + takeover branch closes the lingering incumbent and announces the new front, + which is the "newest publisher wins" rule main already applies to + established ids. +- Regression tests: two anonymous sessions on one relay where the publisher + session dies without unannouncing and a new one announces the same path + during the linger; a third anonymous session subscribes and gets media with + zero parking events. A reflection test in the same shape: the peer that was + advertised the path while it was live announces it back after the + publisher dies, stays parked, and the front closes when the linger expires. + `test_reflection_through_an_exposed_peer_cannot_take_over` and its rival + test in `origin.rs` keep passing unchanged. Run `just test smoke-full`; its + draft-18 clients hit this. +- dev is unaffected: #2704 removed the linger and #3225 deleted + `FrontState::excluded`, `taints_a_reader`, and parking, so a front closes + with its last source and reflection is the chain test against the relay's + own hop. Nothing to port at [merge dev](/quest/m1/merge-dev.md). + +## Closes + +- [#3588](https://github.com/moq-dev/moq/issues/3588) - close this issue when the quest finishes diff --git a/quest/m0/README.md b/quest/m0/README.md index 65e20afa2c4..0b8f6dc7172 100644 --- a/quest/m0/README.md +++ b/quest/m0/README.md @@ -18,6 +18,7 @@ regression test per Root Cause First. - [Audio jitter target](/quest/m0/audio-jitter-target/README.md) - the audio playout target is a measured, ported estimate of arrival timing in both languages, not a round-trip guess - [Jitter estimator](/quest/m0/3479-mux-jitter-flush-span.md) - moq-mux: catalog jitter is the publisher's maximum flush span, never a running minimum - [WebKit gate](/quest/m0/webkit-webtransport-gate.md) - js/net: every WebKit engine takes the WebSocket path, not just the Safari brand, so iOS Chrome and Firefox stop freezing after two minutes +- [Anonymous handoff](/quest/m0/3588-anonymous-publisher-parked.md) - moq-net: a lingering front is not advertised to sessions that arrive after its publisher left, so the next anonymous publisher takes the path over instead of being parked as a reflection - [IETF error codes](/quest/m0/ietf-error-codes.md) - every code on a moq-transport wire is a registered value for the negotiated draft, requests and stream resets alike - [Publisher priority](/quest/m0/3534-ietf-publisher-priority.md) - moq-net: a track's publisher priority survives a moq-transport hop instead of being flattened to 0 - [TRACK_STATUS refusal](/quest/m0/3492-ietf-track-status-refusal.md) - moq-net: TRACK_STATUS gets a NOT_SUPPORTED refusal instead of a silent drop diff --git a/quest/m2/3087-relay-mtls-peers-bypass-auth-api-mode-so-proxy-grants.md b/quest/m2/3087-relay-mtls-peers-bypass-auth-api-mode-so-proxy-grants.md deleted file mode 100644 index b1979817e59..00000000000 --- a/quest/m2/3087-relay-mtls-peers-bypass-auth-api-mode-so-proxy-grants.md +++ /dev/null @@ -1,59 +0,0 @@ -# [M] relay: mTLS peers bypass the auth API mode, so a proxy grant cannot refuse or scope them - -## Goal - -An mTLS peer is authorized through the same auth API path as every other -connection. In proxy mode the endpoint's grant, or its absence, decides what -the peer may publish and subscribe; in token mode a certificate-authenticated -peer with no grant stays unrestricted, so a deployment answering -`{alias, tier}` today is unaffected. Fixes on dev, where the mode lands. - -## Plan - -`Auth::verify_mtls` in `rs/moq-relay/src/auth.rs` calls `resolve_mtls`, which -builds its own `AuthApiRequest`, reads only `alias` and `tier` off the reply, -and mints `AuthToken::unrestricted`. Nothing the endpoint returns can narrow -that, and the request carries no `host`, so host-routed tenants dialing the -same path are indistinguishable at the endpoint. - -- Delete `resolve_mtls`. Build the request through `api_request` with - `mtls` set, plus `host` in proxy mode as the mode already sends it, and - resolve through `authorize`, so a grant is read one way for every credential. -- Send the peer's identity beside the flag: `mtls=true` stays exactly as - documented, since deployed endpoints compare it literally, and a new - `mtls_name=` carries the client certificate's first SAN DNS name (the - CN when it has none), so the endpoint can tell peers apart and issue a - per-peer grant. `moq_tokio::tls::PeerIdentity` grows a name accessor beside - `expiry`, parsed with the `x509-parser` it already uses. A certificate with - neither sends the flag alone, and the docs say the name is a value the - endpoint matches, never proof by itself; the CA that signed the cert is. - The name has to reach `verify_mtls` on every transport: QUIC keeps a - `PeerIdentity` on the request, but the HTTPS and WebSocket path reduces the - verified chain to the unit `MtlsPeer` marker in `rs/moq-relay/src/web.rs`, - so that marker carries the identity too. -- Token mode: `mtls: true` satisfies "has a credential" without a JWT or a - `key`; the certificate is the token. No grant means unrestricted, as today. -- Proxy mode: the endpoint returns a grant like anyone else, and no grant is a - refusal, consistent with the rest of the mode. -- `revalidate` stays `None` for mTLS peers, which the "mTLS peers must never - revalidate" test already pins. A deployed endpoint sending a blanket - `Cache-Control: max-age` would otherwise arm revalidation across a production - relay mesh the moment this ships, gating fleet interconnect on that endpoint - staying reachable. Mesh revalidation is its own change: an explicit opt-in - for `mtls=true` and a relay-side floor on the staleness window. Note - `stale-if-error` alone is not enough, since an endpoint that successfully - answers "no" still partitions the mesh. -- Tests: a proxy-mode mTLS peer refused by an empty reply, scoped by a narrow - grant, and admitted unrestricted in token mode; `host` present on the proxy - request; `mtls=true` unchanged with `mtls_name` carrying the SAN name over - both QUIC and WebSocket, the CN for a certificate with no DNS SAN, and - absent for a nameless cert. - Update the mTLS and auth API sections of `doc/bin/relay/auth.md`. - -## Required - -- [Auth verdict](/quest/m2/auth-verdict.md) - lands the proxy mode, the grant response, and the `host` field this builds on - -## Closes - -- [#3087](https://github.com/moq-dev/moq/issues/3087) - close this issue when the quest finishes diff --git a/quest/m2/3489-ts-import-stream-liveness.md b/quest/m2/3489-ts-import-stream-liveness.md index d410b17a4dc..8865925a879 100644 --- a/quest/m2/3489-ts-import-stream-liveness.md +++ b/quest/m2/3489-ts-import-stream-liveness.md @@ -33,7 +33,7 @@ audio half is visible, late, through #3372's resync line. [SRT import stats](/quest/m2/srt-import-stats.md). - Name and shape the counters so the TR 101 290 quest adopts them as its `PID_error` check, and leave the catalog `stalled` bit alone; that is the - ladder and publisher-stats work. + ladder and client stats work. - Tests with the issue's stimulus shape: suppress one PID's PES while keeping its PCR and continuity legal, assert the row's count stops and the gap grows; audio and SCTE-35 arms. @@ -46,4 +46,4 @@ audio half is visible, late, through #3372's resync line. - [SRT import stats](/quest/m2/srt-import-stats.md) - the same rows read from the SRT gateway - [#1838](/quest/m3/1838-tr-101-290-monitoring-requirements-broadcast-contribution.md) - the monitoring model that subsumes this as `PID_error` -- [Publisher stats](/quest/m2/qos/publisher-stats.md) - where per-rendition liveness would ride the catalog +- [Client stats](/quest/m2/qos/stats/schema.md) - where per-rendition liveness rides a publisher's stats broadcast diff --git a/quest/m2/README.md b/quest/m2/README.md index cb73710a275..3be413084c4 100644 --- a/quest/m2/README.md +++ b/quest/m2/README.md @@ -22,10 +22,11 @@ can act on. Each still carries its own plan and regression test. - [Wildcard](/quest/m2/wildcard/README.md) - a service advertises a path pattern it could serve instead of enumerating broadcasts - [Path patterns](/quest/m2/path-patterns/README.md) - one versioned matcher for every predicate over broadcast paths: tokens, origins, interest - [In-band auth](/quest/m2/auth/README.md) - a session tells its peer what it may publish and subscribe to, unions tokens presented in band, and fails loud on an out-of-scope publish +- [Auth API](/quest/m2/auth-api/README.md) - the relay's auth endpoint names mTLS peers, scopes them explicitly on v1, moves a tier in place, and says once when revalidation is off - [OBS native codecs](/quest/m2/obs-moq-video/README.md) - remove FFmpeg decoding dependencies, deliver GPU frames, and use native audio/video encoders - [Audio codecs](/quest/m2/audio-codecs/README.md) - a broadcast that plays in the browser plays natively: platform decoders and encoders behind a backend seam, HE-AAC, and channel layouts up to 7.1 - [Keyframe trigger](/quest/m2/keyframe-trigger.md) - an application can ask the built-in capture encoder for a keyframe -- [QoS](/quest/m2/qos/README.md) - broadcast health from the relay: viewer starvation and publisher timeliness histograms, publisher stats, viewer feedback +- [QoS](/quest/m2/qos/README.md) - broadcast health: relay starvation and timeliness histograms, and client stats broadcasts from publishers and viewers - [Drain](/quest/m2/drain/README.md) - relay restarts drain sessions over GOAWAY instead of hard-dropping them - [Custom QUIC](/quest/m2/quic/README.md) - noq as the upstream for per-stream ACK progress, reliable reset, hierarchical scheduling, and qmux @@ -81,7 +82,6 @@ can act on. Each still carries its own plan and regression test. - [#2907](/quest/m2/2907-bind-the-browser-through-moq-ffi-uniffi-instead-of-a.md) - Bind the browser through moq-ffi/UniFFI instead of a second hand-written wasm API - [#2850](/quest/m2/2850-js-net-give-reader-a-synchronous-decode-so-the-publisher.md) - js/net: decode messages synchronously from buffered bytes and delete the publisher read-ahead queue (dev) - [Cluster flags](/quest/m2/cluster-flags.md) - a discovery mechanism carries its own prerequisites, so an incomplete cluster config cannot be expressed -- [Revalidation updates](/quest/m2/revalidation-updates.md) - an auth re-check moves the tier in place and names an alias change when it closes the session - [#3137](/quest/m2/3137-moqsrc-bound-the-pending-rendition-subscriptions-a.md) - moqsrc: bound the pending rendition subscriptions a catalog can open - [#3115](/quest/m2/3115-moqsink-the-publication-has-no-generation-so-a-flush.md) - moqsink: a flushing restart after EOS opens a new publication generation - [#709](/quest/m2/709-automatic-letsencrypt-support.md) - the relay provisions and renews its own ACME certificate over HTTP-01, persisted on disk @@ -89,8 +89,6 @@ can act on. Each still carries its own plan and regression test. - [Runtime QA hosts](/quest/m2/runtime-qa-hosts.md) - run exact source snapshots on accessible Linux and device hosts with retrievable debug evidence - [Media QA on other engines](/quest/m2/browser-media-qa-engines.md) - the media harness measures a Firefox or WebKit player over the fallback and names what each engine lacks - [LiveKit shim](/quest/m2/livekit-shim.md) - a drop-in livekit-client-compatible package running rooms over MoQ -- [Auth verdict](/quest/m2/auth-verdict.md) - the relay hands an opaque credential to its auth API and is told the grant; lands as the proxy mode in #3044 -- [#3087](/quest/m2/3087-relay-mtls-peers-bypass-auth-api-mode-so-proxy-grants.md) - relay: mTLS peers bypass the auth API mode, so a proxy grant cannot refuse or scope them - [#1310](/quest/m2/1310-why-use-the-worklet-plugin.md) - why use the worklet plugin? - [Ship capture and playback](/quest/m2/cli-packaging.md) - a released moq binary can capture and play, which no distribution currently enables - [Windows capture parity](/quest/m2/capture-windows.md) - window, app, system-audio and cursor capture on Windows diff --git a/quest/m2/auth-api/README.md b/quest/m2/auth-api/README.md new file mode 100644 index 00000000000..d25e495c13a --- /dev/null +++ b/quest/m2/auth-api/README.md @@ -0,0 +1,52 @@ +# Auth API + +## Goal + +`--auth-api` decides every connection the relay admits, with one request and +reply contract for every credential kind, and the relay asks the endpoint as +rarely as it can. Today an mTLS peer is admitted to whatever it dials with +publish and subscribe unscoped, the endpoint is told only that some +certificate was verified, a revalidation reply cannot move a session's tier, +and an endpoint that names no `max-age` turns revalidation off without a +trace. This line closes those gaps on the HTTP contract; the wire side is +[In-band auth](/quest/m2/auth/README.md). + +## Plan + +The caching model every quest here keeps: + +- Token mode: the request depends on (root, `kid`, transport), so an audience + sharing a signing key is one cached request per relay, however many viewers + arrive at once. +- Proxy mode: the credential is part of the request and the reply is cached + per credential, so auth cost tracks distinct credentials, not viewers. +- mTLS: the request carries the peer's identity and the reply is cached per + (root, identity, transport). Not unrestricted by default once the endpoint + speaks v1; never revalidated, so an endpoint outage cannot partition the + mesh. +- Revalidation rides the admission cache, so a re-check can be answered from + an entry up to one `max-age` old and the revocation window is up to twice + `max-age`, floored at one second. That belongs in operator documentation, + not a doc comment. + +`--auth-api-mode proxy` landed on dev in #3044, and the quest that planned it +is deleted. Everything here branches from dev unless a quest says main. + +## Quests + +- [mTLS identity](/quest/m2/auth-api/mtls-identity.md) - an mTLS peer is + authorized through the auth API like any other connection, named by its + certificate, and a proxy grant can scope or refuse it +- [mTLS explicit scope](/quest/m2/auth-api/mtls-scope.md) - a v1 reply must + grant an mTLS peer its scope; unrestricted survives only for unversioned + endpoints +- [Revalidation updates](/quest/m2/auth-api/revalidation-updates.md) - a + re-check moves the tier in place, names an alias change, and a reply that + disables revalidation says so once + +## Related + +- [Relay auth](/quest/m2/path-patterns/relay-auth.md) - versions the grant + shape and resizes a live session; mTLS explicit scope rides its v1 +- [In-band auth](/quest/m2/auth/README.md) - the AUTH stream, where a + credential can arrive after the connection diff --git a/quest/m2/auth-api/mtls-identity.md b/quest/m2/auth-api/mtls-identity.md new file mode 100644 index 00000000000..9977fcbd92e --- /dev/null +++ b/quest/m2/auth-api/mtls-identity.md @@ -0,0 +1,69 @@ +# [M] An mTLS peer is authorized through the auth API + +## Goal + +A peer that presented a client certificate is authorized through the same +auth API request as every other connection, and the endpoint learns which +certificate: `mtls=` replaces `mtls=true`. In proxy mode the +endpoint's grant, or its absence, decides what the peer may publish and +subscribe; in token mode a certificate-authenticated peer with no grant stays +unrestricted until [mTLS explicit scope](/quest/m2/auth-api/mtls-scope.md), +so an endpoint answering `{alias, tier}` today keeps that reply shape. The +request side is a breaking change to the endpoint contract: an endpoint that +compares `mtls` to the literal `true` must accept any non-empty value before +its relays upgrade. Replies cache per identity. On dev, where the mode lives +and where breaking changes go. + +## Plan + +`Auth::verify_mtls` in `rs/moq-relay/src/auth.rs` calls `resolve_mtls`, which +builds its own `AuthApiRequest` carrying `mtls: true` and nothing else about +the peer, reads only `alias` and `tier` off the reply, discards the cache +hints, and mints `AuthToken::unrestricted`. The party being scoped picks the +scope, because the root is the path the client dialed. + +- Delete `resolve_mtls`. Build the request through `api_request` and resolve + through `authorize`, so a grant is read one way for every credential, with + `host` in proxy mode as the mode already sends it. +- `mtls=` names the peer: the leaf certificate's first SAN DNS + name, the CN when it has none, and the leaf's SHA-256 fingerprint when it + has neither, so the value is never empty. `moq_tokio::tls::PeerIdentity` + grows `name()` beside `expiry()` and `fingerprint()`, parsed with the + `x509-parser` it already uses. The docs say the identity is a value the + endpoint matches, never proof by itself; the CA that signed the chain is. + This replaces the documented `mtls=true`, and an endpoint that compares + the literal breaks for every mTLS peer, cluster peers included, until it + accepts any non-empty value. The auth API section of `doc/bin/relay/auth.md` + states the new value, the migration (accept non-empty first, then upgrade + relays), and the release note carries it as breaking. +- The identity has to reach `verify_mtls` on every transport: QUIC keeps a + `PeerIdentity` on the request, but the HTTPS and WebSocket path reduces the + verified chain to the unit `MtlsPeer` marker in `rs/moq-relay/src/web.rs`, + so that marker carries the identity too. +- Caching: the identity is in the query, so the shared HTTP cache and the + in-flight coalescing already key on it: one request per (root, identity, + transport), however many sessions that peer opens. `revalidate` stays + `None` for mTLS peers, which the "mTLS peers must never revalidate" test + pins: a deployed endpoint sending a blanket `Cache-Control: max-age` would + otherwise arm revalidation across a relay mesh the moment this ships. Mesh + revalidation is its own change, an explicit opt-in per identity plus a + relay-side floor on the staleness window; `stale-if-error` alone is not + enough, since an endpoint that answers "no" still partitions the mesh. +- Token mode: `mtls` satisfies "has a credential" without a JWT or a `key`; + no grant means unrestricted, as today. Proxy mode: the endpoint returns a + grant like anyone else, and no grant is a refusal. +- Tests: a proxy-mode mTLS peer refused by an empty reply, scoped by a narrow + grant, and admitted unrestricted in token mode; `host` present on the proxy + request; the SAN name, the CN for a certificate with no DNS SAN, and the + fingerprint for a nameless one, over both QUIC and WebSocket; two sessions + from one identity produce one endpoint request. Update the mTLS and auth + API sections of `doc/bin/relay/auth.md`. + +## Closes + +- [#3087](https://github.com/moq-dev/moq/issues/3087) - close this issue when the quest finishes + +## Related + +- [mTLS explicit scope](/quest/m2/auth-api/mtls-scope.md) - removes the + unrestricted default once the endpoint speaks v1 diff --git a/quest/m2/auth-api/mtls-scope.md b/quest/m2/auth-api/mtls-scope.md new file mode 100644 index 00000000000..91dfb4b2834 --- /dev/null +++ b/quest/m2/auth-api/mtls-scope.md @@ -0,0 +1,41 @@ +# [M] A v1 reply grants an mTLS peer its scope explicitly + +## Goal + +An endpoint that answers a v1 grant to an `mtls=` request decides +that peer's publish and subscribe scope in every mode, and an absent or empty +grant refuses it. `AuthToken::unrestricted` is minted only for an unversioned +reply, kept for endpoints that predate v1, and the docs say the door is open +there. A cluster peer dialing `/` is scoped like anyone else: its endpoint +grants everything explicitly. On dev. + +## Plan + +[Relay auth](/quest/m2/path-patterns/relay-auth.md) versions the auth API +grant shape: unversioned replies are v0 prefixes, v1 carries pattern grants. +This quest rides that v1 rather than inventing a version for mTLS. + +- `authorize` scores an mTLS reply by version: v1 requires a grant and maps + it onto the token's publish and subscribe patterns in both modes; v0 keeps + today's alias and tier lookup and mints `unrestricted`, logging once per + relay that mTLS peers are unrestricted because the endpoint is unversioned. +- The cluster keeps working on a v1 endpoint only when that endpoint grants + the relay's own identity `[""]` for both; document that in + `doc/bin/relay/cluster.md` beside the mTLS recommendation, and make the + smoke cluster fixture's stub endpoint answer v1. +- `revalidate` stays `None` for mTLS peers, as the identity quest settles. +- Tests: a v1 empty grant refuses a peer in token mode; a v1 narrow grant + scopes it; a v0 reply still admits it unrestricted with the one-line log; + a cluster peer granted everything syncs. The mTLS section of + `doc/bin/relay/auth.md` states the outcome per version. + +## Required + +- [mTLS identity](/quest/m2/auth-api/mtls-identity.md) - the request the + grant answers +- [Relay auth](/quest/m2/path-patterns/relay-auth.md) - the versioned grant + shape + +## Closes + +- [#3603](https://github.com/moq-dev/moq/issues/3603) - close this issue when the quest finishes diff --git a/quest/m2/revalidation-updates.md b/quest/m2/auth-api/revalidation-updates.md similarity index 66% rename from quest/m2/revalidation-updates.md rename to quest/m2/auth-api/revalidation-updates.md index 7033216483e..fe1c66ab9f3 100644 --- a/quest/m2/revalidation-updates.md +++ b/quest/m2/auth-api/revalidation-updates.md @@ -1,4 +1,4 @@ -# [M] An auth re-check moves the tier and names an alias change +# [M] An auth re-check moves the tier, names an alias change, and says when it is off ## Goal @@ -8,8 +8,11 @@ under the old one, and the session stays up. A reply that changes `alias` still closes the session, but with its own expiry reason in the log and to the client instead of a generic revocation, so a benign rename is distinguishable from a refusal. Scope narrowing keeps the -[relay auth](/quest/m2/path-patterns/relay-auth.md) contract, and -`doc/bin/relay/auth.md` states the outcome per field. +[relay auth](/quest/m2/path-patterns/relay-auth.md) contract. An endpoint +reply that schedules no re-check is logged once, so a relay whose revalidation +is off no longer looks like one whose endpoint has never revoked anything, and +`doc/bin/relay/auth.md` states the outcome per field and the revocation window +an operator can actually get. ## Plan @@ -40,19 +43,30 @@ and meters, so rebuilding a local handle would retag nothing. meter through an already-cloned handle and leaves earlier bytes where they were; a re-check that changes the alias closes with `Expired::Alias`; a reply that changes both closes. +- A reply that schedules no re-check (no `max-age`, `max-age=0`, `no-cache`, + `no-store`, or a value the relay cannot parse) is the endpoint opting out, + and stays so. The relay says it once: the first such reply from an endpoint + logs at WARN that sessions admitted under it are never re-checked and end + only at their credential's `exp`. One line per relay, never per session. - Docs: the revalidation section of `doc/bin/relay/auth.md` gains a per-field table: tier updates in place, alias closes, and scope narrowing closes today (`covered_by` failing maps to `Recheck::Revoked`) and resizes once [relay auth](/quest/m2/path-patterns/relay-auth.md) lands; say which is in - effect. + effect. The same section and the `--auth-api` flag help state the cadence + contract where an operator sizes a revocation SLA: `max-age` arms + re-checks, floored at one second; the values above disable them; and + because re-checks ride the admission cache, revocation takes up to twice + `max-age`. The `revalidate` doc comment in `rs/moq-relay/src/auth.rs` on + main repeats one paragraph and claims a 3x staleness window the code does + not have; dev already rewrote it, so take dev's wording. On main, additive. ## Closes - [#3058](https://github.com/moq-dev/moq/issues/3058) - close this issue when the quest finishes +- [#3605](https://github.com/moq-dev/moq/issues/3605) - close this issue when the quest finishes ## Related - [Relay auth](/quest/m2/path-patterns/relay-auth.md) - the scope contract this inherits -- [Auth verdict](/quest/m2/auth-verdict.md) - the proxy mode whose re-check this also governs diff --git a/quest/m2/auth-verdict.md b/quest/m2/auth-verdict.md deleted file mode 100644 index 3cb2a8b63b8..00000000000 --- a/quest/m2/auth-verdict.md +++ /dev/null @@ -1,38 +0,0 @@ -# [L] JWT-free verdict mode - -## Goal - -moq-relay can hand an opaque credential to its auth API and be told the grant, -instead of resolving a `kid` and verifying a JWT locally. Ships as -`--auth-api-mode proxy`. - -## Plan - -[#3044](https://github.com/moq-dev/moq/pull/3044) is the implementation and -targets dev. Landing it completes this quest; delete the quest in that PR. It -settled the design points this quest used to hold open, and they are recorded -here so review does not relitigate them: - -- A mode, not a response shape. Letting one endpoint answer with a `key` for - one connection and a `grant` for another put both paths inside a single - request: which cache key applies, whether the credential may be sent, what - "still vouched for" means. Choosing once per relay deletes all of it. The - mode lives on `AuthApi`, so it rides on a session's grant and a proxy-admitted - session re-checked by a token-mode instance keeps its grant. -- The credential travels as `Authorization: Bearer` on the existing GET. The - relay caches on a SHA-256 of it and declares the cache private, so an endpoint - that forgets `Vary: Authorization` cannot cross-serve grants and the secret - stays out of logs and metrics. -- Refusal is `404`, an empty grant, or in proxy mode a `401`/`403`. Token mode - and anonymous proxy connections carry no credential, so there those statuses - stay an outage rather than disconnecting an audience over a gateway blip. -- Each re-check's `exp` replaces the last. In token mode the JWT's own `exp` is - a ceiling a reply may lower but never raise. -- `--auth-api-mode proxy` excludes `--auth-domain`, and a mode without - `--auth-api` is a startup error. -- `doc/bin/relay/auth.md` carries the mode, refusal statuses, expiry, cache - semantics, and the cost trade: a credential shared across an audience caches - like a `kid`, a per-viewer credential costs a request per viewer. - -What the PR leaves out on purpose is the mTLS path, which still bypasses the -mode; that is [#3087](/quest/m2/3087-relay-mtls-peers-bypass-auth-api-mode-so-proxy-grants.md). diff --git a/quest/m2/auth/relay-refresh.md b/quest/m2/auth/relay-refresh.md index b312bf9c3c6..19fafbb1017 100644 --- a/quest/m2/auth/relay-refresh.md +++ b/quest/m2/auth/relay-refresh.md @@ -75,6 +75,6 @@ Additive. - [Relay auth](/quest/m2/path-patterns/relay-auth.md) - extends the re-scope to a shrinking union -- [Revalidation updates](/quest/m2/revalidation-updates.md) - the tier and +- [Revalidation updates](/quest/m2/auth-api/revalidation-updates.md) - the tier and alias outcomes a re-check has; a token that changes them follows the same rules diff --git a/quest/m2/path-patterns/README.md b/quest/m2/path-patterns/README.md index 8f9d2b231f1..79b7da3e3f8 100644 --- a/quest/m2/path-patterns/README.md +++ b/quest/m2/path-patterns/README.md @@ -80,5 +80,5 @@ represent `pid/*/chat`. - [Wildcard advertisements](/quest/m2/wildcard/README.md) - routing adopts the matcher while retaining its own cost, pool, refusal, and resolution work -- [JWT-free verdict mode](/quest/m2/auth-verdict.md) - verdict grants use the - same versioned publish and subscribe pattern sets +- [mTLS explicit scope](/quest/m2/auth-api/mtls-scope.md) - an mTLS grant + uses the same versioned publish and subscribe pattern sets diff --git a/quest/m2/qos/README.md b/quest/m2/qos/README.md index cc26e5f3292..644f61f24ff 100644 --- a/quest/m2/qos/README.md +++ b/quest/m2/qos/README.md @@ -5,8 +5,8 @@ Publishers, relays, and viewers report the telemetry that broadcast health and congestion views need: how far behind viewers are according to what the network has acknowledged, how timely publishers are against their own media -clock, publisher-reported media stats, sender-side transport health, and -sampled viewer feedback. Together they can drive an +clock, and what publishers and viewers report for themselves in their own +stats broadcasts. Together they can drive an unknown/healthy/degraded/unhealthy verdict per broadcast with congestion visible for viewers in aggregate, the way CMSD does for HLS. @@ -19,10 +19,13 @@ what a health verdict has to mean. Neither is useful alone: delivery without media context cannot tell a slow viewer from a keyframe burst, and media without delivery cannot tell congestion from a publisher that stopped. -Everything here is distilled per broadcast on the existing `moq-stats` keys. -No per-subscriber or per-session row reaches the wire: many subscriptions -collapse into byte-weighted cumulative histograms, which stay monotonic and -merge-patch friendly, and which any consumer can diff into a distribution. +Everything the relay reports is distilled per broadcast on the existing +`moq-stats` keys. No per-subscriber or per-session row reaches the wire from +the relay: many subscriptions collapse into byte-weighted cumulative +histograms, which stay monotonic and merge-patch friendly, and which any +consumer can diff into a distribution. Clients report for themselves, each in +its own `.stats` broadcast on the same layout, so viewer feedback costs +bandwidth only where a publisher or dashboard chose to read it. The counters and channels land here. The moq.pro (downstream) dashboard work, including the health badge, connection-health drill-down, and stream @@ -39,9 +42,6 @@ preflight, consumes them downstream. - [Publisher timeliness](/quest/m2/qos/publisher-timeliness.md) - per broadcast, how late media arrives at the relay against the track's own clock, and whether timestamps stay monotonic -- [Publisher media stats](/quest/m2/qos/publisher-stats.md) - a publisher - reports media cadence and bitrate in its catalog -- [Publisher connection transport](/quest/m2/qos/publisher-transport.md) - a - publisher reports sender transport health on a relay-bound session channel -- [Viewer feedback](/quest/m2/qos/viewer-feedback.md) - sampled per-viewer QoS - reaches consumers, so health reflects what viewers experienced +- [Client stats](/quest/m2/qos/stats/README.md) - publishers and viewers + report their own media, transport, and playback health in `.stats` + broadcasts on the moq-stats layout, and a Rust encoder adapts to its viewers diff --git a/quest/m2/qos/publisher-stats.md b/quest/m2/qos/publisher-stats.md deleted file mode 100644 index 8c8330aaccc..00000000000 --- a/quest/m2/qos/publisher-stats.md +++ /dev/null @@ -1,32 +0,0 @@ -# [M] Publisher-reported media stats - -## Goal - -A publisher reports its own media stats in a catalog section a monitoring -consumer can read: bitrate, frame cadence, and what the publisher thinks it is -sending. - -## Plan - -Implement [#2734](https://github.com/moq-dev/moq/issues/2734): a -publisher-reported stats track carried as a catalog stats section. This is the -MEDIA half of a broadcast health verdict, bitrate, frame cadence, and what the -publisher thinks it is sending, as opposed to the transport backlog. - -Version the section so older publishers remain usable without fabricating -media health. Reject malformed or implausible samples, classify missing or -stale telemetry as unknown, and treat the self-report as diagnostics only, -never as billing, authorization, or route-selection input. - -Land the catalog section, publisher API, fixtures, and tests. No PR exists -yet, so writing the implementation is this quest's work and nothing external -gates a start. The moq.pro (downstream) health badge consumes the released -section downstream. - -Independent of [starvation](/quest/m2/qos/starvation.md): the two halves land in -either order, and a health verdict needs both. Keep connection-scoped sender -transport in its own quest because it has a different wire owner and consumer. - -## Closes - -- [#2734](https://github.com/moq-dev/moq/issues/2734) - close this issue when the quest finishes diff --git a/quest/m2/qos/publisher-timeliness.md b/quest/m2/qos/publisher-timeliness.md index f272e30422d..37366a51d28 100644 --- a/quest/m2/qos/publisher-timeliness.md +++ b/quest/m2/qos/publisher-timeliness.md @@ -53,5 +53,5 @@ excluded. - [Starvation](/quest/m2/qos/starvation.md) - the egress half, same histogram shape -- [Publisher connection transport](/quest/m2/qos/publisher-transport.md) - - the publisher's own view of the same uplink +- [Client stats](/quest/m2/qos/stats/schema.md) - the publisher's own view + of the same uplink, in the transport section of its stats broadcast diff --git a/quest/m2/qos/publisher-transport.md b/quest/m2/qos/publisher-transport.md deleted file mode 100644 index 4c84a989a4c..00000000000 --- a/quest/m2/qos/publisher-transport.md +++ /dev/null @@ -1,28 +0,0 @@ -# [M] Publisher connection transport - -## Goal - -A native MoQ publisher reports its sender-side transport health on a -connection-scoped channel, so each redundant publisher connection has an -independent RTT, bandwidth, loss, and traffic sample regardless of route -selection. - -## Plan - -Add a connection-scoped diagnostic channel for the publisher's -`ConnectionStats` upload sample: RTT, estimated send bandwidth, congestion or -loss counters, traffic-rate deltas, sampling interval, and sample age. The -receiving relay binds each sample to the authenticated session and its own -process-local connection id; the publisher cannot name another connection. -Do not route this channel as a broadcast or catalog track. - -Keep publisher-reported values visibly distinct from relay-observed subscriber -stats, reject malformed or implausible samples, and let consumers classify -missing or stale telemetry as unknown. Treat the self-report as diagnostics -only, never as billing, authorization, or route-selection input. Version the -channel so older publishers remain usable without fabricating transport health. - -Test a rate-limited and lossy publisher whose sender-side health degrades while -relay outbound control traffic remains small. With two redundant publisher -sessions for one broadcast, prove each relay-local connection retains its own -sample regardless of selected route. diff --git a/quest/m2/qos/starvation.md b/quest/m2/qos/starvation.md index 419f3cbc2ee..edffd6e06d6 100644 --- a/quest/m2/qos/starvation.md +++ b/quest/m2/qos/starvation.md @@ -85,5 +85,5 @@ sum into one row; the aggregate consumer sums two nodes bucket by bucket. moves the frontier at every frame end once `poll_acked` is released - [Publisher timeliness](/quest/m2/qos/publisher-timeliness.md) - the ingress mirror on the `Role::Subscriber` rows -- [Viewer feedback](/quest/m2/qos/viewer-feedback.md) - receiver-side - evidence for the same lag +- [Client stats](/quest/m2/qos/stats/README.md) - receiver-side evidence + for the same lag, reported by the viewers themselves diff --git a/quest/m2/qos/stats/README.md b/quest/m2/qos/stats/README.md new file mode 100644 index 00000000000..a4488821c45 --- /dev/null +++ b/quest/m2/qos/stats/README.md @@ -0,0 +1,64 @@ +# Client stats + +## Goal + +Any MoQ client can publish its own stats as a broadcast the way the relay +does: a publisher reports what it sends, a subscriber reports what it received +and played, and a consumer authorized to see them, a dashboard or the publisher +itself, reads them per broadcast. The same `moq-stats` layout carries the +relay's delivery counters and a media client's media counters, so one consumer +reads both, and a broadcast name ending in `.stats` is how a dashboard tells +telemetry from content. Encoders close the loop: a Rust publisher can adapt its +bitrate to what its viewers report. Not here: no wire change, no clock +synchronization, no requirement that any client report, and no relay +involvement beyond routing. + +## Plan + +Decisions settled while planning: + +- **Reuse moq-stats.** `moq_stats::Producer` and `Consumer` take an + extension flattened next to `Traffic` in every per-broadcast entry, the way + `hang::timeline::Record` does; `()` is the relay, `hang::Stats` is a + media client. Old consumers ignore the extra fields; a consumer that knows + the extension reads both halves. A client's `Traffic` comes from the same + registry the relay uses, attached through `Client::with_stats`. +- **One broadcast per client at a path its token allows, ending in + `.stats`**: `pilot/feedback.stats`, `room/alice.stats`. The relay's + `.stats/node/` prefix convention stays; moq-stats documents both. + Reporting is opt-in because reading is: a publisher subscribes to a prefix + it chose, never to every viewer. +- **`publisher.json` and `subscriber.json` stay the everything entry points**, + keyed by broadcast path as the client sees it, so a transcoder's report + attributes each rung to its broadcast. A consumer that wants one broadcast + requests `/subscriber.json` or `/publisher.json` (plus `.z`) + and the producer serves it on demand, the way tier tracks are served + today. On a tiered relay the name is `//...`, matched against + the producer's tier labels longest first; a default-tier broadcast whose + path starts with another tier's label is refused rather than guessed. +- **Counters are cumulative**, like `Traffic`, so `.z` merge-patch deltas stay + small and the aggregate can sum across clients. Gauges, a latency or a + target bitrate, are carried but never summed. +- **Publisher transport rides here.** The publisher role carries a + `transport` section sampled from `ConnectionStats` for the connection the + broadcast is published over, replacing the connection-scoped channel the + QoS line planned. Self-reports are diagnostics: never billing, + authorization, or route-selection input. +- **On dev**, because `moq-stats` is a published crate and the generic + producer is a breaking change, and the moq-json rework there is what the + producers build on. + +## Quests + +- [Schema and library](/quest/m2/qos/stats/schema.md) - moq-stats takes an + extension, serves per-broadcast tracks, and hang defines the media stats +- [Rust reporters](/quest/m2/qos/stats/rust.md) - the CLI, players, and + encoders publish and read `.stats` broadcasts +- [Browser reporters](/quest/m2/qos/stats/js.md) - `@moq/stats` mirrors the + crate, and the browser publisher and player report through it +- [Encoder feedback](/quest/m2/qos/stats/encoder-feedback.md) - a Rust + encoder subscribes to its viewers' stats and adapts its bitrate + +## Closes + +- [#3608](https://github.com/moq-dev/moq/issues/3608) - close this issue when the questline finishes diff --git a/quest/m2/qos/stats/encoder-feedback.md b/quest/m2/qos/stats/encoder-feedback.md new file mode 100644 index 00000000000..27c60094d58 --- /dev/null +++ b/quest/m2/qos/stats/encoder-feedback.md @@ -0,0 +1,45 @@ +# [M] A Rust encoder adapts its bitrate to what its viewers report + +## Goal + +A `moq-video` or `moq-audio` encode producer given a feedback prefix +subscribes to the `.stats` broadcasts announced under it, reads the +per-broadcast subscriber track for the broadcast it publishes, and lowers its +bitrate while viewers report stalls and late frames, beside the congestion +estimate it already follows. Which viewers count is the publisher's choice of +prefix. Keyframe requests stay out. + +## Plan + +- `encode::Config` in `rs/moq-video` and `rs/moq-audio` gains + `feedback: Option`, a handle built from an + `origin::Consumer` and a prefix: it consumes announcements under the + prefix, keeps one `moq_stats::Consumer` per `.stats` broadcast + requesting `/subscriber.json`, and folds the reports into one + signal, the share of viewers stalled over the last interval and their late + frame rate, weighted equally per viewer. Viewers that stop reporting age out + on the stats interval. +- `rate.rs` takes that signal beside the bandwidth estimate: a stalled share + above a threshold steps the target down like a bandwidth drop, recovery + follows the existing attack curve, and the estimate stays the ceiling. + Audio follows the same signal with its narrower ladder. +- `moq import --feedback ` and `moq transcode --feedback ` + wire it; each rung of the ladder reads its own broadcast's track. +- Test with the CLI publishing to a relay and two `moq play --stats` viewers + under the prefix, one throttled through the impairment profile: the target + bitrate drops within two intervals of the throttled viewer reporting stalls + and recovers after it stops. Document the flag in `doc/bin/cli.md` and the + loop in the moq-video README. + +## Required + +- [Schema and library](/quest/m2/qos/stats/schema.md) - the feedback it reads +- [Rust reporters](/quest/m2/qos/stats/rust.md) - the viewers that report and + the CLI it wires + +## Related + +- [Ladder](/quest/m1/ladder/README.md) - the transcode ladder that adapts to + its uplink today +- [Keyframe trigger](/quest/m2/keyframe-trigger.md) - the keyframe request + this loop does not send diff --git a/quest/m2/qos/stats/js.md b/quest/m2/qos/stats/js.md new file mode 100644 index 00000000000..ccb4992ab7d --- /dev/null +++ b/quest/m2/qos/stats/js.md @@ -0,0 +1,41 @@ +# [M] The browser publisher and player report stats + +## Goal + +`@moq/stats` mirrors `moq-stats`: the frame schemas, `Producer`, +`Consumer`, the aggregate, and the `.stats` naming. `@moq/hang` defines the +media stats schema, `` publishes subscriber stats and +`` publisher stats when given a stats path, and the demo +dashboard reads relay stats through the package instead of its own copies. + +## Plan + +- `js/stats`: zod schemas for `Traffic`, `Presence`, and `Stats` with the + extension flattened; snapshot-mode producer pairs (`.json` and `.z`) with + the same delta and compression settings as Rust; the per-broadcast track + served on request through the broadcast's requested-track handle; a + consumer keyed by tier, role, and path; and the aggregate. Fixtures are the + Rust crate's, shared through `js/test`, so the two encoders stay wire + identical. +- `@moq/hang` adds `Stats` in `js/hang/src/stats.ts`, mirroring + `rs/hang/src/stats.rs` field for field. +- `js/watch`: the decoder `Stats` signals grow the counters the schema needs + (late, stalled duration, underruns from the worklet's count, decode errors, + newest timestamp) and a `stats` attribute names the broadcast to publish + at; `js/publish` does the same for the encoder counters, with the + connection's `WebTransport.getStats()` as the transport section. The + existing UI stats panels read the same signals. +- `demo/web/src/stats.ts` drops its hand-written interfaces and + `STATS_PREFIX` for the package, and the demo gains a stats path on both + elements so the media smoke test reads a browser viewer's report through + `moq export stats`. +- `doc/lib/js` documents the package. + +## Required + +- [Schema and library](/quest/m2/qos/stats/schema.md) - the wire shape this + mirrors + +## Closes + +- [#2735](https://github.com/moq-dev/moq/issues/2735) - close this issue when the quest finishes diff --git a/quest/m2/qos/stats/rust.md b/quest/m2/qos/stats/rust.md new file mode 100644 index 00000000000..259f05a2022 --- /dev/null +++ b/quest/m2/qos/stats/rust.md @@ -0,0 +1,42 @@ +# [M] The Rust CLI, players, and encoders report stats + +## Goal + +`moq import --stats ` publishes a `.stats` broadcast reporting what the +import sends, `moq export --stats ` and `moq play --stats ` report +what the player received and played, and `moq export stats ` prints any +stats broadcast, the relay's `.stats/node/` included, as JSON lines. A +publisher of a `.hang` broadcast can learn whether its viewers played it. + +## Plan + +- Counters at the source, in the crates that own the event: the `moq-video` + and `moq-audio` encode producers count frames, bytes, keyframes, and drops; + the decode and render paths count decoded, late, stalled, underruns, and + errors, where `underruns` in `rs/moq-audio/src/playback` is already counted + privately. Each exposes a `stats()` snapshot of cumulative counters; no + callback, no per-frame lock. +- `moq-cli` attaches a `moq_net::stats::Session` to its client through + `Client::with_stats`, folds the codec counters into `hang::Stats` per + broadcast on the stats interval, and publishes through + `moq_stats::Producer` in exact-path mode at the flag's path. + A path that does not end in `.stats` is refused at parse time. The transport section comes from + the connection's `ConnectionStats`. +- `moq export stats ` is a new sink: subscribe the stats broadcast and + print each `publisher.json`, `subscriber.json`, and `sessions.json` frame + as one JSON line tagged with its track, with `--track` selecting one and + `--compressed` reading the `.z` twins. It is the one sink that does not go + through `.hang` catalog discovery, so route it around `catalog_format`. +- `doc/bin/cli.md` documents the flag and the sink. The smoke media test + publishes with `--stats`, plays with `--stats`, and reads both with + `moq export stats`, asserting the subscriber's liveness advances and the + publisher's frame count matches what was sent. + +## Required + +- [Schema and library](/quest/m2/qos/stats/schema.md) - the producer and the + media types + +## Closes + +- [#2734](https://github.com/moq-dev/moq/issues/2734) - close this issue when the quest finishes diff --git a/quest/m2/qos/stats/schema.md b/quest/m2/qos/stats/schema.md new file mode 100644 index 00000000000..25428676cdb --- /dev/null +++ b/quest/m2/qos/stats/schema.md @@ -0,0 +1,64 @@ +# [L] moq-stats takes an extension and hang defines the media stats + +## Goal + +`moq_stats::Producer` publishes a stats broadcast whose per-broadcast +entries are `Traffic` plus an extension `E`, `Consumer` and the aggregate +read it back, any consumer can request one broadcast's entry as its own +track, and `hang::Stats` is the media extension: what a publisher sent and +what a subscriber received and played, per audio and video. The relay is +`Producer<()>` and its wire output does not change. + +## Plan + +- `moq_stats::Ext`: `Serialize + DeserializeOwned + Default + Clone + Merge`, + implemented for `()`. `Merge` is the aggregate's private `Mergeable` made + public with the `Copy` bound dropped; `Traffic` and `Presence` implement it + as they do today. A frame is `BTreeMap>`, where `Stats` + is `Traffic` with `E` flattened beside it; `TrafficFrame` becomes that + alias for `()`. +- An exact-path mode. `ProducerConfig` treats its path as a prefix and + advertises `/node[/]`, so a client asking for + `room/alice.stats` would publish `room/alice.stats/node`, which no longer + ends in `.stats`. `ProducerConfig::at(path)` publishes the broadcast at + exactly that path with no category segment, refusing a path that does not + end in `.stats`; the relay keeps the prefix layout. Test the advertised + path for both modes. +- Per-broadcast tracks: `requested_track_shape` in + `rs/moq-stats/src/produce.rs` accepts + `[/]/{publisher,subscriber}.json[.z]` by matching the + producer's tier labels longest first, and refuses a default-tier path that + starts with another tier's label. The track is a snapshot of that one + entry, emitted on the same interval, and lives while requested under the + existing quotas. `Consumer` gains `traffic_for(tier, role, path)`. +- `hang::Stats { audio, video, transport }` in `rs/hang/src/stats.rs`, one + struct per role folded into sections, every field defaulted and unknown + fields ignored: + - subscriber, per audio and video: bytes and frames received, frames + decoded, frames dropped as late, stalls and stalled duration, audio + underruns, decode errors, the newest media timestamp received and the + wall time it arrived (liveness: exact in media time, as good as the + clock in wall time), and the current playout latency as a gauge; + - publisher, per audio and video: frames, bytes, keyframes, frames dropped + before encode, and the target bitrate as a gauge; + - publisher `transport`: rtt, estimated send rate, bytes and packets lost, + and sample age from `ConnectionStats`, repeated across the broadcasts one + connection carries. + `Merge` sums counters, leaves gauges out of the sum, and keeps the newest + liveness pair. +- Naming: `.stats` as a broadcast suffix, documented in the `moq-stats` + crate docs and `doc/lib/rs/index.md` beside the relay's prefix convention, + with `moq_stats::is_stats(path)` so a dashboard filters telemetry from + content. +- The relay keeps `Producer<()>`; the `[stats]` section of + `doc/bin/relay/config.md` gains the per-broadcast track and its refusal + rule. Fixtures: a relay frame parses as `Stats<()>` and as + `Stats` with the extension defaulted; a media frame parses + under the old `Traffic` with the extension ignored; the aggregate sums two + clients' counters and leaves gauges alone; the per-broadcast track for a + tiered name and a refused ambiguous one. + +## Related + +- [Starvation](/quest/m2/qos/starvation.md) - the relay's delivery counters, + the other half of a health verdict diff --git a/quest/m2/qos/viewer-feedback.md b/quest/m2/qos/viewer-feedback.md deleted file mode 100644 index b254e7c4909..00000000000 --- a/quest/m2/qos/viewer-feedback.md +++ /dev/null @@ -1,27 +0,0 @@ -# [L] Viewer feedback - -## Goal - -Sampled per-viewer QoS reaches monitoring consumers, so health reflects what -viewers actually experienced rather than what the relay believes it sent. - -## Plan - -Implement [#2735](https://github.com/moq-dev/moq/issues/2735): opt-in viewer -feedback broadcasts with per-viewer sampling. Deliberately the last phase; it -is the only half that costs viewer bandwidth and carries a privacy surface, so -it should land after a health verdict built on the other halves proves what is -actually missing. - -No PR exists yet, so writing the implementation is this quest's own work. - -Opt-in and sampled are both load-bearing: a feedback broadcast per viewer at -full rate is the fan-out problem again, pointed at ourselves. - -## Required - -- The moq.pro (downstream) health badge ships first by design, so the verdict exists before viewer bandwidth is spent refining it - -## Closes - -- [#2735](https://github.com/moq-dev/moq/issues/2735) - close this issue when the quest finishes diff --git a/quest/m3/teleop/README.md b/quest/m3/teleop/README.md index ba9d767a372..25ca8240fb9 100644 --- a/quest/m3/teleop/README.md +++ b/quest/m3/teleop/README.md @@ -111,8 +111,8 @@ stating plainly because it is what a builder is comparing against. - [e2ee](/quest/m2/e2ee/README.md) - the answer for a protected control link - [Text schema](/quest/m2/text-schema.md) - non-media tracks in a catalog, arrived at from the media side -- [Publisher-reported media stats](/quest/m2/qos/publisher-stats.md) - - publisher-reported stats as a catalog section (moq#2734); teleop's latency - instrumentation extends that track rather than adding a second one +- [Client stats](/quest/m2/qos/stats/schema.md) - publisher-reported stats + as a `.stats` broadcast (moq#2734); teleop's latency instrumentation + extends that extension rather than adding a second stats surface - [Video hardware validation](/quest/m3/video-hardware.md) - the VAAPI run that covers Intel ground robots and NUC companions diff --git a/quest/m3/teleop/robot.md b/quest/m3/teleop/robot.md index 463ea5a159d..a4c98c9e0a3 100644 --- a/quest/m3/teleop/robot.md +++ b/quest/m3/teleop/robot.md @@ -70,9 +70,9 @@ The framing is where the guarantee lives, not the subscription flags: - The two delivery classes, as `moq-json`'s snapshot and stream modes with the group structure and `Info::latency_max` each one needs. - Per-stage timestamp instrumentation, generalised from moq-boy's `status` - track. Check it against the publisher-reported stats track - ([publisher-stats](/quest/m2/qos/publisher-stats.md), moq#2734) before adding - a second stats surface. Capability only: publishing a competitive benchmark + track. Check it against the publisher-reported stats broadcast + ([client stats](/quest/m2/qos/stats/schema.md), moq#2734) before adding a + second stats surface. Capability only: publishing a competitive benchmark is out of scope, because Transitive's breakdown puts camera plus USB at roughly 100 ms of a 130 ms glass-to-glass total, so we would mostly be measuring somebody's webcam.