Repository navigation
quest: plan PROXY, a proxied byte stream routed to a broadcast #9262
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Changes from all commits
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,61 @@ | ||
| # Proxied streams | ||
|
|
||
| ## Goal | ||
|
|
||
| A session can open `PROXY <broadcast>`: one bidirectional stream of opaque | ||
| bytes, routed hop by hop to that broadcast's publisher the way a subscription | ||
| is, with no group cache and no fan-out. Each hop holds about a stream's flow | ||
| control window. Through a hop whose version lacks PROXY, moq-net carries the | ||
| same stream as two tracks under a hidden `.proxy/` namespace and converts it | ||
| back at the next hop that has it, so an application sees one API on every | ||
| path and never branches on the version. That covers every moq-transport hop | ||
| and a moq-lite hop on a version before PROXY's, as between moq.pro's relays | ||
| mid-rollout, where two releases run side by side (AGENTS.md). A relay on | ||
| cdn.moq.pro forwards it. | ||
|
|
||
| Boundaries: | ||
|
|
||
| - The bytes are opaque. Identity, framing, and meaning are the | ||
| application's, carried in band. | ||
| - A hop failure resets the stream, as a broken TCP path would. Only the | ||
| `.proxy/` track form can resume, from its cache. | ||
| - No fan-out and no caching on the moq-lite form. | ||
|
|
||
| ## Plan | ||
|
|
||
| Decided 2026-11-20 (maintainer, /quest-plan from Kixel's | ||
| [stream-memory](https://github.com/kixel-ai/kixel.ai/blob/main/quest/m1/stream-memory.md) | ||
| question): | ||
|
|
||
| - ✅ A generic primitive here, a proxied stream to an announced broadcast, | ||
| that Kixel's TCP byte streams use first (rejected: a TCP feature with an | ||
| exception to AGENTS.md's rule that TCP tunnels belong to Kixel). Kixel's | ||
| copies of a byte stream hold up to a group's 32 MiB cache per hop, and TCP | ||
| gains nothing from a cache or fan-out. | ||
| - ✅ It reaches cdn.moq.pro too (rejected: only Kixel's own hops, which would | ||
| need nothing here; Kixel's hops first and the CDN later). | ||
| - ✅ `PROXY <broadcast>`, reusing broadcast routing, as one bidirectional | ||
| stream (rejected: addressing by endpoint ID, which needs its own routing). | ||
| - ✅ moq-net converts PROXY to and from moq-transport, as tracks under a | ||
| `.proxy/` namespace (rejected: a dialer that tries PROXY and falls back to | ||
| tracks itself; a dialer that reads the first hop's version, which cannot see | ||
| later hops). | ||
| - ✅ The moq-transport form is Kixel's two-track byte stream, moved here | ||
| ([moqt](/quest/m3/proxy/moqt.md)) (rejected: a fresh encoding). | ||
| - ✅ Identity is in band, the application's job (rejected: the relay vouching | ||
| for the dialer, which needs an identity type moq-net lacks). | ||
| - ✅ Explicit `dial` and `listen` grants ([grants](/quest/m3/proxy/grants.md)) | ||
| (rejected: reading a broadcast meaning dial and publishing it meaning listen, | ||
| which would let any viewer's token open a stream to a media publisher). | ||
| Confirmed by the maintainer in the plan's review, 2026-11-20. | ||
|
|
||
| m3: it is a wire change a named consumer, Kixel, waits on, and it should not | ||
| gate the cut. kixel-ai/kixel.ai's `quest/m1/proxy.md` adopts it once | ||
| cdn.moq.wtf runs it. | ||
|
|
||
| Decided in the plan's review, 2026-11-20 (maintainer): ✅ the | ||
| conversion keys on each hop's negotiated version lacking PROXY, not on | ||
| moq-transport alone, so a mixed-release relay pair or a moq-lite version | ||
| before PROXY's carries the track form rather than refusing (rejected: converting on | ||
| moq-transport hops only, which breaks streams mid-rollout). This extends the | ||
| moq-transport decision above; it adds no dialer-side fallback. |
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,35 @@ | ||
| # [M] Dial and listen grants | ||
|
|
||
| ## Goal | ||
|
|
||
| `moq_auth::Grant` and its JS counterpart carry two more `Access` fields, | ||
| `dial` and `listen`, read from tokens and auth endpoint answers alike. A | ||
| relay admits `PROXY <broadcast>` only from a session whose `dial` covers the | ||
| broadcast, and delivers one only to a publisher whose `listen` covers it. | ||
| Neither `publish` nor `subscribe` implies either. | ||
|
|
||
| ## Plan | ||
|
|
||
| Decided 2026-11-20 (maintainer, /quest-plan), with the | ||
| [epic](/quest/m3/proxy/README.md): explicit grants, so a token that only reads | ||
| a media broadcast can never open a stream to its publisher. | ||
|
|
||
| - An unknown field is already refused (`Grant`'s docs), so a relay that | ||
| predates these fields refuses a grant carrying them rather than widening it. | ||
| Note it in the Impact section with the token and auth endpoint formats that | ||
| change. | ||
| - lite-07's `AUTH_OK` carries a session's publish and subscribe grants, so it | ||
| carries `dial` and `listen` too, a wire change in the current wip version. | ||
| - Grants become path prefixes in | ||
| [moq-dev/moq#9251](https://github.com/moq-dev/moq/pull/9251) | ||
| (`quest/m2/prefix-grants.md`); `dial` and `listen` are prefix sets like the | ||
| others, so build on it once it lands. | ||
| - A cluster link forwards streams for many sessions, so a link's grant covers | ||
| the `dial` and `listen` it relays, as its publish and subscribe already do. | ||
| - Mirror the names in Rust, JS, and the docs. moq.pro's dashboard tokens and | ||
| auth endpoint answers, and kixel.ai's `/mesh/auth`, adopt the fields on | ||
| their side. | ||
|
|
||
| Public API: additive, `Grant::dial` and `Grant::listen` and their JS | ||
| counterparts. Wire: the token and auth endpoint formats gain two fields that | ||
| an older reader refuses, and lite-07-wip's `AUTH_OK` gains them. |
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,35 @@ | ||
| # [M] PROXY through hops without it | ||
|
|
||
| ## Goal | ||
|
|
||
| A proxied stream crosses a hop whose version lacks PROXY: any moq-transport | ||
| hop, and a moq-lite hop on a version before PROXY's, as between two relay | ||
| releases mid-rollout. moq-net's session on that hop carries it as two tracks under a hidden `.proxy/` namespace, one group each | ||
| way, and the next moq-lite hop turns them back into a PROXY stream. A dialer | ||
| and a listener see the same API whether the path has a moq-transport hop or | ||
| not. An interop test runs a stream through a moq-transport relay between two | ||
| moq-lite hops, and a sim test through a relay pinned to a moq-lite version | ||
| before PROXY's. | ||
|
|
||
| ## Plan | ||
|
|
||
| See the [epic](/quest/m3/proxy/README.md) for the decisions. | ||
|
|
||
| - The encoding is Kixel's two-track byte stream, moved here from | ||
| kixel-ai/kixel.ai's `rs/kixel/src/socket/stream.rs`: one group per | ||
| direction, a finished group as FIN, and a reset group with an application | ||
| code as RST. Carry over what Kixel has landed on it by then: resuming a | ||
| session within its track's max-age (its `quest/m0/mesh/reaccept.md`) and a | ||
| buffer-sized cache per hop (its `quest/m1/stream-memory.md`). | ||
| - The `.proxy/` prefix's leading `.` hides it from announce discovery. | ||
| - Admission stays the [grants](/quest/m3/proxy/grants.md): a converting hop | ||
| admits the `.proxy/` tracks of a dial only under `dial` on the broadcast, | ||
| and serves a listener's only under `listen`. Publish and subscribe grants on | ||
| `.proxy/` paths admit nothing, so the track form never widens a session. | ||
|
Comment on lines
+26
to
+28
Contributor
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Require the converter to check the originating session's The plan lets a link's grant cover the
|
||
|
|
||
| Public API: none; the stream's API is unchanged. Wire: none new, since the | ||
| track form is ordinary tracks. | ||
|
|
||
| ## Required | ||
|
|
||
| - [PROXY over moq-lite](/quest/m3/proxy/stream.md) - the stream and API this carries across moq-transport | ||
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,39 @@ | ||
| # [L] PROXY over moq-lite | ||
|
|
||
| ## Goal | ||
|
|
||
| moq-lite gains a `PROXY <broadcast>` stream: one bidirectional stream of | ||
| opaque bytes. A relay forwards it toward the broadcast's publisher along the | ||
| route a subscription would take, holding about a stream window per hop and | ||
| caching nothing. moq-net offers it in Rust and JS with mirrored names: a | ||
| dialer opens a stream to a broadcast, and a publisher listens for streams on | ||
| its broadcast and accepts or refuses each. Finishing a side is a FIN, a reset | ||
| carries an application code, and a hop failure resets both sides. A sim test | ||
| carries a bulk transfer through two relays to a slow reader with each hop's | ||
| memory bounded by its window, and a publisher that does not listen refuses. | ||
|
|
||
| ## Plan | ||
|
|
||
| See the [epic](/quest/m3/proxy/README.md) for the decisions. | ||
|
|
||
| - Admission is the [dial and listen grants](/quest/m3/proxy/grants.md). | ||
| - A new moq-lite stream type is a wire change. It joins the current wip | ||
| version (lite-07-wip until the cut; see | ||
| [lite07-finalize](/quest/m2/lite07-finalize.md)'s freeze policy), and the | ||
| draft changes in the same PR. A peer on an earlier version never sees one: | ||
| [moqt](/quest/m3/proxy/moqt.md) carries it as tracks there. | ||
| - Routing reuses the subscription's: a hop picks the route a subscription to | ||
| the broadcast would, cluster links included, and a broadcast with no route | ||
| refuses the stream as a subscription would end. | ||
| - The relay forwards bytes, not frames: flow control on each hop's stream is | ||
| the only buffer. | ||
| - Kixel's byte stream semantics are the reference: FIN as finish, RST with a | ||
| code, as in kixel-ai/kixel.ai's `rs/kixel/src/socket/stream.rs`. | ||
|
|
||
| Public API: additive, a dial on a session or origin and a listen on a | ||
| broadcast, in Rust and JS. Wire: a new stream type in the current wip | ||
| moq-lite version. | ||
|
|
||
| ## Required | ||
|
|
||
| - [Dial and listen grants](/quest/m3/proxy/grants.md) - the permissions a relay checks before forwarding a PROXY |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Define the admission rule for a dial that crosses a hop without
dial.The admission rule requires
dialon the broadcast for the converting hop's.proxy/tracks. A hop that predates the grant fields refuses a grant that carries them, so the converter behind that hop can have nodialgrant for its incoming track session. The plan does not say which grant applies to that session, or what happens when none does. The goal and the sim test both require a stream through a relay pinned to a version before PROXY's. An implementation that follows the current text can refuse an authorized stream on that path.Specify the grant that admits the incoming track session when the upstream hop cannot carry
dial, and state the admission outcome when that grant is absent.