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
67 changes: 62 additions & 5 deletions .agents/plans/moq-transport-20-migration.md
Original file line number Diff line number Diff line change
Expand Up @@ -254,11 +254,68 @@ ID in `publish-session.ts` (reuse is session-fatal; `onRequestUpdate` reports
the updated request and the update's id); the relay-hub test helper resolves
draft-20 Location Filters like moq-relay 0.14.14 (upstream `relative-group 1`
join, strict `next-object`, LARGEST_OBJECT in SUBSCRIBE_OK); the publisher
sandbox's loopback relay pulls upstream with `relative-group 1`. Still owed:
serving `relative-group 1` from the in-progress group's object 0 in
`track-publisher.ts` (a new binding starts at the next keyframe today, so the
relay's upstream video join lands on the next group), `LARGEST_OBJECT` in the
publisher's SUBSCRIBE_OK, and open-and-reset for inbound FILL_PARAMETERS.
sandbox's loopback relay pulls upstream with `relative-group 1`.

**Phase 5 complete (2026-09-03, `feat/moq-publisher-transport-20` off

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P3: This plan file is a temporary implementation note that AGENTS.md requires be deleted before merge, and the added lines are a completed task log, which the plans README says does not belong in the repository. Remove the plan (including this Phase 5 log) before landing; keep any durable rationale in internal/design or internal/decisions only if explicitly requested.

Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. At .agents/plans/moq-transport-20-migration.md, line 259:

<comment>This plan file is a temporary implementation note that AGENTS.md requires be deleted before merge, and the added lines are a completed task log, which the plans README says does not belong in the repository. Remove the plan (including this Phase 5 log) before landing; keep any durable rationale in internal/design or internal/decisions only if explicitly requested.</comment>

<file context>
@@ -254,11 +254,37 @@ ID in `publish-session.ts` (reuse is session-fatal; `onRequestUpdate` reports
-publisher's SUBSCRIBE_OK, and open-and-reset for inbound FILL_PARAMETERS.
+sandbox's loopback relay pulls upstream with `relative-group 1`.
+
+**Phase 5 complete (2026-09-03, `feat/moq-publisher-transport-20` off
+`mmcc/moq-publisher`):** the three remaining items landed.
+
</file context>

Copy link
Copy Markdown
Owner Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Keeping the plan on this branch deliberately, as on #41: this PR targets the long-lived mmcc/moq-publisher feature branch, which already carries .agents/plans/ notes under the same rule, and they get deleted when the feature branches merge to main.

`mmcc/moq-publisher`):** the three remaining items landed.
Comment on lines +259 to +260

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P1 Badge Remove the completed temporary migration plan

This change marks Phase 5 complete but commits the completed implementation notes under .agents/plans/. Repository guidance defines this directory as temporary and requires these notes to be deleted before merge, so retaining and expanding the file leaves stale branch-specific instructions in the repository. Remove the plan rather than recording completion in it.

AGENTS.md reference: AGENTS.md:L70-L70

Useful? React with 👍 / 👎.

Copy link
Copy Markdown
Owner Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Keeping the plan on this branch deliberately, as on #41: this PR targets the long-lived mmcc/moq-publisher feature branch, which already carries .agents/plans/ notes under the same rule, and they get deleted when the feature branches merge to main.


- **In-progress-group replay.** `track-publisher.ts` retains the current
group's frames (keyframe + deltas, bound or not, reset on each keyframe) in
`currentGroupFrames` and, on `bind`, replays them as a fresh group from
object 0 under the new alias before continuing live. A mid-group subscriber
(the relay's `relative-group 1` upstream join) now decodes instantly instead
of waiting for the next keyframe, and no subgroup stream begins partway
through a group. Group-per-frame tracks keep using `replayLastGroupOnBind`;
the two paths are mutually exclusive.
- **LARGEST_OBJECT in SUBSCRIBE_OK.** The actor tracks the largest
(group, object) it has written on its snapshot (`largestGroupId` /
`largestObjectId`, -1 before the first). `setup-track-publishers` passes a
`getLargestObject` reader into `registerTrack`; the session pulls it at
SUBSCRIBE time and includes LARGEST_OBJECT (§10.2.17, length-prefixed) in
SUBSCRIBE_OK once content exists, omitting it before. Pull-at-subscribe, so
no snapshot churn. The sandbox loopback relay's SUBSCRIBE_OK parser now skips
the parameter block by parity instead of asserting it is empty.
- **Inbound FILL_PARAMETERS.** `#openAndResetFill` opens a uni stream, writes a
FETCH_HEADER carrying the initiating Request ID, and resets it — the honest
§5.1.3.1 minimum for an origin that serves no fills (a reset is the failure
signal; a FIN would falsely claim an empty range). Wired on both the inbound
SUBSCRIBE and the REQUEST_UPDATE paths, gated on Forward State 1, with
FILL_PARAMETERS pulled out of the update's "unsupported" set so it no longer
rejects the update. `encodeFetchHeader` added to `object-stream.ts`.

All spf test projects pass; typecheck passes. PR #42 review fixes landed as
`40c22e90f` (empty fill ranges open no stream, §5.1.3).

**Live pass (2026-09-04, headless Chromium ↔ relay.mux.dev anonymous,
`moq-lite-rs`; the fleet runs moq-relay 0.14.15; publisher = PR #42 head):**
the `moq-publisher` sandbox's synthetic stream under `anon/<name>`, viewed by
the engine's own session driver joining through the relay. Drivers live in the
worktree's `node_modules/.moq-phase5-publish.mjs` (taps WebTransport in-page
and decodes both directions of every request stream plus each subgroup
header) and `.moq-phase5-probe.mjs`.

- The relay's upstream SUBSCRIBE per track is `relative-group 1`, Forward 1,
priority 255, group order descending, and never carries FILL_PARAMETERS —
even when the downstream viewer requested a fill the relay served it from
its cache. The open-and-reset path stays covered by unit tests only.
- In-progress-group replay: on both upstream binds the first video subgroup
stream opened 1 ms after the SUBSCRIBE and carried the retained group from
object 0 (8 objects, then 15 on the rebind); the viewer's first video object
landed 46–48 ms after its SUBSCRIBE_OK. Control: a run where the relay
subscribed before the track publisher had retained a keyframe waited for the
next keyframe (870 ms), the pre-Phase-5 behavior.
- LARGEST_OBJECT: the first-round SUBSCRIBE_OKs omitted it (nothing written
yet); after the relay re-subscribed they carried `{18,54}` video,
`{1899,0}` audio, `{0,0}` catalog, and the relay accepted them (session
stayed live, delivery continued).
- Relay lifecycle: the relay drops its upstream subscriptions 30 s after the
last viewer leaves (STOP_SENDING on the request streams); the publisher
unbinds cleanly (subscriber count back to 0, the unfinished group counted as
dropped). Anonymous relay.mux.dev announces only under the `anon` prefix; a
namespace outside it never matches its SUBSCRIBE_NAMESPACE and `publish()`
never resolves. No decode failures and no data-stream resets over ~3 min.
- Not yet run against sjc.relay.mux.global (needs a put+get token); the same
drivers take `RELAY`/`HOST`, `TOKEN`, and `NS=<root>/<name>`.

Branch points on a `draft: 19 | 20` value in `createMoqtSession` config:

Expand Down
40 changes: 26 additions & 14 deletions apps/sandbox/templates/moq-publisher/loopback-relay.ts
Original file line number Diff line number Diff line change
Expand Up @@ -723,27 +723,39 @@ export function createPublisherLoopbackRelay({ onLog }: PublisherLoopbackRelayOp
}

// SUBSCRIBE_OK (§10.8): track alias + message parameters
// (count-prefixed; the publish engine sends none — per-type
// encodings make a non-empty block unskippable) + track-property
// KVPs to the end of the body (delta-encoded types; even type →
// varint value, odd → length-prefixed bytes). TIMESCALE is the
// one property the engine declares (LOC stamps in microseconds).
// (count-prefixed) + track-property KVPs to the end of the body.
// Both blocks are delta-typed with the same parity encoding — even
// type → varint value, odd → length-prefixed bytes — so each skips
// cleanly. The publish engine sends LARGEST_OBJECT (§10.2.17, an
// odd/length-prefixed parameter) in the parameter block once the
// track has content; TIMESCALE (LOC's microsecond stamp) is the one
// track property it declares.
const fields = new Reader(response.body);

trackAlias = fields.varint();
let timescale: number | undefined;

if (fields.varint() === 0) {
let previousType = 0;
const parameterCount = fields.varint();
let previousParameterType = 0;

while (fields.offset < response.body.length) {
const propertyType = previousType + fields.varint();
for (let index = 0; index < parameterCount; index++) {
const parameterType = previousParameterType + fields.varint();

previousType = propertyType;
const value = propertyType % 2 === 0 ? fields.varint() : fields.slice(fields.varint());
previousParameterType = parameterType;

if (propertyType === TRACK_PROPERTY_TIMESCALE && typeof value === 'number') timescale = value;
}
if (parameterType % 2 === 0) fields.varint();
else fields.slice(fields.varint());
}

let timescale: number | undefined;
let previousType = 0;

while (fields.offset < response.body.length) {
const propertyType = previousType + fields.varint();

previousType = propertyType;
const value = propertyType % 2 === 0 ? fields.varint() : fields.slice(fields.varint());

if (propertyType === TRACK_PROPERTY_TIMESCALE && typeof value === 'number') timescale = value;
}

bindAlias(trackAlias, track);
Expand Down
27 changes: 27 additions & 0 deletions packages/spf/src/network/moqt/control-messages.ts
Original file line number Diff line number Diff line change
Expand Up @@ -482,6 +482,33 @@ export function decodeLocationFilter(bytes: Uint8Array): LocationFilter {
return filter;
}

/**
* Whether a Location filter, evaluated with the fetch rules of §5.1.2, selects no Objects. A fetch range — and so a
* subscription's fill range (§5.1.3) — is capped at Largest Object: with no Largest Object nothing exists to fetch, the
* Next Object and Next Group both lie past it, an absolute start past it selects nothing, and a bounded absolute range
* whose end precedes its start is empty. A publisher opens no fill fetch stream for an empty range.
*/
export function isEmptyFetchRange(filter: LocationFilter, largestObject: Location | undefined): boolean {
if (largestObject === undefined) return true;

switch (filter.type) {
case 'none':
return false;
case 'next-object':
return true;
case 'relative-group':
return filter.groupsBeforeNext === 0;
case 'absolute': {
const { start, endGroupDelta, endObject } = filter;
if (compareLocations(start, largestObject) > 0) return true;

// The end group is a non-negative delta from the start group, so
// only a same-group end can precede the start.
return endGroupDelta === 0 && endObject !== undefined && endObject < start.object;
}
}
}

// ============================================================================
// Message Parameters (§10.2)
// ============================================================================
Expand Down
14 changes: 13 additions & 1 deletion packages/spf/src/network/moqt/object-stream.ts
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,7 @@
* The parsers are async generators over a `StreamReader`, mirroring how `ChunkedStreamIterable` adapts fetch bodies
* elsewhere in `network/`.
*/
import { ByteReader, type StreamReader } from './bytes';
import { ByteReader, ByteWriter, type StreamReader } from './bytes';
import { decodeKeyValuePairs, type KeyValuePair } from './control-messages';
import { MoqtProtocolError } from './errors';
import { MAX_VARINT_VALUE } from './varint';
Expand Down Expand Up @@ -256,6 +256,18 @@ export async function readFetchHeader(reader: StreamReader): Promise<{ requestId
return { requestId: await reader.readVarint() };
}

/**
* Write a FETCH_HEADER (§11.4.4) — the stream-type varint plus the Request ID. A fill fetch stream (§5.1.3) opens with
* this frame carrying the initiating SUBSCRIBE / REQUEST_UPDATE Request ID.
*/
export function encodeFetchHeader(requestId: number): Uint8Array {
const writer = new ByteWriter(16);

writer.writeVarint(STREAM_TYPE.FETCH_HEADER);
writer.writeVarint(requestId);
return writer.toBytes();
}

/**
* Yield the entries of one FETCH response stream until FIN. Group/object IDs are delta-decoded against the prior entry
* per §11.4.4.1; the first object must carry both deltas (as absolute values).
Expand Down
6 changes: 5 additions & 1 deletion packages/spf/src/network/moqt/session.ts
Original file line number Diff line number Diff line change
Expand Up @@ -59,11 +59,15 @@ import { type BidirectionalStreamLike, openRequestStream, type RequestStream } f
/**
* Structural subset of `WebTransport` the session driver needs. A real `WebTransport` instance satisfies this; tests
* provide an in-memory fake (the same seam pattern as SPF's fetch injection).
*
* Publish-side fill failure signaling requires writers with WebTransport's `commit()` method, which preserves the
* written prefix across a reset. Support is detected on the control stream's writer and must be consistent across
* outgoing streams. Without it, nonempty fill requests are rejected with NOT_SUPPORTED.
*/
export interface MoqtTransport {
readonly incomingUnidirectionalStreams: ReadableStream<ReadableStream<Uint8Array>>;
readonly incomingBidirectionalStreams: ReadableStream<BidirectionalStreamLike>;
createUnidirectionalStream(): Promise<WritableStream<Uint8Array>>;
createUnidirectionalStream(options?: { sendOrder?: number }): Promise<WritableStream<Uint8Array>>;
createBidirectionalStream(): Promise<BidirectionalStreamLike>;
close(closeInfo?: { closeCode?: number; reason?: string }): void;
readonly closed: Promise<unknown>;
Expand Down
36 changes: 36 additions & 0 deletions packages/spf/src/network/moqt/tests/control-messages.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -20,6 +20,7 @@ import {
encodeSetup,
encodeSubscribe,
encodeSubscribeOk,
isEmptyFetchRange,
isRetryablePublishDoneStatus,
isRetryableRequestErrorCode,
type LocationFilter,
Expand Down Expand Up @@ -469,6 +470,41 @@ describe('encodeLocationFilter', () => {
});
});

describe('isEmptyFetchRange', () => {
const largest = { group: 4, object: 2 };

it('is empty for every filter before the track has content', () => {
expect(isEmptyFetchRange({ type: 'none' }, undefined)).toBe(true);
expect(isEmptyFetchRange({ type: 'relative-group', groupsBeforeNext: 1 }, undefined)).toBe(true);
expect(isEmptyFetchRange({ type: 'absolute', start: { group: 0, object: 0 } }, undefined)).toBe(true);
});

it('is empty when the start lies past Largest Object', () => {
expect(isEmptyFetchRange({ type: 'next-object' }, largest)).toBe(true);
expect(isEmptyFetchRange({ type: 'relative-group', groupsBeforeNext: 0 }, largest)).toBe(true);
expect(isEmptyFetchRange({ type: 'absolute', start: { group: 4, object: 3 } }, largest)).toBe(true);
expect(isEmptyFetchRange({ type: 'absolute', start: { group: 5, object: 0 } }, largest)).toBe(true);
});

it('is nonempty when the start is at or before Largest Object', () => {
expect(isEmptyFetchRange({ type: 'none' }, largest)).toBe(false);
expect(isEmptyFetchRange({ type: 'relative-group', groupsBeforeNext: 1 }, largest)).toBe(false);
expect(isEmptyFetchRange({ type: 'relative-group', groupsBeforeNext: 9 }, largest)).toBe(false);
expect(isEmptyFetchRange({ type: 'absolute', start: { group: 4, object: 2 } }, largest)).toBe(false);
expect(isEmptyFetchRange({ type: 'absolute', start: { group: 1, object: 7 }, endGroupDelta: 0 }, largest)).toBe(
false
);
});

it('is empty only when a bounded absolute end precedes its start', () => {
const start = { group: 2, object: 5 };

expect(isEmptyFetchRange({ type: 'absolute', start, endGroupDelta: 0, endObject: 4 }, largest)).toBe(true);
expect(isEmptyFetchRange({ type: 'absolute', start, endGroupDelta: 0, endObject: 5 }, largest)).toBe(false);
expect(isEmptyFetchRange({ type: 'absolute', start, endGroupDelta: 1, endObject: 0 }, largest)).toBe(false);
});
});

describe('encodeFetchOk', () => {
it('round-trips and rejects end-of-track values other than 0 and 1', () => {
const notEnded = encodeFetchOk(false, { group: 3, object: 9 });
Expand Down
Loading
Loading