Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
16 changes: 15 additions & 1 deletion packages/spf/src/media/moq/build-catalog.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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. */
Expand Down Expand Up @@ -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. */
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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,
})
Expand Down
19 changes: 16 additions & 3 deletions packages/spf/src/media/moq/tests/build-catalog.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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([
{
Expand All @@ -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);
});
});
54 changes: 54 additions & 0 deletions packages/spf/src/publish/actors/tests/track-publisher.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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<void> | undefined = new Promise<void>((resolve) => (releaseWrites = resolve));
let releaseClose: (() => void) | undefined;
let closed = false;
let aborted = false;
const openUniStream = async () =>
new WritableStream<Uint8Array>({
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<void>((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 });
Expand Down
26 changes: 24 additions & 2 deletions packages/spf/src/publish/actors/track-publisher.ts
Original file line number Diff line number Diff line change
Expand Up @@ -97,7 +97,21 @@ export type TrackPublisherMessage =
}
| { type: 'end' };

export type TrackPublisherActor = MessageActor<TrackPublisherState, TrackPublisherCounters, TrackPublisherMessage>;
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<void>;
}

export interface TrackPublisherOptions {
openUniStream: OpenUniStream;
Expand Down Expand Up @@ -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<TrackPublisherMessage, { type: 'frame' }>[] = [];
/** Detached FIN settlements (see `finishCell`) — `flushed()` waits on them past the runner. */
const pendingFins = new Set<Promise<void>>();

// Assigned right after createMachineActor returns; the runner tasks only
// complete asynchronously, well after construction.
Expand Down Expand Up @@ -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));
};

/**
Expand Down Expand Up @@ -568,6 +586,10 @@ export function createTrackPublisherActor(options: TrackPublisherOptions): Track
send(message: TrackPublisherMessage): void {
actor.send(message);
},
async flushed(): Promise<void> {
await runner.settled;
Comment thread
mmcc marked this conversation as resolved.
Resolved
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
Expand Down
69 changes: 63 additions & 6 deletions packages/spf/src/publish/behaviors/setup-track-publishers.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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';

/**
Expand Down Expand Up @@ -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';
Expand All @@ -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<typeof setTimeout> | undefined;
const flushed = Promise.race([
publisher.flushed(),
new Promise<void>((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
Expand Down Expand Up @@ -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);
Expand All @@ -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);
Comment thread
mmcc marked this conversation as resolved.
Resolved
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
Expand Down
Original file line number Diff line number Diff line change
@@ -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';
Expand Down Expand Up @@ -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' }] });
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -83,7 +83,7 @@ function makePublisher(counters: Partial<TrackPublisherCounters>): TrackPublishe
context: { ...ZERO_PUBLISHER_COUNTERS, ...counters },
});

return { snapshot, send: () => {}, destroy: () => {} };
return { snapshot, send: () => {}, flushed: async () => {}, destroy: () => {} };
}

function makeSessionActor(subscriberCount: number): PublishSessionActor {
Expand Down
Loading
Loading