From 00d4d703833512c3524a003ba00a975a935bd436 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Fri, 20 Nov 2026 17:10:05 -0800 Subject: [PATCH 1/3] quest: plan PROXY, a proxied byte stream routed to a broadcast Co-Authored-By: Claude Opus 5.5 --- quest/m3/proxy/README.md | 51 ++++++++++++++++++++++++++++++++++++++++ quest/m3/proxy/grants.md | 23 ++++++++++++++++++ quest/m3/proxy/moqt.md | 26 ++++++++++++++++++++ quest/m3/proxy/stream.md | 29 +++++++++++++++++++++++ 4 files changed, 129 insertions(+) create mode 100644 quest/m3/proxy/README.md create mode 100644 quest/m3/proxy/grants.md create mode 100644 quest/m3/proxy/moqt.md create mode 100644 quest/m3/proxy/stream.md diff --git a/quest/m3/proxy/README.md b/quest/m3/proxy/README.md new file mode 100644 index 0000000000..de796aa186 --- /dev/null +++ b/quest/m3/proxy/README.md @@ -0,0 +1,51 @@ +# Proxied streams + +## Goal + +A session can open `PROXY `: 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 moq-transport hop, moq-net carries the same stream +as two tracks under a hidden `.proxy/` namespace and converts it back at the +next moq-lite hop, so an application sees one API on every path and never +branches on the version. 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 `, 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). The + maintainer leaned this way without settling it; revisit in this plan's review. + +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. diff --git a/quest/m3/proxy/grants.md b/quest/m3/proxy/grants.md new file mode 100644 index 0000000000..432cfbe540 --- /dev/null +++ b/quest/m3/proxy/grants.md @@ -0,0 +1,23 @@ +# [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 ` 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. +- 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. diff --git a/quest/m3/proxy/moqt.md b/quest/m3/proxy/moqt.md new file mode 100644 index 0000000000..faae25d056 --- /dev/null +++ b/quest/m3/proxy/moqt.md @@ -0,0 +1,26 @@ +# [M] PROXY through moq-transport + +## Goal + +A proxied stream crosses a moq-transport hop. moq-net's moq-transport session +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. + +## 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. + +## Required + +- [PROXY over moq-lite](/quest/m3/proxy/stream.md) - the stream and API this carries across moq-transport diff --git a/quest/m3/proxy/stream.md b/quest/m3/proxy/stream.md new file mode 100644 index 0000000000..b7b06a1fc3 --- /dev/null +++ b/quest/m3/proxy/stream.md @@ -0,0 +1,29 @@ +# [L] PROXY over moq-lite + +## Goal + +moq-lite gains a `PROXY ` 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: follow AGENTS.md's wire rules + for the version it joins and update its draft in the same PR. +- 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`. + +## Required + +- [Dial and listen grants](/quest/m3/proxy/grants.md) - the permissions a relay checks before forwarding a PROXY From fc5fcbcf061161f0da6ed6366a79abbbca200cc4 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Fri, 20 Nov 2026 17:14:19 -0800 Subject: [PATCH 2/3] quest: PROXY converts on any hop without it, and names its wire Co-Authored-By: Claude Opus 5.5 --- quest/m3/proxy/README.md | 17 +++++++++++++---- quest/m3/proxy/grants.md | 12 ++++++++++++ quest/m3/proxy/moqt.md | 17 +++++++++++++---- quest/m3/proxy/stream.md | 14 ++++++++++++-- 4 files changed, 50 insertions(+), 10 deletions(-) diff --git a/quest/m3/proxy/README.md b/quest/m3/proxy/README.md index de796aa186..76323f4090 100644 --- a/quest/m3/proxy/README.md +++ b/quest/m3/proxy/README.md @@ -5,10 +5,13 @@ A session can open `PROXY `: 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 moq-transport hop, moq-net carries the same stream -as two tracks under a hidden `.proxy/` namespace and converts it back at the -next moq-lite hop, so an application sees one API on every path and never -branches on the version. A relay on cdn.moq.pro forwards it. +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: @@ -49,3 +52,9 @@ question): 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. + +Added in the plan's review, 2026-11-20, for the maintainer to confirm: 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. This extends the moq-transport decision above; it adds no +dialer-side fallback. diff --git a/quest/m3/proxy/grants.md b/quest/m3/proxy/grants.md index 432cfbe540..88d5044817 100644 --- a/quest/m3/proxy/grants.md +++ b/quest/m3/proxy/grants.md @@ -18,6 +18,18 @@ a media broadcast can never open a stream to its publisher. 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. diff --git a/quest/m3/proxy/moqt.md b/quest/m3/proxy/moqt.md index faae25d056..598860b4c5 100644 --- a/quest/m3/proxy/moqt.md +++ b/quest/m3/proxy/moqt.md @@ -1,13 +1,15 @@ -# [M] PROXY through moq-transport +# [M] PROXY through hops without it ## Goal -A proxied stream crosses a moq-transport hop. moq-net's moq-transport session -carries it as two tracks under a hidden `.proxy/` namespace, one group each +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. +moq-lite hops, and a sim test through a relay pinned to a moq-lite version +before PROXY's. ## Plan @@ -20,6 +22,13 @@ See the [epic](/quest/m3/proxy/README.md) for the decisions. 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. + +Public API: none; the stream's API is unchanged. Wire: none new, since the +track form is ordinary tracks. ## Required diff --git a/quest/m3/proxy/stream.md b/quest/m3/proxy/stream.md index b7b06a1fc3..c3c7cab47f 100644 --- a/quest/m3/proxy/stream.md +++ b/quest/m3/proxy/stream.md @@ -17,13 +17,23 @@ memory bounded by its window, and a publisher that does not listen refuses. 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: follow AGENTS.md's wire rules - for the version it joins and update its draft in the same PR. +- 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 From 9fd0bfd8a14ce107419e1208027d9c67bfd560f1 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Fri, 20 Nov 2026 17:21:07 -0800 Subject: [PATCH 3/3] quest: record the PROXY plan review's answers Co-Authored-By: Claude Opus 5.5 --- quest/m3/proxy/README.md | 11 ++++++----- 1 file changed, 6 insertions(+), 5 deletions(-) diff --git a/quest/m3/proxy/README.md b/quest/m3/proxy/README.md index 76323f4090..eb7262eb21 100644 --- a/quest/m3/proxy/README.md +++ b/quest/m3/proxy/README.md @@ -46,15 +46,16 @@ question): 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). The - maintainer leaned this way without settling it; revisit in this plan's review. + 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. -Added in the plan's review, 2026-11-20, for the maintainer to confirm: the +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. This extends the moq-transport decision above; it adds no -dialer-side fallback. +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.