diff --git a/.agents/plans/moq-transport-20-migration.md b/.agents/plans/moq-transport-20-migration.md index 625ec133f5..0ffd869f0b 100644 --- a/.agents/plans/moq-transport-20-migration.md +++ b/.agents/plans/moq-transport-20-migration.md @@ -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 +`mmcc/moq-publisher`):** the three remaining items landed. + +- **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/`, 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=/`. Branch points on a `draft: 19 | 20` value in `createMoqtSession` config: diff --git a/apps/sandbox/templates/moq-publisher/loopback-relay.ts b/apps/sandbox/templates/moq-publisher/loopback-relay.ts index 012d074a87..0a867e1ef5 100644 --- a/apps/sandbox/templates/moq-publisher/loopback-relay.ts +++ b/apps/sandbox/templates/moq-publisher/loopback-relay.ts @@ -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); diff --git a/packages/spf/src/network/moqt/control-messages.ts b/packages/spf/src/network/moqt/control-messages.ts index 10f6a48227..56770feb3e 100644 --- a/packages/spf/src/network/moqt/control-messages.ts +++ b/packages/spf/src/network/moqt/control-messages.ts @@ -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) // ============================================================================ diff --git a/packages/spf/src/network/moqt/object-stream.ts b/packages/spf/src/network/moqt/object-stream.ts index 424c80dda2..f518168aec 100644 --- a/packages/spf/src/network/moqt/object-stream.ts +++ b/packages/spf/src/network/moqt/object-stream.ts @@ -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'; @@ -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). diff --git a/packages/spf/src/network/moqt/session.ts b/packages/spf/src/network/moqt/session.ts index aec5c83739..105b4f1d74 100644 --- a/packages/spf/src/network/moqt/session.ts +++ b/packages/spf/src/network/moqt/session.ts @@ -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>; readonly incomingBidirectionalStreams: ReadableStream; - createUnidirectionalStream(): Promise>; + createUnidirectionalStream(options?: { sendOrder?: number }): Promise>; createBidirectionalStream(): Promise; close(closeInfo?: { closeCode?: number; reason?: string }): void; readonly closed: Promise; diff --git a/packages/spf/src/network/moqt/tests/control-messages.test.ts b/packages/spf/src/network/moqt/tests/control-messages.test.ts index 11a2eab7a5..a9c230e40d 100644 --- a/packages/spf/src/network/moqt/tests/control-messages.test.ts +++ b/packages/spf/src/network/moqt/tests/control-messages.test.ts @@ -20,6 +20,7 @@ import { encodeSetup, encodeSubscribe, encodeSubscribeOk, + isEmptyFetchRange, isRetryablePublishDoneStatus, isRetryableRequestErrorCode, type LocationFilter, @@ -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 }); diff --git a/packages/spf/src/publish/actors/tests/track-publisher.test.ts b/packages/spf/src/publish/actors/tests/track-publisher.test.ts index 37abad621f..ffe36771c9 100644 --- a/packages/spf/src/publish/actors/tests/track-publisher.test.ts +++ b/packages/spf/src/publish/actors/tests/track-publisher.test.ts @@ -574,7 +574,7 @@ describe('createTrackPublisherActor', () => { publisher.destroy(); }); - it('joins at the next keyframe after a bind', async () => { + it('replays the retained in-progress group from object 0 on bind', async () => { const factory = makeStreamFactory(); const publisher = createTrackPublisherActor({ openUniStream: factory.openUniStream }); @@ -590,22 +590,87 @@ describe('createTrackPublisherActor', () => { }); }; - sendFrame(0, true); // unbound — dropped + // A whole group — keyframe and a delta — is produced before any + // subscription. Unbound, it opens no stream but is retained. + sendFrame(0, true); + sendFrame(33_333, false); + await new Promise((resolve) => setTimeout(resolve, 20)); + expect(factory.streams).toHaveLength(0); + + // The subscription binds mid-group: the retained group replays from + // object 0 (the keyframe) so the subscriber decodes without waiting + // for the next keyframe, and live frames extend it. publisher.send({ type: 'bind', trackAlias: 9 }); - sendFrame(33_333, false); // bound, but no open group to extend — dropped - sendFrame(2_000_000, true); // the join point - sendFrame(2_033_333, false); + sendFrame(66_666, false); + sendFrame(2_000_000, true); // the next group boundary publisher.send({ type: 'end' }); await vi.waitFor(() => { - expect(factory.streams).toHaveLength(1); + expect(factory.streams).toHaveLength(2); expect(factory.streams[0]!.closed).toBe(true); + expect(factory.streams[1]!.closed).toBe(true); }); - const { header, objects } = await parseSubgroup(factory.streams[0]!); + const first = await parseSubgroup(factory.streams[0]!); + + expect(first.header.trackAlias).toBe(9); + expect(first.objects.map((o) => o.objectId)).toEqual([0, 1, 2]); + expect(toLocFrame(first.objects[0]!)!.timestampUs).toBe(0); + expect(toLocFrame(first.objects[2]!)!.timestampUs).toBe(66_666); - expect(header.trackAlias).toBe(9); - expect(objects.map((o) => o.objectId)).toEqual([0, 1]); - expect(toLocFrame(objects[0]!)!.timestampUs).toBe(2_000_000); + const second = await parseSubgroup(factory.streams[1]!); + + expect(second.header.groupId).toBe(1); + expect(toLocFrame(second.objects[0]!)!.timestampUs).toBe(2_000_000); + publisher.destroy(); + }); + + it('tracks the Largest Object it has written on the snapshot', async () => { + const factory = makeStreamFactory(); + const publisher = createTrackPublisherActor({ openUniStream: factory.openUniStream }); + + expect(counters(publisher).largestGroupId).toBe(-1); + expect(counters(publisher).largestObjectId).toBe(-1); + + publisher.send({ type: 'bind', trackAlias: 5 }); + + const key0 = locFrame(0, [1], new Uint8Array([7])); + + publisher.send({ + type: 'frame', + payload: key0.payload, + properties: key0.properties, + keyframe: true, + timestampUs: 0, + }); + const delta = locFrame(33_333, [2]); + + publisher.send({ + type: 'frame', + payload: delta.payload, + properties: delta.properties, + keyframe: false, + timestampUs: 33_333, + }); + await vi.waitFor(() => { + expect(counters(publisher).largestGroupId).toBe(0); + expect(counters(publisher).largestObjectId).toBe(1); + }); + + const key1 = locFrame(66_666, [3], new Uint8Array([7])); + + publisher.send({ + type: 'frame', + payload: key1.payload, + properties: key1.properties, + keyframe: true, + timestampUs: 66_666, + }); + await vi.waitFor(() => { + // A new group resets the object count — the Largest Object is the + // (group, object) pair, not the running object total. + expect(counters(publisher).largestGroupId).toBe(1); + expect(counters(publisher).largestObjectId).toBe(0); + }); publisher.destroy(); }); @@ -660,7 +725,7 @@ describe('createTrackPublisherActor', () => { publisher.destroy(); }); - it('starts a fresh group under the new alias on rebind and drops the old queue', async () => { + it('replays the in-progress group under the new alias on rebind and drops the old queue', async () => { const factory = makeStreamFactory(); const publisher = createTrackPublisherActor({ openUniStream: factory.openUniStream }); @@ -687,17 +752,24 @@ describe('createTrackPublisherActor', () => { // The old binding's open group dies with its subscription (a stream // under the replaced alias is the peer's unknown-alias drop); the new - // binding starts a fresh group under the new alias. + // binding replays the in-progress group from object 0 under its own + // alias, then continues live. await vi.waitFor(() => { - expect(factory.streams).toHaveLength(2); + expect(factory.streams).toHaveLength(3); expect(factory.streams[0]!.aborted).toBe(true); expect(factory.streams[1]!.closed).toBe(true); + expect(factory.streams[2]!.closed).toBe(true); }); expect(counters(publisher).droppedGroups).toBe(1); - const second = await parseSubgroup(factory.streams[1]!); + const replay = await parseSubgroup(factory.streams[1]!); - expect(second.header.trackAlias).toBe(3); - expect(second.header.groupId).toBe(1); + expect(replay.header.trackAlias).toBe(3); + expect(toLocFrame(replay.objects[0]!)!.timestampUs).toBe(0); + + const next = await parseSubgroup(factory.streams[2]!); + + expect(next.header.trackAlias).toBe(3); + expect(toLocFrame(next.objects[0]!)!.timestampUs).toBe(2_000_000); publisher.destroy(); }); @@ -818,23 +890,32 @@ describe('createTrackPublisherActor', () => { }); expect(onError).not.toHaveBeenCalled(); - // While unbound, frames drop. + // While unbound, a keyframe opens no stream but is retained as the + // in-progress group. factory.gate = false; sendKey(2_000_000); await new Promise((resolve) => setTimeout(resolve, 20)); expect(factory.streams).toHaveLength(1); - // A new subscription re-binds and publishing resumes at its keyframe. + // A new subscription re-binds: the retained keyframe replays (instant + // join) under the new alias, then publishing resumes live. publisher.send({ type: 'bind', trackAlias: 8 }); sendKey(4_000_000); publisher.send({ type: 'end' }); await vi.waitFor(() => { - expect(factory.streams).toHaveLength(2); + expect(factory.streams).toHaveLength(3); expect(factory.streams[1]!.closed).toBe(true); + expect(factory.streams[2]!.closed).toBe(true); }); - const { header } = await parseSubgroup(factory.streams[1]!); + const replay = await parseSubgroup(factory.streams[1]!); + + expect(replay.header.trackAlias).toBe(8); + expect(toLocFrame(replay.objects[0]!)!.timestampUs).toBe(2_000_000); + + const resumed = await parseSubgroup(factory.streams[2]!); - expect(header.trackAlias).toBe(8); + expect(resumed.header.trackAlias).toBe(8); + expect(toLocFrame(resumed.objects[0]!)!.timestampUs).toBe(4_000_000); publisher.destroy(); }); }); diff --git a/packages/spf/src/publish/actors/track-publisher.ts b/packages/spf/src/publish/actors/track-publisher.ts index 23a3cb54bd..680f37e3c8 100644 --- a/packages/spf/src/publish/actors/track-publisher.ts +++ b/packages/spf/src/publish/actors/track-publisher.ts @@ -12,11 +12,13 @@ * **Data flows only while bound to a subscription.** Announce-and-serve ingest is pull-through: a subgroup stream is * only meaningful under a track alias the session bound with a SUBSCRIBE_OK, and an unbound alias is the peer's * "unknown track alias" (stream dropped after a 1 s grace). `{type:'bind'}` carries the current subscription's alias; - * frames arriving unbound are dropped without opening streams. Groups never span bindings — a bind or unbind resets the - * open group, so a fresh subscription starts at the next keyframe (`groupPerFrame` tracks start at the next frame). For - * tracks whose frames flow only on _change_ rather than on a cadence — the catalog — waiting for the next frame would - * stall a new subscription forever, so `replayLastGroupOnBind` retains the latest frame (bound or not) and re-emits it - * as a fresh group on every bind. + * frames arriving unbound are dropped without opening streams. Groups still never span bindings — a bind or unbind + * resets the open group — but the reset does not always cost a wait for fresh data: keyframe-grouped tracks replay the + * retained in-progress group from object 0 so a subscription that arrives mid-group decodes immediately, while + * `groupPerFrame` tracks have no in-progress group to replay and simply start at the next frame. For tracks whose + * frames flow only on _change_ rather than on a cadence — the catalog — waiting for the next frame would stall a new + * subscription forever, so `replayLastGroupOnBind` retains the latest frame (bound or not) and re-emits it as a fresh + * group on every bind. * * Group mapping follows MSF: video starts a new group on every keyframe (`objectId` resets to 0 — the extraction side * recovers the keyframe flag from `objectId === 0`); audio and catalog tracks set `groupPerFrame`, where every frame is @@ -27,7 +29,7 @@ * message order. Async completions feed the reactive snapshot counters through internal messages, mirroring * `actors/dom/encoder-actor.ts`. */ -import type { MessageActor } from '../../core/actors/create-machine-actor'; +import type { ActorStateDefinition, MessageActor } from '../../core/actors/create-machine-actor'; import { createMachineActor } from '../../core/actors/create-machine-actor'; import { SerialRunner, Task } from '../../core/tasks/task'; import type { PropertyPair } from '../../media/moq/loc'; @@ -65,6 +67,13 @@ export interface TrackPublisherCounters { queuedGroups: number; /** Timestamp of the most recently written object; NaN before the first. */ lastTimestampUs: number; + /** + * Group ID of the Largest Object written to the wire (§5.1.2); -1 before the first object. Paired with + * `largestObjectId`, this is what the session reports as LARGEST_OBJECT in SUBSCRIBE_OK. + */ + largestGroupId: number; + /** Object ID of the Largest Object within `largestGroupId`; -1 before the first object. */ + largestObjectId: number; } export type TrackPublisherMessage = @@ -131,7 +140,7 @@ interface GroupCell { /** Snapshot-context updates driven by the async stream work. */ type InternalMessage = - | { type: 'object-written'; bytes: number; timestampUs: number } + | { type: 'object-written'; bytes: number; timestampUs: number; groupId: number; objectId: number } | { type: 'group-opened' } | { type: 'group-finished' } | { type: 'groups-dropped'; count: number }; @@ -159,6 +168,13 @@ export function createTrackPublisherActor(options: TrackPublisherOptions): Track let boundAlias: number | undefined; /** Latest frame, retained for replay-on-bind (bound or not). */ let lastFrame: Extract | undefined; + /** + * Frames of the in-progress group (keyframe + deltas so far), retained for non-`groupPerFrame` tracks — bound or not + * — so a bind mid-group can replay the group from object 0. A fresh subscription (the relay's `relative-group 1` + * upstream join) needs a decodable start, and a subgroup stream that begins partway through a group is dropped by the + * peer. Reset on each keyframe; group-per-frame tracks use `replayLastGroupOnBind` instead. + */ + let currentGroupFrames: Extract[] = []; // Assigned right after createMachineActor returns; the runner tasks only // complete asynchronously, well after construction. @@ -270,7 +286,13 @@ export function createTrackPublisherActor(options: TrackPublisherOptions): Track endOfGroup: true, }); await cell.writer.writeObject({ objectId, properties: frame.properties, payload: frame.payload }); - inner?.send({ type: 'object-written', bytes: frame.payload.length, timestampUs: frame.timestampUs }); + inner?.send({ + type: 'object-written', + bytes: frame.payload.length, + timestampUs: frame.timestampUs, + groupId: cell.groupId, + objectId, + }); if (groupPerFrame) finishCell(cell); }) @@ -289,12 +311,37 @@ export function createTrackPublisherActor(options: TrackPublisherOptions): Track if (signal.aborted || cell.aborted) return; await cell.writer!.writeObject({ objectId, properties: frame.properties, payload: frame.payload }); - inner?.send({ type: 'object-written', bytes: frame.payload.length, timestampUs: frame.timestampUs }); + inner?.send({ + type: 'object-written', + bytes: frame.payload.length, + timestampUs: frame.timestampUs, + groupId: cell.groupId, + objectId, + }); }) ) .catch(failCell(cell)); }; + /** + * Replay the retained in-progress group as a fresh group under the current binding — the instant-join path for a + * subscription that arrived mid-group. Opens one stream, writes the retained frames as objects 0..n-1, and leaves the + * group open (`currentCell`) so live deltas continue extending it and the next keyframe FINs it. + */ + const openReplayGroup = (frames: readonly Extract[]): void => { + const cell: GroupCell = { groupId: nextGroupId++, trackAlias: boundAlias!, aborted: false }; + + openCells.push(cell); + scheduleOpen(cell, frames[0]!); + + let objectId = 1; + + for (let index = 1; index < frames.length; index++) scheduleWrite(cell, objectId++, frames[index]!); + + currentCell = cell; + nextObjectId = objectId; + }; + const scheduleFin = (cell: GroupCell): void => { runner .schedule( @@ -326,6 +373,50 @@ export function createTrackPublisherActor(options: TrackPublisherOptions): Track return dropped.length; }; + type CounterHandlers = Pick< + NonNullable['on']>, + InternalMessage['type'] + >; + + /** + * Counter bookkeeping shared verbatim between `publishing` and `ended`: once a group's stream work is scheduled, its + * async completions still land on the snapshot the same way whether or not a live frame can extend the group + * further. + */ + const counterHandlers = { + 'object-written': (msg, { context, setContext }) => { + const isLarger = + msg.groupId > context.largestGroupId || + (msg.groupId === context.largestGroupId && msg.objectId > context.largestObjectId); + + setContext({ + ...context, + publishedObjects: context.publishedObjects + 1, + bytesSent: context.bytesSent + msg.bytes, + lastTimestampUs: msg.timestampUs, + largestGroupId: isLarger ? msg.groupId : context.largestGroupId, + largestObjectId: isLarger ? msg.objectId : context.largestObjectId, + }); + }, + 'group-opened': (_, { context, setContext }) => { + setContext({ ...context, openedGroups: context.openedGroups + 1 }); + }, + 'group-finished': (_, { context, setContext }) => { + setContext({ + ...context, + publishedGroups: context.publishedGroups + 1, + queuedGroups: openCells.length, + }); + }, + 'groups-dropped': (msg, { context, setContext }) => { + setContext({ + ...context, + droppedGroups: context.droppedGroups + msg.count, + queuedGroups: openCells.length, + }); + }, + } satisfies CounterHandlers; + inner = createMachineActor({ initial: 'publishing', context: { @@ -336,6 +427,8 @@ export function createTrackPublisherActor(options: TrackPublisherOptions): Track bytesSent: 0, queuedGroups: 0, lastTimestampUs: Number.NaN, + largestGroupId: -1, + largestObjectId: -1, }, states: { publishing: { @@ -343,6 +436,15 @@ export function createTrackPublisherActor(options: TrackPublisherOptions): Track frame: (msg, { context, setContext }) => { if (replayLastGroupOnBind) lastFrame = msg; + // Retain the in-progress group (bound or not) so a later bind + // replays it from object 0 — a keyframe starts a fresh group, + // a decodable delta extends it, and a delta before the first + // keyframe has nothing to extend. + if (!groupPerFrame) { + if (msg.keyframe) currentGroupFrames = [msg]; + else if (currentGroupFrames.length > 0) currentGroupFrames.push(msg); + } + // Unbound: no subscription is reading this track — a stream // opened now would carry an alias the peer never registered. if (boundAlias === undefined) return; @@ -393,24 +495,31 @@ export function createTrackPublisherActor(options: TrackPublisherOptions): Track // drop), and stale serial work would delay the new // subscription's first data behind it. Video resumes at its // next keyframe under the new alias. + let droppedNow = 0; + if (boundAlias !== undefined) { - const droppedNow = dropQueuedGroups('the subscription was replaced with the group unfinished'); - - if (droppedNow > 0) { - setContext({ - ...context, - queuedGroups: openCells.length, - droppedGroups: context.droppedGroups + droppedNow, - }); - } + droppedNow = dropQueuedGroups('the subscription was replaced with the group unfinished'); } boundAlias = msg.trackAlias; - // The new subscription must not wait for the next change-driven - // frame; the re-sent frame takes the ordinary path (queued - // behind this message, boundAlias already set). + // Instant join: catalog-shaped tracks re-send their latest + // change-driven frame (queued behind this message, boundAlias + // already set); keyframe-grouped tracks replay the in-progress + // group from object 0 so a mid-group subscriber decodes without + // waiting for the next keyframe. + const replayedGroup = !replayLastGroupOnBind && !groupPerFrame && currentGroupFrames.length > 0; + if (replayLastGroupOnBind && lastFrame) inner?.send(lastFrame); + else if (replayedGroup) openReplayGroup(currentGroupFrames); + + if (droppedNow > 0 || replayedGroup) { + setContext({ + ...context, + queuedGroups: openCells.length, + droppedGroups: context.droppedGroups + droppedNow, + }); + } }, unbind: (_, { context, setContext }) => { if (boundAlias === undefined) return; @@ -437,62 +546,14 @@ export function createTrackPublisherActor(options: TrackPublisherOptions): Track transition('ended'); }, - 'object-written': (msg, { context, setContext }) => { - setContext({ - ...context, - publishedObjects: context.publishedObjects + 1, - bytesSent: context.bytesSent + msg.bytes, - lastTimestampUs: msg.timestampUs, - }); - }, - 'group-opened': (_, { context, setContext }) => { - setContext({ ...context, openedGroups: context.openedGroups + 1 }); - }, - 'group-finished': (_, { context, setContext }) => { - setContext({ - ...context, - publishedGroups: context.publishedGroups + 1, - queuedGroups: openCells.length, - }); - }, - 'groups-dropped': (msg, { context, setContext }) => { - setContext({ - ...context, - droppedGroups: context.droppedGroups + msg.count, - queuedGroups: openCells.length, - }); - }, + ...counterHandlers, }, }, ended: { // Late frames are ignored; queued work still drains, so the // counter updates keep landing. on: { - 'object-written': (msg, { context, setContext }) => { - setContext({ - ...context, - publishedObjects: context.publishedObjects + 1, - bytesSent: context.bytesSent + msg.bytes, - lastTimestampUs: msg.timestampUs, - }); - }, - 'group-opened': (_, { context, setContext }) => { - setContext({ ...context, openedGroups: context.openedGroups + 1 }); - }, - 'group-finished': (_, { context, setContext }) => { - setContext({ - ...context, - publishedGroups: context.publishedGroups + 1, - queuedGroups: openCells.length, - }); - }, - 'groups-dropped': (msg, { context, setContext }) => { - setContext({ - ...context, - droppedGroups: context.droppedGroups + msg.count, - queuedGroups: openCells.length, - }); - }, + ...counterHandlers, }, }, }, diff --git a/packages/spf/src/publish/behaviors/setup-track-publishers.ts b/packages/spf/src/publish/behaviors/setup-track-publishers.ts index fc15ab6d9b..6604c33514 100644 --- a/packages/spf/src/publish/behaviors/setup-track-publishers.ts +++ b/packages/spf/src/publish/behaviors/setup-track-publishers.ts @@ -62,6 +62,31 @@ export const VIDEO_TRACK_NAME = 'video'; export const SCREEN_TRACK_NAME = 'screen'; export const AUDIO_TRACK_NAME = 'audio'; +/** + * Publisher priorities for the built-in tracks. Integers from 0 (highest) to 255 (lowest); omitted entries use catalog + * 0, audio 64, camera 128, and screen 192. Applied to both MoQ subgroup headers and local WebTransport send order. + * Relay scheduling also depends on subscriber priorities and the relay's policy. + */ +export interface PublishTrackPriorities { + catalog?: number; + audio?: number; + camera?: number; + screen?: number; +} + +const DEFAULT_TRACK_PRIORITIES = { catalog: 0, audio: 64, camera: 128, screen: 192 } as const; +const DEFAULT_DATA_TRACK_PRIORITY = 128; + +function resolvePriority(value: number | undefined, fallback: number): number { + if (value === undefined) return fallback; + + if (Number.isInteger(value) && value >= 0 && value <= 255) return value; + + if (__DEV__) console.warn(`[moq-publish] track priority must be an integer from 0 to 255; using ${fallback}`); + + return fallback; +} + /** Track names the engine publishes itself — refused for data tracks. */ const RESERVED_TRACK_NAMES: ReadonlySet = new Set([ CATALOG_TRACK_NAME, @@ -81,6 +106,8 @@ export interface PublishDataTrackConfig { * naming one (or duplicating another data track) is dropped with a dev warning. */ name: string; + /** Publisher priority, 0 (highest) to 255 (lowest). Defaults to 128; invalid values use the default. */ + priority?: number; /** * MSF role label emitted on the track's catalog entry (e.g. `'data'`). Any non-media value keeps the track out of a * subscriber's renderable set; omitted, the entry carries no role and is classified the same way from its absent @@ -184,6 +211,8 @@ export interface SetupTrackPublishersContext { } export interface SetupTrackPublishersConfig { + /** Built-in track priorities; lower numbers are served first. */ + trackPriorities?: PublishTrackPriorities; /** Groups the transport may fall behind before dropping to the keyframe. */ maxQueuedGroups?: number; /** @@ -209,6 +238,7 @@ interface PublisherCluster { session: MoqtPublishSession; namespace: string[]; maxQueuedGroups?: number | undefined; + priorities: Required; /** Creation order; teardown quiesces in reverse. */ created: { handle: RegisteredTrack; @@ -221,18 +251,29 @@ interface PublisherCluster { function addTrackPublisher( cluster: PublisherCluster, trackName: string, - options: { groupPerFrame: boolean; replayLastGroupOnBind?: boolean } + options: { groupPerFrame: boolean; replayLastGroupOnBind?: boolean; priority: number } ): TrackPublisherActor { - const handle = cluster.session.registerTrack({ - trackNamespace: cluster.namespace, - trackName, - }); const publisher = createTrackPublisherActor({ - openUniStream: () => cluster.session.openUniStream(), + // WebTransport orders larger values first. Keep all media below the + // default order (0) of control/request streams so congestion cannot + // starve the signaling needed to stop or change a subscription. + openUniStream: () => cluster.session.openUniStream({ sendOrder: -1 - options.priority }), + priority: options.priority, groupPerFrame: options.groupPerFrame, replayLastGroupOnBind: options.replayLastGroupOnBind === true, maxQueuedGroups: cluster.maxQueuedGroups, }); + const handle = cluster.session.registerTrack({ + trackNamespace: cluster.namespace, + trackName, + // The publisher owns the Largest Object it has written; the session + // reads it here to report LARGEST_OBJECT in SUBSCRIBE_OK (§10.2.17). + getLargestObject: () => { + const { largestGroupId, largestObjectId } = publisher.snapshot.get().context; + + return largestGroupId >= 0 ? { group: largestGroupId, object: largestObjectId } : undefined; + }, + }); cluster.created.push({ handle, publisher, boundAlias: undefined }); return publisher; @@ -323,12 +364,19 @@ function setupTrackPublishersSetup({ session, namespace: endpoint.namespace, maxQueuedGroups: config.maxQueuedGroups, + priorities: { + catalog: resolvePriority(config.trackPriorities?.catalog, DEFAULT_TRACK_PRIORITIES.catalog), + audio: resolvePriority(config.trackPriorities?.audio, DEFAULT_TRACK_PRIORITIES.audio), + camera: resolvePriority(config.trackPriorities?.camera, DEFAULT_TRACK_PRIORITIES.camera), + screen: resolvePriority(config.trackPriorities?.screen, DEFAULT_TRACK_PRIORITIES.screen), + }, created: [], }; // Catalog first — the subscription anchor every player joins on. context.catalogTrackPublisher.set( addTrackPublisher(next, CATALOG_TRACK_NAME, { + priority: next.priorities.catalog, groupPerFrame: true, replayLastGroupOnBind: true, }) @@ -340,6 +388,7 @@ function setupTrackPublishersSetup({ for (const track of dataTracks) { const publisher = addTrackPublisher(next, track.name, { + priority: resolvePriority(track.priority, DEFAULT_DATA_TRACK_PRIORITY), groupPerFrame: true, replayLastGroupOnBind: track.replayLastOnSubscribe, }); @@ -390,15 +439,30 @@ function setupTrackPublishersSetup({ if (!current || !encodings) return; if (encodings.camera && peek(context.videoTrackPublisher) === undefined) { - context.videoTrackPublisher.set(addTrackPublisher(current, VIDEO_TRACK_NAME, { groupPerFrame: false })); + context.videoTrackPublisher.set( + addTrackPublisher(current, VIDEO_TRACK_NAME, { + groupPerFrame: false, + priority: current.priorities.camera, + }) + ); } if (encodings.screen && peek(context.screenTrackPublisher) === undefined) { - context.screenTrackPublisher.set(addTrackPublisher(current, SCREEN_TRACK_NAME, { groupPerFrame: false })); + context.screenTrackPublisher.set( + addTrackPublisher(current, SCREEN_TRACK_NAME, { + groupPerFrame: false, + priority: current.priorities.screen, + }) + ); } if (encodings.audio && peek(context.audioTrackPublisher) === undefined) { - context.audioTrackPublisher.set(addTrackPublisher(current, AUDIO_TRACK_NAME, { groupPerFrame: true })); + context.audioTrackPublisher.set( + addTrackPublisher(current, AUDIO_TRACK_NAME, { + groupPerFrame: true, + priority: current.priorities.audio, + }) + ); } }, diff --git a/packages/spf/src/publish/behaviors/tests/setup-track-publishers.test.ts b/packages/spf/src/publish/behaviors/tests/setup-track-publishers.test.ts index d0e8c0d68b..66ae1f6b03 100644 --- a/packages/spf/src/publish/behaviors/tests/setup-track-publishers.test.ts +++ b/packages/spf/src/publish/behaviors/tests/setup-track-publishers.test.ts @@ -33,7 +33,7 @@ function makeSessionActor() { }); disposals.push(() => actor.destroy()); - return { actor, peer, server: pair.server }; + return { actor, peer, server: pair.server, client: pair.client }; } function setupBehavior(config: SetupTrackPublishersConfig = {}) { @@ -58,6 +58,63 @@ function setupBehavior(config: SetupTrackPublishersConfig = {}) { describe('setupTrackPublishers', () => { afterEach(() => { for (const dispose of disposals.splice(0)) dispose(); + + vi.restoreAllMocks(); + }); + + it.each([ + { name: 'default', priorities: undefined, expected: [0, 128, 192, 64] }, + { name: 'custom', priorities: { audio: 0, camera: 255, screen: 32 }, expected: [0, 255, 32, 0] }, + { name: 'invalid', priorities: { audio: NaN, camera: -1, screen: 256, catalog: 0.5 }, expected: [0, 128, 192, 64] }, + ])('carries $name track priorities on the wire and into upload scheduling', async ({ priorities, expected }) => { + vi.spyOn(console, 'warn').mockImplementation(() => {}); + const { actor, peer, server, client } = makeSessionActor(); + const open = vi.spyOn(client, 'createUnidirectionalStream'); + const { state, context } = setupBehavior({ + trackPriorities: priorities, + dataTracks: [{ name: 'overlay', priority: 17 }], + }); + + state.endpoint.set(ENDPOINT); + state.activeEncodings.set({ camera: VIDEO_CONFIG, screen: VIDEO_CONFIG, audio: AUDIO_CONFIG }); + context.publishSessionActor.set(actor); + void solicitNamespace(server, []); + await vi.waitFor(() => expect(context.audioTrackPublisher.get()).toBeDefined()); + + const received: Record = {}; + const names = ['catalog', 'video', 'screen', 'audio', 'overlay']; + + for (const trackName of names) { + peer.subscribe( + { trackNamespace: ENDPOINT.namespace, trackName }, + { + onObject: (object) => { + received[trackName] = object.priority; + }, + } + ); + } + + await vi.waitFor(() => expect(Object.keys(actor.snapshot.get().context.trackBindings)).toHaveLength(names.length)); + + for (const slot of [ + 'catalogTrackPublisher', + 'videoTrackPublisher', + 'screenTrackPublisher', + 'audioTrackPublisher', + ] as const) { + context[slot] + .get()! + .send({ type: 'frame', payload: new Uint8Array([1]), properties: [], keyframe: true, timestampUs: 0 }); + } + + context.dataTrackProducers.get()!.overlay!.publish(new Uint8Array([1])); + await vi.waitFor(() => expect(Object.keys(received)).toHaveLength(names.length)); + expect(names.map((name) => received[name])).toEqual([...expected, 17]); + + for (const priority of [...expected, 17]) { + expect(open).toHaveBeenCalledWith({ sendOrder: -1 - priority }); + } }); it('registers catalog + active tracks and publishes the actor slots once the session is ready', async () => { @@ -168,7 +225,8 @@ describe('setupTrackPublishers', () => { }); const publisher = context.videoTrackPublisher.get()!; - // Unsubscribed: a keyframe goes nowhere (pull-through ingest). + // Unsubscribed: a keyframe opens no stream (pull-through ingest) but + // is retained as the in-progress group. publisher.send({ type: 'frame', payload: new Uint8Array([1]), properties: [], keyframe: true, timestampUs: 0 }); await new Promise((resolve) => setTimeout(resolve, 20)); expect(publisher.snapshot.get().context.openedGroups).toBe(0); @@ -183,8 +241,14 @@ describe('setupTrackPublishers', () => { expect(actor.snapshot.get().context.trackBindings.video).toBeDefined(); }); - // The binding-sync effect has bound the publisher — the next keyframe - // reaches the subscriber. + // The binding-sync effect bound the publisher, which replays the + // retained in-progress group from object 0 — the instant join. + await vi.waitFor(() => { + expect(payloads).toHaveLength(1); + }); + expect(payloads[0]).toEqual(new Uint8Array([1])); + + // A live keyframe follows on the same subscription. publisher.send({ type: 'frame', payload: new Uint8Array([2, 2]), @@ -193,9 +257,9 @@ describe('setupTrackPublishers', () => { timestampUs: 1_000, }); await vi.waitFor(() => { - expect(payloads).toHaveLength(1); + expect(payloads).toHaveLength(2); }); - expect(payloads[0]).toEqual(new Uint8Array([2, 2])); + expect(payloads[1]).toEqual(new Uint8Array([2, 2])); }); it('keeps the publishers through an encodings gap and destroys them when the session goes away', async () => { diff --git a/packages/spf/src/publish/behaviors/tests/track-publish-stats.test.ts b/packages/spf/src/publish/behaviors/tests/track-publish-stats.test.ts index 78d3e2772f..af22fdafab 100644 --- a/packages/spf/src/publish/behaviors/tests/track-publish-stats.test.ts +++ b/packages/spf/src/publish/behaviors/tests/track-publish-stats.test.ts @@ -73,6 +73,8 @@ const ZERO_PUBLISHER_COUNTERS: TrackPublisherCounters = { bytesSent: 0, queuedGroups: 0, lastTimestampUs: Number.NaN, + largestGroupId: -1, + largestObjectId: -1, }; function makePublisher(counters: Partial): TrackPublisherActor { diff --git a/packages/spf/src/publish/engines/moq/engine.ts b/packages/spf/src/publish/engines/moq/engine.ts index 9723e6ae13..4cbd7c6059 100644 --- a/packages/spf/src/publish/engines/moq/engine.ts +++ b/packages/spf/src/publish/engines/moq/engine.ts @@ -37,7 +37,11 @@ import type { PreviewSource } from '../../behaviors/dom/sync-preview'; import { syncPreview } from '../../behaviors/dom/sync-preview'; import type { PublishSessionStatus } from '../../behaviors/open-publish-session'; import { openPublishSession } from '../../behaviors/open-publish-session'; -import type { DataTrackProducer, PublishDataTrackConfig } from '../../behaviors/setup-track-publishers'; +import type { + DataTrackProducer, + PublishDataTrackConfig, + PublishTrackPriorities, +} from '../../behaviors/setup-track-publishers'; import { setupTrackPublishers } from '../../behaviors/setup-track-publishers'; import type { PublishStatsFacts } from '../../behaviors/track-publish-stats'; import { trackPublishStats } from '../../behaviors/track-publish-stats'; @@ -62,6 +66,7 @@ export type { EncoderSupportFacts, PreviewSource, PublishDataTrackConfig, + PublishTrackPriorities, PublishEndpoint, PublishErrorFacts, PublishSessionActor, @@ -157,6 +162,13 @@ export interface MoqPublishEngineSignals { // ============================================================================ export interface MoqPublishEngineConfig extends ShareSignalsConfig { + /** + * Relative track importance for MoQ delivery and browser upload scheduling. Defaults to catalog, audio, camera, then + * screen. Lower numbers have higher priority; see {@link PublishTrackPriorities}. Invalid values use the default. + * + * To favor screen sharing over camera video while keeping audio first, set `{ audio: 32, screen: 64, camera: 128 }`. + */ + trackPriorities?: PublishTrackPriorities; /** Forced-keyframe cadence; each GoP becomes one MoQ group. */ groupDurationSec?: number; /** Camera video tuning (an array per kind is the simulcast seam, later). */ diff --git a/packages/spf/src/publish/engines/moq/index.ts b/packages/spf/src/publish/engines/moq/index.ts index 16f8643907..7bcda93271 100644 --- a/packages/spf/src/publish/engines/moq/index.ts +++ b/packages/spf/src/publish/engines/moq/index.ts @@ -26,6 +26,7 @@ export type { MoqPublishEngineState, PreviewSource, PublishDataTrackConfig, + PublishTrackPriorities, PublishEndpoint, PublishErrorFacts, PublishSessionActor, diff --git a/packages/spf/src/publish/engines/moq/tests/cross-engine-network.test.ts b/packages/spf/src/publish/engines/moq/tests/cross-engine-network.test.ts new file mode 100644 index 0000000000..3124b196d2 --- /dev/null +++ b/packages/spf/src/publish/engines/moq/tests/cross-engine-network.test.ts @@ -0,0 +1,94 @@ +import { afterEach, describe, expect, it, vi } from 'vite-plus/test'; + +import { createRelayHub } from '../../../tests/helpers/relay-hub'; +import { createMoqPublishEngine } from '../engine'; +import { createSubscriber, makeSyntheticStream } from './helpers/cross-engine-harness'; + +const disposals: (() => void)[] = []; + +describe('createMoqPublishEngine', () => { + afterEach(() => { + for (const dispose of disposals.splice(0)) dispose(); + + vi.restoreAllMocks(); + }); + + it('keeps presented video aligned with audio through delayed object streams and recovery', async () => { + vi.spyOn(navigator.mediaDevices, 'getUserMedia').mockImplementation(async () => + makeSyntheticStream({ width: 320, height: 240 }, true, disposals) + ); + let impaired = false; + let delayedAudio = 0; + const hub = createRelayHub({ + deliveryDelayMs: (trackName, object) => { + if (!impaired || trackName === 'catalog') return 0; + + // Every fifth audio packet arrives after its successor has been + // consumed. These short holes used to disappear from decoder + // output timestamps, accumulating permanent A/V drift. + if (trackName === 'audio' && object.groupId % 5 === 0) { + delayedAudio++; + return 700; + } + + return 100 + ((object.groupId * 37 + object.objectId * 17) % 100); + }, + }); + + disposals.push(() => hub.destroy()); + const publisher = createMoqPublishEngine({ + camera: { codec: 'vp8' }, + connectTransport: hub.connectPublisher, + }); + + disposals.push(() => void publisher.destroy()); + publisher.state.endpoint.set({ url: 'https://relay.test/moq', namespace: ['live'] }); + publisher.state.cameraActive.set(true); + publisher.state.micActive.set(true); + publisher.state.publishActivated.set(true); + + const { signals } = createSubscriber(hub, disposals); + + signals.state.paused.set(false); + await vi.waitFor( + () => { + expect(signals.context.videoRendererActor.get()?.snapshot.get().context.lastPresentedTimestampUs).toBeDefined(); + expect(signals.context.audioRendererActor.get()?.getClockTimeUs()).toBeDefined(); + }, + { timeout: 10_000 } + ); + + for (const phase of ['baseline', 'impaired', 'recovery'] as const) { + impaired = phase === 'impaired'; + const audio = signals.context.audioRendererActor.get()!; + const video = signals.context.videoRendererActor.get()!; + const firstAudioUs = audio.getClockTimeUs()!; + const firstVideoUs = video.snapshot.get().context.lastPresentedTimestampUs!; + const skews: number[] = []; + const durationMs = phase === 'impaired' ? 12_000 : 3_000; + const started = performance.now(); + + while (performance.now() - started < durationMs) { + await new Promise((resolve) => setTimeout(resolve, 100)); + const presentedUs = video.snapshot.get().context.lastPresentedTimestampUs!; + const audioUs = audio.getClockTimeUs()!; + + skews.push(Math.abs(presentedUs - audioUs)); + } + + skews.sort((a, b) => a - b); + expect(skews[Math.floor(skews.length * 0.95)], `${phase} p95 A/V skew`).toBeLessThan(150_000); + expect(Math.max(...skews), `${phase} maximum A/V skew`).toBeLessThan(750_000); + // Aligned frozen clocks are not successful playback. + expect(audio.getClockTimeUs()! - firstAudioUs, `${phase} audio progress`).toBeGreaterThan(durationMs * 700); + expect( + video.snapshot.get().context.lastPresentedTimestampUs! - firstVideoUs, + `${phase} video progress` + ).toBeGreaterThan(durationMs * 700); + expect(audio.snapshot.get().context.status).toBe('rendering'); + expect(video.snapshot.get().context.status).toBe('rendering'); + } + + expect(delayedAudio).toBeGreaterThan(50); + }, 30_000); +}); diff --git a/packages/spf/src/publish/session/publish-session.ts b/packages/spf/src/publish/session/publish-session.ts index 15dc472802..7cb1f0ad69 100644 --- a/packages/spf/src/publish/session/publish-session.ts +++ b/packages/spf/src/publish/session/publish-session.ts @@ -22,6 +22,8 @@ * `publish/` behavior layer through the actor below. Lives in `publish/` rather than `network/moqt` so the parent-owned * wire layer keeps only additive sibling files. */ +import { hasMethods } from '@videojs/utils/predicate'; + import { createTransitionActor, type TransitionActor } from '../../core/actors/create-transition-actor'; import { MICROSECONDS_PER_SECOND } from '../../media/moq/loc'; import { StreamReader, utf8Encode } from '../../network/moqt/bytes'; @@ -34,7 +36,10 @@ import { encodeRequestOk, encodeSetup, encodeSubscribeOk, + type FillParameters, + isEmptyFetchRange, type KeyValuePair, + type Location, MESSAGE_TYPE, type MessageParameters, MOQT_PROTOCOL_ID, @@ -44,7 +49,7 @@ import { type TrackNamespace, } from '../../network/moqt/control-messages'; import { isMoqtProtocolError, MoqtProtocolError, SESSION_ERROR } from '../../network/moqt/errors'; -import { isSubgroupHeaderType, STREAM_TYPE } from '../../network/moqt/object-stream'; +import { encodeFetchHeader, isSubgroupHeaderType, STREAM_TYPE } from '../../network/moqt/object-stream'; import type { BidirectionalStreamLike } from '../../network/moqt/request-stream'; import type { Goaway, MoqtTransport } from '../../network/moqt/session'; @@ -106,6 +111,13 @@ export interface MoqtPublishSessionConfig { export interface RegisterTrackOptions { trackNamespace: TrackNamespace; trackName: string; + /** + * The track's Largest Object (§10.2.17), read when answering SUBSCRIBE and REQUEST_UPDATE so each response reports it + * once content exists (the spec MUST, and moq-lite-rs relays decode it). Pulled at request time rather than pushed so + * it never churns the session; returning `undefined` (or omitting this) means nothing has been published yet and the + * parameter is left off. + */ + getLargestObject?: () => Location | undefined; } export interface RegisteredTrack { @@ -129,7 +141,7 @@ export interface MoqtPublishSession { /** Register one servable track; the peer's SUBSCRIBEs are answered from this registry. */ registerTrack(options: RegisterTrackOptions): RegisteredTrack; /** Open a unidirectional data stream (for a track publisher's subgroups). */ - openUniStream(): Promise>; + openUniStream(options?: { sendOrder?: number }): Promise>; /** * Orderly stop: FIN every live subscription's stream and retract the announce (NAMESPACE_DONE), give those writes a * bounded window to reach the wire (closing a WebTransport discards queued data), then close the transport. @@ -164,6 +176,12 @@ interface SubscriberStream { /** Forward State (§ SUBSCRIBE `forward`, togglable via REQUEST_UPDATE) — data flows only while true. */ forwarding: boolean; finished: boolean; + /** Includes pending stream opens, so cancellation also catches late arrivals. */ + fills: Set; +} + +interface FillStream { + writer?: WritableStreamDefaultWriter; } interface TrackRecord { @@ -179,6 +197,8 @@ interface TrackRecord { pendingFins: Promise[]; /** Settles when the FINs queued by `end()` land. */ doneFlushed?: Promise; + /** Reads the track's Largest Object for responses (see `RegisterTrackOptions.getLargestObject`). */ + getLargestObject?: () => Location | undefined; } /** One accepted inbound SUBSCRIBE_NAMESPACE — the announce carrier. */ @@ -476,6 +496,7 @@ class MoqtPublishSessionImpl implements MoqtPublishSession { subscribers: [], done: false, pendingFins: [], + getLargestObject: options.getLargestObject, }; this.#tracks.set(track.key, track); @@ -533,7 +554,7 @@ class MoqtPublishSessionImpl implements MoqtPublishSession { track.doneFlushed = Promise.all(writes).then(() => {}); } - openUniStream(): Promise> { + openUniStream(options?: { sendOrder?: number }): Promise> { // Refuse rather than touch the transport once the session is going // away. Encoders keep producing frames for a beat after a peer kills // the session, and hammering createUnidirectionalStream() on a @@ -544,7 +565,78 @@ class MoqtPublishSessionImpl implements MoqtPublishSession { return Promise.reject(new Error('moq publish session: closed')); } - return this.#transport.createUnidirectionalStream(); + return this.#transport.createUnidirectionalStream(options); + } + + /** + * Whether a SUBSCRIBE or REQUEST_UPDATE carrying FILL_PARAMETERS calls for a fill fetch stream (§5.1.3.1): only while + * Forward State is 1, only for a subscription that is still live, and only when the fill range is nonempty. The fill + * range is the filter inside FILL_PARAMETERS — else the subscription's own — evaluated as a fetch against the track's + * Largest Object; an empty range, or one starting past Largest Object, opens no stream at all (§5.1.3), so a peer + * asking to fill from the Next Object, or before the track has content, is simply not answered. + */ + #fillRequested( + largestObject: Location | undefined, + subscriber: SubscriberStream, + subscription: MessageParameters, + fill: FillParameters | undefined + ): boolean { + if (fill === undefined || !subscriber.forwarding || subscriber.finished) return false; + + const filter = fill.locationFilter ?? subscription.locationFilter ?? { type: 'none' }; + + return !isEmptyFetchRange(filter, largestObject); + } + + #resetFills(subscriber: SubscriberStream): void { + for (const fill of subscriber.fills) { + void fill.writer?.abort(new Error('moq publish session: subscription ended')).catch(() => {}); + } + + subscriber.fills.clear(); + } + + /** + * Answer a nonempty fill request (see `#fillRequested`). This origin serves no fills, so it meets the §5.1.3.1 + * requirement the honest way: open a uni stream, write the FETCH_HEADER carrying the initiating Request ID so the + * subscriber can correlate the failure, then reset it. A reset is the fill-failure signal — a FIN would falsely claim + * the fill range was delivered in full. The known relays never send FILL_PARAMETERS today; this keeps a peer that + * does from stalling on a fill that never arrives. + */ + #openAndResetFill(requestId: number, subscriber: SubscriberStream): void { + const fill: FillStream = {}; + + subscriber.fills.add(fill); + + void (async () => { + try { + const stream = await this.openUniStream(); + const writer = stream.getWriter(); + + fill.writer = writer; + + if (!subscriber.fills.has(fill) || subscriber.finished) return; + + // All WebTransport writers expose the same capabilities, probed + // on the control writer before accepting a nonempty fill. Check + // this stream too so an inconsistent injected transport never + // writes a header it cannot preserve through the reset. + if (!hasMethods(writer, ['commit'])) return; + + await writer.write(encodeFetchHeader(requestId)); + + if (!subscriber.fills.has(fill) || subscriber.finished) return; + + // write() only hands bytes to the transport. commit() includes + // them in the reliable prefix of RESET_STREAM_AT. + writer.commit(); + } catch { + // Session closing or the peer went away before the header landed. + } finally { + subscriber.fills.delete(fill); + void fill.writer?.abort(new Error('moq publish session: fill fetch streams are not served')).catch(() => {}); + } + })(); } // --------------------------------------------------------------------------- @@ -868,9 +960,13 @@ class MoqtPublishSessionImpl implements MoqtPublishSession { const subscriber: SubscriberStream = { requestId: subscribe.requestId, trackAlias, - fin: () => writer.close(), + fin: () => { + this.#resetFills(subscriber); + return writer.close(); + }, cancel: async () => { subscriber.finished = true; + this.#resetFills(subscriber); writer.abort().catch(() => {}); try { @@ -885,18 +981,50 @@ class MoqtPublishSessionImpl implements MoqtPublishSession { // authorizing data until a REQUEST_UPDATE flips it. forwarding: subscribe.parameters.forward !== 0, finished: false, + fills: new Set(), }; + // Use one snapshot for both the response and its fill range, even if + // the response write is backpressured while live objects advance. + const largestObject = track.getLargestObject?.(); + const fillRequested = this.#fillRequested( + largestObject, + subscriber, + subscribe.parameters, + subscribe.parameters.fillParameters + ); + + if (fillRequested && !hasMethods(this.#controlWriter, ['commit'])) { + try { + await writer.write(encodeRequestError(REQUEST_ERROR_CODE.NOT_SUPPORTED, 'fill requires reliable stream reset')); + await writer.close(); + } catch { + // Peer cancelled. + } + + await reader.cancel(); + return; + } + track.subscribers.push(subscriber); + // STOP_SENDING on the response direction cancels the subscription + // even when the request direction stays open and sends no updates. + void writer.closed.catch(() => subscriber.cancel()); + try { - // Declaring the track's timescale is what keeps object TIMESTAMP - // extensions flowing through moq-lite-rs relays — undeclared, they - // parse and discard them and re-stamp frames on arrival, and the - // viewer's clocks would sync to relay arrival time instead of - // capture time. LOC packaging stamps objects in microseconds. + // Report the track's Largest Object once content exists (§10.2.17 + // MUST; the relay decodes it length-prefixed) so a `relative-group` + // subscriber can resolve its join. Declaring the timescale is what + // keeps object TIMESTAMP extensions flowing through moq-lite-rs + // relays — undeclared, they parse and discard them and re-stamp + // frames on arrival, and the viewer's clocks would sync to relay + // arrival time instead of capture time. LOC packaging stamps objects + // in microseconds. await writer.write( - encodeSubscribeOk(trackAlias, {}, [{ type: TRACK_PROPERTY.TIMESCALE, value: MICROSECONDS_PER_SECOND }]) + encodeSubscribeOk(trackAlias, largestObject ? { largestObject } : {}, [ + { type: TRACK_PROPERTY.TIMESCALE, value: MICROSECONDS_PER_SECOND }, + ]) ); subscriber.accepted = true; } catch { @@ -947,6 +1075,14 @@ class MoqtPublishSessionImpl implements MoqtPublishSession { }); } + // FILL_PARAMETERS on the SUBSCRIBE requests a fill fetch stream, but + // only while Forward State is 1 and only for a nonempty fill range + // (§5.1.3). We serve none — open and reset it rather than leave the + // peer waiting. + if (fillRequested && !subscriber.finished) { + this.#openAndResetFill(subscribe.requestId, subscriber); + } + // Keep serving the request stream: REQUEST_UPDATEs arrive here. try { while (!(await reader.atEnd())) { @@ -955,7 +1091,11 @@ class MoqtPublishSessionImpl implements MoqtPublishSession { if (message.kind === 'request-update') { this.#claimPeerRequestId(message.requestId); - const { forward, subscriberPriority: _priority, ...unsupported } = message.parameters; + // FILL_PARAMETERS is a per-message fill request (§5.1.3), not a + // subscription-state change — pulled out so it neither counts as + // an unsupported update nor sticks to the subscription. + const { forward, subscriberPriority: _priority, fillParameters, ...unsupported } = message.parameters; + const largestObject = track.getLargestObject?.(); // Forward State toggles ride REQUEST_UPDATE; the binding must // follow so data stops (or starts) with the subscription's @@ -972,6 +1112,12 @@ class MoqtPublishSessionImpl implements MoqtPublishSession { } } + // A nonempty fill requested while Forward State is 1 opens (and, + // here, immediately resets) a fill fetch stream keyed by the + // update's own Request ID (§5.1.3.1); an empty range opens none. + const fillRequested = this.#fillRequested(largestObject, subscriber, subscribe.parameters, fillParameters); + const unsupportedFill = fillRequested && !hasMethods(this.#controlWriter, ['commit']); + this.#callbacks.onRequestUpdate?.({ requestId: subscribe.requestId, updateRequestId: message.requestId, @@ -979,13 +1125,14 @@ class MoqtPublishSessionImpl implements MoqtPublishSession { }); if (!subscriber.finished) { - if (Object.keys(unsupported).length > 0) { + if (Object.keys(unsupported).length > 0 || unsupportedFill) { // Acknowledging an update we did not apply would leave the // peer serving stale expectations (a filter or range it // believes is in effect). Forward State is applied above // and priority is advisory (the known relays discard ours // too); anything else ends this request honestly. subscriber.finished = true; + this.#resetFills(subscriber); void writer .write(encodeRequestError(REQUEST_ERROR_CODE.NOT_SUPPORTED, 'unsupported subscription update')) .then(() => writer.close()) @@ -1003,7 +1150,9 @@ class MoqtPublishSessionImpl implements MoqtPublishSession { // completion (`onUpdateOk`). Strictly reactive: a peer that // never sends REQUEST_UPDATE (moq-lite-rs parks on end-of- // stream after SUBSCRIBE_OK) never sees a trailing byte. - void writer.write(encodeRequestOk()).catch(() => {}); + void writer.write(encodeRequestOk(largestObject ? { largestObject } : {})).catch(() => {}); + + if (fillRequested) this.#openAndResetFill(message.requestId, subscriber); } } } else if (message.kind === 'goaway') { @@ -1018,6 +1167,7 @@ class MoqtPublishSessionImpl implements MoqtPublishSession { // Reset — the subscriber cancelled (§3.3.3); ordinary end-of-request. } finally { subscriber.finished = true; + this.#resetFills(subscriber); track.subscribers = track.subscribers.filter((s) => s !== subscriber); // The subscription is over both ways — mirror of the namespace // stream's cleanup: when the peer FINed first, an unclosed response diff --git a/packages/spf/src/publish/session/tests/publish-session.test.ts b/packages/spf/src/publish/session/tests/publish-session.test.ts index 8c910dd273..3ed5439257 100644 --- a/packages/spf/src/publish/session/tests/publish-session.test.ts +++ b/packages/spf/src/publish/session/tests/publish-session.test.ts @@ -4,6 +4,7 @@ import { toLocFrame } from '../../../media/moq/loc'; import { packageLocFrame } from '../../../media/moq/loc-packaging'; import { applyMoqCatalogUpdate } from '../../../media/moq/parse-catalog'; import { utf8Decode, utf8Encode } from '../../../network/moqt/bytes'; +import { StreamReader } from '../../../network/moqt/bytes'; import { type ControlMessage, ControlMessageDeframer, @@ -18,7 +19,7 @@ import { TRACK_PROPERTY, type TrackNamespace, } from '../../../network/moqt/control-messages'; -import type { MoqtObject } from '../../../network/moqt/object-stream'; +import { type MoqtObject, readFetchHeader, STREAM_TYPE } from '../../../network/moqt/object-stream'; import { createMoqtSession, type MoqtSession } from '../../../network/moqt/session'; import { openRawRequest, @@ -68,6 +69,134 @@ function collectTrack( return { objects, aliases, subscription }; } +/** + * A publish session facing a raw peer with no subscribe driver: the peer completes SETUP by hand and watches the + * publisher's uni streams for fill fetch streams, recording each FETCH_HEADER's Request ID and whether the publisher + * reset the stream (the fill-failure signal) or FINed it. `finish()` destroys the session and releases the observer's + * reader — the transport pair never ends its incoming-stream queues, so a pending `read()` would otherwise outlive the + * test. + */ +async function makeFillHarness({ + reliableReset = true, + openFillStream, +}: { + reliableReset?: boolean; + openFillStream?: () => Promise>; +} = {}) { + const pair = createTransportPair(); + const openUniStream = pair.client.createUnidirectionalStream.bind(pair.client); + let openedControl = false; + + pair.client.createUnidirectionalStream = async () => { + if (openedControl && openFillStream) return openFillStream(); + + openedControl = true; + const stream = await openUniStream(); + const getWriter = stream.getWriter.bind(stream); + + // This zero-buffer pipe settles writes only once the peer has read + // them, so its reliable prefix is already delivered at commit time. + if (reliableReset) stream.getWriter = () => Object.assign(getWriter(), { commit() {} }); + + return stream; + }; + + const session = createMoqtPublishSession(pair.client); + const fills: { requestId: number; reset: boolean }[] = []; + const streams = pair.server.incomingUnidirectionalStreams.getReader(); + + void (async () => { + while (true) { + const { done, value } = await streams.read(); + if (done) break; + + void (async () => { + const reader = new StreamReader(value); + const type = await reader.readVarint().catch(() => -1); + if (type !== STREAM_TYPE.FETCH_HEADER) return; + + const { requestId } = await readFetchHeader(reader); + + // The publisher resets after the FETCH_HEADER; the drain throws. + try { + while (!(await reader.atEnd())) await reader.readUint8(); + + fills.push({ requestId, reset: false }); + } catch { + fills.push({ requestId, reset: true }); + } + })(); + } + })(); + + const control = await pair.server.createUnidirectionalStream(); + + await control.getWriter().write(encodeSetup()); + await session.ready; + + return { + pair, + session, + fills, + finish: async () => { + session.destroy(); + await streams.cancel(); + }, + }; +} + +/** A buffered send stream: reset discards everything except the explicitly committed prefix. */ +function makeBufferedFillStream() { + const chunks: Uint8Array[] = []; + let committed = 0; + let readIndex = 0; + let reset: unknown; + let pendingRead: ReadableStreamDefaultController | undefined; + const deliver = () => { + if (!pendingRead) return; + + const controller = pendingRead; + const limit = reset ? committed : chunks.length; + + if (readIndex < limit) { + pendingRead = undefined; + controller.enqueue(chunks[readIndex++]!); + } else if (reset) { + pendingRead = undefined; + controller.error(reset); + } + }; + const readable = new ReadableStream( + { + pull(controller) { + pendingRead = controller; + deliver(); + }, + }, + { highWaterMark: 0 } + ); + const writable = new WritableStream({ + write(chunk) { + chunks.push(chunk); + deliver(); + }, + abort(reason) { + reset = reason; + deliver(); + }, + }); + const getWriter = writable.getWriter.bind(writable); + + writable.getWriter = () => + Object.assign(getWriter(), { + commit() { + committed = chunks.length; + }, + }); + + return { writable, readable, reset: () => reset }; +} + describe('createMoqtPublishSession', () => { it('completes SETUP both ways against the existing subscribe driver', async () => { const { session, subscriber } = makePublishHarness(); @@ -861,6 +990,288 @@ describe('createMoqtPublishSession', () => { subscriber.destroy(); }); + it('reports the track Largest Object in SUBSCRIBE_OK once content exists', async () => { + const { pair, session, subscriber } = makePublishHarness(); + + await session.ready; + let largest: { group: number; object: number } | undefined; + + session.registerTrack({ trackNamespace: NAMESPACE, trackName: 'video', getLargestObject: () => largest }); + + // No content yet — SUBSCRIBE_OK omits LARGEST_OBJECT (§10.2.17). + const early = await rawSubscribe(pair.server, 'video', 201); + + await vi.waitFor(() => { + expect(early.received.map((m) => m.kind)).toEqual(['subscribe-ok']); + }); + const earlyOk = early.received[0]; + + expect(earlyOk?.kind).toBe('subscribe-ok'); + + if (earlyOk?.kind === 'subscribe-ok') expect(earlyOk.parameters.largestObject).toBeUndefined(); + + // Once objects have been written, the next SUBSCRIBE_OK carries it + // (length-prefixed, the way moq-lite-rs decodes it). + largest = { group: 35, object: 28 }; + const later = await rawSubscribe(pair.server, 'video', 203); + + await vi.waitFor(() => { + expect(later.received.map((m) => m.kind)).toEqual(['subscribe-ok']); + }); + const laterOk = later.received[0]; + + expect(laterOk?.kind).toBe('subscribe-ok'); + + if (laterOk?.kind === 'subscribe-ok') expect(laterOk.parameters.largestObject).toEqual({ group: 35, object: 28 }); + + session.destroy(); + subscriber.destroy(); + }); + + it('opens and resets a fill fetch stream for an inbound FILL_PARAMETERS', async () => { + const { pair, session, fills, finish } = await makeFillHarness(); + + session.registerTrack({ + trackNamespace: NAMESPACE, + trackName: 'video', + getLargestObject: () => ({ group: 4, object: 2 }), + }); + + await openRawRequest( + pair.server, + encodeSubscribe({ + requestId: 205, + trackNamespace: NAMESPACE, + trackName: 'video', + parameters: { + forward: 1, + locationFilter: { type: 'next-object' }, + fillParameters: { locationFilter: { type: 'relative-group', groupsBeforeNext: 1 } }, + }, + }) + ); + + await vi.waitFor(() => { + expect(fills).toEqual([{ requestId: 205, reset: true }]); + }); + await finish(); + }); + + it('opens no fill fetch stream for an empty fill range (§5.1.3)', async () => { + const { pair, session, fills, finish } = await makeFillHarness(); + let largest: { group: number; object: number } | undefined; + + session.registerTrack({ trackNamespace: NAMESPACE, trackName: 'video', getLargestObject: () => largest }); + const subscribeWithFill = async (requestId: number, fill: Parameters[0]['parameters']) => { + const request = await openRawRequest( + pair.server, + encodeSubscribe({ + requestId, + trackNamespace: NAMESPACE, + trackName: 'video', + parameters: { forward: 1, locationFilter: { type: 'next-object' }, ...fill }, + }) + ); + + await vi.waitFor(() => { + expect(request.received.map((m) => m.kind)).toEqual(['subscribe-ok']); + }); + }; + + // Nothing published yet: there is nothing to fill, whatever the filter. + await subscribeWithFill(207, { + fillParameters: { locationFilter: { type: 'relative-group', groupsBeforeNext: 1 } }, + }); + + // With content, a fill from the Next Object or the Next Group starts + // past Largest Object, and an omitted fill filter inherits the + // subscription's Next Object filter. + largest = { group: 4, object: 2 }; + await subscribeWithFill(209, { fillParameters: { locationFilter: { type: 'next-object' } } }); + await subscribeWithFill(211, { + fillParameters: { locationFilter: { type: 'relative-group', groupsBeforeNext: 0 } }, + }); + await subscribeWithFill(213, { fillParameters: {} }); + + // Control: a fill of the current group is nonempty and is answered — + // and it is the only fill stream the peer ever saw. + await subscribeWithFill(215, { + fillParameters: { locationFilter: { type: 'relative-group', groupsBeforeNext: 1 } }, + }); + await vi.waitFor(() => { + expect(fills).toEqual([{ requestId: 215, reset: true }]); + }); + await finish(); + }); + + it('keys a fill requested by REQUEST_UPDATE to the update Request ID', async () => { + const { pair, session, fills, finish } = await makeFillHarness(); + let largest = { group: 4, object: 2 }; + + session.registerTrack({ + trackNamespace: NAMESPACE, + trackName: 'video', + getLargestObject: () => largest, + }); + const sub = await rawSubscribe(pair.server, 'video', 217); + + await vi.waitFor(() => { + expect(sub.received.map((m) => m.kind)).toEqual(['subscribe-ok']); + }); + + // An empty-range fill is acknowledged like any update but opens no + // stream; a nonempty one opens (and resets) a stream carrying the + // update's own Request ID, not the subscription's. + await sub.send(encodeRequestUpdate(219, { fillParameters: { locationFilter: { type: 'next-object' } } })); + await vi.waitFor(() => { + expect(sub.received.map((m) => m.kind)).toEqual(['subscribe-ok', 'request-ok']); + }); + largest = { group: 8, object: 3 }; + await sub.send( + encodeRequestUpdate(221, { fillParameters: { locationFilter: { type: 'relative-group', groupsBeforeNext: 1 } } }) + ); + await vi.waitFor(() => { + expect(fills).toEqual([{ requestId: 221, reset: true }]); + expect(sub.received.map((m) => m.kind)).toEqual(['subscribe-ok', 'request-ok', 'request-ok']); + }); + expect(sub.received[2]).toMatchObject({ parameters: { largestObject: { group: 8, object: 3 } } }); + await finish(); + }); + + it('preserves the fill header when the peer reads only after the reset', async () => { + const fill = makeBufferedFillStream(); + const { pair, session, finish } = await makeFillHarness({ openFillStream: async () => fill.writable }); + + session.registerTrack({ + trackNamespace: NAMESPACE, + trackName: 'video', + getLargestObject: () => ({ group: 4, object: 2 }), + }); + await openRawRequest( + pair.server, + encodeSubscribe({ + requestId: 223, + trackNamespace: NAMESPACE, + trackName: 'video', + parameters: { fillParameters: {} }, + }) + ); + await vi.waitFor(() => expect(fill.reset()).toBeDefined()); + + const reader = new StreamReader(fill.readable); + + expect(await reader.readVarint()).toBe(STREAM_TYPE.FETCH_HEADER); + expect(await readFetchHeader(reader)).toEqual({ requestId: 223 }); + await expect(reader.atEnd()).rejects.toThrow('fill fetch streams are not served'); + await finish(); + }); + + it.each(['cancel', 'stop-reading', 'replace', 'end', 'destroy'] as const)( + 'aborts backpressured fills when subscriptions %s', + async (action) => { + let writing = false; + const aborted = vi.fn(); + const writable = new WritableStream({ + write(_, controller) { + writing = true; + return new Promise((_, reject) => { + controller.signal.addEventListener('abort', () => reject(controller.signal.reason), { once: true }); + }); + }, + abort: aborted, + }); + const getWriter = writable.getWriter.bind(writable); + + writable.getWriter = () => Object.assign(getWriter(), { commit() {} }); + + const { pair, session, finish } = await makeFillHarness({ openFillStream: async () => writable }); + const track = session.registerTrack({ + trackNamespace: NAMESPACE, + trackName: 'video', + getLargestObject: () => ({ group: 4, object: 2 }), + }); + const sub = await rawSubscribe(pair.server, 'video', 225); + + await vi.waitFor(() => expect(sub.received[0]?.kind).toBe('subscribe-ok')); + await sub.send(encodeRequestUpdate(227, { fillParameters: {} })); + await vi.waitFor(() => expect(writing).toBe(true)); + + if (action === 'cancel') await sub.reset(); + else if (action === 'stop-reading') await sub.abandonReads(); + else if (action === 'replace') await rawSubscribe(pair.server, 'video', 229); + else if (action === 'destroy') session.destroy(); + else track.end(); + + await vi.waitFor(() => expect(aborted).toHaveBeenCalledOnce()); + await finish(); + } + ); + + it('resets a pending fill open that completes after cancellation without writing its header', async () => { + let resolveOpen!: (stream: WritableStream) => void; + const openFillStream = vi.fn( + () => + new Promise>((resolve) => { + resolveOpen = resolve; + }) + ); + const { pair, session, finish } = await makeFillHarness({ openFillStream }); + + session.registerTrack({ + trackNamespace: NAMESPACE, + trackName: 'video', + getLargestObject: () => ({ group: 4, object: 2 }), + }); + const sub = await rawSubscribe(pair.server, 'video', 231); + + await vi.waitFor(() => expect(sub.received[0]?.kind).toBe('subscribe-ok')); + await sub.send(encodeRequestUpdate(233, { fillParameters: {} })); + await vi.waitFor(() => expect(openFillStream).toHaveBeenCalledOnce()); + await sub.reset(); + await vi.waitFor(() => expect(sub.ended()).toBe(true)); + + const write = vi.fn(); + const abort = vi.fn(); + + resolveOpen(new WritableStream({ write, abort })); + await vi.waitFor(() => expect(abort).toHaveBeenCalledOnce()); + expect(write).not.toHaveBeenCalled(); + await finish(); + }); + + it('rejects nonempty fills without reliable reset support while allowing ordinary subscriptions', async () => { + const { pair, session, fills, finish } = await makeFillHarness({ reliableReset: false }); + + session.registerTrack({ + trackNamespace: NAMESPACE, + trackName: 'video', + getLargestObject: () => ({ group: 4, object: 2 }), + }); + const rejected = await openRawRequest( + pair.server, + encodeSubscribe({ + requestId: 235, + trackNamespace: NAMESPACE, + trackName: 'video', + parameters: { fillParameters: {} }, + }) + ); + + await vi.waitFor(() => expect(rejected.ended()).toBe(true)); + expect(rejected.received).toMatchObject([{ kind: 'request-error', errorCode: REQUEST_ERROR_CODE.NOT_SUPPORTED }]); + + const sub = await rawSubscribe(pair.server, 'video', 237); + + await vi.waitFor(() => expect(sub.received[0]?.kind).toBe('subscribe-ok')); + await sub.send(encodeRequestUpdate(239, { fillParameters: { locationFilter: { type: 'next-object' } } })); + await vi.waitFor(() => expect(sub.received[1]?.kind).toBe('request-ok')); + await sub.send(encodeRequestUpdate(241, { fillParameters: {} })); + await vi.waitFor(() => expect(sub.ended()).toBe(true)); + expect(sub.received[2]).toMatchObject({ kind: 'request-error', errorCode: REQUEST_ERROR_CODE.NOT_SUPPORTED }); + expect(fills).toEqual([]); + await finish(); + }); + it('rejects a subscription update it cannot apply instead of acknowledging it', async () => { const endedRequests: number[] = []; const bindings: (number | undefined)[] = []; diff --git a/packages/spf/src/publish/tests/helpers/relay-hub.ts b/packages/spf/src/publish/tests/helpers/relay-hub.ts index 8b209c193a..90dfca3761 100644 --- a/packages/spf/src/publish/tests/helpers/relay-hub.ts +++ b/packages/spf/src/publish/tests/helpers/relay-hub.ts @@ -170,7 +170,12 @@ function resolveStart(filter: LocationFilter | undefined, largest: Location | un return { group: largest?.group ?? 0, object: 0 }; } -export function createRelayHub(): RelayHub { +export function createRelayHub( + options: { + /** Delay individual downstream object streams to exercise jitter and late arrivals. */ + deliveryDelayMs?: (trackName: string, object: Readonly) => number; + } = {} +): RelayHub { let destroyed = false; let nextSubscriberAlias = 1; let publisherConnections = 0; @@ -179,6 +184,7 @@ export function createRelayHub(): RelayHub { const trackEnds: ObservedTrackEnd[] = []; const tracks = new Map(); const closers = new Set<() => void>(); + const deliveries = new Set>(); /** Tracks with standing upstream demand (downstream viewers or test priming). */ const demand = new Set(); /** The live publisher connection's per-track pull, when one is connected. */ @@ -286,8 +292,8 @@ export function createRelayHub(): RelayHub { /** * Pull one announced track: a fresh bidi stream per SUBSCRIBE, alias recorded from the publisher's SUBSCRIBE_OK, - * held open until one side ends it. A bare FIN from the publisher is the draft-19 clean track end — recorded as - * churn, and forwarded to the track's downstream subscribers as PUBLISH_DONE the way a real relay ends the track. + * held open until one side ends it. A bare FIN from the publisher is the clean track end — recorded as churn, and + * forwarded to the track's downstream subscribers as PUBLISH_DONE the way a real relay ends the track. */ const subscribeUpstream = (trackName: string): void => { if (destroyed || connectionClosed || upstreamTracks.has(trackName)) return; @@ -564,7 +570,21 @@ export function createRelayHub(): RelayHub { subscription = { trackAlias, start: resolveStart(message.parameters.locationFilter, track.largest), - deliver: (object) => forwardObject(trackAlias, object), + deliver: (object) => { + const delay = options.deliveryDelayMs?.(track.name, object) ?? 0; + + if (delay <= 0) { + forwardObject(trackAlias, object); + return; + } + + const timer = setTimeout(() => { + deliveries.delete(timer); + forwardObject(trackAlias, object); + }, delay); + + deliveries.add(timer); + }, end: (statusCode) => { void writer .write(encodePublishDone(statusCode, 0, '')) @@ -662,6 +682,10 @@ export function createRelayHub(): RelayHub { destroy() { destroyed = true; + for (const timer of deliveries) clearTimeout(timer); + + deliveries.clear(); + for (const close of [...closers]) close(); closers.clear();