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
83 changes: 61 additions & 22 deletions apps/sandbox/templates/moq-publisher/loopback-relay.ts
Original file line number Diff line number Diff line change
Expand Up @@ -37,12 +37,16 @@ const MESSAGE_TYPE = {
REQUEST_ERROR: 0x5,
REQUEST_OK: 0x7,
NAMESPACE: 0x8,
PUBLISH_DONE: 0xb,
NAMESPACE_DONE: 0xe,
FETCH: 0x16,
PUBLISH: 0x1d,
SUBSCRIBE_NAMESPACE: 0x50,
} as const;

/** PUBLISH_DONE status codes (§10.12) this relay sends its players. */
const PUBLISH_DONE_INTERNAL_ERROR = 0x0;

/** REQUEST_ERROR code for "nothing published in that range" (§10.6.1). */
const ERROR_INVALID_RANGE = 0x11;

Expand Down Expand Up @@ -334,6 +338,11 @@ function encodeSubscribeOk(trackAlias: number): Uint8Array {
return frame(MESSAGE_TYPE.SUBSCRIBE_OK, new Writer().varint(trackAlias).varint(0).toBytes());
}

function encodePublishDone(statusCode: number, streamCount: number): Uint8Array {
// Status Code + Stream Count + an empty Reason Phrase.
return frame(MESSAGE_TYPE.PUBLISH_DONE, new Writer().varint(statusCode).varint(streamCount).varint(0).toBytes());
}

/**
* SUBSCRIBE_NAMESPACE toward the publisher (§10.18): the empty prefix solicits every namespace the publisher will
* announce — the same solicitation moq-relay 0.14.7 opens right after SETUP.
Expand Down Expand Up @@ -414,10 +423,11 @@ interface PlayerSubscription {
trackAlias: number;
deliver(object: BufferedObject): void;
/**
* End this subscription from the relay side: FIN toward the player and cancel its request stream, so its teardown
* removes the entry. Used when the upstream track is aborted for every viewer.
* End this subscription from the relay side: with a `statusCode`, PUBLISH_DONE (§10.12, counting the streams this
* subscription was sent) and then FIN; without one, a bare FIN. Then cancel its request stream, so its teardown
* removes the entry.
*/
end(): void;
end(statusCode?: number): void;
}

interface TrackBuffer {
Expand Down Expand Up @@ -662,8 +672,8 @@ export function createPublisherLoopbackRelay({ onLog }: PublisherLoopbackRelayOp

/**
* One live upstream subscription per track: SUBSCRIBE, bind the SUBSCRIBE_OK's alias for the data-stream router,
* then hold the stream open. It ends by FIN alone (no PUBLISH_DONE exists in this flow) — the publisher's, ending
* the track for good, or our own via `handle.release()`, withdrawing a track no player watches.
* then hold the stream open. It ends with the publisher's PUBLISH_DONE and FIN, ending the track for good, or with
* our own FIN via `handle.release()`, withdrawing a track no player watches.
*/
const runUpstreamSubscription = async (
track: TrackBuffer,
Expand Down Expand Up @@ -692,7 +702,7 @@ export function createPublisherLoopbackRelay({ onLog }: PublisherLoopbackRelayOp
const reason = fields.string();

if (errorCode === ERROR_DOES_NOT_EXIST && track.ended) {
// Done, not late: the publisher FINed this track and has
// Done, not late: the publisher ended this track and has
// not re-registered it, so DOES_NOT_EXIST is terminal —
// mirror the real relay, which aborts the request rather
// than retrying, by ending the late subscribers. Each
Expand Down Expand Up @@ -767,20 +777,35 @@ export function createPublisherLoopbackRelay({ onLog }: PublisherLoopbackRelayOp
`upstream SUBSCRIBE ${track.name} → alias ${trackAlias}${timescale === undefined ? '' : ` (timescale ${timescale})`}`
);

// Hold for the FIN — the publisher's clean track end, or our own
// release. A subscription ends by FIN *alone*: any byte after
// SUBSCRIBE_OK is a protocol violation, and the real relay
// aborts the track for every viewer — mirror that by ending each
// downstream subscription rather than silently draining.
// Hold for the end — the publisher's PUBLISH_DONE then FIN (the
// clean track end), or our own release. Anything else after
// SUBSCRIBE_OK aborts the track for every viewer.
let publishDoneStatus: number | undefined;

if (!(await reader.atEnd())) {
log(`upstream ${track.name}: data after SUBSCRIBE_OK — aborting the track for its viewers`);
// A truncated or malformed frame aborts the track too — never
// leave its viewers attached to an upstream that is gone.
const message = await readControlFrame(reader).catch(() => undefined);
const clean = message?.type === MESSAGE_TYPE.PUBLISH_DONE && (await reader.atEnd().catch(() => false));

if (!message || !clean) {
const what = message ? `unexpected 0x${message.type.toString(16)}` : 'malformed frame';

log(`upstream ${track.name}: ${what} after SUBSCRIBE_OK — aborting the track`);

for (const subscriber of [...track.subscribers]) subscriber.end(PUBLISH_DONE_INTERNAL_ERROR);

return;
}

publishDoneStatus = new Reader(message.body).varint();

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

P2: A malformed PUBLISH_DONE body can leave every attached player waiting indefinitely: an empty body makes Reader.varint() throw, and the outer catch cleans up the upstream without ending subscribers. Validate the complete body here and end subscribers with INTERNAL_ERROR when it is malformed.

Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. When an issue isn't valid or won't be fixed in this PR, reply in its thread with the reason and then resolve the thread. At apps/sandbox/templates/moq-publisher/loopback-relay.ts, line 801:

<comment>A malformed PUBLISH_DONE body can leave every attached player waiting indefinitely: an empty body makes `Reader.varint()` throw, and the outer catch cleans up the upstream without ending subscribers. Validate the complete body here and end subscribers with INTERNAL_ERROR when it is malformed.</comment>

<file context>
@@ -771,29 +780,32 @@ export function createPublisherLoopbackRelay({ onLog }: PublisherLoopbackRelayOp
             return;
           }
+
+          publishDoneStatus = new Reader(message.body).varint();
         }
 
</file context>
Suggested change
publishDoneStatus = new Reader(message.body).varint();
try {
const fields = new Reader(message.body);
publishDoneStatus = fields.varint();
fields.varint(); // stream count
const reasonLength = fields.varint();
if (fields.offset + reasonLength !== message.body.length) throw new Error('malformed PUBLISH_DONE body');
fields.slice(reasonLength);
} catch {
log(`upstream ${track.name}: malformed PUBLISH_DONE after SUBSCRIBE_OK — aborting the track`);
for (const subscriber of [...track.subscribers]) subscriber.end(PUBLISH_DONE_INTERNAL_ERROR);
return;
}

}

for (const subscriber of [...track.subscribers]) subscriber.end();
} else if (handle.released) {
if (handle.released && publishDoneStatus === undefined) {
log(`upstream unsubscribe ${track.name} — no player interest`);
} else {
// The publisher's FIN is the END of the track: propagate it —
// the same clean FIN toward every attached viewer — so no
// The publisher's PUBLISH_DONE + FIN is the END of the track:
// propagate it to every attached viewer, so no
// player hangs on a dead track and a later publisher session
// cannot resume stale subscriptions. The downstream teardowns'
// releaseUpstream calls land after this routine's finally has
Expand All @@ -793,7 +818,11 @@ export function createPublisherLoopbackRelay({ onLog }: PublisherLoopbackRelayOp
// handed the final frames of a track that is over.
track.groups.clear();

for (const subscriber of [...track.subscribers]) subscriber.end();
// Forward the publisher's status, the way moq-relay 0.17.0 does
// — a bare FIN reaches its viewers as INTERNAL_ERROR.
for (const subscriber of [...track.subscribers]) {
subscriber.end(publishDoneStatus ?? PUBLISH_DONE_INTERNAL_ERROR);
}
}
} catch {
// Stream reset or session teardown — the close path owns cleanup.
Expand Down Expand Up @@ -1234,15 +1263,25 @@ export function createPublisherLoopbackRelay({ onLog }: PublisherLoopbackRelayOp
// Announce-and-serve: player interest is what makes the relay
// SUBSCRIBE upstream (catalog first, then the catalog's tracks).
requestUpstreamTrack?.(track);
// One stream per delivered object — the PUBLISH_DONE Stream Count.
let deliveredStreams = 0;

subscription = {
trackAlias,
deliver: (object) =>
deliver: (object) => {
deliveredStreams++;
publishObject(
encodeObjectStream(trackAlias, object.groupId, object.objectId, object.properties, object.payload)
),
end: () => {
// FIN toward the player (the clean track end), then cancel
// our read side — the loop's teardown removes the entry.
);
},
end: (statusCode) => {
// PUBLISH_DONE (when ending with a status) and FIN toward the
// player, then cancel our read side — the loop's teardown
// removes the entry.
if (statusCode !== undefined) {
void writer.write(encodePublishDone(statusCode, deliveredStreams)).catch(() => {});
}

writer.close().catch(() => {});
abort();
},
Expand Down
19 changes: 11 additions & 8 deletions internal/design/spf/features/moq-publish.md
Original file line number Diff line number Diff line change
Expand Up @@ -49,7 +49,7 @@ none is separately composable today.
|---|---|---|
| Capture | Device enumeration (`devicechange`-reactive, label refresh on grant); capture-source acquisition (`getUserMedia` camera, `getDisplayMedia` + microphone-merge screen share, re-acquire on selection-identity change, stale-async guards); preview mirroring via `srcObject` (forced muted + playsInline); mute toggles via `track.enabled` (capture keeps running) | **Implemented** |
| Encode | `isConfigSupported` probing over a candidate ladder (default `avc1.42E01F` in `avc` bitstream format with a `vp8` fallback; Opus with a 48 kHz fallback; `config.video.codec` prepends rather than replaces); `selectEncoderConfig` strategy resolves support → active encodings; per-kind WebCodecs encoder actors, each stamping one epoch of the kind's `TrackTimeline` — a rebuilt actor (capture-source switch, encoding change) continues the track's published clock domain plus the real monotonic acquisition gap instead of opening a fresh wallclock anchor; frame pumping with a timestamp-driven forced-keyframe cadence so **GoP = MoQ group** (`groupDurationSec`, default 2 s); LOC packaging of every chunk (Timestamp / Timescale / Config-on-keyframes) | **Implemented** |
| Transport | Publish session speaking draft-19 with **announce-and-serve ingest** (see the decision below): SETUP exchange; inbound SUBSCRIBE_NAMESPACE solicitations answered with REQUEST_OK and held as the announce carrier; the namespace announced as a NAMESPACE entry on every covering solicitation (`'live'` = announced); inbound SUBSCRIBEs answered with SUBSCRIBE_OK carrying alias = the request ID and a microsecond TIMESCALE track property; REQUEST_UPDATE routing; GOAWAY → `draining`; track end = a bare FIN of each subscription stream; close retracts the announce (NAMESPACE_DONE) and sends **no GOAWAY**; one `TrackPublisherActor` per track writing subgroup streams **only while bound to a live subscription** (video: new group per keyframe, joins at the next keyframe on bind; audio + catalog: group-per-frame; catalog replays its latest frame on every bind); MSF catalog derivation re-sent on any input-identity change | **Implemented** |
| Transport | Publish session speaking draft-19 with **announce-and-serve ingest** (see the decision below): SETUP exchange; inbound SUBSCRIBE_NAMESPACE solicitations answered with REQUEST_OK and held as the announce carrier; the namespace announced as a NAMESPACE entry on every covering solicitation (`'live'` = announced); inbound SUBSCRIBEs answered with SUBSCRIBE_OK carrying alias = the request ID and a microsecond TIMESCALE track property; REQUEST_UPDATE routing; GOAWAY → `draining`; track end = PUBLISH_DONE (TRACK_ENDED, exact Stream Count) then FIN on each subscription stream; close retracts the announce (NAMESPACE_DONE) and sends **no GOAWAY**; one `TrackPublisherActor` per track writing subgroup streams **only while bound to a live subscription** (video: new group per keyframe, joins at the next keyframe on bind; audio + catalog: group-per-frame; catalog replays its latest frame on every bind); MSF catalog derivation re-sent on any input-identity change | **Implemented** |
| Observability | ~1 Hz `publishStats` sampling from the encoder actor counters (`encodedFps`, bitrates, `droppedFrames`, `bytesSent`) | **Implemented** — `droppedGroups` is counted on the track publishers but not yet folded into `publishStats`; `subscriberCount` is tracked on the session actor but surfaces as `NaN` |

### Ingest model: announce-and-serve (2026-08-07)
Expand Down Expand Up @@ -78,10 +78,12 @@ own reference clients use:
next keyframe; the catalog track replays its latest frame on every
bind because catalog frames flow on change, and a fresh subscription
must not wait for the next one.
- **Three peer-verified teardown rules** (moq-relay 0.14.7 source):
a track ends by a bare FIN of the subscription stream — any trailing
byte (the old PUBLISH_DONE) makes the relay *abort* the track for
every viewer; a client GOAWAY closes the whole session (code 17); and
- **Three peer-verified teardown rules**: a track ends with
PUBLISH_DONE (TRACK_ENDED, exact Stream Count) then a FIN of the
Comment thread
cubic-dev-ai[bot] marked this conversation as resolved.
Resolved
subscription stream — moq-relay 0.17.0 forwards that as "track ended",
but reports a bare FIN as "internal error" (older moq-relay builds
abort the track on any byte after SUBSCRIBE_OK; they are not
supported); a client GOAWAY closes the whole session (code 17); and
SUBSCRIBE_OK should declare the TIMESCALE track property or the relay
discards object TIMESTAMP extensions and re-stamps frames on arrival.
- **Per-stream failures are ordinary lifecycle now** — the relay resets
Expand Down Expand Up @@ -144,7 +146,7 @@ Behaviors (`packages/spf/src/publish/behaviors/`; DOM-bound ones under
| `pumpMediaFrames` | `dom/pump-media-frames.ts` | `MediaStreamTrackProcessor` read loops → `encode` messages; keyframe cadence |
| `trackPublishStats` | `track-publish-stats.ts` | Sample encoder counters into `publishStats` (DOM-free via a structural actor view) |
| `openPublishSession` | `open-publish-session.ts` | Own the publish session actor; gate on `endpoint` + `publishActivated` + capture `'active'`; mirror lifecycle into `sessionStatus` |
| `setupTrackPublishers` | `setup-track-publishers.ts` | Register each track on the session's serve registry; own the per-track publisher actors; sync subscription bindings into them; FIN each track's subscriptions on teardown |
| `setupTrackPublishers` | `setup-track-publishers.ts` | Register each track on the session's serve registry; own the per-track publisher actors; sync subscription bindings into them; on teardown, close each track's data streams, then end its subscriptions with PUBLISH_DONE (TRACK_ENDED) and a FIN |
| `deriveCatalog` | `derive-catalog.ts` | Build + send the MSF catalog as object 0 of a fresh group on every input change |

Actors and session:
Expand Down Expand Up @@ -267,8 +269,9 @@ publisher initiates no requests, so there is no response to bound.
half (solicitation acceptance, suffix-relative NAMESPACE entries,
announce-loss → `onAnnounceEnded`, NAMESPACE_DONE + no-GOAWAY close)
and the serve half (alias = request ID, TIMESCALE declaration,
newest-subscription binding with clean replacement FINs, bare-FIN
track end) through `network/moqt/tests/helpers/raw-peer.ts`, the relay's
newest-subscription binding with bare-FIN ends for superseded
subscriptions, PUBLISH_DONE + FIN track end with exact Stream Counts)
through `network/moqt/tests/helpers/raw-peer.ts`, the relay's
side of the flow the subscribe driver does not initiate.
- **Full pipeline** —
`publish/engines/moq/tests/publish-transport.test.ts`: real capture
Expand Down
15 changes: 12 additions & 3 deletions packages/spf/src/network/moqt/control-messages.ts
Original file line number Diff line number Diff line change
Expand Up @@ -1028,12 +1028,21 @@ export function encodeSubscribeOk(
return frameMessage(MESSAGE_TYPE.SUBSCRIBE_OK, body);
}

/** PUBLISH_DONE (§10.12). */
export function encodePublishDone(statusCode: number, streamCount: number, reason = ''): Uint8Array {
/** 2^64−1, PUBLISH_DONE's "unknown" Stream Count, has one encoding: the 9-byte form with every bit set. */
const UNKNOWN_STREAM_COUNT = new Uint8Array(9).fill(0xff);

/**
* PUBLISH_DONE (§10.12). An `undefined` Stream Count is the publisher that cannot count its streams, encoded as the
* 2^64−1 sentinel the draft mandates (and `readCountVarint` reads back as `undefined`).
*/
export function encodePublishDone(statusCode: number, streamCount: number | undefined, reason = ''): Uint8Array {
const body = new ByteWriter();

body.writeVarint(statusCode);
body.writeVarint(streamCount);

if (streamCount === undefined) body.writeBytes(UNKNOWN_STREAM_COUNT);
else body.writeVarint(streamCount);

writeReasonPhrase(body, reason);
return frameMessage(MESSAGE_TYPE.PUBLISH_DONE, body);
}
Expand Down
6 changes: 3 additions & 3 deletions packages/spf/src/network/moqt/session.ts
Original file line number Diff line number Diff line change
Expand Up @@ -60,9 +60,9 @@ 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.
* Publish-side fill failure signaling uses WebTransport's `commit()` writer method where it exists, which preserves the
* written FETCH_HEADER across the reset. Without it the subscription is still served, and the reset that fails the fill
* may discard its header.
*/
export interface MoqtTransport {
readonly incomingUnidirectionalStreams: ReadableStream<ReadableStream<Uint8Array>>;
Expand Down
7 changes: 7 additions & 0 deletions packages/spf/src/network/moqt/tests/publish-direction.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -66,6 +66,13 @@ describe('encodePublishDone', () => {
reason: 'stopped',
});
});

it('encodes an unknown stream count as the 2^64−1 sentinel', () => {
const bytes = encodePublishDone(PUBLISH_DONE_STATUS.TRACK_ENDED, undefined);

expect(bytes.subarray(-10, -1)).toEqual(new Uint8Array(9).fill(0xff));
expect(decodeOne(bytes)).toMatchObject({ kind: 'publish-done', streamCount: undefined, reason: '' });
});
});

describe('encodeSubscribeOk', () => {
Expand Down
30 changes: 30 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 @@ -338,6 +338,36 @@ describe('createTrackPublisherActor', () => {
]);
});

it('counts the data streams opened under each subscription alias, pruning superseded ones', async () => {
const factory = makeStreamFactory();
const publisher = createTrackPublisherActor({ openUniStream: factory.openUniStream, groupPerFrame: true });
const frame = (timestampUs: number) =>
({ type: 'frame', payload: new Uint8Array([1]), properties: [], keyframe: true, timestampUs }) as const;

// Unbound frames open nothing and count for no one.
publisher.send(frame(0));
publisher.send({ type: 'bind', trackAlias: 3 });
publisher.send(frame(1));
publisher.send(frame(2));
await vi.waitFor(() => expect(counters(publisher).publishedGroups).toBe(2));

// A Forward State toggle unbinds and rebinds the same alias: its
// count must survive, or PUBLISH_DONE would under-report.
publisher.send({ type: 'unbind' });
publisher.send({ type: 'bind', trackAlias: 3 });
publisher.send(frame(3));
await vi.waitFor(() => expect(counters(publisher).publishedGroups).toBe(3));
expect(publisher.streamCount(3)).toBe(3);

// A new alias supersedes the old subscription, whose count is pruned.
publisher.send({ type: 'bind', trackAlias: 5 });
publisher.send(frame(4));
await vi.waitFor(() => expect(counters(publisher).publishedGroups).toBe(4));

expect([publisher.streamCount(3), publisher.streamCount(5), publisher.streamCount(7)]).toEqual([0, 1, 0]);
publisher.destroy();
});

it('ignores delta frames before the first keyframe', async () => {
const factory = makeStreamFactory();
const publisher = createTrackPublisherActor({ openUniStream: factory.openUniStream });
Expand Down
Loading
Loading