From 9c042462f9241db79ed73693c9696e4f9947fa29 Mon Sep 17 00:00:00 2001 From: Matt McClure Date: Wed, 7 Oct 2026 16:39:29 +0000 Subject: [PATCH 1/3] fix(spf): leave isComplete out of live MSF catalogs MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit draft-ietf-moq-msf-01 §5.1.3 makes isComplete an irrevocable commitment that the broadcast is over. buildMsfCatalog stamped it on every catalog, so spec-following players and caches could treat a live broadcast as finished from its first catalog. Refs #60 --- packages/spf/src/media/moq/build-catalog.ts | 4 +++- packages/spf/src/media/moq/tests/build-catalog.test.ts | 5 +++-- 2 files changed, 6 insertions(+), 3 deletions(-) diff --git a/packages/spf/src/media/moq/build-catalog.ts b/packages/spf/src/media/moq/build-catalog.ts index 516c4fcd01..dfd0e1b701 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). */ /** Version emitted — the newest version `parse-catalog.ts` accepts. */ @@ -200,7 +203,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..ae3b081f58 100644 --- a/packages/spf/src/media/moq/tests/build-catalog.test.ts +++ b/packages/spf/src/media/moq/tests/build-catalog.test.ts @@ -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([ { From bdd65558f83eb954f387981a2f950a099297c171 Mon Sep 17 00:00:00 2001 From: Matt McClure Date: Wed, 7 Oct 2026 16:40:08 +0000 Subject: [PATCH 2/3] feat(spf): publish the MSF end-of-broadcast catalog on an intentional stop MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit When a publish session is still serving at teardown (unpublish, endpoint change, engine destroy), end the catalog track with the §11.3 catalog — isComplete with an empty tracks array — after every media track ends. A failed, closed, or GOAWAY-draining session never sends it. To get that last group on the wire during teardown, track publishers gain flushed(), a registered track's end() can hold its subscription FINs until a last object lands, and the session accepts stream opens inside its bounded close drain. Fixes #60 --- packages/spf/src/media/moq/build-catalog.ts | 14 +++- .../src/media/moq/tests/build-catalog.test.ts | 14 +++- .../actors/tests/track-publisher.test.ts | 32 +++++++++ .../spf/src/publish/actors/track-publisher.ts | 22 +++++- .../behaviors/setup-track-publishers.ts | 69 +++++++++++++++++-- .../tests/setup-track-publishers.test.ts | 58 ++++++++++++++++ .../tests/track-publish-stats.test.ts | 2 +- .../src/publish/session/publish-session.ts | 33 +++++++-- .../session/tests/publish-session.test.ts | 31 +++++++++ 9 files changed, 258 insertions(+), 17 deletions(-) diff --git a/packages/spf/src/media/moq/build-catalog.ts b/packages/spf/src/media/moq/build-catalog.ts index dfd0e1b701..eaa0539a2f 100644 --- a/packages/spf/src/media/moq/build-catalog.ts +++ b/packages/spf/src/media/moq/build-catalog.ts @@ -21,7 +21,7 @@ * 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). + * 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. */ @@ -81,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. */ @@ -127,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 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 ae3b081f58..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 @@ -200,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..c6c026d506 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,38 @@ describe('createTrackPublisherActor', () => { publisher.destroy(); }); + it('flushed() settles once the last group is written and FINed, so a destroy after it loses nothing', async () => { + const factory = makeStreamFactory(); + const publisher = createTrackPublisherActor({ openUniStream: factory.openUniStream, groupPerFrame: true }); + const frame = { + type: 'frame', + payload: new Uint8Array([7]), + properties: [], + keyframe: true, + timestampUs: 0, + } as const; + + publisher.send({ type: 'bind', trackAlias: 3 }); + factory.gate = true; + publisher.send(frame); + publisher.send({ type: 'end' }); + + let flushed = false; + const settled = publisher.flushed().then(() => (flushed = true)); + + await new Promise((resolve) => setTimeout(resolve, 10)); + expect(flushed).toBe(false); + + factory.gate = false; + factory.releaseAll(); + await settled; + publisher.destroy(); + + expect(factory.streams).toHaveLength(1); + expect(factory.streams[0]).toMatchObject({ closed: true, aborted: false }); + expect((await parseSubgroup(factory.streams[0]!)).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..ab389819cd 100644 --- a/packages/spf/src/publish/actors/track-publisher.ts +++ b/packages/spf/src/publish/actors/track-publisher.ts @@ -97,7 +97,17 @@ export type TrackPublisherMessage = } | { type: 'end' }; -export type TrackPublisherActor = MessageActor; +export interface TrackPublisherActor extends MessageActor< + TrackPublisherState, + TrackPublisherCounters, + TrackPublisherMessage +> { + /** + * Settles once every group sent 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. + */ + flushed(): Promise; +} export interface TrackPublisherOptions { openUniStream: OpenUniStream; @@ -175,6 +185,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 +223,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 +582,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[] = []; From 8864486799ccc1024fc440c3fc8099f88e468ad2 Mon Sep 17 00:00:00 2001 From: Matt McClure Date: Wed, 7 Oct 2026 17:08:02 +0000 Subject: [PATCH 3/3] test(spf): hold the FIN open when testing track publisher flushed() The previous test let the stream close settle as soon as the write was released, so it still passed if flushed() stopped awaiting the detached FINs. Also document that flushed() observes and closes nothing: a keyframe-grouped track's open group needs an end first. --- .../actors/tests/track-publisher.test.ts | 62 +++++++++++++------ .../spf/src/publish/actors/track-publisher.ts | 8 ++- 2 files changed, 48 insertions(+), 22 deletions(-) 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 c6c026d506..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,36 +284,58 @@ describe('createTrackPublisherActor', () => { publisher.destroy(); }); - it('flushed() settles once the last group is written and FINed, so a destroy after it loses nothing', async () => { - const factory = makeStreamFactory(); - const publisher = createTrackPublisherActor({ openUniStream: factory.openUniStream, groupPerFrame: true }); - const frame = { - type: 'frame', - payload: new Uint8Array([7]), - properties: [], - keyframe: true, - timestampUs: 0, - } as const; + 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 }); - factory.gate = true; - publisher.send(frame); + publisher.send({ type: 'frame', payload: new Uint8Array([7]), properties: [], keyframe: true, timestampUs: 0 }); publisher.send({ type: 'end' }); + void publisher.flushed().then(() => (flushed = true)); - let flushed = false; - const settled = 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); - factory.gate = false; - factory.releaseAll(); - await settled; + releaseClose!(); + await vi.waitFor(() => expect(flushed).toBe(true)); publisher.destroy(); - expect(factory.streams).toHaveLength(1); - expect(factory.streams[0]).toMatchObject({ closed: true, aborted: false }); - expect((await parseSubgroup(factory.streams[0]!)).objects.map((object) => [...object.payload])).toEqual([[7]]); + 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 () => { diff --git a/packages/spf/src/publish/actors/track-publisher.ts b/packages/spf/src/publish/actors/track-publisher.ts index ab389819cd..b9397d7c47 100644 --- a/packages/spf/src/publish/actors/track-publisher.ts +++ b/packages/spf/src/publish/actors/track-publisher.ts @@ -103,8 +103,12 @@ export interface TrackPublisherActor extends MessageActor< TrackPublisherMessage > { /** - * Settles once every group sent 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. + * 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; }