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
5 changes: 4 additions & 1 deletion .agents/plans/moq-engine-implementation.md
Original file line number Diff line number Diff line change
Expand Up @@ -23,7 +23,10 @@ Size baseline (2026-07-17): MoQ entry 18.16 KB min+gzip (90.8% of the

Implemented against the actual spec texts (fetched 2026-07-17):
`draft-ietf-moq-transport-19`, `draft-ietf-moq-msf-01`,
`draft-ietf-moq-loc-02`. Notable corrections to the plan's assumptions:
`draft-ietf-moq-loc-02` (LOC moved to loc-04 in PR #9). The spec texts are
now vendored under `internal/specs/moq/` (transport-20, loc-04, msf-01 as of
2026-09-02); the draft-20 migration plan is `moq-transport-20-migration.md`
beside this file. Notable corrections to the plan's assumptions:

- **Varint is NOT the QUIC RFC 9000 varint.** Draft-15+ uses a
leading-ones vi64 (1–9 bytes). Spec Table 2 vectors are test fixtures.
Expand Down
430 changes: 430 additions & 0 deletions .agents/plans/moq-transport-20-migration.md

Large diffs are not rendered by default.

1 change: 1 addition & 0 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -11,6 +11,7 @@ Use this file for durable repository rules. Prefer retrieval-led reasoning: insp
- Current behavior: implementation and colocated tests
- Public package behavior: package source, exports, and README files
- Architecture rationale: `internal/design/`, `internal/decisions/`, and `rfc/`
- Protocol drafts the MoQ stack implements: `internal/specs/moq/` (vendored IETF texts; its README lists the pinned revisions)

When prose conflicts with executable sources, follow the executable source and update stale prose in the same change.

Expand Down
2 changes: 1 addition & 1 deletion apps/sandbox/templates/moq-relay-interop/main.ts
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
// MoQ (draft-ietf-moq-transport-19 / MSF) relay interop smoke test.
// MoQ (draft-ietf-moq-transport-20 / MSF) relay interop smoke test.
// http://localhost:5173/moq-relay-interop/
//
// Query params:
Expand Down
2 changes: 1 addition & 1 deletion apps/sandbox/templates/spf-moq-player/index.html
Original file line number Diff line number Diff line change
Expand Up @@ -251,7 +251,7 @@ <h1>MoQ Player</h1>
<p>
<code>&lt;simple-moq-video&gt;</code> inside the real <code>&lt;live-video-player&gt;</code> shell and skin — the
MoQ engine driving actual Video.js controls. Defaults to a <strong>loopback relay</strong>: an in-page MSF
publisher speaking draft-19 bytes over an in-memory transport, so playback works with no server. Point at a real
publisher speaking draft-20 bytes over an in-memory transport, so playback works with no server. Point at a real
relay with a full MSF URL (<code>?relay=moqt://…%23msf:…</code> — percent-encode the <code>#</code>, or the
browser reads it as this page's fragment), or compose one from parts: relay host, broadcast path (what your token
was issued for, e.g. <code>mattypoo/room/42</code>), and an optional JWT — the same
Expand Down
13 changes: 7 additions & 6 deletions apps/sandbox/templates/spf-moq-player/loopback-relay.ts
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@
* Loopback MoQ relay — a synthetic MSF publisher for the sandbox.
*
* There is no public relay that serves draft-ietf-moq-msf-01 catalogs yet (Phase 0 interop is still owed), so this
* stands in for one: it speaks real draft-19 bytes over an in-memory `MoqtTransport` and publishes real
* stands in for one: it speaks real draft-20 bytes over an in-memory `MoqtTransport` and publishes real
* WebCodecs-encoded media, which is enough to drive the whole engine — catalog → selection → subscribe → decode →
* canvas + AudioContext.
*
Expand All @@ -19,7 +19,7 @@
import type { CreateMoqTransport } from '@videojs/spf/moq';

// ============================================================================
// Wire primitives (draft-ietf-moq-transport-19)
// Wire primitives (draft-ietf-moq-transport-20)
// ============================================================================

/** Control/request message types (§10, Table 5). */
Expand All @@ -40,8 +40,8 @@ const ERROR_INVALID_RANGE = 0x11;
*/
const SUBGROUP_HEADER_TYPE = 0x31;

/** LOC property IDs (draft-ietf-moq-loc-02 §2.3). */
const LOC_TIMESTAMP = 0x06;
/** LOC property IDs (draft-ietf-moq-loc-04 §2.3). */
const LOC_TIMESTAMP = 0x10;

/**
* The vi64 varint of draft-15+ (§1.4.1) — leading ones on the first byte give the encoded length minus one, so an
Expand Down Expand Up @@ -672,8 +672,9 @@ export function createLoopbackRelay({ onLog }: LoopbackRelayOptions = {}): Loopb
if (message.type === MESSAGE_TYPE.SUBSCRIBE) {
onSubscribe(message.body);
} else if (message.type === MESSAGE_TYPE.FETCH) {
// No history is retained: the engine falls back to joining the
// live catalog track, which is what a fresh live stream does.
// The engine never fetches — a draft-20 join is a subscription
// filter, and every subscription replays the newest group anyway.
// Anything else asking for history is refused: none is retained.
await writer.write(encodeRequestError(ERROR_INVALID_RANGE, 'nothing published'));
await writer.close();
return;
Expand Down
2 changes: 1 addition & 1 deletion apps/sandbox/templates/spf-moq-player/main.ts
Original file line number Diff line number Diff line change
Expand Up @@ -166,7 +166,7 @@ const DEFAULT_RELAY_ORIGIN = 'moqt://relay.mux.dev';
* (the same shape as the publisher sandbox's `?ns=`), and an optional JWT. Delegates to the engine's own
* `composeMoqSource` so the page cannot drift from the encoding `parseMoqSource` accepts. The token rides the `c4m`
* fragment parameter, which the engine composes onto the connect URL as `?jwt=` — the only auth carriage the relay
* fleet accepts (draft-19 AUTHORIZATION_TOKEN structures hard-close the session).
* fleet accepts (AUTHORIZATION_TOKEN request parameters hard-close the session).
*/
function composeMsfSource(origin: string, path: string, token: string): string {
return composeMoqSource(origin.trim() || DEFAULT_RELAY_ORIGIN, path, token ? { token } : {});
Expand Down
29 changes: 29 additions & 0 deletions internal/specs/moq/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,29 @@
# Vendored MoQ specifications

Verbatim IETF Internet-Draft texts for the protocols the MoQ stack in `packages/spf` implements. They are vendored so reviewers and agents can cite sections without network access, and so a revision bump is a reviewable diff.

The version the code actually speaks is declared in code: `MOQT_PROTOCOL_ID` in `packages/spf/src/network/moqt/control-messages.ts` for the transport, and the header comments of `packages/spf/src/media/moq/loc.ts` and `parse-catalog.ts` for LOC and MSF. When the vendored text is newer than the code pin, the gap is tracked by a migration plan under `.agents/plans/`.

| Draft | Revision | Published | Implemented in |
| --- | --- | --- | --- |
| Media over QUIC Transport | `draft-ietf-moq-transport-20` | 2026-08-31 | `packages/spf/src/network/moqt/` |
| Low Overhead Media Container (LOC) | `draft-ietf-moq-loc-04` | 2026-07-20 | `packages/spf/src/media/moq/loc.ts` |
| MOQT Streaming Format (MSF) | `draft-ietf-moq-msf-01` | 2026-06-02 | `packages/spf/src/media/moq/parse-catalog.ts`, `parse-source.ts` |

## Provenance

Fetched 2026-09-02 from the IETF archive at `https://www.ietf.org/archive/id/<draft-name>.txt`, unmodified.

| File | SHA-256 |
| --- | --- |
| `draft-ietf-moq-transport-20.txt` | `96a3a4467da53cd71bb4d1c334ac7ab13887f02b2e27335e715f75889fa9a1c6` |
| `draft-ietf-moq-loc-04.txt` | `fb29e2805be0511a188683b60fc830fb7fd3ecf19931968755d60d83707c3b47` |
| `draft-ietf-moq-msf-01.txt` | `c3e68aac09c36ae1db4afde6fd0600a949e7265348f592520304a31e993c35af` |

Working-group sources: [moq-wg/moq-transport](https://github.com/moq-wg/moq-transport), [moq-wg/loc](https://github.com/moq-wg/loc), [moq-wg/msf](https://github.com/moq-wg/msf). Each transport revision carries a change log in Appendix A; a rendered diff against the prior revision is available at `https://author-tools.ietf.org/iddiff?url1=<old>&url2=<new>`.

## Updating a draft

1. Download the new `.txt` from the IETF archive into this directory and delete the superseded revision.
2. Update the tables above (revision, date, checksum).
3. Either update the code pin and its section citations in the same change, or write the migration plan under `.agents/plans/` and link it from the commit.
Loading
Loading