Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
58 changes: 58 additions & 0 deletions quest/m0/3588-anonymous-publisher-parked.md
Original file line number Diff line number Diff line change
@@ -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
1 change: 1 addition & 0 deletions quest/m0/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down

This file was deleted.

4 changes: 2 additions & 2 deletions quest/m2/3489-ts-import-stream-liveness.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand All @@ -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
Comment thread
coderabbitai[bot] marked this conversation as resolved.
Resolved
6 changes: 2 additions & 4 deletions quest/m2/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -81,16 +82,13 @@ 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
- [Room SDK](/quest/m2/room-sdk.md) - a headless room package: a room is a path prefix, no service, no storage
- [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
Expand Down
52 changes: 52 additions & 0 deletions quest/m2/auth-api/README.md
Original file line number Diff line number Diff line change
@@ -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
69 changes: 69 additions & 0 deletions quest/m2/auth-api/mtls-identity.md
Original file line number Diff line number Diff line change
@@ -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=<identity>` 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=<identity>` 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`
Comment thread
coderabbitai[bot] marked this conversation as resolved.
Resolved
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
Loading
Loading