diff --git a/packages/spf/src/media/moq/build-catalog.ts b/packages/spf/src/media/moq/build-catalog.ts index 516c4fcd01..eaa0539a2f 100644 --- a/packages/spf/src/media/moq/build-catalog.ts +++ b/packages/spf/src/media/moq/build-catalog.ts @@ -19,6 +19,9 @@ * the catalog is the one channel every consumer can read: LOC's per-keyframe Config property (`loc-packaging.ts`) is an * odd-id MOQ object property that relays and non-SPF consumers drop without surfacing, so it is carried as a refresh * bonus, never the only copy. + * + * Live catalogs never carry `isComplete`: §5.1.3 makes it an irrevocable commitment that no track will change or carry + * content again (issue #60). Only the `complete` input emits it, as the §11.3 end-of-broadcast catalog. */ /** Version emitted — the newest version `parse-catalog.ts` accepts. */ @@ -78,6 +81,12 @@ export interface MsfCatalogInput { data?: readonly MsfCatalogDataTrackInput[]; /** Catalog generation time (§5.2.24), epoch milliseconds. */ generatedAt?: number; + /** + * The broadcast has ended for good (§11.3): emit `isComplete` with an empty `tracks` array, ignoring every track + * input. Only for the broadcast's last catalog — §5.1.3 makes the flag irrevocable, so a live catalog never carries + * it. + */ + complete?: boolean; } /** The `buildCatalog` config seam's shape. */ @@ -124,6 +133,12 @@ function registerInitData(entries: MsfInitDataEntry[], name: string, initData: U * drafts settle on. */ export function buildMsfCatalog(input: MsfCatalogInput): string { + if (input.complete) { + return JSON.stringify( + pruneUndefined({ version: MSF_CATALOG_VERSION, generatedAt: input.generatedAt, isComplete: true, tracks: [] }) + ); + } + const namespace = input.namespace.join('/'); const shared = { namespace, packaging: 'loc', isLive: true }; // Only grouped once a screen track exists — a camera-only catalog stays @@ -200,7 +215,6 @@ export function buildMsfCatalog(input: MsfCatalogInput): string { pruneUndefined({ version: MSF_CATALOG_VERSION, generatedAt: input.generatedAt, - isComplete: true, tracks, initDataList: initDataList.length > 0 ? initDataList : undefined, }) diff --git a/packages/spf/src/media/moq/tests/build-catalog.test.ts b/packages/spf/src/media/moq/tests/build-catalog.test.ts index 70bd920307..bb8fdf2b28 100644 --- a/packages/spf/src/media/moq/tests/build-catalog.test.ts +++ b/packages/spf/src/media/moq/tests/build-catalog.test.ts @@ -4,7 +4,7 @@ import { isResolvedPresentation } from '../../types'; import { getTracksByType } from '../../utils/tracks'; import { buildMsfCatalog, MSF_CATALOG_VERSION } from '../build-catalog'; import { toAudioDecoderConfig, toVideoDecoderConfig } from '../codec-mapping'; -import { type MoqAudioTrack, type MoqVideoTrack, parseMoqCatalog } from '../parse-catalog'; +import { applyMoqCatalogUpdate, type MoqAudioTrack, type MoqVideoTrack, parseMoqCatalog } from '../parse-catalog'; const NAMESPACE = ['live', 'abc123']; // The subscriber-side view of the same publication: catalog track under @@ -180,13 +180,14 @@ describe('buildMsfCatalog', () => { expect(new Uint8Array(toAudioDecoderConfig(audio[0]!)!.description as ArrayBuffer)).toEqual(audioSpecificConfig); }); - it('emits the supported version, completeness, and no absent fields', () => { + it('emits the supported version and no absent fields', () => { const raw = JSON.parse( buildMsfCatalog({ namespace: NAMESPACE, audio: { name: 'audio', codec: 'opus' }, generatedAt: 1746104606044 }) ); expect(raw.version).toBe(MSF_CATALOG_VERSION); - expect(raw.isComplete).toBe(true); + // A live catalog must not claim the broadcast is over (§5.1.3). + expect(raw).not.toHaveProperty('isComplete'); expect(raw.generatedAt).toBe(1746104606044); expect(raw.tracks).toEqual([ { @@ -199,4 +200,16 @@ describe('buildMsfCatalog', () => { }, ]); }); + + it('emits the §11.3 end-of-broadcast catalog for complete, ignoring track inputs', () => { + const text = buildMsfCatalog({ ...AV_INPUT, generatedAt: 1746104606044, complete: true }); + + expect(JSON.parse(text)).toEqual({ + version: MSF_CATALOG_VERSION, + generatedAt: 1746104606044, + isComplete: true, + tracks: [], + }); + expect(applyMoqCatalogUpdate(undefined, text, { catalogNamespace: NAMESPACE }).isComplete).toBe(true); + }); }); 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 ffe36771c9..c0228255f4 100644 --- a/packages/spf/src/publish/actors/tests/track-publisher.test.ts +++ b/packages/spf/src/publish/actors/tests/track-publisher.test.ts @@ -284,6 +284,60 @@ describe('createTrackPublisherActor', () => { publisher.destroy(); }); + it('flushed() settles only once the last group is written and its FIN has landed', async () => { + const chunks: Uint8Array[] = []; + let releaseWrites!: () => void; + let writeGate: Promise | undefined = new Promise((resolve) => (releaseWrites = resolve)); + let releaseClose: (() => void) | undefined; + let closed = false; + let aborted = false; + const openUniStream = async () => + new WritableStream({ + write: (chunk) => { + chunks.push(chunk); + return writeGate; + }, + // The FIN settles detached from the runner (`finishCell`), so a + // flushed() that only awaited the runner would resolve here. + close: () => + new Promise((resolve) => { + releaseClose = () => { + closed = true; + resolve(); + }; + }), + abort: () => { + aborted = true; + }, + }); + const publisher = createTrackPublisherActor({ openUniStream, groupPerFrame: true }); + let flushed = false; + + publisher.send({ type: 'bind', trackAlias: 3 }); + publisher.send({ type: 'frame', payload: new Uint8Array([7]), properties: [], keyframe: true, timestampUs: 0 }); + publisher.send({ type: 'end' }); + void publisher.flushed().then(() => (flushed = true)); + + await vi.waitFor(() => expect(chunks.length).toBeGreaterThan(0)); + await new Promise((resolve) => setTimeout(resolve, 10)); + expect(flushed).toBe(false); + + releaseWrites(); + writeGate = undefined; + await vi.waitFor(() => expect(releaseClose).toBeDefined()); + await new Promise((resolve) => setTimeout(resolve, 10)); + expect(flushed).toBe(false); + + releaseClose!(); + await vi.waitFor(() => expect(flushed).toBe(true)); + publisher.destroy(); + + expect({ closed, aborted }).toEqual({ closed: true, aborted: false }); + expect((await parseSubgroup({ chunks, closed, aborted })).objects.map((object) => [...object.payload])).toEqual([ + [7], + ]); + }); + it('ignores delta frames before the first keyframe', async () => { const factory = makeStreamFactory(); const publisher = createTrackPublisherActor({ openUniStream: factory.openUniStream }); diff --git a/packages/spf/src/publish/actors/track-publisher.ts b/packages/spf/src/publish/actors/track-publisher.ts index 680f37e3c8..b9397d7c47 100644 --- a/packages/spf/src/publish/actors/track-publisher.ts +++ b/packages/spf/src/publish/actors/track-publisher.ts @@ -97,7 +97,21 @@ export type TrackPublisherMessage = } | { type: 'end' }; -export type TrackPublisherActor = MessageActor; +export interface TrackPublisherActor extends MessageActor< + TrackPublisherState, + TrackPublisherCounters, + TrackPublisherMessage +> { + /** + * Settles once every group closed so far has been written and its FIN has landed (or the group failed) — never + * rejects. Lets a teardown put a last frame on the wire before `destroy()` resets whatever is still queued. + * + * Observes; it closes nothing. A keyframe-grouped track's in-progress group stays open until the next keyframe or + * `{type:'end'}`, so send `end` first when that group must be covered too. (`groupPerFrame` tracks close every group + * as it is written.) + */ + flushed(): Promise; +} export interface TrackPublisherOptions { openUniStream: OpenUniStream; @@ -175,6 +189,8 @@ export function createTrackPublisherActor(options: TrackPublisherOptions): Track * peer. Reset on each keyframe; group-per-frame tracks use `replayLastGroupOnBind` instead. */ let currentGroupFrames: Extract[] = []; + /** Detached FIN settlements (see `finishCell`) — `flushed()` waits on them past the runner. */ + const pendingFins = new Set>(); // Assigned right after createMachineActor returns; the runner tasks only // complete asynchronously, well after construction. @@ -211,8 +227,10 @@ export function createTrackPublisherActor(options: TrackPublisherOptions): Track const finishCell = (cell: GroupCell): void => { removeCell(cell); const fin = cell.writer?.fin() ?? Promise.resolve(); + const settled = fin.then(() => inner?.send({ type: 'group-finished' }), failCell(cell)); - fin.then(() => inner?.send({ type: 'group-finished' }), failCell(cell)); + pendingFins.add(settled); + void settled.finally(() => pendingFins.delete(settled)); }; /** @@ -568,6 +586,10 @@ export function createTrackPublisherActor(options: TrackPublisherOptions): Track send(message: TrackPublisherMessage): void { actor.send(message); }, + async flushed(): Promise { + await runner.settled; + await Promise.all(pendingFins); + }, destroy(): void { // Every opened stream must end deterministically: the open group // (or the one `{type:'end'}` just closed gracefully) gets a diff --git a/packages/spf/src/publish/behaviors/setup-track-publishers.ts b/packages/spf/src/publish/behaviors/setup-track-publishers.ts index 6604c33514..ae966a87b3 100644 --- a/packages/spf/src/publish/behaviors/setup-track-publishers.ts +++ b/packages/spf/src/publish/behaviors/setup-track-publishers.ts @@ -21,7 +21,9 @@ * Cluster-owner reactor per the per-type setup-actor convention: the encoder chunk router (the engine's default * `chunkSink`) and `deriveCatalog` only read the slots — they never create the actors. On session loss, endpoint * change, or teardown the actors are destroyed in reverse creation order, each track's live subscriptions get their - * clean FIN (`handle.end()`), and the slots are cleared. + * clean FIN (`handle.end()`), and the slots are cleared. When the session is still serving at teardown, the broadcast + * is ending on purpose, so the catalog track's last group is the MSF end-of-broadcast catalog (§11.3) — never on a + * session loss, which may yet reconnect and must not mark the broadcast complete. * * Sole writer of the track-publisher context slots (the four media slots plus `dataTrackProducers`). Per-stream * failures are deliberately not surfaced as `publishError` anymore: under pull-through ingest the peer resets in-flight @@ -32,15 +34,18 @@ import { defineBehavior } from '../../core/composition/create-composition'; import type { Reactor } from '../../core/reactors/create-machine-reactor'; import { createMachineReactor } from '../../core/reactors/create-machine-reactor'; import { peek, type ReadonlySignal, type Signal, signal } from '../../core/signals/primitives'; +import type { BuildMsfCatalog } from '../../media/moq/build-catalog'; +import { buildMsfCatalog } from '../../media/moq/build-catalog'; import { LOC_PROPERTY, MICROSECONDS_PER_SECOND } from '../../media/moq/loc'; import { isMediaCatalogRole } from '../../media/moq/parse-catalog'; import type { TrackPublisherActor } from '../actors/track-publisher'; import { createTrackPublisherActor } from '../actors/track-publisher'; -import type { - MoqtPublishSession, - PublishEndpoint, - PublishSessionActor, - RegisteredTrack, +import { + CLOSE_FLUSH_TIMEOUT_MS, + type MoqtPublishSession, + type PublishEndpoint, + type PublishSessionActor, + type RegisteredTrack, } from '../session/publish-session'; /** @@ -221,6 +226,11 @@ export interface SetupTrackPublishersConfig { * nothing — a data-only broadcast is out of scope. */ dataTracks?: PublishDataTrackConfig[]; + /** + * Catalog-JSON builder seam for the end-of-broadcast catalog; default `buildMsfCatalog` (shared with + * `deriveCatalog`). + */ + buildCatalog?: BuildMsfCatalog; } type SetupTrackPublishersFsmState = 'preconditions-unmet' | 'publishers-ready'; @@ -229,6 +239,40 @@ function hasEncoding(encodings: ActiveEncodingsFacts | undefined): boolean { return Boolean(encodings && (encodings.camera || encodings.screen || encodings.audio)); } +const textEncoder = new TextEncoder(); + +/** + * End the catalog track with the MSF end-of-broadcast catalog (§11.3: `isComplete`, no tracks) as its last group. The + * subscription FINs wait for that group to land — bounded by the session's close drain window, so a stalled stream + * cannot hold the teardown — and only then is the publisher destroyed. + */ +function endCatalogTrack( + handle: RegisteredTrack, + publisher: TrackPublisherActor, + namespace: readonly string[], + buildCatalog: BuildMsfCatalog +): void { + publisher.send({ + type: 'frame', + payload: textEncoder.encode(buildCatalog({ namespace, complete: true })), + properties: [], + keyframe: true, + timestampUs: 0, + }); + publisher.send({ type: 'end' }); + + let timer: ReturnType | undefined; + const flushed = Promise.race([ + publisher.flushed(), + new Promise((resolve) => { + timer = setTimeout(resolve, CLOSE_FLUSH_TIMEOUT_MS); + }), + ]).finally(() => clearTimeout(timer)); + + handle.end({ after: flushed }); + void flushed.then(() => publisher.destroy()); +} + /** * One session's publisher cluster — the shared plumbing between the owner effect (creates and tears it down with the * session), the encoding-sync effect (adds media publishers as kinds appear), and the binding-sync effect (mirrors @@ -406,6 +450,13 @@ function setupTrackPublishersSetup({ // the peer even when this cleanup runs as part of session // teardown (see the composition-order note in the moq engine). return () => { + // Still serving at teardown means the broadcast is ending on + // purpose (unpublish, endpoint change, engine destroy); a + // failed, closed, or GOAWAY-draining session is not an end + // of broadcast, and its transport may not take the write. + const status = peek(actor.snapshot).context.status; + const endOfBroadcast = status === 'ready' || status === 'live'; + cluster.set(undefined); context.dataTrackProducers.set(undefined); context.audioTrackPublisher.set(undefined); @@ -414,6 +465,12 @@ function setupTrackPublishersSetup({ context.catalogTrackPublisher.set(undefined); for (const { handle, publisher } of [...next.created].reverse()) { + // Last, after every media track has ended — the §11.3 order. + if (endOfBroadcast && handle.trackName === CATALOG_TRACK_NAME) { + endCatalogTrack(handle, publisher, next.namespace, config.buildCatalog ?? buildMsfCatalog); + continue; + } + // Quiesce: 'end' FINs the open group, then the track's // live subscriptions get their clean stream FIN (the // clean track end — no trailing message; a relay 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 66ae1f6b03..5849cdf903 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 @@ -1,6 +1,7 @@ import { afterEach, describe, expect, it, vi } from 'vite-plus/test'; import { signal } from '../../../core/signals/primitives'; +import { MSF_CATALOG_VERSION } from '../../../media/moq/build-catalog'; import { parseLocProperties } from '../../../media/moq/loc'; import { REQUEST_ERROR_CODE } from '../../../network/moqt/control-messages'; import type { MoqtObject } from '../../../network/moqt/object-stream'; @@ -292,6 +293,63 @@ describe('setupTrackPublishers', () => { expect(publisher.snapshot.get().value).toBe('destroyed'); }); + it('ends a broadcast stopped on purpose with the §11.3 end-of-broadcast catalog before the catalog FIN', async () => { + const { actor, peer, server } = makeSessionActor(); + const { state, context } = setupBehavior(); + const catalogs: unknown[] = []; + const finishedGroups: number[] = []; + const onSubgroupReset = vi.fn(); + + state.endpoint.set(ENDPOINT); + state.activeEncodings.set({ audio: AUDIO_CONFIG }); + context.publishSessionActor.set(actor); + void solicitNamespace(server, []); + await vi.waitFor(() => expect(context.catalogTrackPublisher.get()).toBeDefined()); + peer.subscribe( + { trackNamespace: ENDPOINT.namespace, trackName: 'catalog' }, + { + onObject: (object) => catalogs.push(JSON.parse(new TextDecoder().decode(object.payload))), + onSubgroupEnd: ({ groupId }) => finishedGroups.push(groupId), + onSubgroupReset, + } + ); + await vi.waitFor(() => expect(actor.snapshot.get().context.trackBindings.catalog).toBeDefined()); + context.catalogTrackPublisher.get()!.send({ + type: 'frame', + payload: new TextEncoder().encode(JSON.stringify({ version: MSF_CATALOG_VERSION, tracks: [] })), + properties: [], + keyframe: true, + timestampUs: 0, + }); + await vi.waitFor(() => expect(catalogs).toHaveLength(1)); + + // `openPublishSession`'s unpublish order: the slot clears, then the + // session starts its orderly close — before this cleanup runs. + context.publishSessionActor.set(undefined); + actor.destroy(); + + await vi.waitFor(() => expect(finishedGroups).toHaveLength(2)); + expect(catalogs.at(-1)).toEqual({ version: MSF_CATALOG_VERSION, isComplete: true, tracks: [] }); + expect(onSubgroupReset).not.toHaveBeenCalled(); + }); + + it('never marks the broadcast complete when the session is lost', async () => { + const { actor, server, client } = makeSessionActor(); + const { state, context } = setupBehavior(); + + state.endpoint.set(ENDPOINT); + state.activeEncodings.set({ audio: AUDIO_CONFIG }); + context.publishSessionActor.set(actor); + void solicitNamespace(server, []); + await vi.waitFor(() => expect(actor.snapshot.get().context.status).toBe('live')); + const catalog = context.catalogTrackPublisher.get()!; + const send = vi.spyOn(catalog, 'send'); + + client.close(); + await vi.waitFor(() => expect(context.catalogTrackPublisher.get()).toBeUndefined()); + expect(send.mock.calls.map(([message]) => message.type)).toEqual(['end']); + }); + it('registers configured data tracks with the cluster and serves a producer-published payload', async () => { const { actor, peer, server } = makeSessionActor(); const { state, context } = setupBehavior({ dataTracks: [{ name: 'overlay', role: 'data' }] }); 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 af22fdafab..99dc918b7e 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 @@ -83,7 +83,7 @@ function makePublisher(counters: Partial): TrackPublishe context: { ...ZERO_PUBLISHER_COUNTERS, ...counters }, }); - return { snapshot, send: () => {}, destroy: () => {} }; + return { snapshot, send: () => {}, flushed: async () => {}, destroy: () => {} }; } function makeSessionActor(subscriberCount: number): PublishSessionActor { diff --git a/packages/spf/src/publish/session/publish-session.ts b/packages/spf/src/publish/session/publish-session.ts index 2b01d13b21..769e2bfd49 100644 --- a/packages/spf/src/publish/session/publish-session.ts +++ b/packages/spf/src/publish/session/publish-session.ts @@ -125,8 +125,12 @@ export interface RegisteredTrack { /** * End the track: FIN every live subscription's request stream (a FIN with no trailing bytes is the clean track end) * and refuse future SUBSCRIBEs with DOES_NOT_EXIST. Idempotent. + * + * `after` holds the FINs (not the refusal) until it settles, so a last object still in flight — the MSF + * end-of-broadcast catalog — reaches subscribers before their subscription ends. An orderly `close()` waits on it + * within its bounded drain window. */ - end(): void; + end(options?: { after?: Promise }): void; } export interface MoqtPublishSession { @@ -511,7 +515,7 @@ class MoqtPublishSessionImpl implements MoqtPublishSession { return { trackName: options.trackName, - end: () => this.#endTrack(track), + end: (options) => this.#endTrack(track, options?.after), }; } @@ -520,10 +524,23 @@ class MoqtPublishSessionImpl implements MoqtPublishSession { * future SUBSCRIBEs. The aggregated write completion lands on `track.doneFlushed` so `close()` can hold the transport * open until the FINs reach the wire. */ - #endTrack(track: TrackRecord): void { + #endTrack(track: TrackRecord, after?: Promise): void { if (track.done) return; track.done = true; + + if (after) { + track.doneFlushed = after.then( + () => this.#finTrack(track), + () => this.#finTrack(track) + ); + return; + } + + track.doneFlushed = this.#finTrack(track); + } + + #finTrack(track: TrackRecord): Promise { const writes: Promise[] = [...track.pendingFins]; let hadReported = false; @@ -551,7 +568,7 @@ class MoqtPublishSessionImpl implements MoqtPublishSession { this.#callbacks.onTrackBinding?.({ trackName: track.trackName, trackAlias: undefined }); } - track.doneFlushed = Promise.all(writes).then(() => {}); + return Promise.all(writes).then(() => {}); } openUniStream(options?: { sendOrder?: number }): Promise> { @@ -560,8 +577,12 @@ class MoqtPublishSessionImpl implements MoqtPublishSession { // the session, and hammering createUnidirectionalStream() on a // torn-down WebTransport segfaults Chromium's renderer (null deref in // the native session teardown race) — observed against a relay that - // resets every stream on protocol disagreement. - if (this.#destroyed || this.#closing) { + // resets every stream on protocol disagreement. An orderly close's + // drain window still accepts opens: the transport is alive until the + // drain closes it (which also marks the session destroyed), and a + // track ending with a last object (`end({ after })`) needs a stream + // for it. + if (this.#destroyed) { return Promise.reject(new Error('moq publish session: closed')); } 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 51f5163ab3..de352ea07f 100644 --- a/packages/spf/src/publish/session/tests/publish-session.test.ts +++ b/packages/spf/src/publish/session/tests/publish-session.test.ts @@ -573,6 +573,37 @@ describe('createMoqtPublishSession', () => { subscriber.destroy(); }); + it('holds the FINs of end({ after }) until it settles, still opening streams inside the close drain', async () => { + const { pair, session, subscriber } = makePublishHarness(); + + await session.ready; + const track = session.registerTrack({ trackNamespace: NAMESPACE, trackName: 'catalog' }); + const subscribe = await rawSubscribe(pair.server, 'catalog', 31); + + await vi.waitFor(() => { + expect(subscribe.received).toHaveLength(1); + }); + + let release!: () => void; + + track.end({ after: new Promise((resolve) => (release = resolve)) }); + session.close(); + // The track's last object needs a stream after close() began: the + // drain window keeps the transport — and opens — available. + const lastObjectStream = await session.openUniStream(); + + void lastObjectStream.abort(); + await new Promise((resolve) => setTimeout(resolve, 30)); + expect(subscribe.ended()).toBe(false); + + release(); + await vi.waitFor(() => { + expect(subscribe.ended()).toBe(true); + }); + expect(subscribe.received.map((m) => m.kind)).toEqual(['subscribe-ok']); + subscriber.destroy(); + }); + it('hands the binding to the newest subscription and FINs the replaced stream', async () => { const bindings: (number | undefined)[] = []; const endedRequests: number[] = [];