From 1c891018b6844f87291d249e9477a5498d3c0a92 Mon Sep 17 00:00:00 2001 From: Matt McClure Date: Wed, 28 Oct 2026 05:02:16 +0000 Subject: [PATCH 1/3] feat(spf): publish through @caprid/moq-core's publish session MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The publisher drove v10's own publish session over a draft-20 copy of network/moqt, kept only so the mmcc/moq sync would build. It now drives createMoqtPublishSession from @caprid/moq-core, the package extracted from that session, and speaks moqt-22 with a moqt-20 fallback like the player. - publish-session.ts keeps only the session actor. The default connect offers MOQT_PROTOCOL_IDS when WebTransport exposes `protocol`, so the session reads the negotiated version. - Track publishers open each group's stream for the alias bound when the group started (`openUniStream(trackAlias)`). The session counts each subscription's streams for PUBLISH_DONE, so the publisher's own per-alias count and the getStreamCount wiring are gone. - setupTrackPublishers declares the microsecond TIMESCALE track property explicitly; the package's session imposes none. - network/moqt is deleted with its tests. raw-peer and transport-pair move beside moqt-wire, which now re-exports the package's relay-side codecs for the relay hub and the raw peers. withServerRequestIds gives a subscribe session standing in for the relay odd request IDs, which the package's publish session requires (§6.4.2.1). Claude-Session: https://claude.ai/code/session_01DaH4ifX9Vb6HuB2yg6TMt5 --- packages/spf/src/network/moqt/bytes.ts | 249 --- .../spf/src/network/moqt/control-messages.ts | 1367 ------------- packages/spf/src/network/moqt/errors.ts | 49 - .../spf/src/network/moqt/object-stream.ts | 372 ---- .../spf/src/network/moqt/request-stream.ts | 133 -- packages/spf/src/network/moqt/session.ts | 1038 ---------- .../spf/src/network/moqt/subgroup-writer.ts | 184 -- .../moqt/tests/control-messages.test.ts | 612 ------ .../moqt/tests/helpers/transport-pair.ts | 86 - .../network/moqt/tests/object-stream.test.ts | 449 ---- .../moqt/tests/publish-direction.test.ts | 211 -- .../src/network/moqt/tests/session.test.ts | 1008 --------- .../moqt/tests/subgroup-writer.test.ts | 220 -- .../spf/src/network/moqt/tests/varint.test.ts | 112 - packages/spf/src/network/moqt/varint.ts | 122 -- .../src/network/tests/helpers/moqt-wire.ts | 24 +- .../{moqt => }/tests/helpers/raw-peer.ts | 10 +- .../network/tests/helpers/transport-pair.ts | 162 ++ .../actors/tests/track-publisher.test.ts | 36 +- .../spf/src/publish/actors/track-publisher.ts | 32 +- .../publish/behaviors/open-publish-session.ts | 3 +- .../behaviors/setup-track-publishers.ts | 29 +- .../tests/open-publish-session-switch.test.ts | 10 +- .../tests/open-publish-session.test.ts | 13 +- .../setup-track-publishers-switch.test.ts | 8 +- .../tests/setup-track-publishers.test.ts | 32 +- .../tests/track-publish-stats.test.ts | 2 +- .../spf/src/publish/engines/moq/engine.ts | 6 +- .../publish/engines/moq/tests/adapter.test.ts | 13 +- .../engines/moq/tests/cross-engine.test.ts | 4 +- .../moq/tests/publish-transport.test.ts | 10 +- .../src/publish/session/publish-session.ts | 1282 +----------- .../session/tests/publish-session.test.ts | 1799 +---------------- .../src/publish/tests/helpers/relay-hub.ts | 59 +- .../spf/src/publish/tests/relay-hub.test.ts | 12 +- 35 files changed, 397 insertions(+), 9361 deletions(-) delete mode 100644 packages/spf/src/network/moqt/bytes.ts delete mode 100644 packages/spf/src/network/moqt/control-messages.ts delete mode 100644 packages/spf/src/network/moqt/errors.ts delete mode 100644 packages/spf/src/network/moqt/object-stream.ts delete mode 100644 packages/spf/src/network/moqt/request-stream.ts delete mode 100644 packages/spf/src/network/moqt/session.ts delete mode 100644 packages/spf/src/network/moqt/subgroup-writer.ts delete mode 100644 packages/spf/src/network/moqt/tests/control-messages.test.ts delete mode 100644 packages/spf/src/network/moqt/tests/helpers/transport-pair.ts delete mode 100644 packages/spf/src/network/moqt/tests/object-stream.test.ts delete mode 100644 packages/spf/src/network/moqt/tests/publish-direction.test.ts delete mode 100644 packages/spf/src/network/moqt/tests/session.test.ts delete mode 100644 packages/spf/src/network/moqt/tests/subgroup-writer.test.ts delete mode 100644 packages/spf/src/network/moqt/tests/varint.test.ts delete mode 100644 packages/spf/src/network/moqt/varint.ts rename packages/spf/src/network/{moqt => }/tests/helpers/raw-peer.ts (93%) create mode 100644 packages/spf/src/network/tests/helpers/transport-pair.ts diff --git a/packages/spf/src/network/moqt/bytes.ts b/packages/spf/src/network/moqt/bytes.ts deleted file mode 100644 index a5f36e7c96..0000000000 --- a/packages/spf/src/network/moqt/bytes.ts +++ /dev/null @@ -1,249 +0,0 @@ -/** - * Byte-level readers/writers shared by the MOQT wire codecs. - * - * `ByteReader`/`ByteWriter` are synchronous cursors over in-memory buffers, used for control-message bodies (always - * fully buffered — the 16-bit message length bounds them). `StreamReader` is the asynchronous counterpart for - * unidirectional data streams, where headers and objects arrive incrementally over a WebTransport `ReadableStream`. - */ -import { decodeVarint, encodeVarintInto, varintByteLength, varintLengthFromFirstByte } from './varint'; - -const textEncoder = new TextEncoder(); -const textDecoder = new TextDecoder(); - -export function utf8Encode(value: string): Uint8Array { - return textEncoder.encode(value); -} - -export function utf8Decode(bytes: Uint8Array): string { - return textDecoder.decode(bytes); -} - -/** Synchronous cursor over a byte buffer. All reads throw `RangeError` past the end. */ -export class ByteReader { - #bytes: Uint8Array; - #offset: number; - - constructor(bytes: Uint8Array, offset = 0) { - this.#bytes = bytes; - this.#offset = offset; - } - - get offset(): number { - return this.#offset; - } - - get remaining(): number { - return this.#bytes.length - this.#offset; - } - - readVarint(): number { - const { value, byteLength } = decodeVarint(this.#bytes, this.#offset); - - this.#offset += byteLength; - return value; - } - - /** - * Read a count whose "unknown" sentinel is the maximal varint 2^64−1 — PUBLISH_DONE's Stream Count (§10.12). Exactly - * that sentinel reads as `undefined`; any other value above this codec's 2^53−1 ceiling is still the protocol error - * `readVarint` raises, since no real count gets there. - */ - readCountVarint(): number | undefined { - const offset = this.#offset; - - // 2^64−1 has one encoding: the 9-byte form with every bit set. - if (this.remaining >= 9 && this.#bytes.subarray(offset, offset + 9).every((byte) => byte === 0xff)) { - this.#offset += 9; - return undefined; - } - - return this.readVarint(); - } - - readUint8(): number { - if (this.remaining < 1) throw new RangeError('read past end of buffer'); - - return this.#bytes[this.#offset++]!; - } - - readUint16(): number { - if (this.remaining < 2) throw new RangeError('read past end of buffer'); - - const value = this.#bytes[this.#offset]! * 256 + this.#bytes[this.#offset + 1]!; - - this.#offset += 2; - return value; - } - - /** Returns a view (not a copy) of the next `length` bytes. */ - readBytes(length: number): Uint8Array { - if (length < 0 || this.remaining < length) throw new RangeError('read past end of buffer'); - - const view = this.#bytes.subarray(this.#offset, this.#offset + length); - - this.#offset += length; - return view; - } -} - -/** Growable byte sink for encoding wire structures. */ -export class ByteWriter { - #buffer: Uint8Array; - #length = 0; - - constructor(initialCapacity = 256) { - this.#buffer = new Uint8Array(initialCapacity); - } - - get length(): number { - return this.#length; - } - - #ensure(extra: number): void { - const needed = this.#length + extra; - if (needed <= this.#buffer.length) return; - - const grown = new Uint8Array(Math.max(needed, this.#buffer.length * 2)); - - grown.set(this.#buffer.subarray(0, this.#length)); - this.#buffer = grown; - } - - writeVarint(value: number): void { - this.#ensure(varintByteLength(value)); - this.#length += encodeVarintInto(this.#buffer, this.#length, value); - } - - writeUint8(value: number): void { - this.#ensure(1); - this.#buffer[this.#length++] = value & 0xff; - } - - writeUint16(value: number): void { - this.#ensure(2); - this.#buffer[this.#length++] = (value >> 8) & 0xff; - this.#buffer[this.#length++] = value & 0xff; - } - - writeBytes(bytes: Uint8Array): void { - this.#ensure(bytes.length); - this.#buffer.set(bytes, this.#length); - this.#length += bytes.length; - } - - /** Varint length prefix followed by the bytes. */ - writeLengthPrefixed(bytes: Uint8Array): void { - this.writeVarint(bytes.length); - this.writeBytes(bytes); - } - - /** Returns a copy of the written bytes. */ - toBytes(): Uint8Array { - return this.#buffer.slice(0, this.#length); - } -} - -/** - * Buffered asynchronous reader over a `ReadableStream`. - * - * Reads never split a varint or byte run: each method pulls chunks until it can satisfy the request. A clean - * end-of-stream mid-read throws `RangeError`; use `atEnd()` to probe for a clean boundary first. - */ -export class StreamReader { - #reader: ReadableStreamDefaultReader; - #chunks: Uint8Array[] = []; - #buffered = 0; - #done = false; - - constructor(stream: ReadableStream) { - this.#reader = stream.getReader(); - } - - async #pull(): Promise { - if (this.#done) return false; - - const { done, value } = await this.#reader.read(); - - if (done) { - this.#done = true; - return false; - } - - if (value.length > 0) { - this.#chunks.push(value); - this.#buffered += value.length; - } - - return true; - } - - async #fill(length: number): Promise { - while (this.#buffered < length) { - if (!(await this.#pull())) throw new RangeError('unexpected end of stream'); - } - } - - #take(length: number): Uint8Array { - const out = new Uint8Array(length); - let copied = 0; - - while (copied < length) { - const head = this.#chunks[0]!; - const take = Math.min(head.length, length - copied); - - out.set(head.subarray(0, take), copied); - - if (take === head.length) { - this.#chunks.shift(); - } else { - this.#chunks[0] = head.subarray(take); - } - - copied += take; - } - - this.#buffered -= length; - return out; - } - - /** True when the stream ended cleanly with no bytes left unread. */ - async atEnd(): Promise { - while (this.#buffered === 0) { - if (!(await this.#pull())) return true; - } - - return false; - } - - async readBytes(length: number): Promise { - await this.#fill(length); - return this.#take(length); - } - - async readUint8(): Promise { - await this.#fill(1); - return this.#take(1)[0]!; - } - - async readVarint(): Promise { - await this.#fill(1); - const firstByte = this.#chunks[0]![0]!; - const byteLength = varintLengthFromFirstByte(firstByte); - - await this.#fill(byteLength); - return decodeVarint(this.#take(byteLength)).value; - } - - /** Cancel the underlying stream (e.g. drop an unwanted data stream). */ - async cancel(reason?: unknown): Promise { - try { - await this.#reader.cancel(reason); - } finally { - this.#reader.releaseLock(); - } - } - - releaseLock(): void { - this.#reader.releaseLock(); - } -} diff --git a/packages/spf/src/network/moqt/control-messages.ts b/packages/spf/src/network/moqt/control-messages.ts deleted file mode 100644 index d759f2030d..0000000000 --- a/packages/spf/src/network/moqt/control-messages.ts +++ /dev/null @@ -1,1367 +0,0 @@ -/** - * MOQT control-message wire codecs (moq-transport draft-20 §10). - * - * Every control or request-stream message is framed as: - * - * MOQT Control Message { - * Message Type (vi64), - * Message Length (16), - * Message Body (..), - * } - * - * Scope follows the subscribe-only engine: the encoders cover what a subscriber sends (SETUP, SUBSCRIBE, FETCH, - * TRACK_STATUS, SUBSCRIBE_NAMESPACE, REQUEST_UPDATE, GOAWAY, and REQUEST_OK / REQUEST_ERROR responses to incoming - * PUBLISH); the decoders cover what it receives. All draft-version specifics live in this directory — this is the - * churn-absorption layer for pre-WGLC drafts. - * - * Where the draft text and the deployed relay (moq-relay, moq-dev/moq) disagree on a wire detail, the codec follows the - * relay and says so at the site — interop is with the relay, not the prose. - * - * Namespace fields and track names are byte strings on the wire; this codec surfaces them as UTF-8 `string`s, which is - * what MSF (the streaming format this engine speaks) constrains them to. - */ -import { ByteReader, ByteWriter, utf8Decode, utf8Encode } from './bytes'; -import { MoqtProtocolError } from './errors'; -import { decodeVarint, MAX_VARINT_VALUE } from './varint'; - -// ============================================================================ -// Wire constants -// ============================================================================ - -/** - * ALPN / WebTransport protocol identifier for the implemented draft (§3.1: `moqt-` plus the draft number). Version - * negotiation happens at connection time (`WT-Available-Protocols` in WebTransport, ALPN in native QUIC) — not in - * SETUP. - */ -export const MOQT_PROTOCOL_ID = 'moqt-20'; - -/** Control/request message type codes (§10, Table 5). */ -export const MESSAGE_TYPE = { - SETUP: 0x2f00, - GOAWAY: 0x10, - SUBSCRIBE: 0x3, - SUBSCRIBE_OK: 0x4, - REQUEST_ERROR: 0x5, - PUBLISH_NAMESPACE: 0x6, - REQUEST_OK: 0x7, - NAMESPACE: 0x8, - PUBLISH_DONE: 0xb, - TRACK_STATUS: 0xd, - NAMESPACE_DONE: 0xe, - PUBLISH_SKIPPED: 0xf, - FETCH: 0x16, - FETCH_OK: 0x18, - PUBLISH: 0x1d, - PUBLISH_STATE_NOTIFY: 0x22, - REQUEST_UPDATE: 0x2, - SUBSCRIBE_NAMESPACE: 0x50, - SUBSCRIBE_TRACKS: 0x51, -} as const; - -/** Setup Option types (§10.3.1). A namespace separate from message parameters. */ -export const SETUP_OPTION = { - PATH: 0x01, - AUTHORIZATION_TOKEN: 0x03, - MAX_AUTH_TOKEN_CACHE_SIZE: 0x04, - AUTHORITY: 0x05, - MAX_FILTER_RANGES: 0x06, - MOQT_IMPLEMENTATION: 0x07, - MAX_REQUEST_UPDATES: 0x08, -} as const; - -/** Message parameter types (§10.2, §15.7). */ -export const PARAMETER_TYPE = { - OBJECT_DELIVERY_TIMEOUT: 0x02, - AUTHORIZATION_TOKEN: 0x03, - RENDEZVOUS_TIMEOUT: 0x04, - SUBGROUP_DELIVERY_TIMEOUT: 0x06, - EXPIRES: 0x08, - LARGEST_OBJECT: 0x09, - FILL_TIMEOUT: 0x0a, - FORWARD: 0x10, - SUBSCRIBER_PRIORITY: 0x20, - LOCATION_FILTER: 0x21, - GROUP_ORDER: 0x22, - FILL_PARAMETERS: 0x23, - SUBGROUP_FILTER: 0x25, - OBJECTID_FILTER: 0x26, - PRIORITY_FILTER: 0x27, - OBJECT_PROPERTY_FILTER: 0x28, - TRACK_PROPERTY_FILTER: 0x29, - NEW_GROUP_REQUEST: 0x32, - TRACK_NAMESPACE_PREFIX: 0x34, - INCLUDE_PROPERTIES: 0x35, -} as const; - -/** - * Track Property types (§10.8) — the KVP block trailing SUBSCRIBE_OK / PUBLISH / FETCH_OK. A registry of its own, - * distinct from both Setup Options and message parameters. - */ -export const TRACK_PROPERTY = { - /** - * Units-per-second for the track's object TIMESTAMP extensions. Declaring it in SUBSCRIBE_OK is what opts the track - * into timestamp forwarding on moq-lite-rs relays — without it they parse and discard the extensions and re-stamp - * frames on arrival. - */ - TIMESCALE: 0x08, -} as const; - -/** REQUEST_ERROR codes (§15.11.2). */ -export const REQUEST_ERROR_CODE = { - INTERNAL_ERROR: 0x0, - UNAUTHORIZED: 0x1, - TIMEOUT: 0x2, - NOT_SUPPORTED: 0x3, - MALFORMED_AUTH_TOKEN: 0x4, - EXPIRED_AUTH_TOKEN: 0x5, - GOING_AWAY: 0x6, - EXCESSIVE_LOAD: 0x9, - DOES_NOT_EXIST: 0x10, - INVALID_RANGE: 0x11, - MALFORMED_TRACK: 0x12, - UNINTERESTED: 0x20, - PREFIX_OVERLAP: 0x30, - NAMESPACE_TOO_LARGE: 0x31, - UNSUPPORTED_EXTENSION: 0x33, - REDIRECT: 0x34, - CONFLICTING_FILTERS: 0x35, - INVALID_FILTER: 0x36, -} as const; - -/** PUBLISH_DONE status codes (§10.12). */ -export const PUBLISH_DONE_STATUS = { - INTERNAL_ERROR: 0x0, - UNAUTHORIZED: 0x1, - TRACK_ENDED: 0x2, - GOING_AWAY: 0x4, - TOO_FAR_BEHIND: 0x5, - EXPIRED: 0x6, - UPDATE_FAILED: 0x8, - EXCESSIVE_LOAD: 0x9, - MALFORMED_TRACK: 0x12, -} as const; - -/** - * REQUEST_ERROR codes for which an identical retry can never succeed: the request or its credentials are wrong in a way - * that does not change between attempts. Everything else — including codes this table does not know — is treated as - * retryable, so a relay introducing a new transient code degrades to paced retries rather than a dead player. - * EXPIRED_AUTH_TOKEN is deliberately absent: it has its own refresh path wherever requests are retried. - */ -const PERMANENT_REQUEST_ERROR_CODES: ReadonlySet = new Set([ - REQUEST_ERROR_CODE.UNAUTHORIZED, - REQUEST_ERROR_CODE.NOT_SUPPORTED, - REQUEST_ERROR_CODE.MALFORMED_AUTH_TOKEN, - REQUEST_ERROR_CODE.INVALID_RANGE, - // The track cannot be served as requested; an identical resubscribe - // re-earns the rejection. A publisher fixing the track surfaces as a - // catalog update, which re-selects and re-subscribes through fresh state. - REQUEST_ERROR_CODE.MALFORMED_TRACK, - REQUEST_ERROR_CODE.UNINTERESTED, - REQUEST_ERROR_CODE.PREFIX_OVERLAP, - REQUEST_ERROR_CODE.NAMESPACE_TOO_LARGE, - REQUEST_ERROR_CODE.UNSUPPORTED_EXTENSION, - // Until session migration exists, the redirect target is unreachable and - // re-asking the same relay just re-earns the redirect. - REQUEST_ERROR_CODE.REDIRECT, - REQUEST_ERROR_CODE.CONFLICTING_FILTERS, - REQUEST_ERROR_CODE.INVALID_FILTER, -]); - -/** - * Whether a failed request is worth re-issuing unchanged after a backoff. The transient family (`DOES_NOT_EXIST` while - * a broadcast has not started, `TIMEOUT`, `INTERNAL_ERROR`, overload, `GOING_AWAY`) reflects relay or publisher _state_ - * that time can fix; the permanent family reflects the request itself and loops forever if retried. - */ -export function isRetryableRequestErrorCode(errorCode: number): boolean { - return !PERMANENT_REQUEST_ERROR_CODES.has(errorCode); -} - -/** - * PUBLISH_DONE statuses after which an identical re-subscribe can never succeed: auth-shaped ends (same credentials the - * relay just rejected) and a malformed track (same request re-earns the same end; a publisher fix arrives as a catalog - * update through fresh state). Every other status describes publisher/relay state a broadcaster restart or live-edge - * rejoin legitimately recovers from (`TRACK_ENDED`, `GOING_AWAY`, `TOO_FAR_BEHIND`, overload, …), and unknown statuses - * degrade to paced retries for the same reason as {@link isRetryableRequestErrorCode}. - */ -const PERMANENT_PUBLISH_DONE_STATUSES: ReadonlySet = new Set([ - PUBLISH_DONE_STATUS.UNAUTHORIZED, - PUBLISH_DONE_STATUS.EXPIRED, - PUBLISH_DONE_STATUS.MALFORMED_TRACK, -]); - -/** Whether a PUBLISH_DONE'd subscription is worth re-subscribing. */ -export function isRetryablePublishDoneStatus(statusCode: number): boolean { - return !PERMANENT_PUBLISH_DONE_STATUSES.has(statusCode); -} - -/** Stream reset / STOP_SENDING error codes (§3.3.4). */ -export const STREAM_RESET_CODE = { - INTERNAL_ERROR: 0x0, - CANCELLED: 0x1, - DELIVERY_TIMEOUT: 0x2, - SESSION_CLOSED: 0x3, - GOING_AWAY: 0x4, - TOO_FAR_BEHIND: 0x5, - UNKNOWN_OBJECT_STATUS: 0x6, - EXPIRED_AUTH_TOKEN: 0x7, - EXCESSIVE_LOAD: 0x9, - MALFORMED_TRACK: 0x12, -} as const; - -/** Maximum body size — the frame length field is 16 bits. */ -export const MAX_CONTROL_MESSAGE_LENGTH = 0xffff; - -const MAX_NAMESPACE_FIELDS = 32; -const MAX_FULL_TRACK_NAME_LENGTH = 4096; -const MAX_REASON_PHRASE_LENGTH = 1024; -const MAX_NEW_SESSION_URI_LENGTH = 8192; -const MAX_KVP_VALUE_LENGTH = 0xffff; -const MAX_LOCATION_FILTER_FIELDS = 4; - -// ============================================================================ -// Shared structures -// ============================================================================ - -/** A particular Object in a Group within a Track (§1.4.2). */ -export interface Location { - group: number; - object: number; -} - -/** `A < B` in Location order (group first, then object). */ -export function compareLocations(a: Location, b: Location): number { - return a.group - b.group || a.object - b.object; -} - -/** Track namespace as an ordered tuple of UTF-8 fields. Byte strings on the wire; MSF constrains them to UTF-8 text. */ -export type TrackNamespace = string[]; - -export interface FullTrackName { - namespace: TrackNamespace; - name: string; -} - -function writeTrackNamespace(writer: ByteWriter, namespace: TrackNamespace): void { - if (namespace.length > MAX_NAMESPACE_FIELDS) { - throw new MoqtProtocolError(`track namespace has more than ${MAX_NAMESPACE_FIELDS} fields`); - } - - writer.writeVarint(namespace.length); - - for (const field of namespace) { - const bytes = utf8Encode(field); - if (bytes.length === 0) throw new MoqtProtocolError('track namespace field must not be empty'); - - writer.writeLengthPrefixed(bytes); - } -} - -function readTrackNamespace(reader: ByteReader): TrackNamespace { - const fieldCount = reader.readVarint(); - - if (fieldCount > MAX_NAMESPACE_FIELDS) { - throw new MoqtProtocolError(`track namespace has more than ${MAX_NAMESPACE_FIELDS} fields`); - } - - const namespace: TrackNamespace = []; - let totalLength = 0; - - for (let i = 0; i < fieldCount; i++) { - const length = reader.readVarint(); - if (length === 0) throw new MoqtProtocolError('track namespace field must not be empty'); - - totalLength += length; - - if (totalLength > MAX_FULL_TRACK_NAME_LENGTH) { - throw new MoqtProtocolError('track namespace exceeds 4096 bytes'); - } - - namespace.push(utf8Decode(reader.readBytes(length))); - } - - return namespace; -} - -function writeReasonPhrase(writer: ByteWriter, reason: string): void { - const bytes = utf8Encode(reason); - if (bytes.length > MAX_REASON_PHRASE_LENGTH) throw new MoqtProtocolError('reason phrase exceeds 1024 bytes'); - - writer.writeLengthPrefixed(bytes); -} - -function readReasonPhrase(reader: ByteReader): string { - const length = reader.readVarint(); - if (length > MAX_REASON_PHRASE_LENGTH) throw new MoqtProtocolError('reason phrase exceeds 1024 bytes'); - - return utf8Decode(reader.readBytes(length)); -} - -// Message parameters use per-type encodings: LARGEST_OBJECT is a bare Location -// (§10.2), including with moq-relay 0.14.17+ on draft-17 and newer (moq-dev/moq#3561). -// This engine speaks draft-20 only; older relays' length prefix is incompatible. -function writeLocation(writer: ByteWriter, location: Location): void { - writer.writeVarint(location.group); - writer.writeVarint(location.object); -} - -function readLocation(reader: ByteReader): Location { - return { group: reader.readVarint(), object: reader.readVarint() }; -} - -// ============================================================================ -// Key-Value-Pairs (§1.4.3) — Setup Options and Track Properties -// ============================================================================ - -/** - * A generic MOQT Key-Value-Pair. Even types carry a varint value, odd types a byte field. Used for Setup Options and - * Track/Object Properties (message parameters use per-type encodings instead — see `MessageParameters`). - */ -export interface KeyValuePair { - type: number; - value: number | Uint8Array; -} - -/** Serialize pairs in ascending type order with delta-encoded types. */ -export function encodeKeyValuePairs(writer: ByteWriter, pairs: readonly KeyValuePair[]): void { - const sorted = [...pairs].sort((a, b) => a.type - b.type); - let previousType = 0; - - for (const { type, value } of sorted) { - writer.writeVarint(type - previousType); - previousType = type; - - if (type % 2 === 0) { - if (typeof value !== 'number') throw new MoqtProtocolError(`even KVP type ${type} requires a varint value`); - - writer.writeVarint(value); - } else { - if (typeof value === 'number') throw new MoqtProtocolError(`odd KVP type ${type} requires a byte value`); - - if (value.length > MAX_KVP_VALUE_LENGTH) throw new MoqtProtocolError('KVP value exceeds 2^16-1 bytes'); - - writer.writeLengthPrefixed(value); - } - } -} - -/** Parse pairs until `reader` reaches `endOffset` (KVP blocks are length-bounded). */ -export function decodeKeyValuePairs(reader: ByteReader, endOffset: number): KeyValuePair[] { - const pairs: KeyValuePair[] = []; - let previousType = 0; - - while (reader.offset < endOffset) { - const type = previousType + reader.readVarint(); - - previousType = type; - - if (type % 2 === 0) { - pairs.push({ type, value: reader.readVarint() }); - } else { - const length = reader.readVarint(); - if (length > MAX_KVP_VALUE_LENGTH) throw new MoqtProtocolError('KVP value exceeds 2^16-1 bytes'); - - pairs.push({ type, value: reader.readBytes(length) }); - } - } - - if (reader.offset !== endOffset) throw new MoqtProtocolError('KVP block overran its bound'); - - return pairs; -} - -// ============================================================================ -// Location Filters (§5.1.2) — carried in the LOCATION_FILTER parameter -// ============================================================================ - -/** - * Which Objects a subscription or fetch covers. On the wire the LOCATION_FILTER value is up to four varints — - * StartGroup, StartObject, EndGroupDelta, EndObject — and how many are present selects the meaning: - * - * - `none` — zero fields. Unfiltered: the whole track for a subscription, `{0,0}` up to Largest Object for a fetch; in - * REQUEST_UPDATE it clears the filter. - * - `relative-group` — one field. Start at `{Largest.Group + 1 − groupsBeforeNext, 0}`, open-ended: `0` is the next - * group, `1` the start of the current group (a decodable join), `N` N−1 groups before it. - * - `next-object` — the two-field spelling `{0,0}`: `{Largest.Group, Largest.Object + 1}`, the live edge, which can begin - * mid-group. - * - `absolute` — two to four fields: an explicit start, optionally bounded by an end group (delta from the start group, - * whole group included unless `endObject` narrows it). An open-ended absolute `{0,0}` is unfiltered by definition and - * encodes as `none` — its two-field spelling would read as `next-object`. - */ -export type LocationFilter = - | { type: 'none' } - | { type: 'next-object' } - | { type: 'relative-group'; groupsBeforeNext: number } - | { type: 'absolute'; start: Location; endGroupDelta?: number; endObject?: number }; - -/** Serialize a filter as the LOCATION_FILTER parameter's value (without its length prefix). */ -export function encodeLocationFilter(filter: LocationFilter): Uint8Array { - const writer = new ByteWriter(32); - - switch (filter.type) { - case 'none': - break; - case 'next-object': - writer.writeVarint(0); - writer.writeVarint(0); - break; - case 'relative-group': - writer.writeVarint(filter.groupsBeforeNext); - break; - case 'absolute': { - const { start, endGroupDelta, endObject } = filter; - - if (endObject !== undefined && endGroupDelta === undefined) { - throw new MoqtProtocolError('location filter end object requires an end group'); - } - - if (start.group === 0 && start.object === 0 && endGroupDelta === undefined) break; - - writeLocation(writer, start); - - if (endGroupDelta !== undefined) writer.writeVarint(endGroupDelta); - - if (endObject !== undefined) writer.writeVarint(endObject); - - break; - } - } - - return writer.toBytes(); -} - -export function decodeLocationFilter(bytes: Uint8Array): LocationFilter { - const reader = new ByteReader(bytes); - const fields: number[] = []; - - while (reader.remaining > 0) { - if (fields.length === MAX_LOCATION_FILTER_FIELDS) { - throw new MoqtProtocolError('location filter has more than four fields'); - } - - fields.push(reader.readVarint()); - } - - if (fields.length === 0) return { type: 'none' }; - - if (fields.length === 1) return { type: 'relative-group', groupsBeforeNext: fields[0]! }; - - const [group, object, endGroupDelta, endObject] = fields as [number, number, number?, number?]; - if (fields.length === 2 && group === 0 && object === 0) return { type: 'next-object' }; - - const filter: LocationFilter = { type: 'absolute', start: { group, object } }; - - if (endGroupDelta !== undefined) { - if (group + endGroupDelta > MAX_VARINT_VALUE) { - throw new MoqtProtocolError('location filter end group exceeds supported range'); - } - - filter.endGroupDelta = endGroupDelta; - } - - if (endObject !== undefined) filter.endObject = endObject; - - return filter; -} - -/** - * Whether a Location filter, evaluated with the fetch rules of §5.1.2, selects no Objects. A fetch range — and so a - * subscription's fill range (§5.1.3) — is capped at Largest Object: with no Largest Object nothing exists to fetch, the - * Next Object and Next Group both lie past it, an absolute start past it selects nothing, and a bounded absolute range - * whose end precedes its start is empty. A publisher opens no fill fetch stream for an empty range. - */ -export function isEmptyFetchRange(filter: LocationFilter, largestObject: Location | undefined): boolean { - if (largestObject === undefined) return true; - - switch (filter.type) { - case 'none': - return false; - case 'next-object': - return true; - case 'relative-group': - return filter.groupsBeforeNext === 0; - case 'absolute': { - const { start, endGroupDelta, endObject } = filter; - if (compareLocations(start, largestObject) > 0) return true; - - // The end group is a non-negative delta from the start group, so - // only a same-group end can precede the start. - return endGroupDelta === 0 && endObject !== undefined && endObject < start.object; - } - } -} - -// ============================================================================ -// Message Parameters (§10.2) -// ============================================================================ - -export type GroupOrder = 'ascending' | 'descending'; - -/** - * Decoded message parameters. Unlike Setup Options, message parameters use per-type encodings (uint8 / varint / - * length-prefixed), so the codec is registry-driven. Per §10.2 an unknown parameter type is a PROTOCOL_VIOLATION - * (parameters cannot be skipped — the block is bounded by count, not length). - */ -export interface MessageParameters { - objectDeliveryTimeout?: number; - subgroupDeliveryTimeout?: number; - rendezvousTimeout?: number; - fillTimeout?: number; - /** Serialized Token structures (§10.2.2). May repeat. */ - authorizationTokens?: Uint8Array[]; - expires?: number; - largestObject?: Location; - forward?: 0 | 1; - subscriberPriority?: number; - locationFilter?: LocationFilter; - groupOrder?: GroupOrder; - /** - * FILL_PARAMETERS (§10.2.15): asks the publisher to deliver a fill range on a fetch stream alongside the subscription - * — its presence alone requests the fill. A nested parameter scope: only the fill-scoped subset is legal inside, and - * omitted entries inherit the subscription's own values. - */ - fillParameters?: FillParameters; - newGroupRequest?: number; - /** Range-filter parameters (§5.1.4), kept opaque — the engine never sends or interprets them. */ - rangeFilters?: { type: number; value: Uint8Array }[]; - trackNamespacePrefix?: TrackNamespace; - /** INCLUDE_PROPERTIES (§10.2.21): `0` asks the responder to send empty Track Properties. Default `1`. */ - includeProperties?: 0 | 1; -} - -/** The parameters FILL_PARAMETERS may carry (§10.2.15, Table 6). */ -export type FillParameters = Pick< - MessageParameters, - 'fillTimeout' | 'subscriberPriority' | 'locationFilter' | 'groupOrder' | 'rangeFilters' ->; - -type ParameterScope = 'message' | 'fill'; - -const FILL_SCOPE_TYPES: ReadonlySet = new Set([ - PARAMETER_TYPE.FILL_TIMEOUT, - PARAMETER_TYPE.SUBSCRIBER_PRIORITY, - PARAMETER_TYPE.LOCATION_FILTER, - PARAMETER_TYPE.GROUP_ORDER, - PARAMETER_TYPE.SUBGROUP_FILTER, - PARAMETER_TYPE.OBJECTID_FILTER, - PARAMETER_TYPE.PRIORITY_FILTER, - PARAMETER_TYPE.OBJECT_PROPERTY_FILTER, -]); - -const GROUP_ORDER_WIRE: Record = { ascending: 0x1, descending: 0x2 }; - -interface ParameterEntry { - type: number; - write(writer: ByteWriter): void; -} - -function collectParameterEntries(parameters: MessageParameters): ParameterEntry[] { - const entries: ParameterEntry[] = []; - const push = (type: number, write: (writer: ByteWriter) => void) => entries.push({ type, write }); - - if (parameters.objectDeliveryTimeout !== undefined) { - push(PARAMETER_TYPE.OBJECT_DELIVERY_TIMEOUT, (w) => w.writeVarint(parameters.objectDeliveryTimeout!)); - } - - if (parameters.subgroupDeliveryTimeout !== undefined) { - push(PARAMETER_TYPE.SUBGROUP_DELIVERY_TIMEOUT, (w) => w.writeVarint(parameters.subgroupDeliveryTimeout!)); - } - - if (parameters.rendezvousTimeout !== undefined) { - push(PARAMETER_TYPE.RENDEZVOUS_TIMEOUT, (w) => w.writeVarint(parameters.rendezvousTimeout!)); - } - - if (parameters.fillTimeout !== undefined) { - push(PARAMETER_TYPE.FILL_TIMEOUT, (w) => w.writeVarint(parameters.fillTimeout!)); - } - - for (const token of parameters.authorizationTokens ?? []) { - push(PARAMETER_TYPE.AUTHORIZATION_TOKEN, (w) => w.writeLengthPrefixed(token)); - } - - if (parameters.expires !== undefined) { - push(PARAMETER_TYPE.EXPIRES, (w) => w.writeVarint(parameters.expires!)); - } - - if (parameters.largestObject !== undefined) { - push(PARAMETER_TYPE.LARGEST_OBJECT, (w) => writeLocation(w, parameters.largestObject!)); - } - - if (parameters.forward !== undefined) { - push(PARAMETER_TYPE.FORWARD, (w) => w.writeUint8(parameters.forward!)); - } - - if (parameters.subscriberPriority !== undefined) { - push(PARAMETER_TYPE.SUBSCRIBER_PRIORITY, (w) => w.writeUint8(parameters.subscriberPriority!)); - } - - if (parameters.locationFilter !== undefined) { - push(PARAMETER_TYPE.LOCATION_FILTER, (w) => - w.writeLengthPrefixed(encodeLocationFilter(parameters.locationFilter!)) - ); - } - - if (parameters.groupOrder !== undefined) { - push(PARAMETER_TYPE.GROUP_ORDER, (w) => w.writeUint8(GROUP_ORDER_WIRE[parameters.groupOrder!])); - } - - if (parameters.fillParameters !== undefined) { - push(PARAMETER_TYPE.FILL_PARAMETERS, (w) => - w.writeLengthPrefixed(encodeFillParameters(parameters.fillParameters!)) - ); - } - - if (parameters.newGroupRequest !== undefined) { - push(PARAMETER_TYPE.NEW_GROUP_REQUEST, (w) => w.writeVarint(parameters.newGroupRequest!)); - } - - for (const filter of parameters.rangeFilters ?? []) { - push(filter.type, (w) => w.writeLengthPrefixed(filter.value)); - } - - if (parameters.trackNamespacePrefix !== undefined) { - push(PARAMETER_TYPE.TRACK_NAMESPACE_PREFIX, (w) => writeTrackNamespace(w, parameters.trackNamespacePrefix!)); - } - - if (parameters.includeProperties !== undefined) { - push(PARAMETER_TYPE.INCLUDE_PROPERTIES, (w) => w.writeUint8(parameters.includeProperties!)); - } - - return entries; -} - -/** - * Serialize as `Number of Parameters (vi64)` + delta-typed parameter list. The `'fill'` scope is the nested list inside - * FILL_PARAMETERS, where only Table 6's types are legal. - */ -export function encodeMessageParameters( - writer: ByteWriter, - parameters: MessageParameters = {}, - scope: ParameterScope = 'message' -): void { - const entries = collectParameterEntries(parameters).sort((a, b) => a.type - b.type); - - if (scope === 'fill') { - const disallowed = entries.find((entry) => !FILL_SCOPE_TYPES.has(entry.type)); - - if (disallowed) { - throw new MoqtProtocolError(`parameter type ${disallowed.type} is not allowed inside FILL_PARAMETERS`); - } - } - - writer.writeVarint(entries.length); - let previousType = 0; - - for (const entry of entries) { - writer.writeVarint(entry.type - previousType); - previousType = entry.type; - entry.write(writer); - } -} - -/** FILL_PARAMETERS' value: a parameter list encoded as if for a separate message (§10.2.15). */ -function encodeFillParameters(fill: FillParameters): Uint8Array { - const writer = new ByteWriter(64); - - encodeMessageParameters(writer, fill, 'fill'); - return writer.toBytes(); -} - -const RANGE_FILTER_TYPES: readonly number[] = [ - PARAMETER_TYPE.SUBGROUP_FILTER, - PARAMETER_TYPE.OBJECTID_FILTER, - PARAMETER_TYPE.PRIORITY_FILTER, - PARAMETER_TYPE.OBJECT_PROPERTY_FILTER, - PARAMETER_TYPE.TRACK_PROPERTY_FILTER, -]; - -export function decodeMessageParameters(reader: ByteReader, scope: ParameterScope = 'message'): MessageParameters { - const count = reader.readVarint(); - const parameters: MessageParameters = {}; - let previousType = 0; - - for (let i = 0; i < count; i++) { - const type = previousType + reader.readVarint(); - - previousType = type; - - // §10.2.15: a type outside Table 6 inside FILL_PARAMETERS is a - // PROTOCOL_VIOLATION, the nested scope included. - if (scope === 'fill' && !FILL_SCOPE_TYPES.has(type)) { - throw new MoqtProtocolError(`parameter type ${type} is not allowed inside FILL_PARAMETERS`); - } - - switch (type) { - case PARAMETER_TYPE.OBJECT_DELIVERY_TIMEOUT: - parameters.objectDeliveryTimeout = reader.readVarint(); - break; - case PARAMETER_TYPE.SUBGROUP_DELIVERY_TIMEOUT: - parameters.subgroupDeliveryTimeout = reader.readVarint(); - break; - case PARAMETER_TYPE.RENDEZVOUS_TIMEOUT: - parameters.rendezvousTimeout = reader.readVarint(); - break; - case PARAMETER_TYPE.FILL_TIMEOUT: - parameters.fillTimeout = reader.readVarint(); - break; - case PARAMETER_TYPE.AUTHORIZATION_TOKEN: { - const token = reader.readBytes(reader.readVarint()); - - (parameters.authorizationTokens ??= []).push(token); - break; - } - case PARAMETER_TYPE.EXPIRES: - parameters.expires = reader.readVarint(); - break; - case PARAMETER_TYPE.LARGEST_OBJECT: - parameters.largestObject = readLocation(reader); - break; - case PARAMETER_TYPE.FORWARD: { - const forward = reader.readUint8(); - if (forward !== 0 && forward !== 1) throw new MoqtProtocolError(`invalid FORWARD value ${forward}`); - - parameters.forward = forward; - break; - } - case PARAMETER_TYPE.SUBSCRIBER_PRIORITY: - parameters.subscriberPriority = reader.readUint8(); - break; - case PARAMETER_TYPE.LOCATION_FILTER: - parameters.locationFilter = decodeLocationFilter(reader.readBytes(reader.readVarint())); - break; - case PARAMETER_TYPE.GROUP_ORDER: { - const order = reader.readUint8(); - if (order !== 0x1 && order !== 0x2) throw new MoqtProtocolError(`invalid GROUP_ORDER value ${order}`); - - parameters.groupOrder = order === 0x1 ? 'ascending' : 'descending'; - break; - } - case PARAMETER_TYPE.FILL_PARAMETERS: { - const value = new ByteReader(reader.readBytes(reader.readVarint())); - - parameters.fillParameters = decodeMessageParameters(value, 'fill'); - - if (value.remaining !== 0) throw new MoqtProtocolError('FILL_PARAMETERS has trailing bytes'); - - break; - } - case PARAMETER_TYPE.NEW_GROUP_REQUEST: - parameters.newGroupRequest = reader.readVarint(); - break; - case PARAMETER_TYPE.TRACK_NAMESPACE_PREFIX: - parameters.trackNamespacePrefix = readTrackNamespace(reader); - break; - case PARAMETER_TYPE.INCLUDE_PROPERTIES: { - // moq-relay framed this length-prefixed by type parity until 0.17.0 - // (moq-dev/moq#4610), which reads the §10.2.21 uint8 bare. - const include = reader.readUint8(); - if (include !== 0 && include !== 1) throw new MoqtProtocolError(`invalid INCLUDE_PROPERTIES value ${include}`); - - parameters.includeProperties = include; - break; - } - default: { - if (RANGE_FILTER_TYPES.includes(type)) { - const value = reader.readBytes(reader.readVarint()); - - (parameters.rangeFilters ??= []).push({ type, value }); - break; - } - - // §10.2: unknown parameters cannot be skipped (the block is bounded - // by count, and the value encoding is per-type) — session error. - throw new MoqtProtocolError(`unknown message parameter type ${type}`); - } - } - } - - return parameters; -} - -// ============================================================================ -// Authorization tokens (§10.2.2) -// ============================================================================ - -/** - * Serialize a Token structure with Alias Type USE_VALUE (0x3) — the stateless form the engine uses to attach an - * MSF-provided token to a request without alias registration. - */ -export function encodeAuthTokenUseValue(tokenType: number, value: Uint8Array): Uint8Array { - const writer = new ByteWriter(value.length + 8); - - writer.writeVarint(0x3); - writer.writeVarint(tokenType); - writer.writeBytes(value); - return writer.toBytes(); -} - -// ============================================================================ -// Message framing -// ============================================================================ - -/** A decoded frame: message type + body bytes (not yet interpreted). */ -export interface ControlMessageFrame { - type: number; - body: Uint8Array; -} - -function frameMessage(type: number, body: ByteWriter): Uint8Array { - const bodyBytes = body.toBytes(); - - if (bodyBytes.length > MAX_CONTROL_MESSAGE_LENGTH) { - throw new MoqtProtocolError('control message exceeds 2^16-1 bytes'); - } - - const writer = new ByteWriter(bodyBytes.length + 8); - - writer.writeVarint(type); - writer.writeUint16(bodyBytes.length); - writer.writeBytes(bodyBytes); - return writer.toBytes(); -} - -/** - * Incremental control-message deframer. Feed it stream chunks; it yields complete `ControlMessageFrame`s as they - * materialize. Used for both the control streams and request streams (same framing). - */ -export class ControlMessageDeframer { - #buffer: Uint8Array = new Uint8Array(0); - - push(chunk: Uint8Array): ControlMessageFrame[] { - if (this.#buffer.length === 0) { - this.#buffer = chunk; - } else { - const merged = new Uint8Array(this.#buffer.length + chunk.length); - - merged.set(this.#buffer); - merged.set(chunk, this.#buffer.length); - this.#buffer = merged; - } - - const frames: ControlMessageFrame[] = []; - let offset = 0; - - while (true) { - const frame = this.#tryReadFrame(offset); - if (!frame) break; - - frames.push(frame.frame); - offset = frame.nextOffset; - } - - this.#buffer = offset > 0 ? this.#buffer.subarray(offset) : this.#buffer; - return frames; - } - - /** Bytes buffered but not yet forming a complete frame. */ - get pendingBytes(): number { - return this.#buffer.length; - } - - #tryReadFrame(offset: number): { frame: ControlMessageFrame; nextOffset: number } | null { - const buffer = this.#buffer; - if (offset >= buffer.length) return null; - - let type: number; - let headerLength: number; - - try { - const decoded = decodeVarint(buffer, offset); - - type = decoded.value; - headerLength = decoded.byteLength; - } catch (error) { - // Incomplete varint — wait for more bytes. - if (error instanceof RangeError) return null; - - throw error; - } - - if (offset + headerLength + 2 > buffer.length) return null; - - const length = buffer[offset + headerLength]! * 256 + buffer[offset + headerLength + 1]!; - const bodyStart = offset + headerLength + 2; - if (bodyStart + length > buffer.length) return null; - - return { - frame: { type, body: buffer.slice(bodyStart, bodyStart + length) }, - nextOffset: bodyStart + length, - }; - } -} - -// ============================================================================ -// Encoders (subscriber → publisher) -// ============================================================================ - -/** SETUP (§10.3) — first message on the endpoint's control stream. */ -export function encodeSetup(options: readonly KeyValuePair[] = []): Uint8Array { - const body = new ByteWriter(); - - encodeKeyValuePairs(body, options); - return frameMessage(MESSAGE_TYPE.SETUP, body); -} - -export interface SubscribeRequest { - requestId: number; - trackNamespace: TrackNamespace; - trackName: string; - parameters?: MessageParameters; -} - -/** - * FETCH (§10.13) has the SUBSCRIBE body: the range is `parameters.locationFilter`, evaluated with the fetch rules of - * §5.1.2 — relative starts count back from Largest Object, an omitted end stops there, and no filter means the whole - * track. Nothing selects "standalone" or "joining" any more; a join is a subscription with FILL_PARAMETERS. - */ -export type FetchRequest = SubscribeRequest; - -/** SUBSCRIBE, TRACK_STATUS, and FETCH share one body: Request ID, Full Track Name, Parameters. */ -function encodeTrackRequest(type: number, request: SubscribeRequest): Uint8Array { - const body = new ByteWriter(); - - body.writeVarint(request.requestId); - writeTrackNamespace(body, request.trackNamespace); - body.writeLengthPrefixed(utf8Encode(request.trackName)); - encodeMessageParameters(body, request.parameters); - return frameMessage(type, body); -} - -/** SUBSCRIBE (§10.7) — first message on a new request stream. */ -export function encodeSubscribe(request: SubscribeRequest): Uint8Array { - return encodeTrackRequest(MESSAGE_TYPE.SUBSCRIBE, request); -} - -/** TRACK_STATUS (§10.15) — identical wire format to SUBSCRIBE. */ -export function encodeTrackStatus(request: SubscribeRequest): Uint8Array { - return encodeTrackRequest(MESSAGE_TYPE.TRACK_STATUS, request); -} - -/** FETCH (§10.13) — first message on a new request stream. */ -export function encodeFetch(request: FetchRequest): Uint8Array { - return encodeTrackRequest(MESSAGE_TYPE.FETCH, request); -} - -export interface SubscribeNamespaceRequest { - requestId: number; - trackNamespacePrefix: TrackNamespace; - parameters?: MessageParameters; -} - -/** SUBSCRIBE_NAMESPACE (§10.19) — first message on a new request stream. */ -export function encodeSubscribeNamespace(request: SubscribeNamespaceRequest): Uint8Array { - const body = new ByteWriter(); - - body.writeVarint(request.requestId); - writeTrackNamespace(body, request.trackNamespacePrefix); - encodeMessageParameters(body, request.parameters); - return frameMessage(MESSAGE_TYPE.SUBSCRIBE_NAMESPACE, body); -} - -/** - * REQUEST_UPDATE (§10.9) — sent on an existing request stream. `requestId` is the update's own, freshly allocated - * Request ID (§10.1 counts REQUEST_UPDATE among the messages that consume one); the stream identifies the request being - * updated. - */ -export function encodeRequestUpdate(requestId: number, parameters: MessageParameters = {}): Uint8Array { - const body = new ByteWriter(); - - body.writeVarint(requestId); - encodeMessageParameters(body, parameters); - return frameMessage(MESSAGE_TYPE.REQUEST_UPDATE, body); -} - -/** - * GOAWAY (§10.4). Clients MUST send a zero-length New Session URI, so the encoder takes only the timeout (milliseconds; - * 0 = no specific timeout). - */ -export function encodeGoaway(timeout = 0): Uint8Array { - const body = new ByteWriter(); - - body.writeVarint(0); - body.writeVarint(timeout); - return frameMessage(MESSAGE_TYPE.GOAWAY, body); -} - -/** - * REQUEST_OK (§10.5). The subscriber sends this to accept an incoming PUBLISH (PUBLISH_OK). Track Properties are always - * empty in that role, and since draft-20 so are the parameters — a subscriber changes subscription parameters with - * REQUEST_UPDATE, not in PUBLISH_OK (§10.11); the session driver's `accept()` therefore takes none. The parameter slot - * stays for the publisher-side roles of REQUEST_OK (TRACK_STATUS_OK, REQUEST_UPDATE_OK), which the fake peer in tests - * exercises. - */ -export function encodeRequestOk(parameters: MessageParameters = {}): Uint8Array { - const body = new ByteWriter(); - - encodeMessageParameters(body, parameters); - return frameMessage(MESSAGE_TYPE.REQUEST_OK, body); -} - -/** REQUEST_ERROR (§10.6) without a Redirect — enough to reject incoming requests. */ -export function encodeRequestError(errorCode: number, reason = '', retryInterval = 0): Uint8Array { - const body = new ByteWriter(); - - body.writeVarint(errorCode); - body.writeVarint(retryInterval); - writeReasonPhrase(body, reason); - return frameMessage(MESSAGE_TYPE.REQUEST_ERROR, body); -} - -// ============================================================================ -// Encoders (publisher → subscriber) -// -// The engine is subscribe-only, but the codec is symmetric: these are used -// by the in-memory fake peer in tests (the same seam a future publish -// path would build on). -// ============================================================================ - -/** SUBSCRIBE_OK (§10.8). */ -export function encodeSubscribeOk( - trackAlias: number, - parameters: MessageParameters = {}, - trackProperties: readonly KeyValuePair[] = [] -): Uint8Array { - const body = new ByteWriter(); - - body.writeVarint(trackAlias); - encodeMessageParameters(body, parameters); - encodeKeyValuePairs(body, trackProperties); - return frameMessage(MESSAGE_TYPE.SUBSCRIBE_OK, body); -} - -/** 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); - - if (streamCount === undefined) body.writeBytes(UNKNOWN_STREAM_COUNT); - else body.writeVarint(streamCount); - - writeReasonPhrase(body, reason); - return frameMessage(MESSAGE_TYPE.PUBLISH_DONE, body); -} - -/** PUBLISH_STATE_NOTIFY (§10.10) — the publisher's unilateral "these subscription parameters changed". */ -export function encodePublishStateNotify(parameters: MessageParameters = {}): Uint8Array { - const body = new ByteWriter(); - - encodeMessageParameters(body, parameters); - return frameMessage(MESSAGE_TYPE.PUBLISH_STATE_NOTIFY, body); -} - -/** FETCH_OK (§10.14). */ -export function encodeFetchOk( - endOfTrack: boolean, - endLocation: Location, - parameters: MessageParameters = {}, - trackProperties: readonly KeyValuePair[] = [] -): Uint8Array { - const body = new ByteWriter(); - - body.writeUint8(endOfTrack ? 1 : 0); - writeLocation(body, endLocation); - encodeMessageParameters(body, parameters); - encodeKeyValuePairs(body, trackProperties); - return frameMessage(MESSAGE_TYPE.FETCH_OK, body); -} - -/** PUBLISH (§10.11). */ -export function encodePublish( - request: SubscribeRequest & { trackAlias: number }, - trackProperties: readonly KeyValuePair[] = [] -): Uint8Array { - const body = new ByteWriter(); - - body.writeVarint(request.requestId); - writeTrackNamespace(body, request.trackNamespace); - body.writeLengthPrefixed(utf8Encode(request.trackName)); - body.writeVarint(request.trackAlias); - encodeMessageParameters(body, request.parameters); - encodeKeyValuePairs(body, trackProperties); - return frameMessage(MESSAGE_TYPE.PUBLISH, body); -} - -export interface PublishNamespaceRequest { - requestId: number; - trackNamespace: TrackNamespace; - parameters?: MessageParameters; -} - -/** PUBLISH_NAMESPACE (§10.16) — a publisher announcing a namespace. */ -export function encodePublishNamespace(request: PublishNamespaceRequest): Uint8Array { - const body = new ByteWriter(); - - body.writeVarint(request.requestId); - writeTrackNamespace(body, request.trackNamespace); - encodeMessageParameters(body, request.parameters); - return frameMessage(MESSAGE_TYPE.PUBLISH_NAMESPACE, body); -} - -/** - * NAMESPACE (§10.19) — announce one namespace on an accepted inbound SUBSCRIBE_NAMESPACE request stream. The body is - * the namespace suffix relative to that stream's subscribed prefix and nothing else: peers bound-check the tuple - * against the frame length (moq-lite-rs treats even a zero parameter count as a malformed entry and kills the announce - * stream), so no parameter block is written. - */ -export function encodeNamespace(trackNamespaceSuffix: TrackNamespace): Uint8Array { - const body = new ByteWriter(); - - writeTrackNamespace(body, trackNamespaceSuffix); - return frameMessage(MESSAGE_TYPE.NAMESPACE, body); -} - -/** NAMESPACE_DONE (§10.20) — retract a NAMESPACE announcement (same body shape). */ -export function encodeNamespaceDone(trackNamespaceSuffix: TrackNamespace): Uint8Array { - const body = new ByteWriter(); - - writeTrackNamespace(body, trackNamespaceSuffix); - return frameMessage(MESSAGE_TYPE.NAMESPACE_DONE, body); -} - -// ============================================================================ -// Decoders (publisher → subscriber) -// ============================================================================ - -export interface Redirect { - connectUri: string; - trackNamespace: TrackNamespace; - trackName: string; -} - -export type ControlMessage = - | { kind: 'setup'; options: KeyValuePair[] } - | { kind: 'goaway'; newSessionUri: string; timeout: number } - | { - kind: 'subscribe'; - requestId: number; - trackNamespace: TrackNamespace; - trackName: string; - parameters: MessageParameters; - } - | { - kind: 'track-status'; - requestId: number; - trackNamespace: TrackNamespace; - trackName: string; - parameters: MessageParameters; - } - | { kind: 'fetch'; request: FetchRequest & { parameters: MessageParameters } } - | { - kind: 'subscribe-namespace'; - requestId: number; - trackNamespacePrefix: TrackNamespace; - parameters: MessageParameters; - } - | { kind: 'subscribe-ok'; trackAlias: number; parameters: MessageParameters; trackProperties: KeyValuePair[] } - | { kind: 'request-ok'; parameters: MessageParameters; trackProperties: KeyValuePair[] } - | { kind: 'request-error'; errorCode: number; retryInterval: number; reason: string; redirect?: Redirect } - | { kind: 'request-update'; requestId: number; parameters: MessageParameters } - | { kind: 'publish-state-notify'; parameters: MessageParameters } - | { - kind: 'publish-done'; - statusCode: number; - /** `undefined` when the publisher could not count its streams (the 2^64−1 sentinel, §10.12). */ - streamCount: number | undefined; - reason: string; - } - | { - kind: 'publish'; - requestId: number; - trackNamespace: TrackNamespace; - trackName: string; - trackAlias: number; - parameters: MessageParameters; - trackProperties: KeyValuePair[]; - } - | { kind: 'publish-namespace'; requestId: number; trackNamespace: TrackNamespace; parameters: MessageParameters } - | { - kind: 'fetch-ok'; - endOfTrack: boolean; - endLocation: Location; - parameters: MessageParameters; - trackProperties: KeyValuePair[]; - } - | { kind: 'namespace'; trackNamespaceSuffix: TrackNamespace } - | { kind: 'namespace-done'; trackNamespaceSuffix: TrackNamespace } - | { kind: 'publish-skipped'; trackNamespaceSuffix: TrackNamespace; trackName: string }; - -function readRedirect(reader: ByteReader): Redirect { - const uriLength = reader.readVarint(); - const connectUri = utf8Decode(reader.readBytes(uriLength)); - const trackNamespace = readTrackNamespace(reader); - const nameLength = reader.readVarint(); - const trackName = utf8Decode(reader.readBytes(nameLength)); - - return { connectUri, trackNamespace, trackName }; -} - -/** - * Decode one control-message frame into a typed message. Throws `MoqtProtocolError` for unknown message types (§10: "An - * endpoint that receives an unknown message type MUST close the session") and for malformed bodies. - */ -export function decodeControlMessage(frame: ControlMessageFrame): ControlMessage { - const reader = new ByteReader(frame.body); - const end = frame.body.length; - let message: ControlMessage; - - try { - message = decodeControlMessageBody(frame.type, reader, end); - } catch (error) { - // Field reads past the declared frame length surface as `RangeError` - // from `ByteReader`. Normalize them: the session's stream loops treat - // only `MoqtProtocolError` as fatal, and a truncated body must - // terminate the session (§10) rather than vanish as a read error. - if (error instanceof RangeError) { - throw new MoqtProtocolError(`control message 0x${frame.type.toString(16)} body is truncated`); - } - - throw error; - } - - if (reader.offset !== end) { - throw new MoqtProtocolError(`control message 0x${frame.type.toString(16)} body length mismatch`); - } - - return message; -} - -function decodeControlMessageBody(type: number, reader: ByteReader, end: number): ControlMessage { - switch (type) { - case MESSAGE_TYPE.SETUP: - return { kind: 'setup', options: decodeKeyValuePairs(reader, end) }; - case MESSAGE_TYPE.GOAWAY: { - const uriLength = reader.readVarint(); - - if (uriLength > MAX_NEW_SESSION_URI_LENGTH) { - throw new MoqtProtocolError('GOAWAY new session URI exceeds 8192 bytes'); - } - - const newSessionUri = utf8Decode(reader.readBytes(uriLength)); - - return { kind: 'goaway', newSessionUri, timeout: reader.readVarint() }; - } - case MESSAGE_TYPE.SUBSCRIBE_OK: { - const trackAlias = reader.readVarint(); - const parameters = decodeMessageParameters(reader); - - return { kind: 'subscribe-ok', trackAlias, parameters, trackProperties: decodeKeyValuePairs(reader, end) }; - } - case MESSAGE_TYPE.REQUEST_OK: { - const parameters = decodeMessageParameters(reader); - - return { kind: 'request-ok', parameters, trackProperties: decodeKeyValuePairs(reader, end) }; - } - case MESSAGE_TYPE.REQUEST_ERROR: { - const errorCode = reader.readVarint(); - const retryInterval = reader.readVarint(); - const reason = readReasonPhrase(reader); - - if (errorCode === REQUEST_ERROR_CODE.REDIRECT) { - return { kind: 'request-error', errorCode, retryInterval, reason, redirect: readRedirect(reader) }; - } - - return { kind: 'request-error', errorCode, retryInterval, reason }; - } - case MESSAGE_TYPE.REQUEST_UPDATE: { - const requestId = reader.readVarint(); - - return { kind: 'request-update', requestId, parameters: decodeMessageParameters(reader) }; - } - case MESSAGE_TYPE.PUBLISH_STATE_NOTIFY: - return { kind: 'publish-state-notify', parameters: decodeMessageParameters(reader) }; - case MESSAGE_TYPE.PUBLISH_DONE: { - const statusCode = reader.readVarint(); - // A publisher that cannot count its streams MUST send 2^64−1 (§10.12), - // which is above this codec's varint ceiling — read that one value as - // "unknown" rather than failing the session over a legitimate - // PUBLISH_DONE. Any other count past the ceiling stays a protocol error. - const streamCount = reader.readCountVarint(); - - return { kind: 'publish-done', statusCode, streamCount, reason: readReasonPhrase(reader) }; - } - case MESSAGE_TYPE.PUBLISH: { - const requestId = reader.readVarint(); - const trackNamespace = readTrackNamespace(reader); - const trackName = utf8Decode(reader.readBytes(reader.readVarint())); - const trackAlias = reader.readVarint(); - const parameters = decodeMessageParameters(reader); - - return { - kind: 'publish', - requestId, - trackNamespace, - trackName, - trackAlias, - parameters, - trackProperties: decodeKeyValuePairs(reader, end), - }; - } - case MESSAGE_TYPE.PUBLISH_NAMESPACE: { - const requestId = reader.readVarint(); - const trackNamespace = readTrackNamespace(reader); - - return { kind: 'publish-namespace', requestId, trackNamespace, parameters: decodeMessageParameters(reader) }; - } - case MESSAGE_TYPE.FETCH_OK: { - const endOfTrackWire = reader.readUint8(); - if (endOfTrackWire > 1) throw new MoqtProtocolError(`invalid FETCH_OK end-of-track value ${endOfTrackWire}`); - - const endOfTrack = endOfTrackWire === 1; - const endLocation = readLocation(reader); - const parameters = decodeMessageParameters(reader); - - return { - kind: 'fetch-ok', - endOfTrack, - endLocation, - parameters, - trackProperties: decodeKeyValuePairs(reader, end), - }; - } - case MESSAGE_TYPE.SUBSCRIBE: - case MESSAGE_TYPE.TRACK_STATUS: - case MESSAGE_TYPE.FETCH: { - const requestId = reader.readVarint(); - const trackNamespace = readTrackNamespace(reader); - const trackName = utf8Decode(reader.readBytes(reader.readVarint())); - const parameters = decodeMessageParameters(reader); - - if (type === MESSAGE_TYPE.FETCH) { - return { kind: 'fetch', request: { requestId, trackNamespace, trackName, parameters } }; - } - - const kind = type === MESSAGE_TYPE.SUBSCRIBE ? 'subscribe' : 'track-status'; - - return { kind, requestId, trackNamespace, trackName, parameters }; - } - case MESSAGE_TYPE.SUBSCRIBE_NAMESPACE: { - const requestId = reader.readVarint(); - const trackNamespacePrefix = readTrackNamespace(reader); - - return { - kind: 'subscribe-namespace', - requestId, - trackNamespacePrefix, - parameters: decodeMessageParameters(reader), - }; - } - case MESSAGE_TYPE.NAMESPACE: - return { kind: 'namespace', trackNamespaceSuffix: readTrackNamespace(reader) }; - case MESSAGE_TYPE.NAMESPACE_DONE: - return { kind: 'namespace-done', trackNamespaceSuffix: readTrackNamespace(reader) }; - case MESSAGE_TYPE.PUBLISH_SKIPPED: { - const trackNamespaceSuffix = readTrackNamespace(reader); - const trackName = utf8Decode(reader.readBytes(reader.readVarint())); - - return { kind: 'publish-skipped', trackNamespaceSuffix, trackName }; - } - default: - throw new MoqtProtocolError(`unknown control message type 0x${type.toString(16)}`); - } -} diff --git a/packages/spf/src/network/moqt/errors.ts b/packages/spf/src/network/moqt/errors.ts deleted file mode 100644 index ee16c972aa..0000000000 --- a/packages/spf/src/network/moqt/errors.ts +++ /dev/null @@ -1,49 +0,0 @@ -/** - * MOQT session-termination error codes (moq-transport draft-20 §3.5). Used as the close code when terminating the - * transport session and as the `code` carried by `MoqtProtocolError`. - */ -export const SESSION_ERROR = { - NO_ERROR: 0x0, - INTERNAL_ERROR: 0x1, - UNAUTHORIZED: 0x2, - PROTOCOL_VIOLATION: 0x3, - INVALID_REQUEST_ID: 0x4, - DUPLICATE_TRACK_ALIAS: 0x5, - KEY_VALUE_FORMATTING_ERROR: 0x6, - INVALID_PATH: 0x8, - MALFORMED_PATH: 0x9, - GOAWAY_TIMEOUT: 0x10, - CONTROL_MESSAGE_TIMEOUT: 0x11, - DATA_STREAM_TIMEOUT: 0x12, - AUTH_TOKEN_CACHE_OVERFLOW: 0x13, - DUPLICATE_AUTH_TOKEN_ALIAS: 0x14, - MALFORMED_AUTH_TOKEN: 0x16, - UNKNOWN_AUTH_TOKEN_ALIAS: 0x17, - EXPIRED_AUTH_TOKEN: 0x18, - INVALID_AUTHORITY: 0x19, - MALFORMED_AUTHORITY: 0x1a, - TOO_MANY_REQUEST_UPDATES: 0x1b, -} as const; - -export type SessionErrorCode = (typeof SESSION_ERROR)[keyof typeof SESSION_ERROR]; - -const MOQT_PROTOCOL_ERROR_SYMBOL = Symbol.for('@videojs/spf/moqt-protocol-error'); - -/** - * A wire-protocol violation detected while encoding or decoding MOQT data. `code` is the session-termination code - * (§3.5) the session driver should close the transport with — defaults to `PROTOCOL_VIOLATION`. - */ -export class MoqtProtocolError extends Error { - [MOQT_PROTOCOL_ERROR_SYMBOL] = true as const; - readonly code: SessionErrorCode; - - constructor(message: string, code: SessionErrorCode = SESSION_ERROR.PROTOCOL_VIOLATION) { - super(message); - this.name = 'MoqtProtocolError'; - this.code = code; - } -} - -export function isMoqtProtocolError(value: unknown): value is MoqtProtocolError { - return typeof value === 'object' && value !== null && MOQT_PROTOCOL_ERROR_SYMBOL in value; -} diff --git a/packages/spf/src/network/moqt/object-stream.ts b/packages/spf/src/network/moqt/object-stream.ts deleted file mode 100644 index f518168aec..0000000000 --- a/packages/spf/src/network/moqt/object-stream.ts +++ /dev/null @@ -1,372 +0,0 @@ -/** - * MOQT unidirectional data-stream parsing (moq-transport draft-20 §3.4, §11). - * - * Every unidirectional stream begins with a varint stream type: - * - * - `SUBGROUP_HEADER` (a Type Flags bitfield with bit 4 set, §11.4.2) — objects for one subgroup of one group of a - * subscribed track, identified by Track Alias. - * - `FETCH_HEADER` (0x05) — objects for a FETCH response, identified by Request ID. A fill fetch stream (§5.1.3) has the - * same shape and names the SUBSCRIBE or REQUEST_UPDATE that asked for it. - * - `SETUP` (0x2F00) — the peer's control stream (handled by the session). - * - `PADDING` (0x132B3E28) — bandwidth probing; drained and ignored. - * - * The parsers are async generators over a `StreamReader`, mirroring how `ChunkedStreamIterable` adapts fetch bodies - * elsewhere in `network/`. - */ -import { ByteReader, ByteWriter, type StreamReader } from './bytes'; -import { decodeKeyValuePairs, type KeyValuePair } from './control-messages'; -import { MoqtProtocolError } from './errors'; -import { MAX_VARINT_VALUE } from './varint'; - -// ============================================================================ -// Stream types -// ============================================================================ - -export const STREAM_TYPE = { - FETCH_HEADER: 0x05, - SETUP: 0x2f00, - PADDING: 0x132b3e28, -} as const; - -/** - * Whether a stream-type varint is a SUBGROUP_HEADER. §11.4.2 describes the type as Type Flags: bit 4 is always set, - * SUBGROUP_ID_MODE 0b11 is reserved, and a value of 128 or more — or any set bit without a specified meaning — is a - * PROTOCOL_VIOLATION. Every bit below 0x80 is assigned, so "bit 7 clear" is that last rule in full. - */ -export function isSubgroupHeaderType(type: number): boolean { - if (type > 0x7f || (type & 0x10) === 0) return false; - - return (type & 0x06) >> 1 !== 0b11; -} - -// ============================================================================ -// Object model -// ============================================================================ - -/** - * Ceiling on a single object's payload, and on its Properties block. - * - * Unlike control messages — bounded by their 16-bit frame length — a data stream's payload length is an unbounded - * varint that feeds straight into `StreamReader.readBytes`, which buffers until satisfied. A malformed or hostile relay - * declaring 2^53 would exhaust memory before the read ever completed, so the declaration is rejected before any - * allocation. - * - * 16 MiB clears any real LOC frame (a 4K keyframe is low single-digit MB). The Properties block is Key-Value-Pairs - * whose individual byte values may legally reach 2^16-1 (`MAX_KVP_VALUE_LENGTH`), so its bound leaves room for several - * maximum-size values, not just typical frame metadata. - */ -export const MAX_OBJECT_PAYLOAD_LENGTH = 16 * 1024 * 1024; -export const MAX_OBJECT_PROPERTIES_LENGTH = 1024 * 1024; - -function checkPayloadLength(length: number): number { - if (length > MAX_OBJECT_PAYLOAD_LENGTH) { - throw new MoqtProtocolError(`object payload length ${length} exceeds ${MAX_OBJECT_PAYLOAD_LENGTH} bytes`); - } - - return length; -} - -export type ObjectStatus = 'normal' | 'end-of-group' | 'end-of-track'; - -const OBJECT_STATUS_WIRE: Record = { - 0: 'normal', - 3: 'end-of-group', - 4: 'end-of-track', -}; - -/** An object delivered on a subscription's subgroup stream. */ -export interface MoqtObject { - groupId: number; - objectId: number; - subgroupId: number; - /** Publisher priority; `undefined` inherits the subscription's priority. */ - priority?: number; - status: ObjectStatus; - properties: KeyValuePair[]; - payload: Uint8Array; -} - -// ============================================================================ -// Subgroup streams (§11.4.2) -// ============================================================================ - -const SUBGROUP_FLAG = { - PROPERTIES: 0x01, - SUBGROUP_ID_MODE_MASK: 0x06, - END_OF_GROUP: 0x08, - DEFAULT_PRIORITY: 0x20, - FIRST_OBJECT: 0x40, -} as const; - -export type SubgroupIdMode = 'zero' | 'first-object-id' | 'explicit'; - -export interface SubgroupHeader { - type: number; - trackAlias: number; - groupId: number; - subgroupIdMode: SubgroupIdMode; - /** Present when `subgroupIdMode` is `'explicit'`. */ - subgroupId?: number; - /** Present when the header carries an explicit priority. */ - priority?: number; - /** All objects in this subgroup carry a Properties field. */ - hasProperties: boolean; - /** This subgroup contains the largest object in the group (on FIN). */ - endOfGroup: boolean; - /** The first object on this stream is the subgroup's first published object. */ - firstObject: boolean; -} - -/** Read the SUBGROUP_HEADER fields (the stream-type varint must already be consumed). */ -export async function readSubgroupHeader(reader: StreamReader, type: number): Promise { - if (!isSubgroupHeaderType(type)) { - throw new MoqtProtocolError(`invalid subgroup header type 0x${type.toString(16)}`); - } - - const modeBits = (type & SUBGROUP_FLAG.SUBGROUP_ID_MODE_MASK) >> 1; - const subgroupIdMode: SubgroupIdMode = - modeBits === 0b00 ? 'zero' : modeBits === 0b01 ? 'first-object-id' : 'explicit'; - - const trackAlias = await reader.readVarint(); - const groupId = await reader.readVarint(); - const subgroupId = subgroupIdMode === 'explicit' ? await reader.readVarint() : undefined; - const priority = (type & SUBGROUP_FLAG.DEFAULT_PRIORITY) === 0 ? await reader.readUint8() : undefined; - - return { - type, - trackAlias, - groupId, - subgroupIdMode, - subgroupId, - priority, - hasProperties: (type & SUBGROUP_FLAG.PROPERTIES) !== 0, - endOfGroup: (type & SUBGROUP_FLAG.END_OF_GROUP) !== 0, - firstObject: (type & SUBGROUP_FLAG.FIRST_OBJECT) !== 0, - }; -} - -/** Object Properties structure (§11.2.1.2): varint length + Key-Value-Pairs. */ -async function readObjectProperties(reader: StreamReader): Promise { - const length = await reader.readVarint(); - if (length === 0) return []; - - if (length > MAX_OBJECT_PROPERTIES_LENGTH) { - throw new MoqtProtocolError(`object properties length ${length} exceeds ${MAX_OBJECT_PROPERTIES_LENGTH} bytes`); - } - - const bytes = await reader.readBytes(length); - - return decodeKeyValuePairs(new ByteReader(bytes), length); -} - -function readObjectStatus(statusWire: number): ObjectStatus { - const status = OBJECT_STATUS_WIRE[statusWire]; - if (status === undefined) throw new MoqtProtocolError(`unknown object status ${statusWire}`); - - return status; -} - -/** - * Yield the objects of one subgroup stream until FIN. Object IDs are delta-decoded (`delta + 1` from the previous - * object; absolute for the first). The stream's `subgroupId` resolves per the header's mode — for `'first-object-id'` - * it is the first object's ID. - */ -export async function* readSubgroupObjects(reader: StreamReader, header: SubgroupHeader): AsyncGenerator { - let previousObjectId: number | undefined; - let subgroupId = header.subgroupIdMode === 'explicit' ? header.subgroupId! : 0; - - while (!(await reader.atEnd())) { - const objectIdDelta = await reader.readVarint(); - - const objectId = previousObjectId === undefined ? objectIdDelta : previousObjectId + objectIdDelta + 1; - // Each operand fits the varint range, but the delta sum can round past - // 2^53-1 and silently collide subsequent IDs — the exact corruption the - // varint layer rejects loudly. - if (objectId > MAX_VARINT_VALUE) throw new MoqtProtocolError('subgroup object ID exceeds supported range'); - - if (previousObjectId === undefined && header.subgroupIdMode === 'first-object-id') { - subgroupId = objectId; - } - - previousObjectId = objectId; - - const properties = header.hasProperties ? await readObjectProperties(reader) : []; - const payloadLength = checkPayloadLength(await reader.readVarint()); - const status = payloadLength === 0 ? readObjectStatus(await reader.readVarint()) : 'normal'; - const payload = payloadLength > 0 ? await reader.readBytes(payloadLength) : new Uint8Array(0); - - yield { - groupId: header.groupId, - objectId, - subgroupId, - priority: header.priority, - status, - properties, - payload, - }; - } -} - -// ============================================================================ -// Fetch streams (§11.4.4) -// ============================================================================ - -const FETCH_FLAG = { - SUBGROUP_MODE_MASK: 0x03, - OBJECT_ID_DELTA_PRESENT: 0x04, - GROUP_ID_DELTA_PRESENT: 0x08, - PRIORITY_PRESENT: 0x10, - PROPERTIES_PRESENT: 0x20, - DATAGRAM: 0x40, -} as const; - -/** End of Range serialization flags (§11.4.4, Table 7). */ -const FETCH_END_OF_RANGE_STATUS: Record = { - 0x8c: 'non-existent', - 0x10c: 'unknown', - 0x20c: 'timed-out', -}; - -/** - * Why a run of Locations was not serialized: they do not exist, their status is unknown to the relay, or the relay's - * Fill Timeout expired before upstream supplied them (§10.2.5). - */ -export type FetchEndOfRangeStatus = 'non-existent' | 'unknown' | 'timed-out'; - -export type FetchStreamEntry = - | { - kind: 'object'; - groupId: number; - objectId: number; - /** Absent for objects with Forwarding Preference = Datagram. */ - subgroupId?: number; - priority: number; - properties: KeyValuePair[]; - payload: Uint8Array; - } - | { - kind: 'end-of-range'; - status: FetchEndOfRangeStatus; - groupId: number; - objectId: number; - }; - -/** Read the FETCH_HEADER's Request ID (the stream-type varint must already be consumed). */ -export async function readFetchHeader(reader: StreamReader): Promise<{ requestId: number }> { - return { requestId: await reader.readVarint() }; -} - -/** - * Write a FETCH_HEADER (§11.4.4) — the stream-type varint plus the Request ID. A fill fetch stream (§5.1.3) opens with - * this frame carrying the initiating SUBSCRIBE / REQUEST_UPDATE Request ID. - */ -export function encodeFetchHeader(requestId: number): Uint8Array { - const writer = new ByteWriter(16); - - writer.writeVarint(STREAM_TYPE.FETCH_HEADER); - writer.writeVarint(requestId); - return writer.toBytes(); -} - -/** - * Yield the entries of one FETCH response stream until FIN. Group/object IDs are delta-decoded against the prior entry - * per §11.4.4.1; the first object must carry both deltas (as absolute values). - */ -export async function* readFetchEntries( - reader: StreamReader, - groupOrder: 'ascending' | 'descending' = 'ascending' -): AsyncGenerator { - let prior: { groupId: number; objectId: number; subgroupId?: number; priority?: number } | undefined; - - while (!(await reader.atEnd())) { - const flags = await reader.readVarint(); - const endOfRange = FETCH_END_OF_RANGE_STATUS[flags]; - - if (endOfRange !== undefined) { - const groupId = await reader.readVarint(); - const objectId = await reader.readVarint(); - - // The indicator becomes the prior Location; subgroup/priority carry - // over from the last actual object (§11.4.4.2). - prior = { groupId, objectId, subgroupId: prior?.subgroupId, priority: prior?.priority }; - yield { kind: 'end-of-range', status: endOfRange, groupId, objectId }; - continue; - } - - if (flags > 0x7f) { - throw new MoqtProtocolError(`invalid fetch serialization flags 0x${flags.toString(16)}`); - } - - const groupIdDeltaPresent = (flags & FETCH_FLAG.GROUP_ID_DELTA_PRESENT) !== 0; - const objectIdDeltaPresent = (flags & FETCH_FLAG.OBJECT_ID_DELTA_PRESENT) !== 0; - - if (prior === undefined && (!groupIdDeltaPresent || !objectIdDeltaPresent)) { - throw new MoqtProtocolError('first fetch object must carry group and object IDs'); - } - - const groupIdDelta = groupIdDeltaPresent ? await reader.readVarint() : undefined; - - // Subgroup encoding: 2 LSBs, ignored when the DATAGRAM bit is set. - const isDatagram = (flags & FETCH_FLAG.DATAGRAM) !== 0; - const subgroupMode = isDatagram ? -1 : flags & FETCH_FLAG.SUBGROUP_MODE_MASK; - let subgroupId: number | undefined; - - if (subgroupMode === 0x03) { - subgroupId = await reader.readVarint(); - } else if (subgroupMode === 0x00) { - subgroupId = 0; - } else if (subgroupMode === 0x01 || subgroupMode === 0x02) { - if (prior?.subgroupId === undefined) { - throw new MoqtProtocolError('fetch object references prior subgroup ID with no prior object'); - } - - subgroupId = subgroupMode === 0x01 ? prior.subgroupId : prior.subgroupId + 1; - } - - const objectIdDelta = objectIdDeltaPresent ? await reader.readVarint() : undefined; - - const groupId = - groupIdDelta === undefined - ? prior!.groupId - : prior === undefined - ? groupIdDelta - : groupOrder === 'ascending' - ? prior.groupId + groupIdDelta + 1 - : prior.groupId - (groupIdDelta + 1); - if (groupId < 0) throw new MoqtProtocolError('fetch group ID underflow'); - - const objectId = - prior === undefined - ? objectIdDelta! - : groupIdDelta !== undefined - ? (objectIdDelta ?? prior.objectId + 1) - : objectIdDelta !== undefined - ? prior.objectId + objectIdDelta - : prior.objectId + 1; - - // Mirror of the underflow check above: delta sums can round past 2^53-1 - // and silently collapse later locations. - if (groupId > MAX_VARINT_VALUE || objectId > MAX_VARINT_VALUE) { - throw new MoqtProtocolError('fetch location exceeds supported range'); - } - - let priority: number; - - if ((flags & FETCH_FLAG.PRIORITY_PRESENT) !== 0) { - priority = await reader.readUint8(); - } else { - if (prior?.priority === undefined) { - throw new MoqtProtocolError('fetch object references prior priority with no prior object'); - } - - priority = prior.priority; - } - - const properties = (flags & FETCH_FLAG.PROPERTIES_PRESENT) !== 0 ? await readObjectProperties(reader) : []; - const payloadLength = checkPayloadLength(await reader.readVarint()); - const payload = payloadLength > 0 ? await reader.readBytes(payloadLength) : new Uint8Array(0); - - prior = { groupId, objectId, subgroupId: subgroupId ?? prior?.subgroupId, priority }; - yield { kind: 'object', groupId, objectId, subgroupId, priority, properties, payload }; - } -} diff --git a/packages/spf/src/network/moqt/request-stream.ts b/packages/spf/src/network/moqt/request-stream.ts deleted file mode 100644 index 38c20e3637..0000000000 --- a/packages/spf/src/network/moqt/request-stream.ts +++ /dev/null @@ -1,133 +0,0 @@ -/** - * Per-request bidirectional-stream lifecycle (moq-transport draft-20 §3.3). - * - * The control model is request-stream based: each request (SUBSCRIBE, FETCH, TRACK_STATUS, …) opens its own - * bidirectional stream, the first message on it is the request, and responses (SUBSCRIBE_OK / REQUEST_OK / - * REQUEST_ERROR / PUBLISH_DONE / GOAWAY) arrive as control messages on the same stream. There is no UNSUBSCRIBE message - * — cancellation IS the stream lifecycle: abort our sending direction (RESET_STREAM) and cancel the receiving direction - * (STOP_SENDING), per §3.3.3. - * - * Callback-shaped, no signals — the session driver binds this to its own bookkeeping; SPF actors bind signals at the - * `playback/` layer. - */ -import { type ControlMessage, ControlMessageDeframer, decodeControlMessage } from './control-messages'; -import { MoqtProtocolError } from './errors'; - -/** Structural subset of `WebTransportBidirectionalStream`. */ -export interface BidirectionalStreamLike { - readable: ReadableStream; - writable: WritableStream; -} - -export interface RequestStreamHandlers { - onMessage(message: ControlMessage): void; - /** - * The peer FINed its direction. Per §3.3.2 this signals the request is complete; an endpoint that receives a FIN - * before all required messages treats the request as failed — that judgement is the caller's (it knows which messages - * arrived). - */ - onFin?(): void; - /** Read failure, stream reset, or a decode error (`MoqtProtocolError`). */ - onError?(error: unknown): void; -} - -export interface RequestStream { - /** Send a follow-up message (e.g. REQUEST_UPDATE) on the request stream. */ - send(bytes: Uint8Array): Promise; - /** Gracefully close our sending direction (FIN). Not a cancellation. */ - finWrite(): Promise; - /** - * Cancel the request (§3.3.3): abort the sending direction and stop reading the receiving direction. `reason` is - * surfaced to the transport — a DOM caller passes a `WebTransportError` carrying the stream error code; tests pass - * anything. - */ - cancel(reason?: unknown): void; - readonly cancelled: boolean; -} - -/** - * Open a request over an established bidirectional stream: write the encoded request message, then pump incoming - * control messages to `handlers.onMessage` until FIN, reset, or cancellation. - */ -export function openRequestStream( - stream: BidirectionalStreamLike, - requestMessage: Uint8Array, - handlers: RequestStreamHandlers -): RequestStream { - const writer = stream.writable.getWriter(); - // Acquired here (not inside the loop) so `cancel()` can cancel through - // the reader — cancelling a locked stream directly throws. - const reader = stream.readable.getReader(); - let cancelled = false; - let finished = false; - - const readLoop = async () => { - const deframer = new ControlMessageDeframer(); - - try { - while (true) { - const { done, value } = await reader.read(); - if (done) break; - - for (const frame of deframer.push(value)) { - handlers.onMessage(decodeControlMessage(frame)); - } - } - - if (!cancelled) { - // A FIN that lands mid-frame is a truncated response, not a clean - // completion — surfacing it as FIN would leave the request pending - // with neither response nor error. - if (deframer.pendingBytes > 0) { - handlers.onError?.(new MoqtProtocolError('request stream ended mid-control-message')); - } else { - handlers.onFin?.(); - } - } - } catch (error) { - if (!cancelled) handlers.onError?.(error); - } finally { - reader.releaseLock(); - } - }; - - const firstWrite = writer.write(requestMessage).catch((error) => { - if (!cancelled) handlers.onError?.(error); - }); - - void readLoop(); - - return { - async send(bytes: Uint8Array): Promise { - await firstWrite; - await writer.write(bytes); - }, - - async finWrite(): Promise { - if (finished || cancelled) return; - - finished = true; - await firstWrite; - await writer.close(); - }, - - cancel(reason?: unknown): void { - if (cancelled) return; - - cancelled = true; - - if (!finished) { - finished = true; - writer.abort(reason).catch(() => {}); - } - - // STOP_SENDING on the receiving direction. The read loop's pending - // read resolves as done; `cancelled` suppresses the FIN callback. - reader.cancel(reason).catch(() => {}); - }, - - get cancelled(): boolean { - return cancelled; - }, - }; -} diff --git a/packages/spf/src/network/moqt/session.ts b/packages/spf/src/network/moqt/session.ts deleted file mode 100644 index e849db2543..0000000000 --- a/packages/spf/src/network/moqt/session.ts +++ /dev/null @@ -1,1038 +0,0 @@ -/** - * Pure MOQT session protocol driver (moq-transport draft-20), subscribe side only. - * - * Owns the protocol mechanics over an established transport: the SETUP exchange on paired unidirectional control - * streams (§3.3), request-stream bookkeeping keyed by Request ID (§10.1 — client IDs are even, starting at 0), routing - * of incoming data streams to subscriptions (by Track Alias) and fetches (by Request ID), GOAWAY handling, and session - * termination. - * - * Deliberately callback-shaped with NO signals (like `onMediaSourceReadyStateChange`) — signal awareness enters at the - * `playback/` layer, where the moq-session actor binds these callbacks to SPF state. The transport is a structural - * subset of `WebTransport`, so tests drive the driver with an in-memory fake and the DOM layer passes a real - * `WebTransport` unchanged. - * - * Version negotiation happens at connection time (ALPN / `WT-Available-Protocols`, `MOQT_PROTOCOL_ID`), before this - * driver sees the transport. - * - * Datagram reception is not implemented: MSF maps every object to its own stream, so a subscribe-only MSF engine never - * legitimately receives OBJECT_DATAGRAMs. - */ -import { StreamReader, utf8Encode } from './bytes'; -import { - type ControlMessage, - decodeControlMessage, - encodeFetch, - encodeGoaway, - encodeRequestError, - encodeRequestOk, - encodeRequestUpdate, - encodeSetup, - encodeSubscribe, - encodeTrackStatus, - type FetchRequest, - type KeyValuePair, - MESSAGE_TYPE, - type MessageParameters, - REQUEST_ERROR_CODE, - type Redirect, - SETUP_OPTION, - type TrackNamespace, -} from './control-messages'; -import { isMoqtProtocolError, MoqtProtocolError, SESSION_ERROR } from './errors'; -import { - type FetchStreamEntry, - isSubgroupHeaderType, - type MoqtObject, - readFetchEntries, - readFetchHeader, - readSubgroupHeader, - readSubgroupObjects, - STREAM_TYPE, - type SubgroupHeader, -} from './object-stream'; -import { type BidirectionalStreamLike, openRequestStream, type RequestStream } from './request-stream'; - -// ============================================================================ -// Transport seam -// ============================================================================ - -/** - * 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 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>; - readonly incomingBidirectionalStreams: ReadableStream; - createUnidirectionalStream(options?: { sendOrder?: number }): Promise>; - createBidirectionalStream(): Promise; - close(closeInfo?: { closeCode?: number; reason?: string }): void; - readonly closed: Promise; -} - -// ============================================================================ -// Public session surface -// ============================================================================ - -export interface RequestError { - errorCode: number; - retryInterval: number; - reason: string; - redirect?: Redirect; -} - -export interface SubscribeOk { - trackAlias: number; - parameters: MessageParameters; - trackProperties: KeyValuePair[]; -} - -export interface PublishDone { - statusCode: number; - /** Data streams the publisher opened; `undefined` when it could not count them (§10.12). */ - streamCount: number | undefined; - reason: string; -} - -export interface SubscriptionHandlers { - onOk?(ok: SubscribeOk): void; - onError?(error: RequestError): void; - onObject?(object: MoqtObject): void; - /** A subgroup stream finished cleanly (FIN). */ - onSubgroupEnd?(info: { groupId: number; subgroupId: number; endOfGroup: boolean }): void; - /** A subgroup stream was reset — objects from it may be missing. */ - onSubgroupReset?(info: { groupId: number; error: unknown }): void; - onDone?(done: PublishDone): void; - /** Response to a REQUEST_UPDATE sent on this subscription. */ - onUpdateOk?(): void; - /** - * PUBLISH_STATE_NOTIFY (§10.10): the publisher changed subscription state on its own — `parameters` carries only what - * changed, with LARGEST_OBJECT marking where. Informational; the session sends no reply. - */ - onStateNotify?(parameters: MessageParameters): void; - /** GOAWAY on this request stream: re-issue the request (possibly elsewhere). */ - onGoaway?(goaway: Goaway): void; -} - -export interface Subscription { - readonly requestId: number; - /** Modify the subscription (REQUEST_UPDATE, §10.9). */ - update(parameters: MessageParameters): void; - /** Tear the subscription down. MOQT has no UNSUBSCRIBE message — teardown is the request stream's lifecycle (§3.3.3). */ - cancel(reason?: unknown): void; -} - -export interface FetchOk { - endOfTrack: boolean; - endLocation: { group: number; object: number }; - parameters: MessageParameters; - trackProperties: KeyValuePair[]; -} - -export interface FetchHandlers { - onOk?(ok: FetchOk): void; - onError?(error: RequestError): void; - onEntry?(entry: FetchStreamEntry): void; - /** The fetch data stream finished cleanly (FIN). */ - onEnd?(): void; - /** The fetch data stream was reset — delivered entries may be incomplete. */ - onReset?(info: { error: unknown }): void; - onGoaway?(goaway: Goaway): void; -} - -export interface FetchHandle { - readonly requestId: number; - cancel(reason?: unknown): void; -} - -export interface TrackStatusHandlers { - onOk?(status: { parameters: MessageParameters; trackProperties: KeyValuePair[] }): void; - onError?(error: RequestError): void; -} - -export interface Goaway { - newSessionUri: string; - timeout: number; -} - -export interface IncomingPublish { - requestId: number; - trackNamespace: TrackNamespace; - trackName: string; - trackAlias: number; - parameters: MessageParameters; -} - -export interface MoqtSessionCallbacks { - /** The server's SETUP arrived; the session is fully established. */ - onReady?(serverOptions: KeyValuePair[]): void; - /** GOAWAY on the control stream: stop initiating requests, migrate. */ - onGoaway?(goaway: Goaway): void; - /** - * A server-initiated PUBLISH arrived. Call exactly one of the responders. Absent, the session rejects with - * UNINTERESTED (a subscribe-only client). - * - * `accept` sends a bare PUBLISH_OK: since draft-20 the subscription parameters (FORWARD, LOCATION_FILTER, …) are - * legal only on PUBLISH and REQUEST_UPDATE, and a parameter in the wrong message is a PROTOCOL_VIOLATION (§10.2.1). - */ - onIncomingPublish?( - publish: IncomingPublish, - respond: { accept(): void; reject(errorCode?: number, reason?: string): void } - ): void; - /** The session ended — transport closed, or a fatal protocol error. */ - onClosed?(info: { error?: unknown }): void; -} - -export interface MoqtSessionConfig { - /** Extra Setup Options to send (an implementation identifier is added automatically). */ - setupOptions?: KeyValuePair[]; - /** Identifies this implementation in SETUP (§10.3.1.5). */ - implementationName?: string; - /** - * How long to hold an incoming data stream whose Track Alias has no registered subscription yet (objects can outrace - * SUBSCRIBE_OK). §11.4.2 allows brief buffering; expired streams are dropped. Default 2000ms. - */ - unknownAliasTimeoutMs?: number; - /** - * How long to wait for a request's first response (SUBSCRIBE_OK / FETCH_OK / REQUEST_OK / REQUEST_ERROR) before - * failing it. The draft expects implementations to bound control exchanges (§3.5's CONTROL_MESSAGE_TIMEOUT); without - * this a relay that accepts the stream and then goes quiet leaves the request pending forever. Default 10000ms. - */ - requestTimeoutMs?: number; - callbacks?: MoqtSessionCallbacks; -} - -export interface MoqtSubscribeOptions { - trackNamespace: TrackNamespace; - trackName: string; - parameters?: MessageParameters; -} - -/** - * FETCH (§10.13) takes the SUBSCRIBE shape; the range is `parameters.locationFilter`, read with fetch rules (§5.1.2): a - * relative start counts back from Largest Object, an omitted end stops there, no filter means the whole track. - */ -export type MoqtFetchOptions = MoqtSubscribeOptions; - -export interface MoqtSession { - /** Resolves when the server's SETUP has been received. */ - readonly ready: Promise; - subscribe(options: MoqtSubscribeOptions, handlers?: SubscriptionHandlers): Subscription; - fetch(options: MoqtFetchOptions, handlers?: FetchHandlers): FetchHandle; - trackStatus(options: MoqtSubscribeOptions, handlers?: TrackStatusHandlers): void; - /** Send GOAWAY then close the transport session. */ - close(closeCode?: number, reason?: string): void; - destroy(): void; -} - -const DEFAULT_UNKNOWN_ALIAS_TIMEOUT_MS = 2000; -const DEFAULT_REQUEST_TIMEOUT_MS = 10_000; -const DEFAULT_IMPLEMENTATION_NAME = '@videojs/spf moqt'; - -/** - * A request failure that arrives as a _stream_ event — FIN before any response, a transport reset, or the response - * timeout — rather than as a REQUEST_ERROR message. Shaped as a `RequestError` so consumers have one failure path - * regardless of how the request died. - */ -function streamFailure(reason: string, errorCode: number = REQUEST_ERROR_CODE.INTERNAL_ERROR): RequestError { - return { errorCode, retryInterval: 0, reason }; -} - -// ============================================================================ -// Internal records -// ============================================================================ - -/** Bookkeeping `#openRequest` manages for every request kind. */ -interface RequestRecordBase { - cancelled: boolean; - pendingCancelReason?: unknown; - stream?: RequestStream; - /** - * The request's first response (an OK or a REQUEST_ERROR) arrived. Until it does, a FIN / reset / timeout on the - * stream is a failure; after it, those are ordinary end-of-request events. - */ - settled: boolean; - responseTimer?: ReturnType; -} - -interface SubscriptionRecord extends RequestRecordBase { - requestId: number; - handlers: SubscriptionHandlers; - trackAlias?: number; -} - -interface FetchRecord extends RequestRecordBase { - requestId: number; - handlers: FetchHandlers; - groupOrder: 'ascending' | 'descending'; -} - -interface TrackStatusRecord extends RequestRecordBase { - requestId: number; - handlers: TrackStatusHandlers; -} - -interface AliasWaiter { - resolve(record: SubscriptionRecord | undefined): void; - timer: ReturnType; -} - -// ============================================================================ -// Session driver -// ============================================================================ - -class MoqtSessionImpl implements MoqtSession { - readonly ready: Promise; - - #transport: MoqtTransport; - #config: MoqtSessionConfig; - #callbacks: MoqtSessionCallbacks; - - #nextRequestId = 0; // client request IDs: even, starting at 0 (§10.1) - #subscriptions = new Map(); - #fetches = new Map(); - #trackStatuses = new Map(); - #aliasRoutes = new Map(); - #aliasWaiters = new Map(); - - #resolveReady!: () => void; - #rejectReady!: (error: unknown) => void; - #controlWriter: WritableStreamDefaultWriter | undefined; - #receivedServerSetup = false; - #receivedControlGoaway = false; - #destroyed = false; - - constructor(transport: MoqtTransport, config: MoqtSessionConfig = {}) { - this.#transport = transport; - this.#config = config; - this.#callbacks = config.callbacks ?? {}; - this.ready = new Promise((resolve, reject) => { - this.#resolveReady = resolve; - this.#rejectReady = reject; - }); - // Consumers may observe readiness through `onClosed` alone. - this.ready.catch(() => {}); - - void this.#start(); - } - - // -------------------------------------------------------------------------- - // Session lifecycle - // -------------------------------------------------------------------------- - - async #start(): Promise { - // Accept loops start first: the peer's streams must be processed even - // while our own SETUP write is still propagating (either peer may send - // stream data first, §3.3). - void this.#acceptUnidirectionalStreams(); - void this.#acceptBidirectionalStreams(); - void this.#transport.closed.then( - () => this.#handleClosed(undefined), - (error) => this.#handleClosed(error) - ); - - try { - const control = await this.#transport.createUnidirectionalStream(); - - this.#controlWriter = control.getWriter(); - const options: KeyValuePair[] = [ - { - type: SETUP_OPTION.MOQT_IMPLEMENTATION, - value: utf8Encode(this.#config.implementationName ?? DEFAULT_IMPLEMENTATION_NAME), - }, - ...(this.#config.setupOptions ?? []), - ]; - - await this.#controlWriter.write(encodeSetup(options)); - } catch (error) { - this.#fatal(error); - } - } - - #fatal(error: unknown): void { - if (this.#destroyed) return; - - const closeCode = isMoqtProtocolError(error) ? error.code : SESSION_ERROR.INTERNAL_ERROR; - - try { - this.#transport.close({ closeCode, reason: error instanceof Error ? error.message : 'session error' }); - } catch { - // transport already gone - } - - this.#handleClosed(error); - } - - #handleClosed(error: unknown, { expected = false }: { expected?: boolean } = {}): void { - if (this.#destroyed) return; - - this.#destroyed = true; - const setupError = this.#receivedServerSetup - ? undefined - : (error ?? new MoqtProtocolError('session closed before server SETUP')); - - if (setupError !== undefined) this.#rejectReady(setupError); - - for (const waiters of this.#aliasWaiters.values()) { - for (const waiter of waiters) { - clearTimeout(waiter.timer); - waiter.resolve(undefined); - } - } - - this.#aliasWaiters.clear(); - - // Requests still awaiting their first response die with the session. An - // unexpected close (transport drop) is a failure each of them has to - // hear about — otherwise a dropped transport leaves subscribers pending - // forever. A deliberate `close()` is ordinary teardown, and cancelled - // requests already have their answer. - const records = [...this.#subscriptions.values(), ...this.#fetches.values(), ...this.#trackStatuses.values()]; - const pending = expected ? [] : records.filter((r) => !r.settled && !r.cancelled); - - for (const record of records) { - this.#settleRequest(record); - record.stream?.cancel(error); - } - - this.#subscriptions.clear(); - this.#fetches.clear(); - this.#trackStatuses.clear(); - this.#aliasRoutes.clear(); - this.#controlWriter = undefined; - - const failure = streamFailure( - error instanceof Error ? error.message : 'session closed before the request was answered' - ); - - for (const record of pending) record.handlers.onError?.(failure); - - // A transport that drops before server SETUP is a session failure even - // when the close itself was clean — callback-only consumers observing - // `onClosed` alone must see the error too. A deliberate local `close()` - // stays a clean close. - const closeError = error ?? (expected ? undefined : setupError); - - this.#callbacks.onClosed?.(closeError === undefined ? {} : { error: closeError }); - } - - close(closeCode = SESSION_ERROR.NO_ERROR, reason = ''): void { - if (this.#destroyed) return; - - // Best-effort GOAWAY so the peer can stop routing to us first. - this.#controlWriter?.write(encodeGoaway(0)).catch(() => {}); - - try { - this.#transport.close({ closeCode, reason }); - } catch { - // transport already gone - } - - this.#handleClosed(undefined, { expected: true }); - } - - destroy(): void { - this.close(); - } - - // -------------------------------------------------------------------------- - // Requests - // -------------------------------------------------------------------------- - - #allocateRequestId(): number { - const id = this.#nextRequestId; - - this.#nextRequestId += 2; - return id; - } - - subscribe(options: MoqtSubscribeOptions, handlers: SubscriptionHandlers = {}): Subscription { - const requestId = this.#allocateRequestId(); - const record: SubscriptionRecord = { requestId, handlers, cancelled: false, settled: false }; - - this.#subscriptions.set(requestId, record); - - const message = encodeSubscribe({ - requestId, - trackNamespace: options.trackNamespace, - trackName: options.trackName, - parameters: options.parameters, - }); - - void this.#openRequest( - message, - record, - (msg) => this.#handleSubscriptionMessage(record, msg), - (error) => { - this.#removeSubscription(record); - handlers.onError?.(error); - } - ); - - return { - requestId, - update: (parameters) => { - // REQUEST_UPDATE consumes a Request ID of its own (§10.1); the stream - // it travels on is what names the subscription. Reusing the - // subscription's id would be a duplicate the peer MUST close on. - record.stream?.send(encodeRequestUpdate(this.#allocateRequestId(), parameters)).catch(() => {}); - }, - cancel: (reason) => this.#cancelSubscription(record, reason), - }; - } - - fetch(options: MoqtFetchOptions, handlers: FetchHandlers = {}): FetchHandle { - const requestId = this.#allocateRequestId(); - const record: FetchRecord = { - requestId, - handlers, - groupOrder: options.parameters?.groupOrder ?? 'ascending', - cancelled: false, - settled: false, - }; - - this.#fetches.set(requestId, record); - - const request: FetchRequest = { requestId, ...options }; - - void this.#openRequest( - encodeFetch(request), - record, - (msg) => this.#handleFetchMessage(record, msg), - (error) => { - this.#fetches.delete(requestId); - handlers.onError?.(error); - } - ); - - return { - requestId, - cancel: (reason) => this.#cancelFetch(record, reason), - }; - } - - trackStatus(options: MoqtSubscribeOptions, handlers: TrackStatusHandlers = {}): void { - const requestId = this.#allocateRequestId(); - const record: TrackStatusRecord = { requestId, handlers, cancelled: false, settled: false }; - - // Tracked so session teardown fails a still-pending TRACK_STATUS the - // same way it fails pending subscriptions and fetches. Answered - // requests leave the map — nothing else arrives on their stream. - this.#trackStatuses.set(requestId, record); - - const message = encodeTrackStatus({ - requestId, - trackNamespace: options.trackNamespace, - trackName: options.trackName, - parameters: options.parameters, - }); - - void this.#openRequest( - message, - record, - (msg) => { - if (msg.kind === 'request-ok') { - this.#settleRequest(record); - this.#trackStatuses.delete(requestId); - handlers.onOk?.({ parameters: msg.parameters, trackProperties: msg.trackProperties }); - record.stream?.finWrite().catch(() => {}); - } else if (msg.kind === 'request-error') { - this.#settleRequest(record); - this.#trackStatuses.delete(requestId); - handlers.onError?.(msg); - record.stream?.finWrite().catch(() => {}); - } - }, - (error) => { - this.#trackStatuses.delete(requestId); - handlers.onError?.(error); - } - ); - } - - /** - * Open a request stream and bind its lifecycle to `record`. - * - * `onFailure` is the caller's "this request died without answering me" path — `request-stream` deliberately leaves - * that judgement here, since only the session knows which messages a given request kind requires. It fires for a FIN - * before any response, a non-protocol stream error (transport reset), and the response timeout; a protocol error - * still kills the whole session. Once `record.settled` is set the same events are ordinary end-of-request signals and - * are ignored. - */ - async #openRequest( - message: Uint8Array, - record: RequestRecordBase, - onMessage: (message: ControlMessage) => void, - onFailure: (error: RequestError) => void - ): Promise { - const fail = (error: RequestError): void => { - if (record.settled || record.cancelled || this.#destroyed) return; - - this.#settleRequest(record); - onFailure(error); - }; - - let stream: BidirectionalStreamLike; - - try { - stream = await this.#transport.createBidirectionalStream(); - } catch (error) { - // Losing the ability to open streams is a session-level failure, but - // this request also has to hear about it. - fail(streamFailure(error instanceof Error ? error.message : 'failed to open request stream')); - - if (!this.#destroyed) this.#fatal(error); - - return; - } - - const timeout = this.#config.requestTimeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS; - - if (timeout > 0 && !record.settled && !record.cancelled) { - record.responseTimer = setTimeout(() => { - const failure = streamFailure('no response before the request timeout', REQUEST_ERROR_CODE.TIMEOUT); - - // The stream dies with the request: left open, a late SUBSCRIBE_OK - // would fire onOk after onError and re-register the alias route of - // a subscription already reported dead. - record.stream?.cancel(failure); - fail(failure); - }, timeout); - } - - record.stream = openRequestStream(stream, message, { - onMessage, - onFin: () => fail(streamFailure('request stream closed before a response')), - onError: (error) => { - if (isMoqtProtocolError(error)) { - this.#fatal(error); - return; - } - - fail(streamFailure(error instanceof Error ? error.message : 'request stream failed')); - }, - }); - - // A cancel that raced the stream opening lands here. - if (record.cancelled) record.stream.cancel(record.pendingCancelReason); - } - - /** Mark a request answered (or dead) and disarm its response timeout. */ - #settleRequest(record: RequestRecordBase): void { - record.settled = true; - - if (record.responseTimer !== undefined) { - clearTimeout(record.responseTimer); - record.responseTimer = undefined; - } - } - - #handleSubscriptionMessage(record: SubscriptionRecord, message: ControlMessage): void { - switch (message.kind) { - case 'subscribe-ok': { - if (record.trackAlias !== undefined && record.trackAlias !== message.trackAlias) { - this.#fatal(new MoqtProtocolError('SUBSCRIBE_OK changed track alias')); - return; - } - - const existing = this.#aliasRoutes.get(message.trackAlias); - - if (existing && existing !== record) { - this.#fatal(new MoqtProtocolError('duplicate track alias', SESSION_ERROR.DUPLICATE_TRACK_ALIAS)); - return; - } - - this.#settleRequest(record); - record.trackAlias = message.trackAlias; - this.#aliasRoutes.set(message.trackAlias, record); - const waiters = this.#aliasWaiters.get(message.trackAlias); - - if (waiters) { - this.#aliasWaiters.delete(message.trackAlias); - - for (const waiter of waiters) { - clearTimeout(waiter.timer); - waiter.resolve(record); - } - } - - record.handlers.onOk?.({ - trackAlias: message.trackAlias, - parameters: message.parameters, - trackProperties: message.trackProperties, - }); - break; - } - case 'request-ok': - record.handlers.onUpdateOk?.(); - break; - case 'request-error': - this.#settleRequest(record); - this.#removeSubscription(record); - record.handlers.onError?.(message); - break; - case 'publish-done': - // Data streams may still be inbound; the alias route stays until - // the subscription is cancelled or the session ends, so late - // subgroups still deliver (§10.12 leaves the timing policy to us). - record.handlers.onDone?.(message); - break; - case 'publish-state-notify': - // Unilateral (§10.10): no REQUEST_OK back, and it does not count - // against MAX_REQUEST_UPDATES. - record.handlers.onStateNotify?.(message.parameters); - break; - case 'goaway': - record.handlers.onGoaway?.(message); - break; - default: - this.#fatal(new MoqtProtocolError(`unexpected ${message.kind} on a subscribe request stream`)); - } - } - - #handleFetchMessage(record: FetchRecord, message: ControlMessage): void { - switch (message.kind) { - case 'fetch-ok': - this.#settleRequest(record); - record.handlers.onOk?.({ - endOfTrack: message.endOfTrack, - endLocation: message.endLocation, - parameters: message.parameters, - trackProperties: message.trackProperties, - }); - break; - // Some deployed relays accept a FETCH with the generic REQUEST_OK - // instead of the FETCH_OK §10.13 mandates. It - // carries no End Location/End Of Track, so `onOk` can't fire — the - // fetch's actual completion still surfaces via onEntry/onEnd on the - // data stream, which this response has no bearing on. It is still - // the response, so it has to settle the request: leaving the timer - // armed would fail an answered fetch (and drop its data stream) - // once the deadline passed. - case 'request-ok': - this.#settleRequest(record); - break; - case 'request-error': - this.#settleRequest(record); - this.#fetches.delete(record.requestId); - record.handlers.onError?.(message); - break; - case 'goaway': - record.handlers.onGoaway?.(message); - break; - default: - this.#fatal(new MoqtProtocolError(`unexpected ${message.kind} on a fetch request stream`)); - } - } - - #cancelSubscription(record: SubscriptionRecord, reason?: unknown): void { - if (record.cancelled) return; - - record.cancelled = true; - record.pendingCancelReason = reason; - this.#settleRequest(record); - record.stream?.cancel(reason); - this.#removeSubscription(record); - } - - #removeSubscription(record: SubscriptionRecord): void { - this.#subscriptions.delete(record.requestId); - - if (record.trackAlias !== undefined && this.#aliasRoutes.get(record.trackAlias) === record) { - this.#aliasRoutes.delete(record.trackAlias); - } - } - - #cancelFetch(record: FetchRecord, reason?: unknown): void { - if (record.cancelled) return; - - record.cancelled = true; - record.pendingCancelReason = reason; - this.#settleRequest(record); - record.stream?.cancel(reason); - this.#fetches.delete(record.requestId); - } - - // -------------------------------------------------------------------------- - // Incoming unidirectional streams (control, subgroup, fetch, padding) - // -------------------------------------------------------------------------- - - async #acceptUnidirectionalStreams(): Promise { - const reader = this.#transport.incomingUnidirectionalStreams.getReader(); - - try { - while (true) { - const { done, value } = await reader.read(); - if (done) break; - - void this.#handleUnidirectionalStream(value).catch((error) => { - if (isMoqtProtocolError(error)) this.#fatal(error); - }); - } - } catch { - // Transport went away; `closed` handles the surfacing. - } finally { - reader.releaseLock(); - } - } - - async #handleUnidirectionalStream(stream: ReadableStream): Promise { - const reader = new StreamReader(stream); - const streamType = await reader.readVarint(); - - if (streamType === STREAM_TYPE.SETUP) { - await this.#runControlStream(reader); - return; - } - - if (isSubgroupHeaderType(streamType)) { - const header = await readSubgroupHeader(reader, streamType); - - await this.#runSubgroupStream(reader, header); - return; - } - - if (streamType === STREAM_TYPE.FETCH_HEADER) { - const { requestId } = await readFetchHeader(reader); - - await this.#runFetchStream(reader, requestId); - return; - } - - if (streamType === STREAM_TYPE.PADDING) { - await reader.cancel(); - return; - } - - await reader.cancel(); - throw new MoqtProtocolError(`unknown unidirectional stream type 0x${streamType.toString(16)}`); - } - - /** Read one control-message frame using the pull-based stream reader. */ - async #readControlFrame(reader: StreamReader, type: number): Promise { - const high = await reader.readUint8(); - const low = await reader.readUint8(); - const body = await reader.readBytes(high * 256 + low); - - return decodeControlMessage({ type, body }); - } - - async #runControlStream(reader: StreamReader): Promise { - // The stream-type varint (0x2F00) doubles as the first message's type. - const setup = await this.#readControlFrame(reader, MESSAGE_TYPE.SETUP); - if (setup.kind !== 'setup') throw new MoqtProtocolError('control stream did not begin with SETUP'); - - if (this.#receivedServerSetup) { - throw new MoqtProtocolError('received a second control stream'); - } - - this.#receivedServerSetup = true; - this.#resolveReady(); - this.#callbacks.onReady?.(setup.options); - - // Subsequent control-stream messages: GOAWAY (at most once). - while (!(await reader.atEnd())) { - const type = await reader.readVarint(); - const message = await this.#readControlFrame(reader, type); - if (message.kind !== 'goaway') throw new MoqtProtocolError(`unexpected ${message.kind} on the control stream`); - - if (this.#receivedControlGoaway) { - throw new MoqtProtocolError('received more than one GOAWAY on the control stream'); - } - - this.#receivedControlGoaway = true; - this.#callbacks.onGoaway?.(message); - } - - // A closed control stream ends the session (§3.3). - if (!this.#destroyed) { - this.#fatal(new MoqtProtocolError('peer closed its control stream')); - } - } - - /** Wait briefly for a subscription to claim `trackAlias` (§11.4.2 buffering). */ - #waitForAlias(trackAlias: number): Promise { - const known = this.#aliasRoutes.get(trackAlias); - if (known || this.#destroyed) return Promise.resolve(known); - - return new Promise((resolve) => { - const waiters = this.#aliasWaiters.get(trackAlias) ?? []; - const timeout = this.#config.unknownAliasTimeoutMs ?? DEFAULT_UNKNOWN_ALIAS_TIMEOUT_MS; - const waiter: AliasWaiter = { - resolve, - timer: setTimeout(() => { - const remaining = this.#aliasWaiters.get(trackAlias)?.filter((w) => w !== waiter); - - if (remaining?.length) this.#aliasWaiters.set(trackAlias, remaining); - else this.#aliasWaiters.delete(trackAlias); - - resolve(undefined); - }, timeout), - }; - - waiters.push(waiter); - this.#aliasWaiters.set(trackAlias, waiters); - }); - } - - async #runSubgroupStream(reader: StreamReader, header: SubgroupHeader): Promise { - const record = await this.#waitForAlias(header.trackAlias); - - if (!record || record.cancelled) { - await reader.cancel(); - return; - } - - let lastSubgroupId = header.subgroupIdMode === 'explicit' ? header.subgroupId! : 0; - - try { - for await (const object of readSubgroupObjects(reader, header)) { - if (record.cancelled) { - await reader.cancel(); - return; - } - - lastSubgroupId = object.subgroupId; - record.handlers.onObject?.(object); - } - - record.handlers.onSubgroupEnd?.({ - groupId: header.groupId, - subgroupId: lastSubgroupId, - endOfGroup: header.endOfGroup, - }); - } catch (error) { - if (isMoqtProtocolError(error)) throw error; - - // A reset stream is a delivery event (timeout, cancellation), not a - // session error — surface it to the subscription. - record.handlers.onSubgroupReset?.({ groupId: header.groupId, error }); - } - } - - async #runFetchStream(reader: StreamReader, requestId: number): Promise { - const record = this.#fetches.get(requestId); - - // A FETCH_HEADER naming no fetch of ours is dropped, not fatal. That - // includes a fill fetch stream (§5.1.3), keyed by a SUBSCRIBE's Request - // ID — this subscriber never asks for one, so none is expected. - if (!record || record.cancelled) { - await reader.cancel(); - return; - } - - try { - for await (const entry of readFetchEntries(reader, record.groupOrder)) { - if (record.cancelled) { - await reader.cancel(); - return; - } - - record.handlers.onEntry?.(entry); - } - - record.handlers.onEnd?.(); - } catch (error) { - if (isMoqtProtocolError(error)) throw error; - - // A reset mid-replay means entries may be missing — never report it - // as the clean FIN `onEnd` promises. - record.handlers.onReset?.({ error }); - } - } - - // -------------------------------------------------------------------------- - // Incoming bidirectional streams (server-initiated requests) - // -------------------------------------------------------------------------- - - async #acceptBidirectionalStreams(): Promise { - const reader = this.#transport.incomingBidirectionalStreams.getReader(); - - try { - while (true) { - const { done, value } = await reader.read(); - if (done) break; - - void this.#handleIncomingRequest(value).catch((error) => { - if (isMoqtProtocolError(error)) this.#fatal(error); - }); - } - } catch { - // Transport went away. - } finally { - reader.releaseLock(); - } - } - - async #handleIncomingRequest(stream: BidirectionalStreamLike): Promise { - const reader = new StreamReader(stream.readable); - const type = await reader.readVarint(); - const message = await this.#readControlFrame(reader, type); - - const respond = async (bytes: Uint8Array) => { - const writer = stream.writable.getWriter(); - - try { - await writer.write(bytes); - await writer.close(); - } catch { - // Peer cancelled; nothing to clean up. - } - - await reader.cancel(); - }; - - if (message.kind === 'publish') { - const callbacks = this.#callbacks; - - if (callbacks.onIncomingPublish) { - let responded = false; - - callbacks.onIncomingPublish(message, { - accept: () => { - if (responded) return; - - responded = true; - void respond(encodeRequestOk()); - }, - reject: (errorCode = REQUEST_ERROR_CODE.UNINTERESTED, reason = '') => { - if (responded) return; - - responded = true; - void respond(encodeRequestError(errorCode, reason)); - }, - }); - return; - } - - await respond(encodeRequestError(REQUEST_ERROR_CODE.UNINTERESTED, 'subscribe-only client')); - return; - } - - // Any other server-initiated request: this client doesn't serve them. - await respond(encodeRequestError(REQUEST_ERROR_CODE.NOT_SUPPORTED, 'subscribe-only client')); - } -} - -/** - * Create a MOQT session driver over an established transport. - * - * @example - * ```ts - * const transport = new WebTransport(url, { protocols: [MOQT_PROTOCOL_ID] }); - * await transport.ready; - * const session = createMoqtSession(transport, { - * callbacks: { onGoaway: (g) => migrate(g.newSessionUri) }, - * }); - * const subscription = session.subscribe( - * { trackNamespace: ['live', 'stream1'], trackName: 'catalog' }, - * { onObject: (object) => handleCatalogObject(object) } - * ); - * ```; - */ -export function createMoqtSession(transport: MoqtTransport, config: MoqtSessionConfig = {}): MoqtSession { - return new MoqtSessionImpl(transport, config); -} diff --git a/packages/spf/src/network/moqt/subgroup-writer.ts b/packages/spf/src/network/moqt/subgroup-writer.ts deleted file mode 100644 index ab5f5ee0f1..0000000000 --- a/packages/spf/src/network/moqt/subgroup-writer.ts +++ /dev/null @@ -1,184 +0,0 @@ -/** - * MOQT subgroup data-stream writing (moq-transport draft-19 §11.4.2) — the publish-direction complement to - * `object-stream.ts`'s reader. - * - * One writer owns one unidirectional stream carrying one subgroup of one group: the SUBGROUP_HEADER goes out first, - * objects follow serially with delta-encoded object IDs, and `fin()` closes the stream to mark the group complete. - * `abort()` resets the stream instead — the drop path for a publisher falling behind transport backpressure. - * - * The MSF/LOC shape this engine publishes is one subgroup per group at subgroup ID 0, so the writer pins - * SUBGROUP_ID_MODE to `0b00` (no explicit subgroup-id field) and sets END_OF_GROUP: on FIN the subgroup contains the - * group's largest object by construction. - * - * Everything written here round-trips through `readSubgroupHeader` + `readSubgroupObjects` — that pairing is the - * module's contract and its test suite. - */ -import { ByteWriter } from './bytes'; -import { encodeKeyValuePairs, type KeyValuePair } from './control-messages'; -import { MoqtProtocolError } from './errors'; -import { MAX_OBJECT_PAYLOAD_LENGTH, MAX_OBJECT_PROPERTIES_LENGTH, type ObjectStatus } from './object-stream'; - -const SUBGROUP_TYPE_BASE = 0x10; -const SUBGROUP_TYPE_PROPERTIES = 0x01; -const SUBGROUP_TYPE_END_OF_GROUP = 0x08; -const SUBGROUP_TYPE_DEFAULT_PRIORITY = 0x20; -const SUBGROUP_TYPE_FIRST_OBJECT = 0x40; - -const OBJECT_STATUS_WIRE: Record = { - normal: 0, - 'end-of-group': 3, - 'end-of-track': 4, -}; - -export interface SubgroupWriterOptions { - trackAlias: number; - groupId: number; - /** - * Explicit publisher priority byte. Omitted, the header sets the DEFAULT_PRIORITY flag and subscribers fall back to - * the subscription's priority. - */ - priority?: number; - /** - * Every object on this stream carries a Properties block (LOC frame metadata). Default true — an empty properties - * list still encodes (as a zero length), so mixed-metadata tracks need no special casing. - */ - hasProperties?: boolean; - /** The subgroup contains the group's largest object on FIN. Default true. */ - endOfGroup?: boolean; -} - -export interface SubgroupObjectInput { - /** Absolute object ID; must increase monotonically within the stream. */ - objectId: number; - properties?: readonly KeyValuePair[]; - payload: Uint8Array; - /** Only meaningful for zero-length payloads (§11.2.1.1). Default 'normal'. */ - status?: ObjectStatus; -} - -export interface SubgroupWriter { - readonly groupId: number; - /** Serialize one object. Resolves when the transport accepted the bytes. */ - writeObject(object: SubgroupObjectInput): Promise; - /** FIN the stream — the group is complete. */ - fin(): Promise; - /** Reset the stream — delivered objects may be incomplete (drop path). */ - abort(reason?: unknown): void; -} - -function encodeSubgroupHeader(options: SubgroupWriterOptions): Uint8Array { - const hasProperties = options.hasProperties ?? true; - const endOfGroup = options.endOfGroup ?? true; - const type = - SUBGROUP_TYPE_BASE | - SUBGROUP_TYPE_FIRST_OBJECT | - (hasProperties ? SUBGROUP_TYPE_PROPERTIES : 0) | - (endOfGroup ? SUBGROUP_TYPE_END_OF_GROUP : 0) | - (options.priority === undefined ? SUBGROUP_TYPE_DEFAULT_PRIORITY : 0); - - const writer = new ByteWriter(32); - - writer.writeVarint(type); - writer.writeVarint(options.trackAlias); - writer.writeVarint(options.groupId); - - if (options.priority !== undefined) writer.writeUint8(options.priority); - - return writer.toBytes(); -} - -function encodeObject( - object: SubgroupObjectInput, - previousObjectId: number | undefined, - hasProperties: boolean -): Uint8Array { - if (previousObjectId !== undefined && object.objectId <= previousObjectId) { - throw new MoqtProtocolError(`subgroup object ID ${object.objectId} does not increase past ${previousObjectId}`); - } - - if (object.payload.length > MAX_OBJECT_PAYLOAD_LENGTH) { - throw new MoqtProtocolError( - `object payload length ${object.payload.length} exceeds ${MAX_OBJECT_PAYLOAD_LENGTH} bytes` - ); - } - - const writer = new ByteWriter(object.payload.length + 64); - - // First object carries its absolute ID; the rest are `delta + 1` (§11.4.2). - writer.writeVarint(previousObjectId === undefined ? object.objectId : object.objectId - previousObjectId - 1); - - if (hasProperties) { - const properties = new ByteWriter(64); - - encodeKeyValuePairs(properties, object.properties ?? []); - - if (properties.length > MAX_OBJECT_PROPERTIES_LENGTH) { - throw new MoqtProtocolError( - `object properties length ${properties.length} exceeds ${MAX_OBJECT_PROPERTIES_LENGTH} bytes` - ); - } - - writer.writeLengthPrefixed(properties.toBytes()); - } else if (object.properties?.length) { - throw new MoqtProtocolError('object carries properties on a subgroup stream without the PROPERTIES flag'); - } - - writer.writeVarint(object.payload.length); - - if (object.payload.length === 0) { - writer.writeVarint(OBJECT_STATUS_WIRE[object.status ?? 'normal']); - } else { - writer.writeBytes(object.payload); - } - - return writer.toBytes(); -} - -/** - * Open a subgroup writer over an established unidirectional stream. The SUBGROUP_HEADER is queued immediately; objects - * follow in `writeObject` call order (writes serialize through the stream's own queue). - */ -export function createSubgroupWriter( - stream: WritableStream, - options: SubgroupWriterOptions -): SubgroupWriter { - const hasProperties = options.hasProperties ?? true; - const writer = stream.getWriter(); - let previousObjectId: number | undefined; - let finished = false; - - // Header errors surface on the first awaited write/fin — an errored - // stream rejects everything queued after it. - const headerWrite = writer.write(encodeSubgroupHeader(options)); - - headerWrite.catch(() => {}); - - return { - groupId: options.groupId, - - async writeObject(object: SubgroupObjectInput): Promise { - if (finished) throw new MoqtProtocolError('subgroup stream already finished'); - - const bytes = encodeObject(object, previousObjectId, hasProperties); - - previousObjectId = object.objectId; - await headerWrite; - await writer.write(bytes); - }, - - async fin(): Promise { - if (finished) return; - - finished = true; - await headerWrite; - await writer.close(); - }, - - abort(reason?: unknown): void { - if (finished) return; - - finished = true; - writer.abort(reason).catch(() => {}); - }, - }; -} diff --git a/packages/spf/src/network/moqt/tests/control-messages.test.ts b/packages/spf/src/network/moqt/tests/control-messages.test.ts deleted file mode 100644 index 62f823c071..0000000000 --- a/packages/spf/src/network/moqt/tests/control-messages.test.ts +++ /dev/null @@ -1,612 +0,0 @@ -import { describe, expect, it } from 'vite-plus/test'; - -import { ByteReader, ByteWriter, utf8Encode } from '../bytes'; -import { - ControlMessageDeframer, - decodeControlMessage, - decodeKeyValuePairs, - decodeLocationFilter, - decodeMessageParameters, - encodeFetch, - encodeFetchOk, - encodeGoaway, - encodeKeyValuePairs, - encodeLocationFilter, - encodeMessageParameters, - encodePublishDone, - encodePublishNamespace, - encodePublishStateNotify, - encodeRequestError, - encodeRequestOk, - encodeSetup, - encodeSubscribe, - encodeSubscribeOk, - isEmptyFetchRange, - isRetryablePublishDoneStatus, - isRetryableRequestErrorCode, - type LocationFilter, - MESSAGE_TYPE, - type MessageParameters, - PARAMETER_TYPE, - PUBLISH_DONE_STATUS, - REQUEST_ERROR_CODE, - SETUP_OPTION, -} from '../control-messages'; -import { MoqtProtocolError } from '../errors'; - -function frames(...messages: Uint8Array[]): Uint8Array { - const merged = new Uint8Array(messages.reduce((total, m) => total + m.length, 0)); - let offset = 0; - - for (const message of messages) { - merged.set(message, offset); - offset += message.length; - } - - return merged; -} - -function decodeAll(bytes: Uint8Array) { - const deframer = new ControlMessageDeframer(); - - return deframer.push(bytes).map(decodeControlMessage); -} - -function encodeParameters(parameters: MessageParameters): Uint8Array { - const writer = new ByteWriter(); - - encodeMessageParameters(writer, parameters); - return writer.toBytes(); -} - -describe('ControlMessageDeframer', () => { - it('reassembles messages split across arbitrary chunk boundaries', () => { - const encoded = frames( - encodeSubscribe({ requestId: 0, trackNamespace: ['live', 'a'], trackName: 'video' }), - encodeGoaway(250) - ); - - // Split at every possible boundary and confirm both frames come out. - for (let split = 1; split < encoded.length; split++) { - const deframer = new ControlMessageDeframer(); - const first = deframer.push(encoded.subarray(0, split)); - const second = deframer.push(encoded.subarray(split)); - const all = [...first, ...second]; - - expect(all).toHaveLength(2); - expect(all[0]!.type).toBe(MESSAGE_TYPE.SUBSCRIBE); - expect(all[1]!.type).toBe(MESSAGE_TYPE.GOAWAY); - expect(deframer.pendingBytes).toBe(0); - } - }); - - it('yields one frame per push when messages arrive whole', () => { - const deframer = new ControlMessageDeframer(); - - expect(deframer.push(encodeGoaway(0))).toHaveLength(1); - expect(deframer.push(encodePublishDone(0x2, 5, 'track ended'))).toHaveLength(1); - }); -}); - -describe('encodeSubscribe', () => { - it('round-trips through the decoder', () => { - const parameters: MessageParameters = { - subscriberPriority: 16, - groupOrder: 'ascending', - locationFilter: { type: 'next-object' }, - forward: 1, - }; - const [message] = decodeAll( - encodeSubscribe({ requestId: 4, trackNamespace: ['live', 'stream1'], trackName: 'catalog', parameters }) - ); - - expect(message).toMatchObject({ - kind: 'subscribe', - requestId: 4, - trackNamespace: ['live', 'stream1'], - trackName: 'catalog', - parameters: { - subscriberPriority: 16, - groupOrder: 'ascending', - locationFilter: { type: 'next-object' }, - forward: 1, - }, - }); - }); - - it('round-trips the canonical current-group join: Next Object plus a StartGroup=1 fill', () => { - const parameters: MessageParameters = { - locationFilter: { type: 'next-object' }, - fillParameters: { locationFilter: { type: 'relative-group', groupsBeforeNext: 1 } }, - }; - const [message] = decodeAll( - encodeSubscribe({ requestId: 0, trackNamespace: ['live'], trackName: 'video', parameters }) - ); - - expect(message).toMatchObject({ kind: 'subscribe', parameters }); - }); - - it('rejects empty namespace fields', () => { - expect(() => encodeSubscribe({ requestId: 0, trackNamespace: [''], trackName: 't' })).toThrow(MoqtProtocolError); - }); -}); - -describe('encodeFetch', () => { - it('round-trips a fetch whose range rides in LOCATION_FILTER', () => { - const [message] = decodeAll( - encodeFetch({ - requestId: 2, - trackNamespace: ['live'], - trackName: 'video', - parameters: { locationFilter: { type: 'absolute', start: { group: 10, object: 0 }, endGroupDelta: 2 } }, - }) - ); - - expect(message).toEqual({ - kind: 'fetch', - request: { - requestId: 2, - trackNamespace: ['live'], - trackName: 'video', - parameters: { locationFilter: { type: 'absolute', start: { group: 10, object: 0 }, endGroupDelta: 2 } }, - }, - }); - }); - - it('round-trips an unfiltered fetch (the whole track up to Largest Object)', () => { - const [message] = decodeAll(encodeFetch({ requestId: 6, trackNamespace: ['live'], trackName: 'catalog' })); - - expect(message).toEqual({ - kind: 'fetch', - request: { requestId: 6, trackNamespace: ['live'], trackName: 'catalog', parameters: {} }, - }); - }); -}); - -describe('encodeSubscribeOk', () => { - it('matches relay 0.14.17 framing with content and trailing track properties', () => { - const wire = Uint8Array.of(0x04, 0x00, 0x09, 0x07, 0x01, 0x09, 0x80, 0xff, 0x80, 0x80, 0x02, 0x01); - const parameters = { largestObject: { group: 255, object: 128 } }; - const trackProperties = [{ type: 0x02, value: 1 }]; - - expect(encodeSubscribeOk(7, parameters, trackProperties)).toEqual(wire); - expect(decodeAll(wire)).toEqual([{ kind: 'subscribe-ok', trackAlias: 7, parameters, trackProperties }]); - }); - - it('round-trips alias, parameters, and track properties', () => { - const [message] = decodeAll( - encodeSubscribeOk(7, { expires: 30_000, largestObject: { group: 41, object: 12 } }, [{ type: 0x02, value: 1 }]) - ); - - expect(message).toMatchObject({ - kind: 'subscribe-ok', - trackAlias: 7, - parameters: { expires: 30_000, largestObject: { group: 41, object: 12 } }, - }); - expect(message).toHaveProperty('trackProperties', [{ type: 0x02, value: 1 }]); - }); -}); - -describe('encodeRequestOk', () => { - it('matches relay 0.14.17 framing when acknowledging an update after content exists', () => { - const wire = Uint8Array.of(0x07, 0x00, 0x06, 0x01, 0x09, 0x80, 0xff, 0x80, 0x80); - const parameters = { largestObject: { group: 255, object: 128 } }; - - expect(encodeRequestOk(parameters)).toEqual(wire); - expect(decodeAll(wire)).toEqual([{ kind: 'request-ok', parameters, trackProperties: [] }]); - }); -}); - -describe('encodePublishDone', () => { - it('round-trips a counted stream total', () => { - const [message] = decodeAll(encodePublishDone(PUBLISH_DONE_STATUS.TRACK_ENDED, 5, 'ended')); - - expect(message).toEqual({ - kind: 'publish-done', - statusCode: PUBLISH_DONE_STATUS.TRACK_ENDED, - streamCount: 5, - reason: 'ended', - }); - }); - - it('reads the 2^64-1 "could not count" sentinel as an undefined stream count', () => { - // Status, then the 9-byte varint 0xFF..FF (2^64-1), then an empty reason. - const body = Uint8Array.of(PUBLISH_DONE_STATUS.GOING_AWAY, ...new Array(9).fill(0xff), 0x00); - const message = decodeControlMessage({ type: MESSAGE_TYPE.PUBLISH_DONE, body }); - - expect(message).toEqual({ - kind: 'publish-done', - statusCode: PUBLISH_DONE_STATUS.GOING_AWAY, - streamCount: undefined, - reason: '', - }); - }); - - it('rejects a stream count above 2^53-1 that is not the sentinel', () => { - // A 9-byte varint one bit short of the sentinel: 2^63 + …, not a count any publisher can mean. - const body = Uint8Array.of(PUBLISH_DONE_STATUS.GOING_AWAY, 0xff, 0x80, ...new Array(7).fill(0xff), 0x00); - - expect(() => decodeControlMessage({ type: MESSAGE_TYPE.PUBLISH_DONE, body })).toThrow(MoqtProtocolError); - }); -}); - -describe('encodePublishStateNotify', () => { - it('round-trips the changed parameters', () => { - const parameters: MessageParameters = { - largestObject: { group: 9, object: 4 }, - locationFilter: { type: 'relative-group', groupsBeforeNext: 0 }, - }; - const [message] = decodeAll(encodePublishStateNotify(parameters)); - - expect(message).toEqual({ kind: 'publish-state-notify', parameters }); - }); -}); - -describe('encodeRequestError', () => { - it('round-trips code, retry interval, and reason', () => { - const [message] = decodeAll(encodeRequestError(REQUEST_ERROR_CODE.DOES_NOT_EXIST, 'no such track', 1500)); - - expect(message).toEqual({ - kind: 'request-error', - errorCode: REQUEST_ERROR_CODE.DOES_NOT_EXIST, - retryInterval: 1500, - reason: 'no such track', - }); - }); -}); - -describe('encodeSetup', () => { - it('round-trips setup options as generic key-value pairs', () => { - const [message] = decodeAll( - encodeSetup([ - { type: SETUP_OPTION.MOQT_IMPLEMENTATION, value: utf8Encode('spf-test') }, - { type: SETUP_OPTION.MAX_REQUEST_UPDATES, value: 3 }, - ]) - ); - - expect(message?.kind).toBe('setup'); - - if (message?.kind !== 'setup') return; - - // Serialized in ascending type order regardless of input order. - expect(message.options.map((o) => o.type)).toEqual([ - SETUP_OPTION.MOQT_IMPLEMENTATION, - SETUP_OPTION.MAX_REQUEST_UPDATES, - ]); - expect(message.options[1]!.value).toBe(3); - }); -}); - -describe('encodeGoaway', () => { - it('encodes a zero-length URI (client rule) and round-trips the timeout', () => { - const [message] = decodeAll(encodeGoaway(500)); - - expect(message).toEqual({ kind: 'goaway', newSessionUri: '', timeout: 500 }); - }); -}); - -describe('encodePublishNamespace', () => { - it('round-trips through the decoder', () => { - const [message] = decodeAll( - encodePublishNamespace({ requestId: 1, trackNamespace: ['anon'], parameters: { forward: 1 } }) - ); - - expect(message).toMatchObject({ - kind: 'publish-namespace', - requestId: 1, - trackNamespace: ['anon'], - parameters: { forward: 1 }, - }); - }); -}); - -describe('decodeControlMessage', () => { - it('throws MoqtProtocolError for unknown message types', () => { - expect(() => decodeControlMessage({ type: 0x99, body: new Uint8Array(0) })).toThrow(MoqtProtocolError); - }); - - it('throws when the body has trailing bytes', () => { - // GOAWAY body: uri length 0, timeout 0, plus a stray trailing byte. - expect(() => decodeControlMessage({ type: MESSAGE_TYPE.GOAWAY, body: new Uint8Array([0, 0, 0xab]) })).toThrow( - MoqtProtocolError - ); - }); - - it('throws MoqtProtocolError (not RangeError) for a truncated body', () => { - // PUBLISH_NAMESPACE body cut short: request id, then no namespace — - // the RangeError from reading past the frame must be normalized so - // malformed frames terminate the session. - expect(() => decodeControlMessage({ type: MESSAGE_TYPE.PUBLISH_NAMESPACE, body: new Uint8Array([0x01]) })).toThrow( - MoqtProtocolError - ); - - // A namespace field whose declared length overruns the frame. - const body = new ByteWriter(); - - body.writeVarint(1); // request id - body.writeVarint(1); // field count - body.writeVarint(10); // field length, followed by only 2 bytes - body.writeBytes(utf8Encode('ab')); - expect(() => decodeControlMessage({ type: MESSAGE_TYPE.PUBLISH_NAMESPACE, body: body.toBytes() })).toThrow( - MoqtProtocolError - ); - }); -}); - -describe('encodeMessageParameters', () => { - it('round-trips every supported parameter', () => { - const parameters: MessageParameters = { - objectDeliveryTimeout: 100, - subgroupDeliveryTimeout: 200, - authorizationTokens: [utf8Encode('tok-a'), utf8Encode('tok-b')], - expires: 60_000, - largestObject: { group: 100, object: 3 }, - forward: 0, - subscriberPriority: 200, - locationFilter: { type: 'absolute', start: { group: 5, object: 1 }, endGroupDelta: 4 }, - groupOrder: 'descending', - fillParameters: { - fillTimeout: 500, - subscriberPriority: 8, - locationFilter: { type: 'relative-group', groupsBeforeNext: 1 }, - groupOrder: 'ascending', - }, - newGroupRequest: 42, - includeProperties: 0, - }; - const decoded = decodeMessageParameters(new ByteReader(encodeParameters(parameters))); - - expect(decoded).toEqual(parameters); - }); - - it('throws MoqtProtocolError on an unknown parameter type', () => { - // Hand-craft: 1 parameter, type 0x99 (unknown). - const writer = new ByteWriter(); - - writer.writeVarint(1); - writer.writeVarint(0x99); - expect(() => decodeMessageParameters(new ByteReader(writer.toBytes()))).toThrow(MoqtProtocolError); - }); - - // Draft-17+ vector from moq-dev/moq#3561, shipped in moq-relay 0.14.17. - it('frames LARGEST_OBJECT as two bare varints, byte-for-byte with moq-relay', () => { - const parameters = { largestObject: { group: 255, object: 128 } }; - const wire = Uint8Array.of(0x01, 0x09, 0x80, 0xff, 0x80, 0x80); - - expect(encodeParameters(parameters)).toEqual(wire); - expect(decodeMessageParameters(new ByteReader(wire))).toEqual(parameters); - }); - - it.each([ - [0x01, 0x09], - [0x01, 0x09, 0x00], - [0x01, 0x09, 0x80], - [0x01, 0x09, 0x00, 0x80], - ])('rejects a truncated LARGEST_OBJECT (case %#)', (...wire) => { - expect(() => decodeControlMessage({ type: MESSAGE_TYPE.REQUEST_OK, body: Uint8Array.from(wire) })).toThrow( - MoqtProtocolError - ); - }); - - it('keeps parameters following a small LARGEST_OBJECT aligned', () => { - const parameters: MessageParameters = { largestObject: { group: 0, object: 1 }, forward: 1, includeProperties: 0 }; - const wire = Uint8Array.of(0x03, 0x09, 0x00, 0x01, 0x07, 0x01, 0x25, 0x00); - - expect(encodeParameters(parameters)).toEqual(wire); - expect(decodeMessageParameters(new ByteReader(wire))).toEqual(parameters); - }); - - // Wire vector matches moq-relay 0.17.0, which decodes 0x35 as a bare bool (moq-dev/moq#4610). - it.each([0, 1] as const)('frames INCLUDE_PROPERTIES %i as a bare byte', (includeProperties) => { - const wire = Uint8Array.of(0x01, 0x35, includeProperties); - - expect(encodeParameters({ includeProperties })).toEqual(wire); - expect(decodeMessageParameters(new ByteReader(wire))).toEqual({ includeProperties }); - }); - - it('rejects INCLUDE_PROPERTIES values other than 0 and 1', () => { - expect(() => decodeMessageParameters(new ByteReader(Uint8Array.of(0x01, 0x35, 0x02)))).toThrow( - /INCLUDE_PROPERTIES/ - ); - }); - - it('encodes FILL_PARAMETERS as a nested parameter list', () => { - const bytes = encodeParameters({ - fillParameters: { locationFilter: { type: 'relative-group', groupsBeforeNext: 1 } }, - }); - - // count 1, type 0x23, length 4, then the nested list: count 1, type 0x21, length 1, StartGroup 1. - expect(Array.from(bytes)).toEqual([0x01, 0x23, 0x04, 0x01, 0x21, 0x01, 0x01]); - }); - - it('rejects parameters outside Table 6 inside FILL_PARAMETERS, on both sides', () => { - // Decode: FILL_PARAMETERS whose nested list carries FORWARD (0x10). - const writer = new ByteWriter(); - - writer.writeVarint(1); - writer.writeVarint(PARAMETER_TYPE.FILL_PARAMETERS); - writer.writeVarint(3); - writer.writeVarint(1); // nested count - writer.writeVarint(PARAMETER_TYPE.FORWARD); - writer.writeUint8(1); - expect(() => decodeMessageParameters(new ByteReader(writer.toBytes()))).toThrow(/FILL_PARAMETERS/); - - // Encode: a range filter type the fill scope excludes (TRACK_PROPERTY_FILTER). - expect(() => - encodeParameters({ - fillParameters: { rangeFilters: [{ type: PARAMETER_TYPE.TRACK_PROPERTY_FILTER, value: new Uint8Array(0) }] }, - }) - ).toThrow(/FILL_PARAMETERS/); - }); -}); - -describe('encodeLocationFilter', () => { - it('round-trips every filter shape', () => { - const filters: LocationFilter[] = [ - { type: 'none' }, - { type: 'next-object' }, - { type: 'relative-group', groupsBeforeNext: 0 }, - { type: 'relative-group', groupsBeforeNext: 1 }, - { type: 'relative-group', groupsBeforeNext: 5 }, - { type: 'absolute', start: { group: 3, object: 9 } }, - { type: 'absolute', start: { group: 3, object: 9 }, endGroupDelta: 0 }, - { type: 'absolute', start: { group: 3, object: 9 }, endGroupDelta: 2, endObject: 7 }, - ]; - - for (const filter of filters) { - expect(decodeLocationFilter(encodeLocationFilter(filter))).toEqual(filter); - } - }); - - it('selects the meaning by field count (§5.1.2)', () => { - expect(Array.from(encodeLocationFilter({ type: 'none' }))).toEqual([]); - expect(Array.from(encodeLocationFilter({ type: 'relative-group', groupsBeforeNext: 1 }))).toEqual([1]); - expect(Array.from(encodeLocationFilter({ type: 'next-object' }))).toEqual([0, 0]); - expect(Array.from(encodeLocationFilter({ type: 'absolute', start: { group: 3, object: 9 } }))).toEqual([3, 9]); - expect( - Array.from( - encodeLocationFilter({ type: 'absolute', start: { group: 3, object: 9 }, endGroupDelta: 2, endObject: 7 }) - ) - ).toEqual([3, 9, 2, 7]); - }); - - it('normalizes an open-ended absolute {0,0} to no filter rather than the Next Object spelling', () => { - expect(Array.from(encodeLocationFilter({ type: 'absolute', start: { group: 0, object: 0 } }))).toEqual([]); - // Bounded, {0,0} is a real absolute start. - expect( - Array.from(encodeLocationFilter({ type: 'absolute', start: { group: 0, object: 0 }, endGroupDelta: 3 })) - ).toEqual([0, 0, 3]); - }); - - it('rejects an end object without an end group', () => { - expect(() => encodeLocationFilter({ type: 'absolute', start: { group: 1, object: 0 }, endObject: 4 })).toThrow( - MoqtProtocolError - ); - }); - - it('rejects more than four fields', () => { - expect(() => decodeLocationFilter(Uint8Array.of(1, 2, 3, 4, 5))).toThrow(MoqtProtocolError); - }); - - it('rejects an end group past the supported range', () => { - const writer = new ByteWriter(); - - writer.writeVarint(Number.MAX_SAFE_INTEGER); - writer.writeVarint(0); - writer.writeVarint(1); - expect(() => decodeLocationFilter(writer.toBytes())).toThrow(MoqtProtocolError); - }); -}); - -describe('isEmptyFetchRange', () => { - const largest = { group: 4, object: 2 }; - - it('is empty for every filter before the track has content', () => { - expect(isEmptyFetchRange({ type: 'none' }, undefined)).toBe(true); - expect(isEmptyFetchRange({ type: 'relative-group', groupsBeforeNext: 1 }, undefined)).toBe(true); - expect(isEmptyFetchRange({ type: 'absolute', start: { group: 0, object: 0 } }, undefined)).toBe(true); - }); - - it('is empty when the start lies past Largest Object', () => { - expect(isEmptyFetchRange({ type: 'next-object' }, largest)).toBe(true); - expect(isEmptyFetchRange({ type: 'relative-group', groupsBeforeNext: 0 }, largest)).toBe(true); - expect(isEmptyFetchRange({ type: 'absolute', start: { group: 4, object: 3 } }, largest)).toBe(true); - expect(isEmptyFetchRange({ type: 'absolute', start: { group: 5, object: 0 } }, largest)).toBe(true); - }); - - it('is nonempty when the start is at or before Largest Object', () => { - expect(isEmptyFetchRange({ type: 'none' }, largest)).toBe(false); - expect(isEmptyFetchRange({ type: 'relative-group', groupsBeforeNext: 1 }, largest)).toBe(false); - expect(isEmptyFetchRange({ type: 'relative-group', groupsBeforeNext: 9 }, largest)).toBe(false); - expect(isEmptyFetchRange({ type: 'absolute', start: { group: 4, object: 2 } }, largest)).toBe(false); - expect(isEmptyFetchRange({ type: 'absolute', start: { group: 1, object: 7 }, endGroupDelta: 0 }, largest)).toBe( - false - ); - }); - - it('is empty only when a bounded absolute end precedes its start', () => { - const start = { group: 2, object: 5 }; - - expect(isEmptyFetchRange({ type: 'absolute', start, endGroupDelta: 0, endObject: 4 }, largest)).toBe(true); - expect(isEmptyFetchRange({ type: 'absolute', start, endGroupDelta: 0, endObject: 5 }, largest)).toBe(false); - expect(isEmptyFetchRange({ type: 'absolute', start, endGroupDelta: 1, endObject: 0 }, largest)).toBe(false); - }); -}); - -describe('encodeFetchOk', () => { - it('round-trips and rejects end-of-track values other than 0 and 1', () => { - const notEnded = encodeFetchOk(false, { group: 3, object: 9 }); - const ended = encodeFetchOk(true, { group: 3, object: 9 }); - - expect(decodeAll(notEnded)[0]).toMatchObject({ kind: 'fetch-ok', endOfTrack: false }); - expect(decodeAll(ended)[0]).toMatchObject({ kind: 'fetch-ok', endOfTrack: true }); - - // The end-of-track byte is the single position where the two differ. - const offset = notEnded.findIndex((byte, index) => byte !== ended[index]); - const invalid = notEnded.slice(); - - invalid[offset] = 2; - expect(() => decodeAll(invalid)).toThrow(MoqtProtocolError); - }); -}); - -describe('encodeKeyValuePairs', () => { - it('delta-encodes types and round-trips even/odd values', () => { - const pairs = [ - { type: 0x02, value: 7 }, - { type: 0x07, value: utf8Encode('bytes') }, - { type: 0x08, value: 1_000_000 }, - ]; - const writer = new ByteWriter(); - - encodeKeyValuePairs(writer, pairs); - const bytes = writer.toBytes(); - - // First delta is the absolute type (0x02), then 5, then 1. - expect(bytes[0]).toBe(0x02); - const decoded = decodeKeyValuePairs(new ByteReader(bytes), bytes.length); - - expect(decoded).toEqual(pairs); - }); -}); - -describe('isRetryableRequestErrorCode', () => { - it('keeps transient state-shaped failures retryable', () => { - expect(isRetryableRequestErrorCode(REQUEST_ERROR_CODE.DOES_NOT_EXIST)).toBe(true); - expect(isRetryableRequestErrorCode(REQUEST_ERROR_CODE.TIMEOUT)).toBe(true); - expect(isRetryableRequestErrorCode(REQUEST_ERROR_CODE.INTERNAL_ERROR)).toBe(true); - expect(isRetryableRequestErrorCode(REQUEST_ERROR_CODE.GOING_AWAY)).toBe(true); - expect(isRetryableRequestErrorCode(REQUEST_ERROR_CODE.EXCESSIVE_LOAD)).toBe(true); - // EXPIRED_AUTH_TOKEN has its own refresh path; the generic classifier - // must not preempt it. - expect(isRetryableRequestErrorCode(REQUEST_ERROR_CODE.EXPIRED_AUTH_TOKEN)).toBe(true); - }); - - it('treats request-shaped rejections as permanent', () => { - expect(isRetryableRequestErrorCode(REQUEST_ERROR_CODE.UNAUTHORIZED)).toBe(false); - expect(isRetryableRequestErrorCode(REQUEST_ERROR_CODE.MALFORMED_AUTH_TOKEN)).toBe(false); - expect(isRetryableRequestErrorCode(REQUEST_ERROR_CODE.NOT_SUPPORTED)).toBe(false); - expect(isRetryableRequestErrorCode(REQUEST_ERROR_CODE.MALFORMED_TRACK)).toBe(false); - expect(isRetryableRequestErrorCode(REQUEST_ERROR_CODE.INVALID_FILTER)).toBe(false); - expect(isRetryableRequestErrorCode(REQUEST_ERROR_CODE.REDIRECT)).toBe(false); - }); - - it('degrades unknown codes to retryable, not dead', () => { - expect(isRetryableRequestErrorCode(0x7fff)).toBe(true); - }); -}); - -describe('isRetryablePublishDoneStatus', () => { - it('keeps publisher/relay life-cycle ends retryable', () => { - expect(isRetryablePublishDoneStatus(PUBLISH_DONE_STATUS.TRACK_ENDED)).toBe(true); - expect(isRetryablePublishDoneStatus(PUBLISH_DONE_STATUS.GOING_AWAY)).toBe(true); - expect(isRetryablePublishDoneStatus(PUBLISH_DONE_STATUS.TOO_FAR_BEHIND)).toBe(true); - expect(isRetryablePublishDoneStatus(0x7fff)).toBe(true); - }); - - it('treats auth-shaped and malformed-track ends as permanent', () => { - expect(isRetryablePublishDoneStatus(PUBLISH_DONE_STATUS.UNAUTHORIZED)).toBe(false); - expect(isRetryablePublishDoneStatus(PUBLISH_DONE_STATUS.EXPIRED)).toBe(false); - expect(isRetryablePublishDoneStatus(PUBLISH_DONE_STATUS.MALFORMED_TRACK)).toBe(false); - }); -}); diff --git a/packages/spf/src/network/moqt/tests/helpers/transport-pair.ts b/packages/spf/src/network/moqt/tests/helpers/transport-pair.ts deleted file mode 100644 index ee96a1fc10..0000000000 --- a/packages/spf/src/network/moqt/tests/helpers/transport-pair.ts +++ /dev/null @@ -1,86 +0,0 @@ -/** - * Symmetric in-memory `MoqtTransport` pair for loopback tests: two transports whose stream-creation methods surface on - * the peer's incoming stream queues, so a publish session on one side can talk to a subscribe session on the other over - * real (in-process) WHATWG streams — the same structural seam a `WebTransport` satisfies in production. - */ -import type { BidirectionalStreamLike } from '../../request-stream'; -import type { MoqtTransport } from '../../session'; - -interface PushChannel { - stream: ReadableStream; - push(value: T): void; -} - -function pushChannel(): PushChannel { - let controller!: ReadableStreamDefaultController; - const stream = new ReadableStream({ - start(c) { - controller = c; - }, - }); - - return { stream, push: (value) => controller.enqueue(value) }; -} - -export interface TransportPair { - client: MoqtTransport; - server: MoqtTransport; -} - -/** Create two transports wired back-to-back. */ -export function createTransportPair(): TransportPair { - const makeSide = () => ({ - incomingUni: pushChannel>(), - incomingBidi: pushChannel(), - resolveClosed: undefined as ((info: unknown) => void) | undefined, - }); - const a = makeSide(); - const b = makeSide(); - - let closed = false; - const closedPromises = [a, b].map( - (side) => - new Promise((resolve) => { - side.resolveClosed = resolve; - }) - ); - - const closeBoth = (info?: { closeCode?: number; reason?: string }): void => { - if (closed) return; - - closed = true; - a.resolveClosed?.(info); - b.resolveClosed?.(info); - }; - - const makeTransport = (local: typeof a, remote: typeof b, closedPromise: Promise): MoqtTransport => ({ - incomingUnidirectionalStreams: local.incomingUni.stream, - incomingBidirectionalStreams: local.incomingBidi.stream, - async createUnidirectionalStream() { - if (closed) throw new Error('transport closed'); - - const pipe = new TransformStream(); - - remote.incomingUni.push(pipe.readable); - return pipe.writable; - }, - async createBidirectionalStream() { - if (closed) throw new Error('transport closed'); - - const localToRemote = new TransformStream(); - const remoteToLocal = new TransformStream(); - - remote.incomingBidi.push({ readable: localToRemote.readable, writable: remoteToLocal.writable }); - return { readable: remoteToLocal.readable, writable: localToRemote.writable }; - }, - close(closeInfo) { - closeBoth(closeInfo); - }, - closed: closedPromise, - }); - - return { - client: makeTransport(a, b, closedPromises[0]!), - server: makeTransport(b, a, closedPromises[1]!), - }; -} diff --git a/packages/spf/src/network/moqt/tests/object-stream.test.ts b/packages/spf/src/network/moqt/tests/object-stream.test.ts deleted file mode 100644 index de3e89f8f2..0000000000 --- a/packages/spf/src/network/moqt/tests/object-stream.test.ts +++ /dev/null @@ -1,449 +0,0 @@ -import { describe, expect, it } from 'vite-plus/test'; - -import { ByteWriter, StreamReader, utf8Encode } from '../bytes'; -import { MoqtProtocolError } from '../errors'; -import { - type FetchStreamEntry, - isSubgroupHeaderType, - MAX_OBJECT_PAYLOAD_LENGTH, - MAX_OBJECT_PROPERTIES_LENGTH, - type MoqtObject, - readFetchEntries, - readFetchHeader, - readSubgroupHeader, - readSubgroupObjects, -} from '../object-stream'; - -function streamOf(bytes: Uint8Array, chunkSize = Number.POSITIVE_INFINITY): ReadableStream { - return new ReadableStream({ - start(controller) { - for (let offset = 0; offset < bytes.length; offset += chunkSize) { - controller.enqueue(bytes.subarray(offset, Math.min(offset + chunkSize, bytes.length))); - } - - controller.close(); - }, - }); -} - -/** Build a subgroup stream: header (with explicit subgroup id + priority) and objects. */ -function encodeSubgroupStream(options: { - type: number; - trackAlias: number; - groupId: number; - subgroupId?: number; - priority?: number; - objects: { objectIdDelta: number; payload?: Uint8Array; status?: number; properties?: Uint8Array }[]; -}): Uint8Array { - const writer = new ByteWriter(); - - writer.writeVarint(options.type); - writer.writeVarint(options.trackAlias); - writer.writeVarint(options.groupId); - - if (options.subgroupId !== undefined) writer.writeVarint(options.subgroupId); - - if (options.priority !== undefined) writer.writeUint8(options.priority); - - for (const object of options.objects) { - writer.writeVarint(object.objectIdDelta); - - if (object.properties !== undefined) { - writer.writeVarint(object.properties.length); - writer.writeBytes(object.properties); - } - - const payload = object.payload ?? new Uint8Array(0); - - writer.writeVarint(payload.length); - - if (payload.length === 0) writer.writeVarint(object.status ?? 0x0); - else writer.writeBytes(payload); - } - - return writer.toBytes(); -} - -async function collect(iterable: AsyncIterable): Promise { - const items: T[] = []; - - for await (const item of iterable) items.push(item); - - return items; -} - -describe('isSubgroupHeaderType', () => { - it('accepts the valid 0b0XX1XXXX ranges', () => { - for (const type of [0x10, 0x15, 0x18, 0x1d, 0x30, 0x3d, 0x50, 0x5d, 0x70, 0x7d]) { - expect(isSubgroupHeaderType(type)).toBe(true); - } - }); - - it('rejects reserved SUBGROUP_ID_MODE 0b11 and out-of-form values', () => { - for (const type of [0x16, 0x17, 0x1e, 0x1f, 0x36, 0x76, 0x7e]) { - expect(isSubgroupHeaderType(type)).toBe(false); - } - - for (const type of [0x00, 0x05, 0x0f, 0x20, 0x2f, 0x40, 0x80, 0x2f00]) { - expect(isSubgroupHeaderType(type)).toBe(false); - } - }); -}); - -describe('readSubgroupHeader', () => { - it('parses an explicit-subgroup-id header with priority', () => { - // 0x14: bit4 set, mode 0b10 (explicit), no properties, priority present. - const bytes = encodeSubgroupStream({ - type: 0x14, - trackAlias: 3, - groupId: 41, - subgroupId: 2, - priority: 128, - objects: [], - }); - const reader = new StreamReader(streamOf(bytes)); - - return reader.readVarint().then(async (type) => { - const header = await readSubgroupHeader(reader, type); - - expect(header).toMatchObject({ - trackAlias: 3, - groupId: 41, - subgroupIdMode: 'explicit', - subgroupId: 2, - priority: 128, - hasProperties: false, - endOfGroup: false, - firstObject: false, - }); - }); - }); - - it('parses default-priority and end-of-group flag bits', async () => { - // 0x38: bit4 set, mode 0b00 (zero), END_OF_GROUP (0x08), DEFAULT_PRIORITY (0x20). - const bytes = encodeSubgroupStream({ type: 0x38, trackAlias: 1, groupId: 7, objects: [] }); - const reader = new StreamReader(streamOf(bytes)); - const header = await readSubgroupHeader(reader, await reader.readVarint()); - - expect(header).toMatchObject({ subgroupIdMode: 'zero', endOfGroup: true, priority: undefined }); - }); -}); - -describe('readSubgroupObjects', () => { - it('delta-decodes object IDs (first absolute, then +delta+1)', async () => { - const bytes = encodeSubgroupStream({ - type: 0x38, - trackAlias: 1, - groupId: 7, - objects: [ - { objectIdDelta: 0, payload: utf8Encode('a') }, - { objectIdDelta: 0, payload: utf8Encode('b') }, // 0 + 0 + 1 = 1 - { objectIdDelta: 2, payload: utf8Encode('c') }, // 1 + 2 + 1 = 4 - ], - }); - const reader = new StreamReader(streamOf(bytes, 3)); // tiny chunks - - await reader.readVarint(); - const header = await readSubgroupHeader(reader, 0x38); - const objects = await collect(readSubgroupObjects(reader, header)); - - expect(objects.map((o: MoqtObject) => o.objectId)).toEqual([0, 1, 4]); - expect(objects.map((o) => new TextDecoder().decode(o.payload))).toEqual(['a', 'b', 'c']); - expect(objects[0]).toMatchObject({ groupId: 7, subgroupId: 0, status: 'normal' }); - }); - - it('resolves subgroup id from the first object in first-object-id mode', async () => { - // 0x32: bit4 set... 0x32 = 0b0110010 — bit4 (0x10) set, mode bits (0x06)>>1 = 0b01, DEFAULT_PRIORITY set. - const bytes = encodeSubgroupStream({ - type: 0x32, - trackAlias: 1, - groupId: 9, - objects: [{ objectIdDelta: 5, payload: utf8Encode('x') }], - }); - const reader = new StreamReader(streamOf(bytes)); - - await reader.readVarint(); - const header = await readSubgroupHeader(reader, 0x32); - - expect(header.subgroupIdMode).toBe('first-object-id'); - const objects = await collect(readSubgroupObjects(reader, header)); - - expect(objects[0]).toMatchObject({ objectId: 5, subgroupId: 5 }); - }); - - it('parses zero-length objects with explicit status', async () => { - const bytes = encodeSubgroupStream({ - type: 0x38, - trackAlias: 1, - groupId: 7, - objects: [ - { objectIdDelta: 0, payload: utf8Encode('a') }, - { objectIdDelta: 0, status: 0x3 }, // end of group - ], - }); - const reader = new StreamReader(streamOf(bytes)); - - await reader.readVarint(); - const header = await readSubgroupHeader(reader, 0x38); - const objects = await collect(readSubgroupObjects(reader, header)); - - expect(objects[1]).toMatchObject({ objectId: 1, status: 'end-of-group', payload: new Uint8Array(0) }); - }); - - it('throws MoqtProtocolError on an unknown object status', async () => { - const bytes = encodeSubgroupStream({ - type: 0x38, - trackAlias: 1, - groupId: 7, - objects: [{ objectIdDelta: 0, status: 0x9 }], - }); - const reader = new StreamReader(streamOf(bytes)); - - await reader.readVarint(); - const header = await readSubgroupHeader(reader, 0x38); - - await expect(collect(readSubgroupObjects(reader, header))).rejects.toThrow(MoqtProtocolError); - }); - - it('throws MoqtProtocolError when delta-decoded object IDs overflow the varint range', async () => { - const bytes = encodeSubgroupStream({ - type: 0x38, - trackAlias: 1, - groupId: 7, - objects: [ - { objectIdDelta: Number.MAX_SAFE_INTEGER, payload: utf8Encode('a') }, - { objectIdDelta: 0, payload: utf8Encode('b') }, // 2^53-1 + 0 + 1 overflows - ], - }); - const reader = new StreamReader(streamOf(bytes)); - - await reader.readVarint(); - const header = await readSubgroupHeader(reader, 0x38); - - await expect(collect(readSubgroupObjects(reader, header))).rejects.toThrow(MoqtProtocolError); - }); - - // The declared lengths below are followed by NO bytes: reaching the read - // would surface a RangeError from the stream, so a MoqtProtocolError proves - // the declaration is rejected before anything is allocated. - it('rejects a payload length beyond MAX_OBJECT_PAYLOAD_LENGTH before allocating', async () => { - const writer = new ByteWriter(); - - writer.writeVarint(0x38); - writer.writeVarint(1); // track alias - writer.writeVarint(7); // group id - writer.writeVarint(0); // object id delta - writer.writeVarint(MAX_OBJECT_PAYLOAD_LENGTH + 1); - const reader = new StreamReader(streamOf(writer.toBytes())); - - await reader.readVarint(); - const header = await readSubgroupHeader(reader, 0x38); - - await expect(collect(readSubgroupObjects(reader, header))).rejects.toThrow(/payload length .* exceeds/); - }); - - it('rejects a properties length beyond MAX_OBJECT_PROPERTIES_LENGTH before allocating', async () => { - const writer = new ByteWriter(); - - writer.writeVarint(0x39); // 0x38 | PROPERTIES - writer.writeVarint(1); - writer.writeVarint(7); - writer.writeVarint(0); // object id delta - writer.writeVarint(MAX_OBJECT_PROPERTIES_LENGTH + 1); - const reader = new StreamReader(streamOf(writer.toBytes())); - - await reader.readVarint(); - const header = await readSubgroupHeader(reader, 0x39); - - await expect(collect(readSubgroupObjects(reader, header))).rejects.toThrow(/properties length .* exceeds/); - }); - - it('accepts a payload exactly at MAX_OBJECT_PAYLOAD_LENGTH', async () => { - const bytes = encodeSubgroupStream({ - type: 0x38, - trackAlias: 1, - groupId: 7, - objects: [{ objectIdDelta: 0, payload: new Uint8Array(MAX_OBJECT_PAYLOAD_LENGTH) }], - }); - const reader = new StreamReader(streamOf(bytes)); - - await reader.readVarint(); - const header = await readSubgroupHeader(reader, 0x38); - const objects = await collect(readSubgroupObjects(reader, header)); - - expect(objects[0]!.payload.length).toBe(MAX_OBJECT_PAYLOAD_LENGTH); - }); - - it('accepts a properties block holding a maximum-size KVP value', async () => { - // One odd-type KVP whose byte value is the largest the KVP codec - // permits (2^16-1): the aggregate block bound must not reject what the - // per-value rule allows. - const props = new ByteWriter(); - - props.writeVarint(0x07); - props.writeVarint(0xffff); - props.writeBytes(new Uint8Array(0xffff).fill(1)); - const bytes = encodeSubgroupStream({ - type: 0x39, // 0x38 | PROPERTIES - trackAlias: 1, - groupId: 7, - objects: [{ objectIdDelta: 0, payload: utf8Encode('a'), properties: props.toBytes() }], - }); - const reader = new StreamReader(streamOf(bytes)); - - await reader.readVarint(); - const header = await readSubgroupHeader(reader, 0x39); - const objects = await collect(readSubgroupObjects(reader, header)); - - expect(objects[0]!.properties).toHaveLength(1); - expect(objects[0]!.properties[0]).toMatchObject({ type: 0x07 }); - expect((objects[0]!.properties[0]!.value as Uint8Array).length).toBe(0xffff); - }); - - it('parses per-object properties when the header PROPERTIES bit is set', async () => { - // Properties KVP: type 0x06 (Timestamp), varint value 90000. - const props = new ByteWriter(); - - props.writeVarint(0x06); - props.writeVarint(90_000); - const bytes = encodeSubgroupStream({ - type: 0x39, // 0x38 | PROPERTIES - trackAlias: 1, - groupId: 7, - objects: [{ objectIdDelta: 0, payload: utf8Encode('a'), properties: props.toBytes() }], - }); - const reader = new StreamReader(streamOf(bytes)); - - await reader.readVarint(); - const header = await readSubgroupHeader(reader, 0x39); - const objects = await collect(readSubgroupObjects(reader, header)); - - expect(objects[0]!.properties).toEqual([{ type: 0x06, value: 90_000 }]); - }); -}); - -describe('readFetchEntries', () => { - function encodeFetchStream(build: (writer: ByteWriter) => void): Uint8Array { - const writer = new ByteWriter(); - - writer.writeVarint(0x05); // FETCH_HEADER - writer.writeVarint(8); // request id - build(writer); - return writer.toBytes(); - } - - it('parses the fetch header request id', async () => { - const reader = new StreamReader(streamOf(encodeFetchStream(() => {}))); - - await reader.readVarint(); - expect(await readFetchHeader(reader)).toEqual({ requestId: 8 }); - }); - - it('decodes absolute-first then delta-encoded objects', async () => { - const bytes = encodeFetchStream((w) => { - // First object: flags need GROUP_ID_DELTA (0x08) + OBJECT_ID_DELTA (0x04) - // + PRIORITY (0x10); subgroup mode 0 (subgroup id zero). - w.writeVarint(0x1c); - w.writeVarint(10); // group id (absolute) - w.writeVarint(0); // object id (absolute) - w.writeUint8(100); // priority - w.writeVarint(1); // payload length - w.writeBytes(utf8Encode('a')); - // Second object: same group, next object id (no fields at all). - w.writeVarint(0x00); - w.writeVarint(1); - w.writeBytes(utf8Encode('b')); - // Third object: next group (delta 0 → +1), object id resets via delta. - w.writeVarint(0x0c); - w.writeVarint(0); // group delta → 10 + 0 + 1 = 11 - w.writeVarint(0); // object id absolute within new group - w.writeVarint(1); - w.writeBytes(utf8Encode('c')); - }); - const reader = new StreamReader(streamOf(bytes, 4)); - - await reader.readVarint(); - await readFetchHeader(reader); - const entries = await collect(readFetchEntries(reader)); - - expect(entries.map((e: FetchStreamEntry) => (e.kind === 'object' ? [e.groupId, e.objectId] : null))).toEqual([ - [10, 0], - [10, 1], - [11, 0], - ]); - }); - - it('rejects a payload length beyond MAX_OBJECT_PAYLOAD_LENGTH before allocating', async () => { - const bytes = encodeFetchStream((w) => { - w.writeVarint(0x1c); // GROUP_ID_DELTA | OBJECT_ID_DELTA | PRIORITY - w.writeVarint(10); // group id - w.writeVarint(0); // object id - w.writeUint8(100); // priority - w.writeVarint(MAX_OBJECT_PAYLOAD_LENGTH + 1); // no bytes follow - }); - const reader = new StreamReader(streamOf(bytes)); - - await reader.readVarint(); - await readFetchHeader(reader); - await expect(collect(readFetchEntries(reader))).rejects.toThrow(/payload length .* exceeds/); - }); - - it('yields end-of-range markers for all three statuses (§11.4.4, Table 7)', async () => { - const bytes = encodeFetchStream((w) => { - w.writeVarint(0x8c); // End of Non-Existent Range - w.writeVarint(4); - w.writeVarint(20); - w.writeVarint(0x10c); // End of Unknown Range - w.writeVarint(5); - w.writeVarint(0); - w.writeVarint(0x20c); // End of Timed-Out Range - w.writeVarint(6); - w.writeVarint(2); - }); - const reader = new StreamReader(streamOf(bytes)); - - await reader.readVarint(); - await readFetchHeader(reader); - const entries = await collect(readFetchEntries(reader)); - - expect(entries).toEqual([ - { kind: 'end-of-range', status: 'non-existent', groupId: 4, objectId: 20 }, - { kind: 'end-of-range', status: 'unknown', groupId: 5, objectId: 0 }, - { kind: 'end-of-range', status: 'timed-out', groupId: 6, objectId: 2 }, - ]); - }); - - it('rejects a first object that references the prior object', async () => { - const bytes = encodeFetchStream((w) => { - w.writeVarint(0x00); // no group/object deltas on the first object - }); - const reader = new StreamReader(streamOf(bytes)); - - await reader.readVarint(); - await readFetchHeader(reader); - await expect(collect(readFetchEntries(reader))).rejects.toThrow(MoqtProtocolError); - }); - - it('rejects delta-decoded locations that overflow the varint range', async () => { - const bytes = encodeFetchStream((w) => { - // First object: absolute group at the varint ceiling. - w.writeVarint(0x1c); - w.writeVarint(Number.MAX_SAFE_INTEGER); // group id (absolute) - w.writeVarint(0); // object id (absolute) - w.writeUint8(100); // priority - w.writeVarint(1); // payload length - w.writeBytes(utf8Encode('a')); - // Second object: group delta 0 → 2^53-1 + 0 + 1 overflows. - w.writeVarint(0x0c); - w.writeVarint(0); // group delta - w.writeVarint(0); // object id - w.writeVarint(1); - w.writeBytes(utf8Encode('b')); - }); - const reader = new StreamReader(streamOf(bytes)); - - await reader.readVarint(); - await readFetchHeader(reader); - await expect(collect(readFetchEntries(reader))).rejects.toThrow(MoqtProtocolError); - }); -}); diff --git a/packages/spf/src/network/moqt/tests/publish-direction.test.ts b/packages/spf/src/network/moqt/tests/publish-direction.test.ts deleted file mode 100644 index faf05148f9..0000000000 --- a/packages/spf/src/network/moqt/tests/publish-direction.test.ts +++ /dev/null @@ -1,211 +0,0 @@ -/** - * Publish-direction codec round-trips: the encode↔decode pairs the publish session exercises (the announce-and-serve - * NAMESPACE entries, the SUBSCRIBE_OK/REQUEST_OK responses, inbound REQUEST_UPDATE, and the legacy PUBLISH/PUBLISH_DONE - * shapes the codec keeps for symmetric fakes) against the existing decoders as the golden reference — plus byte-exact - * pins where moq-lite-rs's decoder is stricter than a round-trip can prove. - */ -import { describe, expect, it } from 'vite-plus/test'; - -import { utf8Encode } from '../bytes'; -import { - ControlMessageDeframer, - decodeControlMessage, - encodeNamespace, - encodeNamespaceDone, - encodePublish, - encodePublishDone, - encodeRequestOk, - encodeRequestUpdate, - encodeSubscribeOk, - PUBLISH_DONE_STATUS, - TRACK_PROPERTY, -} from '../control-messages'; - -function decodeOne(bytes: Uint8Array) { - const frames = new ControlMessageDeframer().push(bytes); - - expect(frames).toHaveLength(1); - return decodeControlMessage(frames[0]!); -} - -describe('encodePublish', () => { - it('round-trips the publisher-initiated track offer', () => { - const message = decodeOne( - encodePublish( - { - requestId: 4, - trackNamespace: ['live', 'abc123'], - trackName: 'video', - trackAlias: 2, - parameters: { forward: 1, authorizationTokens: [utf8Encode('token')] }, - }, - [{ type: 0x02, value: 7 }] - ) - ); - - expect(message).toEqual({ - kind: 'publish', - requestId: 4, - trackNamespace: ['live', 'abc123'], - trackName: 'video', - trackAlias: 2, - parameters: { forward: 1, authorizationTokens: [utf8Encode('token')] }, - trackProperties: [{ type: 0x02, value: 7 }], - }); - }); -}); - -describe('encodePublishDone', () => { - it('round-trips status, stream count, and reason', () => { - const message = decodeOne(encodePublishDone(PUBLISH_DONE_STATUS.TRACK_ENDED, 12, 'stopped')); - - expect(message).toEqual({ - kind: 'publish-done', - statusCode: PUBLISH_DONE_STATUS.TRACK_ENDED, - streamCount: 12, - 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', () => { - it('round-trips the publisher answer to an inbound SUBSCRIBE', () => { - const message = decodeOne(encodeSubscribeOk(5, { expires: 0 }, [{ type: 0x02, value: 1 }])); - - expect(message).toEqual({ - kind: 'subscribe-ok', - trackAlias: 5, - parameters: { expires: 0 }, - trackProperties: [{ type: 0x02, value: 1 }], - }); - }); -}); - -describe('encodeRequestOk', () => { - it('round-trips the PUBLISH_OK-role response with parameters', () => { - const message = decodeOne(encodeRequestOk({ forward: 1 })); - - expect(message).toEqual({ kind: 'request-ok', parameters: { forward: 1 }, trackProperties: [] }); - }); -}); - -describe('encodeRequestUpdate', () => { - it('round-trips the update a publisher receives on its request streams', () => { - const message = decodeOne(encodeRequestUpdate(4, { forward: 0, subscriberPriority: 8 })); - - expect(message).toEqual({ - kind: 'request-update', - requestId: 4, - parameters: { forward: 0, subscriberPriority: 8 }, - }); - }); -}); - -describe('encodeNamespace', () => { - it('round-trips the announce entry', () => { - const message = decodeOne(encodeNamespace(['live', 'abc123'])); - - expect(message).toEqual({ kind: 'namespace', trackNamespaceSuffix: ['live', 'abc123'] }); - }); - - it('writes the suffix tuple and nothing else', () => { - // moq-lite-rs requires the body to END with the tuple: even a zero - // parameter count after it is a WrongSize error that kills the - // announce stream. - expect(encodeNamespace(['abc123'])).toEqual( - new Uint8Array([0x08, 0x00, 0x08, 0x01, 0x06, ...utf8Encode('abc123')]) - ); - }); - - it('encodes announcing the prefix itself as an empty tuple', () => { - expect(encodeNamespace([])).toEqual(new Uint8Array([0x08, 0x00, 0x01, 0x00])); - }); -}); - -describe('encodeNamespaceDone', () => { - it('round-trips the retraction with the same body shape', () => { - const message = decodeOne(encodeNamespaceDone(['live', 'abc123'])); - - expect(message).toEqual({ kind: 'namespace-done', trackNamespaceSuffix: ['live', 'abc123'] }); - expect(encodeNamespaceDone(['abc123'])).toEqual( - new Uint8Array([0x0e, 0x00, 0x08, 0x01, 0x06, ...utf8Encode('abc123')]) - ); - }); -}); - -describe('decodeControlMessage', () => { - it('accepts a SUBSCRIBE laid out exactly as moq-lite-rs writes it', () => { - // Hand-assembled from the relay's `write_subscribe` at moq-relay - // 0.14.14 on draft-20: delta-encoded ascending parameter types; - // FORWARD (0x10), SUBSCRIBER_PRIORITY (0x20), and GROUP_ORDER (0x22) - // as single RAW bytes (not varints — pinned with a priority of 0x80, - // which a varint decoder would misread as a two-byte prefix); - // LOCATION_FILTER (0x21) length-prefixed holding the single field 0x1 - // (`relative-group 1`: the current group from object 0). - const body = [ - 0x05, // request id - 0x02, // namespace: 2 fields - 0x04, - ...utf8Encode('live'), - 0x06, - ...utf8Encode('abc123'), - 0x05, // track name - ...utf8Encode('video'), - 0x04, // parameter count - 0x10, // +0x10 → FORWARD - 0x01, // raw byte: true - 0x10, // +0x10 → SUBSCRIBER_PRIORITY - 0x80, // raw byte 128 - 0x01, // +0x01 → LOCATION_FILTER - 0x01, // length 1 - 0x01, // relative-group 1 - 0x01, // +0x01 → GROUP_ORDER - 0x02, // raw byte: descending - ]; - const message = decodeOne(new Uint8Array([0x03, 0x00, body.length, ...body])); - - expect(message).toEqual({ - kind: 'subscribe', - requestId: 5, - trackNamespace: ['live', 'abc123'], - trackName: 'video', - parameters: { - forward: 1, - subscriberPriority: 0x80, - locationFilter: { type: 'relative-group', groupsBeforeNext: 1 }, - groupOrder: 'descending', - }, - }); - }); -}); - -describe('encodeRequestOk (draft-20 byte shape)', () => { - it('emits the bare parameter-count body a solicitation acceptance needs', () => { - // The publisher's REQUEST_OK to a SUBSCRIBE_NAMESPACE carries no - // request id and no parameters — moq-lite-rs decodes exactly - // `[type][u16 1][0x00]` and anything longer is a decode error on the - // announce path. - expect(encodeRequestOk()).toEqual(new Uint8Array([0x07, 0x00, 0x01, 0x00])); - }); -}); - -describe('encodeSubscribeOk (serving shape)', () => { - it('carries the alias, no parameters, and the microsecond TIMESCALE property', () => { - const bytes = encodeSubscribeOk(11, {}, [{ type: TRACK_PROPERTY.TIMESCALE, value: 1_000_000 }]); - const message = decodeOne(bytes); - - expect(message).toEqual({ - kind: 'subscribe-ok', - trackAlias: 11, - parameters: {}, - trackProperties: [{ type: TRACK_PROPERTY.TIMESCALE, value: 1_000_000 }], - }); - }); -}); diff --git a/packages/spf/src/network/moqt/tests/session.test.ts b/packages/spf/src/network/moqt/tests/session.test.ts deleted file mode 100644 index 53e882ca00..0000000000 --- a/packages/spf/src/network/moqt/tests/session.test.ts +++ /dev/null @@ -1,1008 +0,0 @@ -import { describe, expect, it, vi } from 'vite-plus/test'; - -import { ByteWriter, StreamReader, utf8Encode } from '../bytes'; -import { - type ControlMessage, - ControlMessageDeframer, - decodeControlMessage, - encodePublishDone, - encodePublishNamespace, - encodePublishStateNotify, - encodeRequestError, - encodeRequestOk, - encodeSetup, - encodeSubscribeOk, - type LocationFilter, - PUBLISH_DONE_STATUS, - REQUEST_ERROR_CODE, -} from '../control-messages'; -import type { MoqtObject } from '../object-stream'; -import type { BidirectionalStreamLike } from '../request-stream'; -import { createMoqtSession, type MoqtSessionCallbacks, type MoqtTransport } from '../session'; - -// ============================================================================ -// In-memory transport fake — the same seam pattern as SPF's fetch injection. -// ============================================================================ - -interface PushChannel { - stream: ReadableStream; - push(value: T): void; - close(): void; -} - -function pushChannel(): PushChannel { - let controller!: ReadableStreamDefaultController; - const stream = new ReadableStream({ - start(c) { - controller = c; - }, - }); - - return { - stream, - push: (value) => controller.enqueue(value), - close: () => controller.close(), - }; -} - -/** Server-side view of one client-initiated bidirectional stream. */ -interface ServerRequestStream { - /** Decoded control messages received from the client, in order. */ - messages: ControlMessage[]; - /** Resolves when the first client message has been decoded. */ - firstMessage: Promise; - send(bytes: Uint8Array): Promise; - fin(): Promise; - reset(reason?: unknown): void; -} - -function createFakeTransport() { - const incomingUni = pushChannel>(); - const incomingBidi = pushChannel(); - const clientUniStreams: ReadableStream[] = []; - const requestStreams: ServerRequestStream[] = []; - const requestWaiters: ((stream: ServerRequestStream) => void)[] = []; - let closeInfo: { closeCode?: number; reason?: string } | undefined; - let resolveClosed!: (info: unknown) => void; - const closed = new Promise((resolve) => { - resolveClosed = resolve; - }); - - const transport: MoqtTransport = { - incomingUnidirectionalStreams: incomingUni.stream, - incomingBidirectionalStreams: incomingBidi.stream, - async createUnidirectionalStream() { - const pipe = new TransformStream(); - - clientUniStreams.push(pipe.readable); - return pipe.writable; - }, - async createBidirectionalStream() { - const clientToServer = new TransformStream(); - const serverToClient = new TransformStream(); - const writer = serverToClient.writable.getWriter(); - - const messages: ControlMessage[] = []; - let resolveFirst!: (message: ControlMessage) => void; - const firstMessage = new Promise((resolve) => { - resolveFirst = resolve; - }); - - // Server-side read pump for the client's messages. - void (async () => { - const reader = clientToServer.readable.getReader(); - const deframer = new ControlMessageDeframer(); - - try { - while (true) { - const { done, value } = await reader.read(); - if (done) break; - - for (const frame of deframer.push(value)) { - const message = decodeControlMessage(frame); - - messages.push(message); - - if (messages.length === 1) resolveFirst(message); - } - } - } catch { - // client reset its sending direction - } - })(); - - const serverStream: ServerRequestStream = { - messages, - firstMessage, - send: (bytes) => writer.write(bytes), - fin: () => writer.close(), - reset: (reason) => { - writer.abort(reason).catch(() => {}); - }, - }; - - requestStreams.push(serverStream); - requestWaiters.shift()?.(serverStream); - return { readable: serverToClient.readable, writable: clientToServer.writable }; - }, - close(info) { - closeInfo = info; - resolveClosed(info); - }, - closed, - }; - - return { - transport, - /** The SETUP control stream the client opened (first client uni stream). */ - async clientControlStream(): Promise { - await vi.waitFor(() => { - if (clientUniStreams.length === 0) throw new Error('no client uni stream yet'); - }); - return new StreamReader(clientUniStreams[0]!); - }, - /** Wait for the next client-initiated request stream. */ - nextRequestStream(): Promise { - const existing = requestStreams.shift(); - if (existing) return Promise.resolve(existing); - - return new Promise((resolve) => requestWaiters.push(resolve)); - }, - /** Open the server's control stream and send its SETUP. */ - sendServerSetup(): void { - const pipe = new TransformStream(); - const writer = pipe.writable.getWriter(); - - void writer.write(encodeSetup([])); - incomingUni.push(pipe.readable); - }, - /** Open a unidirectional data stream to the client. */ - openDataStream(bytes: Uint8Array): void { - const pipe = new TransformStream(); - const writer = pipe.writable.getWriter(); - - void writer.write(bytes).then(() => writer.close()); - incomingUni.push(pipe.readable); - }, - /** Open a unidirectional data stream the test writes to (and may reset). */ - openControlledDataStream(): { write(bytes: Uint8Array): Promise; reset(error: unknown): void } { - const pipe = new TransformStream(); - const writer = pipe.writable.getWriter(); - - incomingUni.push(pipe.readable); - return { - write: (bytes) => writer.write(bytes), - reset: (error) => { - writer.abort(error).catch(() => {}); - }, - }; - }, - openIncomingBidi(bytes: Uint8Array): { responses: Promise } { - const serverToClient = new TransformStream(); - const clientToServer = new TransformStream(); - const writer = serverToClient.writable.getWriter(); - - void writer.write(bytes).then(() => writer.close()); - incomingBidi.push({ readable: serverToClient.readable, writable: clientToServer.writable }); - const responses = (async () => { - const chunks: Uint8Array[] = []; - const reader = clientToServer.readable.getReader(); - - while (true) { - const { done, value } = await reader.read(); - if (done) break; - - chunks.push(value); - } - - return chunks; - })(); - - return { responses }; - }, - getCloseInfo: () => closeInfo, - /** Simulate a transport-side drop (peer/network close, not a local `close()`). */ - dropTransport: () => resolveClosed(undefined), - }; -} - -/** Encode a one-object subgroup stream for `trackAlias` (type 0x38: subgroup 0, default priority, end-of-group). */ -function encodeSubgroup(trackAlias: number, groupId: number, payload: Uint8Array, objectId = 0): Uint8Array { - const writer = new ByteWriter(); - - writer.writeVarint(0x38); - writer.writeVarint(trackAlias); - writer.writeVarint(groupId); - writer.writeVarint(objectId); // first object id (absolute) - writer.writeVarint(payload.length); - writer.writeBytes(payload); - return writer.toBytes(); -} - -/** The fetch range playback would ask for if it fetched: the current group from its start. */ -const CURRENT_GROUP: LocationFilter = { type: 'relative-group', groupsBeforeNext: 1 }; - -function createSessionHarness(callbacks?: MoqtSessionCallbacks) { - const fake = createFakeTransport(); - const session = createMoqtSession(fake.transport, { callbacks, unknownAliasTimeoutMs: 200 }); - - return { ...fake, session }; -} - -describe('createMoqtSession', () => { - it('sends SETUP on a fresh unidirectional control stream', async () => { - const harness = createSessionHarness(); - const control = await harness.clientControlStream(); - const type = await control.readVarint(); - - expect(type).toBe(0x2f00); - const high = await control.readUint8(); - const low = await control.readUint8(); - const body = await control.readBytes(high * 256 + low); - const setup = decodeControlMessage({ type, body }); - - expect(setup.kind).toBe('setup'); - harness.session.destroy(); - }); - - it('resolves ready and reports server options once the server SETUP arrives', async () => { - const onReady = vi.fn(); - const harness = createSessionHarness({ onReady }); - - harness.sendServerSetup(); - await harness.session.ready; - expect(onReady).toHaveBeenCalledWith([]); - harness.session.destroy(); - }); - - it('subscribes on a new request stream and routes objects by track alias', async () => { - const harness = createSessionHarness(); - - harness.sendServerSetup(); - - const onOk = vi.fn(); - const objects: MoqtObject[] = []; - const subgroupEnds: unknown[] = []; - - harness.session.subscribe( - { trackNamespace: ['live', 'stream1'], trackName: 'video' }, - { - onOk, - onObject: (object) => objects.push(object), - onSubgroupEnd: (info) => subgroupEnds.push(info), - } - ); - - const request = await harness.nextRequestStream(); - const message = await request.firstMessage; - - expect(message).toMatchObject({ - kind: 'subscribe', - requestId: 0, - trackNamespace: ['live', 'stream1'], - trackName: 'video', - }); - - await request.send(encodeSubscribeOk(11)); - await vi.waitFor(() => expect(onOk).toHaveBeenCalled()); - expect(onOk).toHaveBeenCalledWith(expect.objectContaining({ trackAlias: 11 })); - - harness.openDataStream(encodeSubgroup(11, 41, utf8Encode('frame'))); - await vi.waitFor(() => expect(objects).toHaveLength(1)); - expect(objects[0]).toMatchObject({ groupId: 41, objectId: 0, subgroupId: 0, status: 'normal' }); - await vi.waitFor(() => expect(subgroupEnds).toHaveLength(1)); - expect(subgroupEnds[0]).toEqual({ groupId: 41, subgroupId: 0, endOfGroup: true }); - - harness.session.destroy(); - }); - - it('buffers a data stream that arrives before SUBSCRIBE_OK registers the alias', async () => { - const harness = createSessionHarness(); - - harness.sendServerSetup(); - - const objects: MoqtObject[] = []; - - harness.session.subscribe( - { trackNamespace: ['live'], trackName: 'audio' }, - { onObject: (object) => objects.push(object) } - ); - const request = await harness.nextRequestStream(); - - await request.firstMessage; - - // Objects outrace the SUBSCRIBE_OK. - harness.openDataStream(encodeSubgroup(5, 100, utf8Encode('early'))); - await new Promise((resolve) => setTimeout(resolve, 20)); - expect(objects).toHaveLength(0); - - await request.send(encodeSubscribeOk(5)); - await vi.waitFor(() => expect(objects).toHaveLength(1)); - expect(objects[0]).toMatchObject({ groupId: 100 }); - - harness.session.destroy(); - }); - - it('drops a data stream whose alias never registers (timeout)', async () => { - const harness = createSessionHarness(); - - harness.sendServerSetup(); - // No subscription at all — stream must be cancelled after the timeout, - // and the session must survive. - harness.openDataStream(encodeSubgroup(99, 1, utf8Encode('orphan'))); - await new Promise((resolve) => setTimeout(resolve, 300)); - expect(harness.getCloseInfo()).toBeUndefined(); - harness.session.destroy(); - }); - - it('surfaces REQUEST_ERROR to the subscription handlers', async () => { - const harness = createSessionHarness(); - - harness.sendServerSetup(); - - const onError = vi.fn(); - - harness.session.subscribe({ trackNamespace: ['live'], trackName: 'nope' }, { onError }); - const request = await harness.nextRequestStream(); - - await request.firstMessage; - await request.send(encodeRequestError(REQUEST_ERROR_CODE.DOES_NOT_EXIST, 'no such track')); - - await vi.waitFor(() => expect(onError).toHaveBeenCalled()); - expect(onError).toHaveBeenCalledWith( - expect.objectContaining({ errorCode: REQUEST_ERROR_CODE.DOES_NOT_EXIST, reason: 'no such track' }) - ); - harness.session.destroy(); - }); - - // §3.3.2 leaves "was this FIN premature?" to the caller; the session is the - // only layer that knows a SUBSCRIBE needs a SUBSCRIBE_OK. Without these the - // subscription sits pending forever with neither response nor error. - it('fails a subscription when the peer FINs before SUBSCRIBE_OK', async () => { - const harness = createSessionHarness(); - - harness.sendServerSetup(); - - const onError = vi.fn(); - - harness.session.subscribe({ trackNamespace: ['live'], trackName: 'video' }, { onError }); - const request = await harness.nextRequestStream(); - - await request.firstMessage; - await request.fin(); - - await vi.waitFor(() => expect(onError).toHaveBeenCalled()); - expect(onError).toHaveBeenCalledWith( - expect.objectContaining({ reason: 'request stream closed before a response' }) - ); - harness.session.destroy(); - }); - - it('fails a subscription when the request stream is reset before SUBSCRIBE_OK', async () => { - const harness = createSessionHarness(); - - harness.sendServerSetup(); - - const onError = vi.fn(); - - harness.session.subscribe({ trackNamespace: ['live'], trackName: 'video' }, { onError }); - const request = await harness.nextRequestStream(); - - await request.firstMessage; - request.reset(new Error('stream reset')); - - await vi.waitFor(() => expect(onError).toHaveBeenCalled()); - harness.session.destroy(); - }); - - it('does not fail a subscription when the FIN follows SUBSCRIBE_OK', async () => { - const harness = createSessionHarness(); - - harness.sendServerSetup(); - - const onOk = vi.fn(); - const onError = vi.fn(); - - harness.session.subscribe({ trackNamespace: ['live'], trackName: 'video' }, { onOk, onError }); - const request = await harness.nextRequestStream(); - - await request.firstMessage; - await request.send(encodeSubscribeOk(7)); - await vi.waitFor(() => expect(onOk).toHaveBeenCalled()); - await request.fin(); - - await new Promise((resolve) => setTimeout(resolve, 20)); - expect(onError).not.toHaveBeenCalled(); - harness.session.destroy(); - }); - - it('fails a subscription that gets no response before the request timeout', async () => { - const fake = createFakeTransport(); - const session = createMoqtSession(fake.transport, { requestTimeoutMs: 10 }); - - fake.sendServerSetup(); - - const onError = vi.fn(); - - session.subscribe({ trackNamespace: ['live'], trackName: 'video' }, { onError }); - const request = await fake.nextRequestStream(); - - await request.firstMessage; - - await vi.waitFor(() => expect(onError).toHaveBeenCalled()); - expect(onError).toHaveBeenCalledWith(expect.objectContaining({ errorCode: REQUEST_ERROR_CODE.TIMEOUT })); - session.destroy(); - }); - - it('ignores a response that arrives after the request timeout', async () => { - const fake = createFakeTransport(); - const session = createMoqtSession(fake.transport, { requestTimeoutMs: 10, unknownAliasTimeoutMs: 50 }); - - fake.sendServerSetup(); - - const onOk = vi.fn(); - const onError = vi.fn(); - const objects: MoqtObject[] = []; - - session.subscribe( - { trackNamespace: ['live'], trackName: 'video' }, - { onOk, onError, onObject: (object) => objects.push(object) } - ); - const request = await fake.nextRequestStream(); - - await request.firstMessage; - await vi.waitFor(() => expect(onError).toHaveBeenCalled()); - - // A SUBSCRIBE_OK after the timeout must not fire onOk after onError, - // and must not resurrect the alias route of the dead subscription. - await request.send(encodeSubscribeOk(11)).catch(() => {}); - fake.openDataStream(encodeSubgroup(11, 41, utf8Encode('late'))); - await new Promise((resolve) => setTimeout(resolve, 80)); - expect(onOk).not.toHaveBeenCalled(); - expect(objects).toHaveLength(0); - session.destroy(); - }); - - it('fails a pending trackStatus when the transport drops', async () => { - const harness = createSessionHarness(); - - harness.sendServerSetup(); - - const onError = vi.fn(); - - harness.session.trackStatus({ trackNamespace: ['live'], trackName: 'video' }, { onError }); - await ( - await harness.nextRequestStream() - ).firstMessage; - harness.dropTransport(); - - await vi.waitFor(() => expect(onError).toHaveBeenCalled()); - expect(onError).toHaveBeenCalledWith( - expect.objectContaining({ reason: 'session closed before the request was answered' }) - ); - }); - - it('fails pending requests when the transport drops, but not on a local close()', async () => { - const dropped = createSessionHarness(); - - dropped.sendServerSetup(); - const onDropError = vi.fn(); - - dropped.session.subscribe({ trackNamespace: ['live'], trackName: 'video' }, { onError: onDropError }); - await ( - await dropped.nextRequestStream() - ).firstMessage; - dropped.dropTransport(); - await vi.waitFor(() => expect(onDropError).toHaveBeenCalled()); - - const closed = createSessionHarness(); - - closed.sendServerSetup(); - const onCloseError = vi.fn(); - - closed.session.subscribe({ trackNamespace: ['live'], trackName: 'video' }, { onError: onCloseError }); - await ( - await closed.nextRequestStream() - ).firstMessage; - closed.session.close(); - await new Promise((resolve) => setTimeout(resolve, 20)); - expect(onCloseError).not.toHaveBeenCalled(); - }); - - it('surfaces PUBLISH_DONE and keeps late subgroups flowing until cancel', async () => { - const harness = createSessionHarness(); - - harness.sendServerSetup(); - - const onDone = vi.fn(); - const objects: MoqtObject[] = []; - const subscription = harness.session.subscribe( - { trackNamespace: ['live'], trackName: 'video' }, - { onDone, onObject: (object) => objects.push(object) } - ); - const request = await harness.nextRequestStream(); - - await request.firstMessage; - await request.send(encodeSubscribeOk(7)); - await request.send(encodePublishDone(PUBLISH_DONE_STATUS.TRACK_ENDED, 1, 'ended')); - - await vi.waitFor(() => expect(onDone).toHaveBeenCalled()); - expect(onDone).toHaveBeenCalledWith(expect.objectContaining({ statusCode: PUBLISH_DONE_STATUS.TRACK_ENDED })); - - // A late-opening stream still routes (PUBLISH_DONE often beats data). - harness.openDataStream(encodeSubgroup(7, 1, utf8Encode('late'))); - await vi.waitFor(() => expect(objects).toHaveLength(1)); - - subscription.cancel(); - harness.session.destroy(); - }); - - it('allocates even request IDs starting at 0', async () => { - const harness = createSessionHarness(); - - harness.sendServerSetup(); - const first = harness.session.subscribe({ trackNamespace: ['a'], trackName: 'x' }); - const second = harness.session.subscribe({ trackNamespace: ['a'], trackName: 'y' }); - - expect(first.requestId).toBe(0); - expect(second.requestId).toBe(2); - harness.session.destroy(); - }); - - it('routes fetch streams by request id', async () => { - const harness = createSessionHarness(); - - harness.sendServerSetup(); - - harness.session.subscribe({ trackNamespace: ['live'], trackName: 'catalog' }); - const subscribeStream = await harness.nextRequestStream(); - - await subscribeStream.firstMessage; - - const entries: unknown[] = []; - const onEnd = vi.fn(); - - harness.session.fetch( - { trackNamespace: ['live'], trackName: 'catalog', parameters: { locationFilter: CURRENT_GROUP } }, - { onEntry: (entry) => entries.push(entry), onEnd } - ); - const fetchStream = await harness.nextRequestStream(); - const fetchMessage = await fetchStream.firstMessage; - - expect(fetchMessage).toMatchObject({ - kind: 'fetch', - request: { - requestId: 2, - trackNamespace: ['live'], - trackName: 'catalog', - parameters: { locationFilter: CURRENT_GROUP }, - }, - }); - - // Fetch data stream: FETCH_HEADER + one object. - const writer = new ByteWriter(); - - writer.writeVarint(0x05); - writer.writeVarint(2); // fetch request id - writer.writeVarint(0x1c); // group delta + object delta + priority present - writer.writeVarint(41); // group (absolute) - writer.writeVarint(0); // object (absolute) - writer.writeUint8(128); - const payload = utf8Encode('{"version":"1"}'); - - writer.writeVarint(payload.length); - writer.writeBytes(payload); - harness.openDataStream(writer.toBytes()); - - await vi.waitFor(() => expect(entries).toHaveLength(1)); - expect(entries[0]).toMatchObject({ kind: 'object', groupId: 41, objectId: 0 }); - await vi.waitFor(() => expect(onEnd).toHaveBeenCalled()); - - harness.session.destroy(); - }); - - it('tolerates REQUEST_OK in place of FETCH_OK on a fetch stream (relay deviation)', async () => { - const onClosed = vi.fn(); - const harness = createSessionHarness({ onClosed }); - - harness.sendServerSetup(); - - harness.session.subscribe({ trackNamespace: ['live'], trackName: 'catalog' }); - - await harness.nextRequestStream(); - - const entries: unknown[] = []; - const onEnd = vi.fn(); - - harness.session.fetch( - { trackNamespace: ['live'], trackName: 'catalog', parameters: { locationFilter: CURRENT_GROUP } }, - { onEntry: (entry) => entries.push(entry), onEnd } - ); - const fetchStream = await harness.nextRequestStream(); - - await fetchStream.firstMessage; - await fetchStream.send(encodeRequestOk()); - - // The data stream still delivers normally — REQUEST_OK on the bidi - // stream has no bearing on the separate unidirectional data stream. - const writer = new ByteWriter(); - - writer.writeVarint(0x05); - writer.writeVarint(2); // fetch request id - writer.writeVarint(0x1c); // group delta + object delta + priority present - writer.writeVarint(41); // group (absolute) - writer.writeVarint(0); // object (absolute) - writer.writeUint8(128); - const payload = utf8Encode('{"version":"1"}'); - - writer.writeVarint(payload.length); - writer.writeBytes(payload); - harness.openDataStream(writer.toBytes()); - - await vi.waitFor(() => expect(entries).toHaveLength(1)); - await vi.waitFor(() => expect(onEnd).toHaveBeenCalled()); - expect(onClosed).not.toHaveBeenCalled(); - - harness.session.destroy(); - }); - - // REQUEST_OK *is* the response on such a relay, so it has to disarm the - // response timer. If it doesn't, the deadline fires on an answered fetch, - // deletes the record, and `#runFetchStream` then cancels the data stream - // instead of delivering it — the replay vanishes with no protocol error. - it('settles a fetch answered with REQUEST_OK so the request timeout cannot fail it', async () => { - const fake = createFakeTransport(); - // 25ms: below the 30ms wait (an un-disarmed timer would still fire in - // time to be observed) with headroom for the REQUEST_OK on slow CI. - const session = createMoqtSession(fake.transport, { requestTimeoutMs: 25, unknownAliasTimeoutMs: 200 }); - - fake.sendServerSetup(); - - session.subscribe({ trackNamespace: ['live'], trackName: 'catalog' }); - - await fake.nextRequestStream(); - - const onError = vi.fn(); - const entries: unknown[] = []; - - session.fetch( - { trackNamespace: ['live'], trackName: 'catalog', parameters: { locationFilter: CURRENT_GROUP } }, - { onEntry: (entry) => entries.push(entry), onError } - ); - const fetchStream = await fake.nextRequestStream(); - - await fetchStream.firstMessage; - await fetchStream.send(encodeRequestOk()); - - await new Promise((resolve) => setTimeout(resolve, 30)); - expect(onError).not.toHaveBeenCalled(); - - // The data stream arrives after the deadline would have passed. - const writer = new ByteWriter(); - - writer.writeVarint(0x05); - writer.writeVarint(2); // fetch request id - writer.writeVarint(0x1c); // group delta + object delta + priority present - writer.writeVarint(41); // group (absolute) - writer.writeVarint(0); // object (absolute) - writer.writeUint8(128); - const payload = utf8Encode('{"version":"1"}'); - - writer.writeVarint(payload.length); - writer.writeBytes(payload); - fake.openDataStream(writer.toBytes()); - - await vi.waitFor(() => expect(entries).toHaveLength(1)); - session.destroy(); - }); - - it('rejects ready when the session closes before the server SETUP', async () => { - const harness = createSessionHarness(); - - harness.session.close(); - await expect(harness.session.ready).rejects.toThrow('session closed before server SETUP'); - }); - - it('reports a transport drop before the server SETUP as an error close', async () => { - const onClosed = vi.fn(); - const harness = createSessionHarness({ onClosed }); - - harness.dropTransport(); - - // Callback-only consumers must observe the failure too — a clean - // `onClosed({})` would read as a normal session close. - await vi.waitFor(() => expect(onClosed).toHaveBeenCalled()); - expect(onClosed).toHaveBeenCalledWith({ - error: expect.objectContaining({ message: 'session closed before server SETUP' }), - }); - await expect(harness.session.ready).rejects.toThrow('session closed before server SETUP'); - }); - - it('reports a local close() before the server SETUP as a clean close', async () => { - const onClosed = vi.fn(); - const harness = createSessionHarness({ onClosed }); - - harness.session.close(); - - await vi.waitFor(() => expect(onClosed).toHaveBeenCalled()); - expect(onClosed).toHaveBeenCalledWith({}); - }); - - it('reports a reset fetch stream as onReset, not a clean onEnd', async () => { - const harness = createSessionHarness(); - - harness.sendServerSetup(); - - harness.session.subscribe({ trackNamespace: ['live'], trackName: 'catalog' }); - const subscribeStream = await harness.nextRequestStream(); - - await subscribeStream.firstMessage; - - const entries: unknown[] = []; - const onEnd = vi.fn(); - const onReset = vi.fn(); - - harness.session.fetch( - { trackNamespace: ['live'], trackName: 'catalog', parameters: { locationFilter: CURRENT_GROUP } }, - { onEntry: (entry) => entries.push(entry), onEnd, onReset } - ); - const fetchStream = await harness.nextRequestStream(); - - await fetchStream.firstMessage; - - // Fetch data stream: header + one full entry, then a reset mid-replay. - const writer = new ByteWriter(); - - writer.writeVarint(0x05); - writer.writeVarint(2); // fetch request id - writer.writeVarint(0x1c); // group delta + object delta + priority present - writer.writeVarint(41); - writer.writeVarint(0); - writer.writeUint8(128); - const payload = utf8Encode('{"version":"1"}'); - - writer.writeVarint(payload.length); - writer.writeBytes(payload); - const dataStream = harness.openControlledDataStream(); - - await dataStream.write(writer.toBytes()); - await vi.waitFor(() => expect(entries).toHaveLength(1)); - dataStream.reset(new Error('reset mid-replay')); - - await vi.waitFor(() => expect(onReset).toHaveBeenCalled()); - expect(onEnd).not.toHaveBeenCalled(); - - harness.session.destroy(); - }); - - it('treats a truncated response frame on a request stream as a protocol error', async () => { - const onClosed = vi.fn(); - const harness = createSessionHarness({ onClosed }); - - harness.sendServerSetup(); - await harness.session.ready; - - harness.session.subscribe({ trackNamespace: ['live'], trackName: 'video' }); - const request = await harness.nextRequestStream(); - - await request.firstMessage; - - // A frame header promising a 100-byte body, then FIN with none of it. - const partial = new ByteWriter(); - - partial.writeVarint(0x04); - partial.writeUint16(100); - await request.send(partial.toBytes()); - await request.fin(); - - await vi.waitFor(() => expect(onClosed).toHaveBeenCalled()); - expect(harness.getCloseInfo()).toMatchObject({ closeCode: 0x3 }); - }); - - it('reports GOAWAY from the control stream', async () => { - const onGoaway = vi.fn(); - const harness = createSessionHarness({ onGoaway }); - // Server control stream with SETUP then GOAWAY. - const writer = new ByteWriter(); - const setup = encodeSetup([]); - - writer.writeBytes(setup); - // GOAWAY with a migration URI. - const goawayBody = new ByteWriter(); - const uri = utf8Encode('https://relay2.example.com/moq'); - - goawayBody.writeVarint(uri.length); - goawayBody.writeBytes(uri); - goawayBody.writeVarint(1000); - const goawayFrame = new ByteWriter(); - - goawayFrame.writeVarint(0x10); - goawayFrame.writeUint16(goawayBody.length); - goawayFrame.writeBytes(goawayBody.toBytes()); - writer.writeBytes(goawayFrame.toBytes()); - harness.openDataStream(writer.toBytes()); - - await vi.waitFor(() => expect(onGoaway).toHaveBeenCalled()); - expect(onGoaway).toHaveBeenCalledWith( - expect.objectContaining({ newSessionUri: 'https://relay2.example.com/moq', timeout: 1000 }) - ); - harness.session.destroy(); - }); - - it('rejects incoming PUBLISH with UNINTERESTED by default', async () => { - const harness = createSessionHarness(); - - harness.sendServerSetup(); - - // Server-initiated PUBLISH request stream. - const publishBody = new ByteWriter(); - - publishBody.writeVarint(1); // server request id (odd) - publishBody.writeVarint(1); // namespace field count - const field = utf8Encode('live'); - - publishBody.writeVarint(field.length); - publishBody.writeBytes(field); - const name = utf8Encode('unwanted'); - - publishBody.writeVarint(name.length); - publishBody.writeBytes(name); - publishBody.writeVarint(9); // track alias - publishBody.writeVarint(0); // parameter count - const publishFrame = new ByteWriter(); - - publishFrame.writeVarint(0x1d); - publishFrame.writeUint16(publishBody.length); - publishFrame.writeBytes(publishBody.toBytes()); - - const { responses } = harness.openIncomingBidi(publishFrame.toBytes()); - const chunks = await responses; - const deframer = new ControlMessageDeframer(); - const messages = chunks.flatMap((chunk) => deframer.push(chunk)).map(decodeControlMessage); - - expect(messages[0]).toMatchObject({ kind: 'request-error', errorCode: REQUEST_ERROR_CODE.UNINTERESTED }); - - harness.session.destroy(); - }); - - it('rejects incoming PUBLISH_NAMESPACE with NOT_SUPPORTED by default', async () => { - const harness = createSessionHarness(); - - harness.sendServerSetup(); - - // Server-initiated PUBLISH_NAMESPACE request stream — relays commonly - // announce active namespaces unsolicited to newly connected clients. - const { responses } = harness.openIncomingBidi(encodePublishNamespace({ requestId: 1, trackNamespace: ['anon'] })); - const chunks = await responses; - const deframer = new ControlMessageDeframer(); - const messages = chunks.flatMap((chunk) => deframer.push(chunk)).map(decodeControlMessage); - - expect(messages[0]).toMatchObject({ kind: 'request-error', errorCode: REQUEST_ERROR_CODE.NOT_SUPPORTED }); - - harness.session.destroy(); - }); - - it('closes the session when an incoming request frame has a truncated body', async () => { - const onClosed = vi.fn(); - const harness = createSessionHarness({ onClosed }); - - harness.sendServerSetup(); - - // A PUBLISH_NAMESPACE frame whose declared body length cuts the - // namespace off — decoding must terminate the session, not vanish as - // an unhandled RangeError in the accept loop. - const frame = new ByteWriter(); - - frame.writeVarint(0x06); // PUBLISH_NAMESPACE - frame.writeUint16(1); - frame.writeVarint(1); // request id, then no namespace at all - harness.openIncomingBidi(frame.toBytes()); - - await vi.waitFor(() => expect(onClosed).toHaveBeenCalled()); - expect(harness.getCloseInfo()).toMatchObject({ closeCode: 0x3 }); - }); - - it('closes the session with PROTOCOL_VIOLATION on an unknown data stream type', async () => { - const onClosed = vi.fn(); - const harness = createSessionHarness({ onClosed }); - - harness.sendServerSetup(); - - const writer = new ByteWriter(); - - writer.writeVarint(0x0f); // not a valid unidirectional stream type - harness.openDataStream(writer.toBytes()); - - await vi.waitFor(() => expect(onClosed).toHaveBeenCalled()); - expect(harness.getCloseInfo()).toMatchObject({ closeCode: 0x3 }); - }); - - it('surfaces PUBLISH_STATE_NOTIFY to the subscription without replying', async () => { - const harness = createSessionHarness(); - - harness.sendServerSetup(); - - const onStateNotify = vi.fn(); - - harness.session.subscribe({ trackNamespace: ['live'], trackName: 'video' }, { onStateNotify }); - const request = await harness.nextRequestStream(); - - await request.firstMessage; - await request.send(encodeSubscribeOk(7)); - await request.send(encodePublishStateNotify({ largestObject: { group: 12, object: 3 } })); - - await vi.waitFor(() => expect(onStateNotify).toHaveBeenCalled()); - expect(onStateNotify).toHaveBeenCalledWith({ largestObject: { group: 12, object: 3 } }); - - // §10.10: unilateral — no REQUEST_OK or REQUEST_ERROR goes back. - await new Promise((resolve) => setTimeout(resolve, 20)); - expect(request.messages).toHaveLength(1); - harness.session.destroy(); - }); - - it('closes the session on PUBLISH_STATE_NOTIFY over a fetch stream', async () => { - const onClosed = vi.fn(); - const harness = createSessionHarness({ onClosed }); - - harness.sendServerSetup(); - harness.session.fetch({ trackNamespace: ['live'], trackName: 'catalog' }); - const request = await harness.nextRequestStream(); - - await request.firstMessage; - await request.send(encodePublishStateNotify({})); - - await vi.waitFor(() => expect(onClosed).toHaveBeenCalled()); - expect(harness.getCloseInfo()).toMatchObject({ closeCode: 0x3 }); - }); - - // §10.1 counts REQUEST_UPDATE among the messages that consume a Request - // ID; reusing the subscription's would be a duplicate the peer closes on. - it('gives each REQUEST_UPDATE a fresh request id', async () => { - const harness = createSessionHarness(); - - harness.sendServerSetup(); - - const subscription = harness.session.subscribe({ trackNamespace: ['live'], trackName: 'video' }); - const request = await harness.nextRequestStream(); - - await request.firstMessage; - subscription.update({ forward: 0 }); - subscription.update({ forward: 1 }); - - await vi.waitFor(() => expect(request.messages).toHaveLength(3)); - expect(request.messages[1]).toMatchObject({ kind: 'request-update', requestId: 2, parameters: { forward: 0 } }); - expect(request.messages[2]).toMatchObject({ kind: 'request-update', requestId: 4, parameters: { forward: 1 } }); - harness.session.destroy(); - }); - - it('reports an uncountable PUBLISH_DONE stream count as undefined instead of failing the session', async () => { - const onClosed = vi.fn(); - const harness = createSessionHarness({ onClosed }); - - harness.sendServerSetup(); - - const onDone = vi.fn(); - - harness.session.subscribe({ trackNamespace: ['live'], trackName: 'video' }, { onDone }); - const request = await harness.nextRequestStream(); - - await request.firstMessage; - await request.send(encodeSubscribeOk(7)); - - // Status, the 9-byte varint 2^64-1 (§10.12's sentinel), empty reason. - const body = Uint8Array.of(PUBLISH_DONE_STATUS.TRACK_ENDED, ...new Array(9).fill(0xff), 0x00); - const frame = new ByteWriter(); - - frame.writeVarint(0x0b); - frame.writeUint16(body.length); - frame.writeBytes(body); - await request.send(frame.toBytes()); - - await vi.waitFor(() => expect(onDone).toHaveBeenCalled()); - expect(onDone).toHaveBeenCalledWith( - expect.objectContaining({ statusCode: PUBLISH_DONE_STATUS.TRACK_ENDED, streamCount: undefined, reason: '' }) - ); - expect(onClosed).not.toHaveBeenCalled(); - harness.session.destroy(); - }); -}); diff --git a/packages/spf/src/network/moqt/tests/subgroup-writer.test.ts b/packages/spf/src/network/moqt/tests/subgroup-writer.test.ts deleted file mode 100644 index fecd6977f7..0000000000 --- a/packages/spf/src/network/moqt/tests/subgroup-writer.test.ts +++ /dev/null @@ -1,220 +0,0 @@ -import { describe, expect, it, vi } from 'vite-plus/test'; - -import { StreamReader } from '../bytes'; -import { MoqtProtocolError } from '../errors'; -import { - MAX_OBJECT_PAYLOAD_LENGTH, - MAX_OBJECT_PROPERTIES_LENGTH, - type MoqtObject, - readSubgroupHeader, - readSubgroupObjects, -} from '../object-stream'; -import { createSubgroupWriter } from '../subgroup-writer'; - -// LOC property ids (media/moq/loc.ts) — used numerically so the wire -// round-trip matches what LOC packaging emits without a media import. -const TIMESTAMP = 0x06; -const TIMESCALE = 0x08; -const VIDEO_CONFIG = 13; - -function collectingStream() { - const chunks: Uint8Array[] = []; - let closed = false; - let aborted = false; - let abortReason: unknown; - const stream = new WritableStream({ - write(chunk) { - chunks.push(chunk); - }, - close() { - closed = true; - }, - abort(reason) { - aborted = true; - abortReason = reason; - }, - }); - - return { - stream, - chunks, - isClosed: () => closed, - isAborted: () => aborted, - abortReason: () => abortReason, - }; -} - -function readableFrom(chunks: Uint8Array[]): ReadableStream { - return new ReadableStream({ - start(controller) { - for (const chunk of chunks) controller.enqueue(chunk); - - controller.close(); - }, - }); -} - -/** Parse a fully written subgroup stream with the existing reader. */ -async function parseSubgroup(chunks: Uint8Array[]) { - const reader = new StreamReader(readableFrom(chunks)); - const type = await reader.readVarint(); - const header = await readSubgroupHeader(reader, type); - const objects: MoqtObject[] = []; - - for await (const object of readSubgroupObjects(reader, header)) objects.push(object); - - return { header, objects }; -} - -describe('createSubgroupWriter', () => { - it('round-trips a multi-object group through the existing reader', async () => { - const sink = collectingStream(); - const writer = createSubgroupWriter(sink.stream, { trackAlias: 7, groupId: 3 }); - - await writer.writeObject({ - objectId: 0, - properties: [ - { type: TIMESTAMP, value: 1_000_000 }, - { type: TIMESCALE, value: 1_000_000 }, - { type: VIDEO_CONFIG, value: new Uint8Array([1, 2, 3]) }, - ], - payload: new Uint8Array([0xaa, 0xbb]), - }); - await writer.writeObject({ - objectId: 1, - properties: [{ type: TIMESTAMP, value: 1_033_333 }], - payload: new Uint8Array([0xcc]), - }); - await writer.fin(); - - expect(sink.isClosed()).toBe(true); - const { header, objects } = await parseSubgroup(sink.chunks); - - expect(header.trackAlias).toBe(7); - expect(header.groupId).toBe(3); - expect(header.subgroupIdMode).toBe('zero'); - expect(header.hasProperties).toBe(true); - expect(header.endOfGroup).toBe(true); - expect(header.firstObject).toBe(true); - expect(header.priority).toBeUndefined(); - - expect(objects.map((o) => o.objectId)).toEqual([0, 1]); - expect(objects.map((o) => o.subgroupId)).toEqual([0, 0]); - expect(objects[0]!.properties).toEqual([ - { type: TIMESTAMP, value: 1_000_000 }, - { type: TIMESCALE, value: 1_000_000 }, - { type: VIDEO_CONFIG, value: new Uint8Array([1, 2, 3]) }, - ]); - expect(objects[0]!.payload).toEqual(new Uint8Array([0xaa, 0xbb])); - expect(objects[1]!.properties).toEqual([{ type: TIMESTAMP, value: 1_033_333 }]); - expect(objects[1]!.payload).toEqual(new Uint8Array([0xcc])); - }); - - it('round-trips object-id gaps via delta encoding', async () => { - const sink = collectingStream(); - const writer = createSubgroupWriter(sink.stream, { trackAlias: 1, groupId: 0, hasProperties: false }); - - await writer.writeObject({ objectId: 0, payload: new Uint8Array([1]) }); - await writer.writeObject({ objectId: 5, payload: new Uint8Array([2]) }); - await writer.writeObject({ objectId: 9, payload: new Uint8Array([3]) }); - await writer.fin(); - - const { header, objects } = await parseSubgroup(sink.chunks); - - expect(header.hasProperties).toBe(false); - expect(objects.map((o) => o.objectId)).toEqual([0, 5, 9]); - expect(objects.every((o) => o.properties.length === 0)).toBe(true); - }); - - it('carries an explicit publisher priority', async () => { - const sink = collectingStream(); - const writer = createSubgroupWriter(sink.stream, { trackAlias: 2, groupId: 1, priority: 42 }); - - await writer.writeObject({ objectId: 0, properties: [], payload: new Uint8Array([1]) }); - await writer.fin(); - - const { header, objects } = await parseSubgroup(sink.chunks); - - expect(header.priority).toBe(42); - expect(objects[0]!.priority).toBe(42); - }); - - it('round-trips zero-length payloads with an explicit status', async () => { - const sink = collectingStream(); - const writer = createSubgroupWriter(sink.stream, { trackAlias: 2, groupId: 1 }); - - await writer.writeObject({ objectId: 0, properties: [], payload: new Uint8Array([1]) }); - await writer.writeObject({ objectId: 1, properties: [], payload: new Uint8Array(0), status: 'end-of-group' }); - await writer.fin(); - - const { objects } = await parseSubgroup(sink.chunks); - - expect(objects[1]!.status).toBe('end-of-group'); - expect(objects[1]!.payload).toEqual(new Uint8Array(0)); - }); - - it('accepts a payload exactly at MAX_OBJECT_PAYLOAD_LENGTH and rejects one past it', async () => { - const sink = collectingStream(); - const writer = createSubgroupWriter(sink.stream, { trackAlias: 1, groupId: 0, hasProperties: false }); - - await writer.writeObject({ objectId: 0, payload: new Uint8Array(MAX_OBJECT_PAYLOAD_LENGTH) }); - await expect( - writer.writeObject({ objectId: 1, payload: new Uint8Array(MAX_OBJECT_PAYLOAD_LENGTH + 1) }) - ).rejects.toThrow(MoqtProtocolError); - await writer.fin(); - - const { objects } = await parseSubgroup(sink.chunks); - - expect(objects).toHaveLength(1); - expect(objects[0]!.payload.length).toBe(MAX_OBJECT_PAYLOAD_LENGTH); - }); - - it('rejects a properties block past MAX_OBJECT_PROPERTIES_LENGTH', async () => { - const sink = collectingStream(); - const writer = createSubgroupWriter(sink.stream, { trackAlias: 1, groupId: 0 }); - - await expect( - writer.writeObject({ - objectId: 0, - properties: [{ type: VIDEO_CONFIG, value: new Uint8Array(MAX_OBJECT_PROPERTIES_LENGTH + 1) }], - payload: new Uint8Array([1]), - }) - ).rejects.toThrow(MoqtProtocolError); - }); - - it('rejects non-increasing object ids and properties without the PROPERTIES flag', async () => { - const sink = collectingStream(); - const writer = createSubgroupWriter(sink.stream, { trackAlias: 1, groupId: 0, hasProperties: false }); - - await writer.writeObject({ objectId: 3, payload: new Uint8Array([1]) }); - await expect(writer.writeObject({ objectId: 3, payload: new Uint8Array([2]) })).rejects.toThrow(MoqtProtocolError); - await expect( - writer.writeObject({ objectId: 4, properties: [{ type: TIMESTAMP, value: 1 }], payload: new Uint8Array([2]) }) - ).rejects.toThrow(MoqtProtocolError); - }); - - it('rejects writes after fin', async () => { - const sink = collectingStream(); - const writer = createSubgroupWriter(sink.stream, { trackAlias: 1, groupId: 0 }); - - await writer.fin(); - await expect(writer.writeObject({ objectId: 0, properties: [], payload: new Uint8Array([1]) })).rejects.toThrow( - MoqtProtocolError - ); - }); - - it('abort() resets the stream and the reader surfaces the truncation', async () => { - const sink = collectingStream(); - const writer = createSubgroupWriter(sink.stream, { trackAlias: 9, groupId: 4 }); - - await writer.writeObject({ objectId: 0, properties: [], payload: new Uint8Array([1, 2, 3]) }); - const reason = new Error('dropped under backpressure'); - - writer.abort(reason); - - await vi.waitFor(() => { - expect(sink.isAborted()).toBe(true); - }); - expect(sink.abortReason()).toBe(reason); - }); -}); diff --git a/packages/spf/src/network/moqt/tests/varint.test.ts b/packages/spf/src/network/moqt/tests/varint.test.ts deleted file mode 100644 index 06583a6a27..0000000000 --- a/packages/spf/src/network/moqt/tests/varint.test.ts +++ /dev/null @@ -1,112 +0,0 @@ -import { describe, expect, it } from 'vite-plus/test'; - -import { MoqtProtocolError } from '../errors'; -import { decodeVarint, encodeVarint, varintByteLength, varintLengthFromFirstByte } from '../varint'; - -function bytes(...values: number[]): Uint8Array { - return new Uint8Array(values); -} - -// Golden vectors from moq-transport draft-19 §1.4.1, Table 2. -const SPEC_VECTORS: [Uint8Array, number][] = [ - [bytes(0x25), 37], - [bytes(0x80, 0x25), 37], - [bytes(0xbb, 0xbd), 15_293], - [bytes(0xed, 0x7f, 0x3e, 0x7d), 226_442_877], - [bytes(0xfa, 0xa1, 0xa0, 0xe4, 0x03, 0xd8), 2_893_212_287_960], - [bytes(0xfc, 0x89, 0x98, 0xab, 0xc6, 0x6b, 0xc0), 151_288_809_941_952], -]; - -describe('decodeVarint', () => { - it('decodes the spec example encodings', () => { - for (const [encoded, value] of SPEC_VECTORS) { - expect(decodeVarint(encoded)).toEqual({ value, byteLength: encoded.length }); - } - }); - - it('accepts non-minimal encodings (any representable length is valid)', () => { - expect(decodeVarint(bytes(0x00)).value).toBe(0); - expect(decodeVarint(bytes(0x80, 0x00)).value).toBe(0); - expect(decodeVarint(bytes(0xc0, 0x00, 0x00)).value).toBe(0); - }); - - it('decodes at an offset', () => { - expect(decodeVarint(bytes(0xff, 0xff, 0x25), 2)).toEqual({ value: 37, byteLength: 1 }); - }); - - it('throws RangeError on truncated input', () => { - expect(() => decodeVarint(bytes())).toThrow(RangeError); - expect(() => decodeVarint(bytes(0xbb))).toThrow(RangeError); - expect(() => decodeVarint(bytes(0xed, 0x7f, 0x3e))).toThrow(RangeError); - }); - - it('rejects values above 2^53-1 with MoqtProtocolError', () => { - // 0xfefa318fa8e3ca11 = 70,423,237,261,249,041 (> 2^53-1) from the spec table. - expect(() => decodeVarint(bytes(0xfe, 0xfa, 0x31, 0x8f, 0xa8, 0xe3, 0xca, 0x11))).toThrow(MoqtProtocolError); - expect(() => decodeVarint(bytes(0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff))).toThrow(MoqtProtocolError); - }); - - it('accepts 9-byte encodings of in-range values', () => { - // 9-byte non-minimal encoding of 1. - expect(decodeVarint(bytes(0xff, 0, 0, 0, 0, 0, 0, 0, 1))).toEqual({ value: 1, byteLength: 9 }); - }); -}); - -describe('encodeVarint', () => { - it('round-trips boundary values at each length', () => { - const boundaries = [ - 0, - 127, - 128, - 16_383, - 16_384, - 2 ** 21 - 1, - 2 ** 21, - 2 ** 28 - 1, - 2 ** 28, - 2 ** 35 - 1, - 2 ** 35, - 2 ** 42 - 1, - 2 ** 42, - 2 ** 49 - 1, - 2 ** 49, - Number.MAX_SAFE_INTEGER, - ]; - - for (const value of boundaries) { - const encoded = encodeVarint(value); - - expect(encoded.length).toBe(varintByteLength(value)); - expect(decodeVarint(encoded)).toEqual({ value, byteLength: encoded.length }); - } - }); - - it('produces minimal encodings matching the spec vectors', () => { - expect(encodeVarint(37)).toEqual(bytes(0x25)); - expect(encodeVarint(15_293)).toEqual(bytes(0xbb, 0xbd)); - expect(encodeVarint(226_442_877)).toEqual(bytes(0xed, 0x7f, 0x3e, 0x7d)); - expect(encodeVarint(2_893_212_287_960)).toEqual(bytes(0xfa, 0xa1, 0xa0, 0xe4, 0x03, 0xd8)); - }); - - it('rejects negative and unsafe values', () => { - expect(() => encodeVarint(-1)).toThrow(RangeError); - expect(() => encodeVarint(1.5)).toThrow(RangeError); - expect(() => encodeVarint(Number.MAX_SAFE_INTEGER + 2)).toThrow(RangeError); - }); -}); - -describe('varintLengthFromFirstByte', () => { - it('maps prefixes to lengths', () => { - expect(varintLengthFromFirstByte(0x00)).toBe(1); - expect(varintLengthFromFirstByte(0x7f)).toBe(1); - expect(varintLengthFromFirstByte(0x80)).toBe(2); - expect(varintLengthFromFirstByte(0xbf)).toBe(2); - expect(varintLengthFromFirstByte(0xc0)).toBe(3); - expect(varintLengthFromFirstByte(0xe0)).toBe(4); - expect(varintLengthFromFirstByte(0xf0)).toBe(5); - expect(varintLengthFromFirstByte(0xf8)).toBe(6); - expect(varintLengthFromFirstByte(0xfc)).toBe(7); - expect(varintLengthFromFirstByte(0xfe)).toBe(8); - expect(varintLengthFromFirstByte(0xff)).toBe(9); - }); -}); diff --git a/packages/spf/src/network/moqt/varint.ts b/packages/spf/src/network/moqt/varint.ts deleted file mode 100644 index 9a7cf523d9..0000000000 --- a/packages/spf/src/network/moqt/varint.ts +++ /dev/null @@ -1,122 +0,0 @@ -/** - * MOQT variable-length integers (moq-transport draft-20 §1.4.1). - * - * NOT the QUIC RFC 9000 varint: draft-15 replaced it with a leading-ones scheme. The number of leading 1 bits of the - * first byte gives the encoded length minus one (1-9 bytes); the bits after the first 0, plus any subsequent bytes, - * hold the value in network byte order. - * - * Values are represented as JS `number`. The wire format allows up to 2^64-1, but this decoder rejects anything above - * `Number.MAX_SAFE_INTEGER` (2^53-1) with a `MoqtProtocolError` — no field a media subscriber consumes legitimately - * needs more (Group IDs derived from Unix-epoch milliseconds are ~2^41), and silent precision loss would corrupt IDs. - */ -import { MoqtProtocolError } from './errors'; - -export interface VarintDecodeResult { - value: number; - /** Total encoded size in bytes (1-9). */ - byteLength: number; -} - -/** Largest value `encodeVarint` accepts (`Number.MAX_SAFE_INTEGER`). */ -export const MAX_VARINT_VALUE = Number.MAX_SAFE_INTEGER; - -/** Encoded length in bytes implied by a varint's first byte. */ -export function varintLengthFromFirstByte(firstByte: number): number { - let leadingOnes = 0; - let mask = 0x80; - - while (leadingOnes < 8 && (firstByte & mask) !== 0) { - leadingOnes++; - mask >>= 1; - } - - return leadingOnes + 1; -} - -/** - * Decode a varint at `offset`. Throws `RangeError` when `bytes` ends before the encoding completes, and - * `MoqtProtocolError` when the decoded value exceeds `MAX_VARINT_VALUE`. - */ -export function decodeVarint(bytes: Uint8Array, offset = 0): VarintDecodeResult { - const firstByte = bytes[offset]; - if (firstByte === undefined) throw new RangeError('varint: unexpected end of input'); - - const byteLength = varintLengthFromFirstByte(firstByte); - if (offset + byteLength > bytes.length) throw new RangeError('varint: unexpected end of input'); - - // Value bits contributed by the first byte: everything after the - // leading-ones prefix and its terminating 0. For a 9-byte encoding - // (prefix 0xFF) the first byte contributes nothing. - const firstByteBits = byteLength <= 8 ? firstByte & (0xff >> byteLength) : 0; - - if (byteLength <= 7) { - // Up to 49 value bits — exact in double-precision number math. - let value = firstByteBits; - - for (let i = 1; i < byteLength; i++) value = value * 256 + bytes[offset + i]!; - - return { value, byteLength }; - } - - // 8-9 byte encodings can exceed 2^53 — accumulate in bigint, then bound. - let big = BigInt(firstByteBits); - - for (let i = 1; i < byteLength; i++) big = big * 256n + BigInt(bytes[offset + i]!); - - if (big > BigInt(MAX_VARINT_VALUE)) { - throw new MoqtProtocolError(`varint: value ${big} exceeds supported range (2^53-1)`); - } - - return { value: Number(big), byteLength }; -} - -/** Minimal encoded length in bytes for `value`. */ -export function varintByteLength(value: number): number { - if (!Number.isSafeInteger(value) || value < 0) { - throw new RangeError(`varint: value out of range: ${value}`); - } - - if (value < 2 ** 7) return 1; - - if (value < 2 ** 14) return 2; - - if (value < 2 ** 21) return 3; - - if (value < 2 ** 28) return 4; - - if (value < 2 ** 35) return 5; - - if (value < 2 ** 42) return 6; - - if (value < 2 ** 49) return 7; - - // 8 bytes carry 56 value bits, which covers everything up to 2^53-1. - return 8; -} - -/** Encode `value` into `target` at `offset` using the minimal length. Returns the number of bytes written. */ -export function encodeVarintInto(target: Uint8Array, offset: number, value: number): number { - const byteLength = varintByteLength(value); - // Fill value bytes from the least-significant end. Number math is exact - // here: value < 2^53 and each step divides by 256. - let remaining = value; - - for (let i = byteLength - 1; i >= 1; i--) { - target[offset + i] = remaining % 256; - remaining = Math.floor(remaining / 256); - } - - // First byte: leading-ones prefix for (byteLength - 1) ones, then the - // top value bits. - const prefix = byteLength === 1 ? 0 : (0xff << (9 - byteLength)) & 0xff; - - target[offset] = prefix | remaining; - return byteLength; -} - -export function encodeVarint(value: number): Uint8Array { - const bytes = new Uint8Array(varintByteLength(value)); - - encodeVarintInto(bytes, 0, value); - return bytes; -} diff --git a/packages/spf/src/network/tests/helpers/moqt-wire.ts b/packages/spf/src/network/tests/helpers/moqt-wire.ts index ffc47d4c34..e0b018bf57 100644 --- a/packages/spf/src/network/tests/helpers/moqt-wire.ts +++ b/packages/spf/src/network/tests/helpers/moqt-wire.ts @@ -1,18 +1,32 @@ /** * Relay-side MOQT codec for the in-memory fake relays in SPF's tests. * - * The player speaks MOQT through `@caprid/moq-core`, whose public entry exports only the subscriber's surface. A fake - * relay also needs the other side of the wire — server SETUP, SUBSCRIBE decoding, SUBSCRIBE_OK, REQUEST_ERROR and - * PUBLISH_DONE — so this re-exports the package's own codec modules instead of keeping a second implementation that - * could drift from the one the player runs. The deep path bypasses the package's `exports` map on purpose; it is - * test-only, and a package release that moves these modules fails the tests loudly rather than silently. + * The player and the publisher speak MOQT through `@caprid/moq-core`, whose public entry exports only each endpoint's + * own surface. A fake relay also needs the other side of the wire — server SETUP, SUBSCRIBE_NAMESPACE and SUBSCRIBE + * encoding, SUBSCRIBE_OK, REQUEST_ERROR, PUBLISH_DONE and the object stream readers — so this re-exports the package's + * own codec modules instead of keeping a second implementation that could drift from the one the engines run. The deep + * path bypasses the package's `exports` map on purpose; it is test-only, and a package release that moves these modules + * fails the tests loudly rather than silently. */ export { StreamReader, utf8Encode } from '../../../../node_modules/@caprid/moq-core/dist/protocol/bytes.js'; export { type ControlMessage, + ControlMessageDeframer, decodeControlMessage, + encodeGoaway, + encodePublish, encodePublishDone, encodeRequestError, encodeSetup, + encodeSubscribe, + encodeSubscribeNamespace, encodeSubscribeOk, } from '../../../../node_modules/@caprid/moq-core/dist/protocol/control-messages.js'; +export { + isSubgroupHeaderType, + readFetchHeader, + readSubgroupHeader, + readSubgroupObjects, + STREAM_TYPE, +} from '../../../../node_modules/@caprid/moq-core/dist/protocol/object-stream.js'; +export { decodeVarint, encodeVarint } from '../../../../node_modules/@caprid/moq-core/dist/protocol/varint.js'; diff --git a/packages/spf/src/network/moqt/tests/helpers/raw-peer.ts b/packages/spf/src/network/tests/helpers/raw-peer.ts similarity index 93% rename from packages/spf/src/network/moqt/tests/helpers/raw-peer.ts rename to packages/spf/src/network/tests/helpers/raw-peer.ts index 4a9989cecf..c7e1699071 100644 --- a/packages/spf/src/network/moqt/tests/helpers/raw-peer.ts +++ b/packages/spf/src/network/tests/helpers/raw-peer.ts @@ -5,15 +5,15 @@ * `rawSubscribe` wrap it with the two messages moq-lite-rs sends (SUBSCRIBE_NAMESPACE right after SETUP, SUBSCRIBE per * pulled track). */ +import type { MoqtTransport, TrackNamespace } from '@caprid/moq-core'; + import { type ControlMessage, ControlMessageDeframer, decodeControlMessage, encodeSubscribe, encodeSubscribeNamespace, - type TrackNamespace, -} from '../../control-messages'; -import type { MoqtTransport } from '../../session'; +} from './moqt-wire'; export interface RawRequest { /** Control frames the publisher wrote back, in order. */ @@ -32,7 +32,7 @@ export interface RawRequest { * response-side write failure test needs. */ abandonReads: () => Promise; - /** FIN the peer's side — half-closure, NOT a withdrawal (§3.3.2). */ + /** FIN the peer's side — half-closure, NOT a withdrawal (§6.4.2.2). */ fin: () => Promise; /** Reset the peer's side — the actual withdrawal signal. */ reset: () => Promise; @@ -82,7 +82,7 @@ export function solicitNamespace(server: MoqtTransport, prefix: TrackNamespace, return openRawRequest(server, encodeSubscribeNamespace({ requestId, trackNamespacePrefix: prefix })); } -/** The relay's per-track pull, with the parameters moq-relay 0.14.14 sends on draft-20 (a `relative-group 1` join). */ +/** The relay's per-track pull, with the parameters moq-relay sends upstream (a `relative-group 1` join). */ export function rawSubscribe( server: MoqtTransport, trackNamespace: TrackNamespace, diff --git a/packages/spf/src/network/tests/helpers/transport-pair.ts b/packages/spf/src/network/tests/helpers/transport-pair.ts new file mode 100644 index 0000000000..c37180d656 --- /dev/null +++ b/packages/spf/src/network/tests/helpers/transport-pair.ts @@ -0,0 +1,162 @@ +/** + * Symmetric in-memory `MoqtTransport` pair for loopback tests: two transports whose stream-creation methods surface on + * the peer's incoming stream queues, so a publish session on one side can talk to a subscribe session on the other over + * real (in-process) WHATWG streams — the same structural seam a `WebTransport` satisfies in production. + */ +import type { BidirectionalStreamLike, MoqtTransport } from '@caprid/moq-core'; + +import { decodeVarint, encodeVarint } from './moqt-wire'; + +interface PushChannel { + stream: ReadableStream; + push(value: T): void; +} + +function pushChannel(): PushChannel { + let controller!: ReadableStreamDefaultController; + const stream = new ReadableStream({ + start(c) { + controller = c; + }, + }); + + return { stream, push: (value) => controller.enqueue(value) }; +} + +export interface TransportPair { + client: MoqtTransport; + server: MoqtTransport; +} + +/** Create two transports wired back-to-back. */ +export function createTransportPair(): TransportPair { + const makeSide = () => ({ + incomingUni: pushChannel>(), + incomingBidi: pushChannel(), + resolveClosed: undefined as ((info: unknown) => void) | undefined, + }); + const a = makeSide(); + const b = makeSide(); + + let closed = false; + const closedPromises = [a, b].map( + (side) => + new Promise((resolve) => { + side.resolveClosed = resolve; + }) + ); + + const closeBoth = (info?: { closeCode?: number; reason?: string }): void => { + if (closed) return; + + closed = true; + a.resolveClosed?.(info); + b.resolveClosed?.(info); + }; + + const makeTransport = (local: typeof a, remote: typeof b, closedPromise: Promise): MoqtTransport => ({ + incomingUnidirectionalStreams: local.incomingUni.stream, + incomingBidirectionalStreams: local.incomingBidi.stream, + async createUnidirectionalStream() { + if (closed) throw new Error('transport closed'); + + const pipe = new TransformStream(); + + remote.incomingUni.push(pipe.readable); + return pipe.writable; + }, + async createBidirectionalStream() { + if (closed) throw new Error('transport closed'); + + const localToRemote = new TransformStream(); + const remoteToLocal = new TransformStream(); + + remote.incomingBidi.push({ readable: localToRemote.readable, writable: remoteToLocal.writable }); + return { readable: remoteToLocal.readable, writable: localToRemote.writable }; + }, + close(closeInfo) { + closeBoth(closeInfo); + }, + closed: closedPromise, + }); + + return { + client: makeTransport(a, b, closedPromises[0]!), + server: makeTransport(b, a, closedPromises[1]!), + }; +} + +/** + * Offset added to the Request IDs of a subscribe session standing in for the relay (see `withServerRequestIds`). Odd, + * so the client's even IDs become server ones, and far above the small odd IDs tests hand `raw-peer` requests. + */ +export const SERVER_REQUEST_ID_OFFSET = 1_000_001; + +/** + * Give a subscribe session standing in for the relay the server's (odd) Request IDs: the publish session closes with + * INVALID_REQUEST_ID on a peer request carrying the client's (even) parity (§6.4.2.1), and the subscribe driver only + * allocates client IDs. Each request stream's first message — the request itself — has {@link SERVER_REQUEST_ID_OFFSET} + * added to its Request ID. The publish session uses that Request ID as the Track Alias, so a binding reads + * `subscription.requestId + SERVER_REQUEST_ID_OFFSET`. + */ +export function withServerRequestIds(transport: MoqtTransport): MoqtTransport { + return { + ...transport, + async createBidirectionalStream() { + const stream = await transport.createBidirectionalStream(); + + return { readable: stream.readable, writable: offsetFirstRequestId(stream.writable) }; + }, + }; +} + +function offsetFirstRequestId(target: WritableStream): WritableStream { + let pending: Uint8Array | undefined = new Uint8Array(0); + const rewrite = new TransformStream({ + transform(chunk, controller) { + if (!pending) { + controller.enqueue(chunk); + return; + } + + const bytes = new Uint8Array(pending.length + chunk.length); + + bytes.set(pending); + bytes.set(chunk, pending.length); + pending = bytes; + + // Message Type (varint), Message Length (16 bits), then the body, whose + // first field is the Request ID. + let type: ReturnType; + + try { + type = decodeVarint(bytes); + } catch { + return; + } + + const bodyStart = type.byteLength + 2; + if (bytes.length < bodyStart) return; + + const bodyLength = (bytes[type.byteLength]! << 8) | bytes[type.byteLength + 1]!; + if (bytes.length < bodyStart + bodyLength) return; + + const requestId = decodeVarint(bytes, bodyStart); + const rest = bytes.subarray(bodyStart + requestId.byteLength); + const id = encodeVarint(requestId.value + SERVER_REQUEST_ID_OFFSET); + const newBodyLength = bodyLength - requestId.byteLength + id.length; + const out = new Uint8Array(bodyStart + id.length + rest.length); + + out.set(bytes.subarray(0, type.byteLength)); + out[type.byteLength] = newBodyLength >> 8; + out[type.byteLength + 1] = newBodyLength & 0xff; + out.set(id, bodyStart); + out.set(rest, bodyStart + id.length); + pending = undefined; + controller.enqueue(out); + }, + }); + + void rewrite.readable.pipeTo(target).catch(() => {}); + return rewrite.writable; +} 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 315535b42a..73987a5702 100644 --- a/packages/spf/src/publish/actors/tests/track-publisher.test.ts +++ b/packages/spf/src/publish/actors/tests/track-publisher.test.ts @@ -1,9 +1,9 @@ +import { type MoqtObject } from '@caprid/moq-core'; import { describe, expect, it, vi } from 'vite-plus/test'; import { toLocFrame } from '../../../media/moq/loc'; import { packageLocFrame } from '../../../media/moq/loc-packaging'; -import { StreamReader } from '../../../network/moqt/bytes'; -import { type MoqtObject, readSubgroupHeader, readSubgroupObjects } from '../../../network/moqt/object-stream'; +import { StreamReader, readSubgroupHeader, readSubgroupObjects } from '../../../network/tests/helpers/moqt-wire'; import { createTrackPublisherActor, type TrackPublisherActor } from '../track-publisher'; // ============================================================================= @@ -11,6 +11,8 @@ import { createTrackPublisherActor, type TrackPublisherActor } from '../track-pu // ============================================================================= interface FakeUniStream { + /** The subscription alias the stream was opened for. */ + trackAlias?: number; chunks: Uint8Array[]; closed: boolean; aborted: boolean; @@ -27,8 +29,8 @@ function makeStreamFactory() { releaseAll() { for (const release of releases.splice(0)) release(); }, - openUniStream: async (): Promise> => { - const record: FakeUniStream = { chunks: [], closed: false, aborted: false }; + openUniStream: async (trackAlias: number): Promise> => { + const record: FakeUniStream = { trackAlias, chunks: [], closed: false, aborted: false }; streams.push(record); return new WritableStream({ @@ -229,8 +231,8 @@ describe('createTrackPublisherActor', () => { // groups reset by the drop policy) while in-memory transports, whose // close() settles instantly, showed nothing. const streams: FakeUniStream[] = []; - const openUniStream = async (): Promise> => { - const record: FakeUniStream = { chunks: [], closed: false, aborted: false }; + const openUniStream = async (trackAlias: number): Promise> => { + const record: FakeUniStream = { trackAlias, chunks: [], closed: false, aborted: false }; streams.push(record); return new WritableStream({ @@ -338,33 +340,23 @@ describe('createTrackPublisherActor', () => { ]); }); - it('counts the data streams opened under each subscription alias, pruning superseded ones', async () => { + it('opens each group stream for the subscription bound when the group started', 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. + // Unbound frames open nothing. 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)); + await vi.waitFor(() => expect(counters(publisher).publishedGroups).toBe(1)); - // 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)); + publisher.send(frame(2)); + await vi.waitFor(() => expect(counters(publisher).publishedGroups).toBe(2)); - expect([publisher.streamCount(3), publisher.streamCount(5), publisher.streamCount(7)]).toEqual([0, 1, 0]); + expect(factory.streams.map((stream) => stream.trackAlias)).toEqual([3, 5]); publisher.destroy(); }); diff --git a/packages/spf/src/publish/actors/track-publisher.ts b/packages/spf/src/publish/actors/track-publisher.ts index 494bceb4e9..bc99c74ada 100644 --- a/packages/spf/src/publish/actors/track-publisher.ts +++ b/packages/spf/src/publish/actors/track-publisher.ts @@ -29,19 +29,19 @@ * message order. Async completions feed the reactive snapshot counters through internal messages, mirroring * `actors/dom/encoder-actor.ts`. */ +import { createSubgroupWriter, type SubgroupWriter } from '@caprid/moq-core'; + import type { ActorStateDefinition, MessageActor } from '../../core/actors/create-machine-actor'; import { createMachineActor } from '../../core/actors/create-machine-actor'; import { SerialRunner, Task } from '../../core/tasks/task'; import type { PropertyPair } from '../../media/moq/loc'; -import type { SubgroupWriter } from '../../network/moqt/subgroup-writer'; -import { createSubgroupWriter } from '../../network/moqt/subgroup-writer'; // ============================================================================= // Types // ============================================================================= -/** Opens one unidirectional stream on the publish session's transport. */ -export type OpenUniStream = () => Promise>; +/** Opens one unidirectional data stream for the live subscription bound as `trackAlias`. */ +export type OpenUniStream = (trackAlias: number) => Promise>; export type TrackPublisherUserState = 'publishing' | 'ended'; export type TrackPublisherState = TrackPublisherUserState | 'destroyed'; @@ -68,7 +68,7 @@ export interface TrackPublisherCounters { /** Timestamp of the most recently written object; NaN before the first. */ lastTimestampUs: number; /** - * Group ID of the Largest Object written to the wire (§5.1.2); -1 before the first object. Paired with + * Group ID of the Largest Object written to the wire (§3.1.4); -1 before the first object. Paired with * `largestObjectId`, this is what the session reports as LARGEST_OBJECT in SUBSCRIBE_OK. */ largestGroupId: number; @@ -111,12 +111,6 @@ export interface TrackPublisherActor extends MessageActor< * as it is written.) */ flushed(): Promise; - /** - * Data streams opened under the subscription bound as `trackAlias` — PUBLISH_DONE's Stream Count (§10.12). Counted at - * the commit to writing the subgroup header (the `openedGroups` boundary), so a stream reset before its header — one - * the peer cannot attribute to the subscription — is excluded. - */ - streamCount(trackAlias: number): number; } export interface TrackPublisherOptions { @@ -197,8 +191,6 @@ export function createTrackPublisherActor(options: TrackPublisherOptions): Track let currentGroupFrames: Extract[] = []; /** Detached FIN settlements (see `finishCell`) — `flushed()` waits on them past the runner. */ const pendingFins = new Set>(); - /** Opened data streams per subscription alias (see `streamCount`); pruned to the current alias on each bind. */ - const streamsByAlias = new Map(); // Assigned right after createMachineActor returns; the runner tasks only // complete asynchronously, well after construction. @@ -287,7 +279,7 @@ export function createTrackPublisherActor(options: TrackPublisherOptions): Track new Task(async (signal) => { if (signal.aborted || cell.aborted) return; - const stream = await raceOpenAgainstAbort(openUniStream(), signal); + const stream = await raceOpenAgainstAbort(openUniStream(cell.trackAlias), signal); if (stream === undefined) return; // `signal.aborted` again, not just the cell: destroy() leaves the @@ -304,7 +296,6 @@ export function createTrackPublisherActor(options: TrackPublisherOptions): Track // counting at queue time inflated the opened-stream count with // groups that were dropped before they ever opened one. inner?.send({ type: 'group-opened' }); - streamsByAlias.set(cell.trackAlias, (streamsByAlias.get(cell.trackAlias) ?? 0) + 1); cell.writer = createSubgroupWriter(stream, { trackAlias: cell.trackAlias, groupId: cell.groupId, @@ -530,14 +521,6 @@ export function createTrackPublisherActor(options: TrackPublisherOptions): Track boundAlias = msg.trackAlias; - // A new alias binds only after the session has ended every - // older subscription on the track, so their counts are dead - // weight. The current alias keeps its count across an unbind - // (a Forward State toggle rebinds the same alias). - for (const alias of streamsByAlias.keys()) { - if (alias !== msg.trackAlias) streamsByAlias.delete(alias); - } - // Instant join: catalog-shaped tracks re-send their latest // change-driven frame (queued behind this message, boundAlias // already set); keyframe-grouped tracks replay the in-progress @@ -607,9 +590,6 @@ export function createTrackPublisherActor(options: TrackPublisherOptions): Track await runner.settled; await Promise.all(pendingFins); }, - streamCount(trackAlias: number): number { - return streamsByAlias.get(trackAlias) ?? 0; - }, 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/open-publish-session.ts b/packages/spf/src/publish/behaviors/open-publish-session.ts index a3b3c64bb4..0993ae0315 100644 --- a/packages/spf/src/publish/behaviors/open-publish-session.ts +++ b/packages/spf/src/publish/behaviors/open-publish-session.ts @@ -14,11 +14,12 @@ * Sole writer of `state.sessionStatus` and `context.publishSessionActor`; co-writer of `state.publishError` * (transport/protocol failures only). */ +import { isMoqtProtocolError } from '@caprid/moq-core'; + 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 } from '../../core/signals/primitives'; -import { isMoqtProtocolError } from '../../network/moqt/errors'; import type { ConnectPublishTransport, PublishEndpoint, diff --git a/packages/spf/src/publish/behaviors/setup-track-publishers.ts b/packages/spf/src/publish/behaviors/setup-track-publishers.ts index 9ff117efe6..fa571232fa 100644 --- a/packages/spf/src/publish/behaviors/setup-track-publishers.ts +++ b/packages/spf/src/publish/behaviors/setup-track-publishers.ts @@ -31,6 +31,13 @@ * subgroup streams on every unsubscribe, so a stream failure is ordinary lifecycle — the publishers count it * (`droppedGroups`) and genuine transport death surfaces through the session's own `closed`/`failed` path. */ +import { + CLOSE_FLUSH_TIMEOUT_MS, + type MoqtPublishSession, + type RegisteredTrack, + TRACK_PROPERTY, +} from '@caprid/moq-core'; + import { defineBehavior } from '../../core/composition/create-composition'; import type { Reactor } from '../../core/reactors/create-machine-reactor'; import { createMachineReactor } from '../../core/reactors/create-machine-reactor'; @@ -41,13 +48,7 @@ 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 { - CLOSE_FLUSH_TIMEOUT_MS, - type MoqtPublishSession, - type PublishEndpoint, - type PublishSessionActor, - type RegisteredTrack, -} from '../session/publish-session'; +import type { PublishEndpoint, PublishSessionActor } from '../session/publish-session'; /** * Structural mirror of `behaviors/dom/probe-encoder-support.ts`'s `ActiveEncodingsFacts` (DOM-bound behavior, so not @@ -249,7 +250,7 @@ const textEncoder = new TextEncoder(); const TRACK_FLUSH_TIMEOUT_MS = CLOSE_FLUSH_TIMEOUT_MS / 2; /** - * End one track in the order §10.12 requires — every data stream closed before PUBLISH_DONE: `end` FINs the open group, + * End one track in the order §9.9 requires — every data stream closed before PUBLISH_DONE: `end` FINs the open group, * the queued groups get a bounded window to flush, `destroy()` FINs or resets whatever is left, and only then does the * session send each subscription PUBLISH_DONE and its FIN. */ @@ -312,7 +313,7 @@ function addTrackPublisher( // WebTransport orders larger values first. Keep all media below the // default order (0) of control/request streams so congestion cannot // starve the signaling needed to stop or change a subscription. - openUniStream: () => cluster.session.openUniStream({ sendOrder: -1 - options.priority }), + openUniStream: (trackAlias) => cluster.session.openUniStream(trackAlias, { sendOrder: -1 - options.priority }), priority: options.priority, groupPerFrame: options.groupPerFrame, replayLastGroupOnBind: options.replayLastGroupOnBind === true, @@ -321,16 +322,18 @@ function addTrackPublisher( const handle = cluster.session.registerTrack({ trackNamespace: cluster.namespace, trackName, + // Declaring the timescale keeps object TIMESTAMP properties flowing + // through moq-lite-rs relays — undeclared, they discard them and + // re-stamp frames on arrival, so viewers would sync to relay arrival + // time instead of capture time. LOC packaging stamps microseconds. + trackProperties: [{ type: TRACK_PROPERTY.TIMESCALE, value: MICROSECONDS_PER_SECOND }], // The publisher owns the Largest Object it has written; the session - // reads it here to report LARGEST_OBJECT in SUBSCRIBE_OK (§10.2.17). + // reads it here to report LARGEST_OBJECT in SUBSCRIBE_OK (§9.20.17). getLargestObject: () => { const { largestGroupId, largestObjectId } = publisher.snapshot.get().context; return largestGroupId >= 0 ? { group: largestGroupId, object: largestObjectId } : undefined; }, - // ...and the streams it opened per subscription, for the Stream Count - // a track end reports in PUBLISH_DONE (§10.12). - getStreamCount: (trackAlias) => publisher.streamCount(trackAlias), }); cluster.created.push({ handle, publisher, boundAlias: undefined }); diff --git a/packages/spf/src/publish/behaviors/tests/open-publish-session-switch.test.ts b/packages/spf/src/publish/behaviors/tests/open-publish-session-switch.test.ts index bc39449933..0ea58000f9 100644 --- a/packages/spf/src/publish/behaviors/tests/open-publish-session-switch.test.ts +++ b/packages/spf/src/publish/behaviors/tests/open-publish-session-switch.test.ts @@ -1,8 +1,12 @@ +import { createMoqtSession } from '@caprid/moq-core'; import { afterEach, describe, expect, it, vi } from 'vite-plus/test'; import { signal } from '../../../core/signals/primitives'; -import { createMoqtSession } from '../../../network/moqt/session'; -import { createTransportPair, type TransportPair } from '../../../network/moqt/tests/helpers/transport-pair'; +import { + createTransportPair, + type TransportPair, + withServerRequestIds, +} from '../../../network/tests/helpers/transport-pair'; import type { ConnectPublishTransport } from '../../session/publish-session'; import { type OpenPublishSessionContext, @@ -23,7 +27,7 @@ const disposals: (() => void)[] = []; function makeAcceptingPeer(pair: TransportPair) { const closes: unknown[] = []; - const peer = createMoqtSession(pair.server, { + const peer = createMoqtSession(withServerRequestIds(pair.server), { callbacks: { onIncomingPublish: (_publish, respond) => respond.accept(), onClosed: (info) => closes.push(info), diff --git a/packages/spf/src/publish/behaviors/tests/open-publish-session.test.ts b/packages/spf/src/publish/behaviors/tests/open-publish-session.test.ts index 248aee5f7a..175ac99955 100644 --- a/packages/spf/src/publish/behaviors/tests/open-publish-session.test.ts +++ b/packages/spf/src/publish/behaviors/tests/open-publish-session.test.ts @@ -1,11 +1,14 @@ +import { PUBLISH_DONE_STATUS, createMoqtSession } from '@caprid/moq-core'; import { afterEach, describe, expect, it, vi } from 'vite-plus/test'; import { createComposition } from '../../../core/composition/create-composition'; import { signal } from '../../../core/signals/primitives'; -import { PUBLISH_DONE_STATUS } from '../../../network/moqt/control-messages'; -import { createMoqtSession } from '../../../network/moqt/session'; -import { type RawRequest, rawSubscribe, solicitNamespace } from '../../../network/moqt/tests/helpers/raw-peer'; -import { createTransportPair, type TransportPair } from '../../../network/moqt/tests/helpers/transport-pair'; +import { type RawRequest, rawSubscribe, solicitNamespace } from '../../../network/tests/helpers/raw-peer'; +import { + createTransportPair, + type TransportPair, + withServerRequestIds, +} from '../../../network/tests/helpers/transport-pair'; import type { ConnectPublishTransport } from '../../session/publish-session'; import { type OpenPublishSessionContext, @@ -20,7 +23,7 @@ const disposals: (() => void)[] = []; function makePeer(pair: TransportPair) { const closes: unknown[] = []; - const peer = createMoqtSession(pair.server, { + const peer = createMoqtSession(withServerRequestIds(pair.server), { callbacks: { onClosed: (info) => closes.push(info), }, diff --git a/packages/spf/src/publish/behaviors/tests/setup-track-publishers-switch.test.ts b/packages/spf/src/publish/behaviors/tests/setup-track-publishers-switch.test.ts index a4b2e56a1c..d77eb9b8a2 100644 --- a/packages/spf/src/publish/behaviors/tests/setup-track-publishers-switch.test.ts +++ b/packages/spf/src/publish/behaviors/tests/setup-track-publishers-switch.test.ts @@ -1,9 +1,9 @@ +import { createMoqtSession } from '@caprid/moq-core'; import { afterEach, describe, expect, it, vi } from 'vite-plus/test'; import { signal } from '../../../core/signals/primitives'; -import { createMoqtSession } from '../../../network/moqt/session'; -import { rawSubscribe, solicitNamespace } from '../../../network/moqt/tests/helpers/raw-peer'; -import { createTransportPair } from '../../../network/moqt/tests/helpers/transport-pair'; +import { rawSubscribe, solicitNamespace } from '../../../network/tests/helpers/raw-peer'; +import { createTransportPair, withServerRequestIds } from '../../../network/tests/helpers/transport-pair'; import { createPublishSessionActor, type PublishSessionActor } from '../../session/publish-session'; import { type SetupTrackPublishersContext, @@ -28,7 +28,7 @@ const disposals: (() => void)[] = []; function makeSessionActor() { const pair = createTransportPair(); - const peer = createMoqtSession(pair.server, {}); + const peer = createMoqtSession(withServerRequestIds(pair.server), {}); disposals.push(() => peer.destroy()); const actor: PublishSessionActor = createPublishSessionActor({ 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 9dd4a03f9c..2414765df0 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,13 +1,17 @@ +import { + createMoqtSession, + type MoqtObject, + REQUEST_ERROR_CODE, + type SubscribeOk, + TRACK_PROPERTY, +} from '@caprid/moq-core'; 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'; -import { createMoqtSession } from '../../../network/moqt/session'; -import { solicitNamespace } from '../../../network/moqt/tests/helpers/raw-peer'; -import { createTransportPair } from '../../../network/moqt/tests/helpers/transport-pair'; +import { MICROSECONDS_PER_SECOND, parseLocProperties } from '../../../media/moq/loc'; +import { solicitNamespace } from '../../../network/tests/helpers/raw-peer'; +import { createTransportPair, withServerRequestIds } from '../../../network/tests/helpers/transport-pair'; import { createPublishSessionActor, type PublishSessionActor } from '../../session/publish-session'; import { type SetupTrackPublishersConfig, @@ -25,7 +29,7 @@ const disposals: (() => void)[] = []; function makeSessionActor() { const pair = createTransportPair(); - const peer = createMoqtSession(pair.server, {}); + const peer = createMoqtSession(withServerRequestIds(pair.server), {}); disposals.push(() => peer.destroy()); const actor: PublishSessionActor = createPublishSessionActor({ @@ -133,17 +137,21 @@ describe('setupTrackPublishers', () => { }); // Registration is local under announce-and-serve — the observable - // proof is that the peer's SUBSCRIBEs are answered. - const aliases: number[] = []; + // proof is that the peer's SUBSCRIBEs are answered, each declaring the + // microsecond timescale LOC packaging stamps objects in. + const answers: SubscribeOk[] = []; for (const trackName of ['catalog', 'video', 'audio'] as const) { - peer.subscribe({ trackNamespace: ENDPOINT.namespace, trackName }, { onOk: (ok) => aliases.push(ok.trackAlias) }); + peer.subscribe({ trackNamespace: ENDPOINT.namespace, trackName }, { onOk: (ok) => answers.push(ok) }); } await vi.waitFor(() => { - expect(aliases).toHaveLength(3); + expect(answers).toHaveLength(3); expect(actor.snapshot.get().context.subscriberCount).toBe(3); }); + expect(answers.map((ok) => ok.trackProperties)).toEqual( + Array(3).fill([{ type: TRACK_PROPERTY.TIMESCALE, value: MICROSECONDS_PER_SECOND }]) + ); }); it('skips the video publisher for an audio-only encoding', async () => { @@ -333,7 +341,7 @@ describe('setupTrackPublishers', () => { expect(onSubgroupReset).not.toHaveBeenCalled(); }); - it("closes a track's open group before its PUBLISH_DONE (§10.12)", async () => { + it("closes a track's open group before its PUBLISH_DONE (§9.9)", async () => { const { actor, peer, server } = makeSessionActor(); const { state, context } = setupBehavior(); const events: string[] = []; 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 0e57ca7d9c..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: () => {}, flushed: async () => {}, streamCount: () => 0, destroy: () => {} }; + return { snapshot, send: () => {}, flushed: async () => {}, destroy: () => {} }; } function makeSessionActor(subscriberCount: number): PublishSessionActor { diff --git a/packages/spf/src/publish/engines/moq/engine.ts b/packages/spf/src/publish/engines/moq/engine.ts index 4cbd7c6059..a481342269 100644 --- a/packages/spf/src/publish/engines/moq/engine.ts +++ b/packages/spf/src/publish/engines/moq/engine.ts @@ -233,9 +233,9 @@ const shareSignals = makeShareSignals peer.destroy()); return peer; diff --git a/packages/spf/src/publish/engines/moq/tests/cross-engine.test.ts b/packages/spf/src/publish/engines/moq/tests/cross-engine.test.ts index 855f1496db..5d10019a2b 100644 --- a/packages/spf/src/publish/engines/moq/tests/cross-engine.test.ts +++ b/packages/spf/src/publish/engines/moq/tests/cross-engine.test.ts @@ -1,6 +1,6 @@ +import { PUBLISH_DONE_STATUS } from '@caprid/moq-core'; import { afterEach, describe, expect, it, vi } from 'vite-plus/test'; -import { PUBLISH_DONE_STATUS } from '../../../../network/moqt/control-messages'; import { createRelayHub } from '../../../tests/helpers/relay-hub'; import { createMoqPublishEngine } from '../engine'; import { createSubscriber, makeSyntheticStream } from './helpers/cross-engine-harness'; @@ -8,7 +8,7 @@ import { createSubscriber, makeSyntheticStream } from './helpers/cross-engine-ha /** * Cross-engine regression suite: the real publish engine (DEFAULT encoder config — H.264 in `avc` (AVCC) bitstream * format, with the avcC published out-of-band as the catalog's `initDataList`; see `probe-encoder-support.ts` for the - * carriage history) publishing through an in-memory draft-20 relay hub to the real playback engine rendering onto a + * carriage history) publishing through an in-memory moqt-22 relay hub to the real playback engine rendering onto a * canvas. * * Covers the real-world publisher bugs: - a LATE-joining subscriber (after ≥1 group boundary) must reach decoded video diff --git a/packages/spf/src/publish/engines/moq/tests/publish-transport.test.ts b/packages/spf/src/publish/engines/moq/tests/publish-transport.test.ts index 2db841da2e..5223445198 100644 --- a/packages/spf/src/publish/engines/moq/tests/publish-transport.test.ts +++ b/packages/spf/src/publish/engines/moq/tests/publish-transport.test.ts @@ -1,13 +1,11 @@ +import { utf8Decode, type MoqtObject, createMoqtSession } from '@caprid/moq-core'; import { afterEach, describe, expect, it, vi } from 'vite-plus/test'; import { effect } from '../../../../core/signals/effect'; import { toLocFrame } from '../../../../media/moq/loc'; import { applyMoqCatalogUpdate } from '../../../../media/moq/parse-catalog'; -import { utf8Decode } from '../../../../network/moqt/bytes'; -import type { MoqtObject } from '../../../../network/moqt/object-stream'; -import { createMoqtSession } from '../../../../network/moqt/session'; -import { solicitNamespace } from '../../../../network/moqt/tests/helpers/raw-peer'; -import { createTransportPair } from '../../../../network/moqt/tests/helpers/transport-pair'; +import { solicitNamespace } from '../../../../network/tests/helpers/raw-peer'; +import { createTransportPair, withServerRequestIds } from '../../../../network/tests/helpers/transport-pair'; import { MoqPublishMediaMixin } from '../adapter'; /** @@ -66,7 +64,7 @@ describe('MoqPublishMediaMixin transport (M3)', () => { const pair = createTransportPair(); const proactivePublishes: string[] = []; - const subscriber = createMoqtSession(pair.server, { + const subscriber = createMoqtSession(withServerRequestIds(pair.server), { unknownAliasTimeoutMs: 2000, callbacks: { // Regression tripwire: moq-relay 0.14.7 removed PUBLISH ingest — diff --git a/packages/spf/src/publish/session/publish-session.ts b/packages/spf/src/publish/session/publish-session.ts index 9424d1f32f..b7f1f89550 100644 --- a/packages/spf/src/publish/session/publish-session.ts +++ b/packages/spf/src/publish/session/publish-session.ts @@ -1,1268 +1,25 @@ /** - * Publish-capable MOQT session (moq-transport draft-20), the publish-side sibling of `network/moqt/session.ts`'s - * subscribe-only driver. + * Publish session actor: connects to a relay and drives `@caprid/moq-core`'s publish session (moq-transport draft-22, + * draft-20 as a fallback) through its lifecycle, exposing a reactive snapshot for the `publish/` behaviors. * - * Owns the protocol mechanics over an established transport: the SETUP exchange on paired unidirectional control - * streams (§3.3), and the announce-and-serve ingest flow — answering the peer's SUBSCRIBE_NAMESPACE solicitation with - * REQUEST_OK and a NAMESPACE entry for the announced namespace (§10.18–19), then serving the per-track SUBSCRIBEs the - * peer routes back (answered with SUBSCRIBE_OK carrying a publisher-assigned track alias, §10.8) for as long as each - * subscription's request stream stays open. - * - * Flow choice: the publisher initiates no request streams at all. moq-relay 0.14.7 removed PUBLISH-based ingest - * (upstream `de336492`: every PUBLISH is answered with a request error), and it solicits namespaces itself — one - * SUBSCRIBE_NAMESPACE per authorized prefix, sent immediately after SETUP. Announcing rides the solicitation stream as - * NAMESPACE entries (suffix-relative, parameterless — the relay treats even an empty parameter count as malformed); - * data flows only on aliases bound by our own SUBSCRIBE_OKs, per subscription. A track end sends each subscription - * PUBLISH_DONE (TRACK_ENDED, with the exact count of data streams it received) and then FINs it — moq-relay 0.17.0 - * forwards that downstream as "track ended", where a bare FIN reaches viewers as "internal error" (older moq-relay - * builds abort the track on any byte after SUBSCRIBE_OK; they are not supported). Two more hard-won peer constraints - * shape the teardown paths: a client-sent GOAWAY closes the whole session (code 17), and a track alias bound to two - * live request IDs closes it too (code 12) — so aliases are the peer's own request IDs, unique by construction. - * - * Deliberately callback-shaped with NO signals, mirroring the subscribe driver — signal awareness enters at the - * `publish/` behavior layer through the actor below. Lives in `publish/` rather than `network/moqt` so the parent-owned - * wire layer keeps only additive sibling files. + * The protocol mechanics — SETUP, the announce-and-serve ingest flow, SUBSCRIBE_OK with LARGEST_OBJECT and the declared + * track properties, fills, and PUBLISH_DONE with the session's own Stream Count — live in the package. Its session is + * callback-shaped with no signals; signal awareness enters here. */ -import { hasMethods } from '@videojs/utils/predicate'; - -import { createTransitionActor, type TransitionActor } from '../../core/actors/create-transition-actor'; -import { MICROSECONDS_PER_SECOND } from '../../media/moq/loc'; -import { StreamReader, utf8Encode } from '../../network/moqt/bytes'; import { - type ControlMessage, - decodeControlMessage, - encodeNamespace, - encodeNamespaceDone, - encodePublishDone, - encodeRequestError, - encodeRequestOk, - encodeSetup, - encodeSubscribeOk, - type FillParameters, - isEmptyFetchRange, - type KeyValuePair, - type Location, - MESSAGE_TYPE, - PUBLISH_DONE_STATUS, - type MessageParameters, + createMoqtPublishSession, + type Goaway, MOQT_PROTOCOL_ID, - REQUEST_ERROR_CODE, - SETUP_OPTION, - TRACK_PROPERTY, - type TrackNamespace, -} from '../../network/moqt/control-messages'; -import { isMoqtProtocolError, MoqtProtocolError, SESSION_ERROR } from '../../network/moqt/errors'; -import { encodeFetchHeader, isSubgroupHeaderType, STREAM_TYPE } from '../../network/moqt/object-stream'; -import type { BidirectionalStreamLike } from '../../network/moqt/request-stream'; -import type { Goaway, MoqtTransport } from '../../network/moqt/session'; - -// ============================================================================= -// Driver types -// ============================================================================= - -export interface IncomingSubscribe { - requestId: number; - trackNamespace: TrackNamespace; - trackName: string; - parameters: MessageParameters; -} - -export interface MoqtPublishSessionCallbacks { - /** The server's SETUP arrived; the session is fully established. */ - onReady?(serverOptions: KeyValuePair[]): void; - /** GOAWAY (control stream or a request stream): stop initiating, migrate. */ - onGoaway?(goaway: Goaway): void; - /** - * The announced namespace reached the wire on an accepted SUBSCRIBE_NAMESPACE solicitation — the peer can now route - * SUBSCRIBEs to it. NAMESPACE entries have no acknowledgement of their own; this is the strongest "announced" fact - * the transport draft offers. - */ - onAnnounced?(info: { namespace: TrackNamespace }): void; - /** - * The solicitation stream carrying the announce ended while the session was still live — the peer rejected the - * announce (unauthorized suffix) or withdrew its namespace interest. Either way the ingest path is gone. - */ - onAnnounceEnded?(info: { error?: unknown }): void; - /** The peer subscribed to a registered track (already answered SUBSCRIBE_OK). */ - onSubscribe?(subscribe: IncomingSubscribe): void; - /** A subscriber's request stream ended (FIN, reset, or track done). */ - onSubscribeEnd?(info: { requestId: number }): void; - /** - * A track's effective alias binding changed. The most recent live subscription wins the binding (a replaced one is - * FINed — a clean end for that request, covering the peer's resubscribe races), and only while its Forward State - * permits data (`forward: 0` subscribes without authorizing it; REQUEST_UPDATE toggles it). `undefined` means no live - * forwarding subscription, so no data streams may be opened for the track. - */ - onTrackBinding?(info: { trackName: string; trackAlias: number | undefined }): void; - /** - * REQUEST_UPDATE on an inbound request stream. `requestId` is the request being updated (the stream's SUBSCRIBE or - * SUBSCRIBE_NAMESPACE); `updateRequestId` is the update's own, freshly consumed Request ID (§10.1). - */ - onRequestUpdate?(info: { requestId: number; updateRequestId: number; parameters: MessageParameters }): void; - /** The session ended — transport closed, or a fatal protocol error. */ - onClosed?(info: { error?: unknown }): void; -} + MOQT_PROTOCOL_IDS, + MoqtProtocolError, + type MoqtPublishSession, + type MoqtTransport, +} from '@caprid/moq-core'; -export interface MoqtPublishSessionConfig { - /** Extra Setup Options to send (an implementation identifier is added automatically). */ - setupOptions?: KeyValuePair[]; - /** Identifies this implementation in SETUP (§10.3.1.5). */ - implementationName?: string; - callbacks?: MoqtPublishSessionCallbacks; -} - -export interface RegisterTrackOptions { - trackNamespace: TrackNamespace; - trackName: string; - /** - * The track's Largest Object (§10.2.17), read when answering SUBSCRIBE and REQUEST_UPDATE so each response reports it - * once content exists (the spec MUST, and moq-lite-rs relays decode it). Pulled at request time rather than pushed so - * it never churns the session; returning `undefined` (or omitting this) means nothing has been published yet and the - * parameter is left off. - */ - getLargestObject?: () => Location | undefined; - /** - * Data streams opened under the subscription with this alias — the PUBLISH_DONE Stream Count (§10.12) the track's end - * reports, plus the fill streams the session opens itself. Omitted, the count is reported as unknown (2^64−1). - */ - getStreamCount?: (trackAlias: number) => number; -} - -export interface RegisteredTrack { - readonly trackName: string; - /** - * End the track: send every live subscription PUBLISH_DONE with TRACK_ENDED and its Stream Count, FIN its request - * stream, 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(options?: { after?: Promise }): void; -} - -export interface MoqtPublishSession { - /** Resolves when the server's SETUP has been received. */ - readonly ready: Promise; - /** - * Announce the namespace on every matching solicitation — current and future. The wire write additionally waits for - * the first `registerTrack()`: an announce invites immediate SUBSCRIBEs, and an empty registry would answer them with - * a terminal DOES_NOT_EXIST. Result via `onAnnounced` / `onAnnounceEnded`. - */ - announce(trackNamespace: TrackNamespace): void; - /** Register one servable track; the peer's SUBSCRIBEs are answered from this registry. */ - registerTrack(options: RegisterTrackOptions): RegisteredTrack; - /** Open a unidirectional data stream (for a track publisher's subgroups). */ - openUniStream(options?: { sendOrder?: number }): Promise>; - /** - * Orderly stop: FIN every live subscription's stream and retract the announce (NAMESPACE_DONE), give those writes a - * bounded window to reach the wire (closing a WebTransport discards queued data), then close the transport. - * Synchronous callers return immediately; the transport closes within roughly {@link CLOSE_FLUSH_TIMEOUT_MS}. - */ - close(closeCode?: number, reason?: string): void; - destroy(): void; -} +import { createTransitionActor, type TransitionActor } from '../../core/actors/create-transition-actor'; const DEFAULT_IMPLEMENTATION_NAME = '@videojs/spf moqt publisher'; -/** - * How long `close()` waits for the subscription FINs / NAMESPACE_DONE writes to drain before closing the transport out - * from under them. - */ -export const CLOSE_FLUSH_TIMEOUT_MS = 250; - -// ============================================================================= -// Internal records -// ============================================================================= - -/** One inbound subscription's stream-side plumbing. */ -interface SubscriberStream { - requestId: number; - trackAlias: number; - /** Bare FIN — ends a subscription the peer superseded, which is not a track end. */ - fin(): Promise; - /** PUBLISH_DONE, then FIN — the track ended (§10.12). */ - done(statusCode: number, streamCount: number | undefined): Promise; - cancel(): Promise; - /** SUBSCRIBE_OK reached the wire — only accepted subscriptions may carry the binding. */ - accepted: boolean; - /** `onSubscribe` fired — `onSubscribeEnd` pairs on this, keeping counts balanced. */ - reported: boolean; - /** Forward State (§ SUBSCRIBE `forward`, togglable via REQUEST_UPDATE) — data flows only while true. */ - forwarding: boolean; - finished: boolean; - /** Includes pending stream opens, so cancellation also catches late arrivals. */ - fills: Set; - /** Fill streams opened for this subscription — they count toward PUBLISH_DONE's Stream Count. */ - fillStreams: number; -} - -interface FillStream { - writer?: WritableStreamDefaultWriter; -} - -interface TrackRecord { - key: string; - trackName: string; - subscribers: SubscriberStream[]; - done: boolean; - /** - * Replacement FINs still in flight (pruned as they settle). `end()` folds them into `doneFlushed` — a swept - * predecessor is already `finished`, so it would otherwise be skipped and its queued FIN discarded by the transport - * close, turning the clean replacement into an abrupt reset. - */ - pendingFins: Promise[]; - /** Settles when the FINs queued by `end()` land. */ - doneFlushed?: Promise; - /** Reads the track's Largest Object for responses (see `RegisterTrackOptions.getLargestObject`). */ - getLargestObject?: () => Location | undefined; - /** Reads a subscription's data-stream count (see `RegisterTrackOptions.getStreamCount`). */ - getStreamCount?: (trackAlias: number) => number; -} - -/** One accepted inbound SUBSCRIBE_NAMESPACE — the announce carrier. */ -interface NamespaceStream { - prefix: TrackNamespace; - writer: WritableStreamDefaultWriter; - /** Suffixes announced on this stream (for NAMESPACE_DONE at close). */ - announced: TrackNamespace[]; -} - -function trackKey(namespace: TrackNamespace, name: string): string { - return `${namespace.join('/')}--${name}`; -} - -function isNamespacePrefix(prefix: TrackNamespace, namespace: TrackNamespace): boolean { - return prefix.length <= namespace.length && prefix.every((part, i) => namespace[i] === part); -} - -// ============================================================================= -// Session driver -// ============================================================================= - -class MoqtPublishSessionImpl implements MoqtPublishSession { - readonly ready: Promise; - - #transport: MoqtTransport; - #config: MoqtPublishSessionConfig; - #callbacks: MoqtPublishSessionCallbacks; - - #tracks = new Map(); - #namespaceStreams = new Set(); - /** - * Prefixes whose solicitation is mid-acceptance. Request handlers run concurrently and registration happens only - * after the REQUEST_OK write settles, so an overlapping solicitation racing that await must be refused off this - * reservation, not just off the registered set. - */ - #pendingNamespacePrefixes = new Set(); - /** - * Every inbound request ID ever seen. Reuse is a protocol violation (§10.1), and because aliases ARE the peer's - * request IDs, a reused ID would hand two subscriptions the same alias and make their subgroup streams - * indistinguishable — session-fatal, per the draft. - */ - #peerRequestIds = new Set(); - #desiredNamespace: TrackNamespace | undefined; - #announcedFired = false; - - #resolveReady!: () => void; - #rejectReady!: (error: unknown) => void; - #controlWriter: WritableStreamDefaultWriter | undefined; - #receivedServerSetup = false; - #receivedControlGoaway = false; - /** Any GOAWAY (control or request stream) — the peer is migrating. */ - #receivedGoaway = false; - #closing = false; - #destroyed = false; - - constructor(transport: MoqtTransport, config: MoqtPublishSessionConfig = {}) { - this.#transport = transport; - this.#config = config; - this.#callbacks = config.callbacks ?? {}; - this.ready = new Promise((resolve, reject) => { - this.#resolveReady = resolve; - this.#rejectReady = reject; - }); - this.ready.catch(() => {}); - - void this.#start(); - } - - // --------------------------------------------------------------------------- - // Session lifecycle - // --------------------------------------------------------------------------- - - async #start(): Promise { - void this.#acceptUnidirectionalStreams(); - void this.#acceptBidirectionalStreams(); - void this.#transport.closed.then( - () => this.#handleClosed(undefined), - (error) => this.#handleClosed(error) - ); - - try { - const control = await this.#transport.createUnidirectionalStream(); - - this.#controlWriter = control.getWriter(); - // A control stream MUST stay open for the session's lifetime - // (§3.3) — a peer stopping it has ended the session, so fail now - // rather than on the next control write or the transport's own - // `closed` (~an RTT later); the gap is long enough for a busy - // publisher to keep churning streams against a dying transport. - // A clean local close resolves the writer instead, and #fatal - // no-ops once #handleClosed has run. - void this.#controlWriter.closed.catch((error: unknown) => this.#fatal(error)); - const options: KeyValuePair[] = [ - { - type: SETUP_OPTION.MOQT_IMPLEMENTATION, - value: utf8Encode(this.#config.implementationName ?? DEFAULT_IMPLEMENTATION_NAME), - }, - ...(this.#config.setupOptions ?? []), - ]; - - await this.#controlWriter.write(encodeSetup(options)); - } catch (error) { - this.#fatal(error); - } - } - - #fatal(error: unknown): void { - if (this.#destroyed) return; - - const closeCode = isMoqtProtocolError(error) ? error.code : SESSION_ERROR.INTERNAL_ERROR; - - try { - this.#transport.close({ closeCode, reason: error instanceof Error ? error.message : 'session error' }); - } catch { - // transport already gone - } - - this.#handleClosed(error); - } - - #handleClosed(error: unknown, { expected = false }: { expected?: boolean } = {}): void { - if (this.#destroyed) return; - - this.#destroyed = true; - - if (!this.#receivedServerSetup) { - this.#rejectReady(error ?? new MoqtProtocolError('session closed before server SETUP')); - } - - for (const track of this.#tracks.values()) { - for (const subscriber of track.subscribers) void subscriber.cancel(); - } - - this.#tracks.clear(); - this.#namespaceStreams.clear(); - this.#controlWriter = undefined; - - // Mirror the subscribe driver: a transport that drops before server - // SETUP is a session failure even when the close itself was clean. - const closeError = - error ?? - (expected || this.#receivedServerSetup ? undefined : new MoqtProtocolError('session closed before server SETUP')); - - this.#callbacks.onClosed?.(closeError === undefined ? {} : { error: closeError }); - } - - close(closeCode = SESSION_ERROR.NO_ERROR, reason = ''): void { - if (this.#destroyed || this.#closing) return; - - this.#closing = true; - void this.#drainAndClose(closeCode, reason); - } - - /** - * Orderly close: closing the transport discards queued data (WebTransport semantics), so the track ends (PUBLISH_DONE - * - * - FIN per subscription) and NAMESPACE_DONE retractions must be given a bounded window to land first — a peer should - * observe every track ending cleanly, not an abrupt transport end. No GOAWAY is sent: moq-lite-rs closes the - * session on a client GOAWAY (see the module doc). - */ - async #drainAndClose(closeCode: number, reason: string): Promise { - // One macrotask beat before the last-resort sweep below: track owners - // tearing down in the same reactive flush (`setupTrackPublishers`'s - // cleanup runs on a microtask after ours on the unpublish path) get to - // end their tracks themselves. - await new Promise((resolve) => setTimeout(resolve, 0)); - - if (this.#destroyed) return; - - for (const track of this.#tracks.values()) { - this.#endTrack(track); - } - - const writes: Promise[] = [...this.#tracks.values()].map( - (track) => track.doneFlushed ?? Promise.resolve() - ); - - for (const stream of this.#namespaceStreams) { - for (const suffix of stream.announced.splice(0)) { - writes.push(stream.writer.write(encodeNamespaceDone(suffix)).catch(() => {})); - } - } - - let flushTimer: ReturnType | undefined; - - try { - await Promise.race([ - Promise.all(writes), - new Promise((resolve) => { - flushTimer = setTimeout(resolve, CLOSE_FLUSH_TIMEOUT_MS); - }), - ]); - } finally { - if (flushTimer !== undefined) clearTimeout(flushTimer); - } - - if (this.#destroyed) return; - - try { - this.#transport.close({ closeCode, reason }); - } catch { - // transport already gone - } - - this.#handleClosed(undefined, { expected: true }); - } - - destroy(): void { - this.close(); - } - - // --------------------------------------------------------------------------- - // Announcing and the track registry - // --------------------------------------------------------------------------- - - announce(trackNamespace: TrackNamespace): void { - if (this.#destroyed || this.#closing) return; - - this.#desiredNamespace = trackNamespace; - - for (const stream of this.#namespaceStreams) { - this.#reconcileAnnounce(stream); - } - } - - /** - * Write the desired namespace onto a solicitation stream whose prefix covers it. Solicitations, `announce()`, and the - * first `registerTrack()` arrive in any order — the relay's SUBSCRIBE_NAMESPACE races our post-SETUP setup — so all - * three paths funnel here. The announce is deferred until at least one track is registered: an announced namespace - * invites immediate SUBSCRIBEs, and answering one with DOES_NOT_EXIST is terminal on moq-lite-rs (the relay aborts - * the request rather than retrying), so advertising an empty registry would permanently break the first viewer in the - * pre-registration window. - */ - #reconcileAnnounce(stream: NamespaceStream): void { - const namespace = this.#desiredNamespace; - if (namespace === undefined || this.#tracks.size === 0) return; - - if (!isNamespacePrefix(stream.prefix, namespace)) return; - - const suffix = namespace.slice(stream.prefix.length); - if (stream.announced.some((existing) => existing.join('/') === suffix.join('/'))) return; - - stream.announced.push(suffix); - stream.writer - .write(encodeNamespace(suffix)) - .then(() => { - if (this.#destroyed || this.#announcedFired) return; - - this.#announcedFired = true; - this.#callbacks.onAnnounced?.({ namespace }); - }) - .catch(() => { - // The response half died alone (a reset the request half may - // never mirror): the entry never reached the peer, no future - // write can, and the read loop may stay open forever — the - // carrier is dead. Deregister it so the peer's replacement - // solicitation is a fresh start rather than a PREFIX_OVERLAP - // against a corpse; if another path already swept it, the loss - // was reported there. - if (!this.#namespaceStreams.delete(stream)) return; - - stream.announced = stream.announced.filter((existing) => existing !== suffix); - void stream.writer.close().catch(() => {}); - this.#reportAnnounceLoss(); - }); - } - - /** - * Fire `onAnnounceEnded` when no solicitation carries the announce anymore — shared by the read-loop cleanup and the - * response-write failure path. Silent while closing, destroyed, or migrating (a GOAWAY makes the peer's streams - * ending the orderly drain). - */ - #reportAnnounceLoss(): void { - if (this.#destroyed || this.#closing || this.#receivedGoaway) return; - - const stillCarried = [...this.#namespaceStreams].some((stream) => stream.announced.length > 0); - if (stillCarried) return; - - this.#callbacks.onAnnounceEnded?.({ - error: new MoqtProtocolError('the namespace solicitation carrying the announce ended'), - }); - } - - registerTrack(options: RegisterTrackOptions): RegisteredTrack { - if (this.#destroyed || this.#closing) { - // A closed session must not repopulate `#tracks` — hand back an - // inert handle so late callers still get the RegisteredTrack shape. - return { trackName: options.trackName, end: () => {} }; - } - - const track: TrackRecord = { - key: trackKey(options.trackNamespace, options.trackName), - trackName: options.trackName, - subscribers: [], - done: false, - pendingFins: [], - getLargestObject: options.getLargestObject, - getStreamCount: options.getStreamCount, - }; - - this.#tracks.set(track.key, track); - - // The first registration may be what the deferred announce was - // waiting for (see #reconcileAnnounce). - if (this.#tracks.size === 1) { - for (const stream of this.#namespaceStreams) { - this.#reconcileAnnounce(stream); - } - } - - return { - trackName: options.trackName, - end: (options) => this.#endTrack(track, options?.after), - }; - } - - /** - * End every live subscription with PUBLISH_DONE (TRACK_ENDED) and a FIN, and refuse future SUBSCRIBEs. The aggregated - * write completion lands on `track.doneFlushed` so `close()` can hold the transport open until the ends reach the - * wire. - */ - #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; - - for (const subscriber of track.subscribers) { - if (!subscriber.finished) { - subscriber.finished = true; - // Read at the end, not at subscribe time: the count must cover - // every stream the subscription received (§10.12). - const streamCount = track.getStreamCount - ? track.getStreamCount(subscriber.trackAlias) + subscriber.fillStreams - : undefined; - - writes.push(subscriber.done(PUBLISH_DONE_STATUS.TRACK_ENDED, streamCount).catch(() => {})); - } - - // The local end is authoritative: report each live subscription - // ended NOW rather than when the peer eventually closes its - // request direction — otherwise `subscriberCount` and the binding - // stay live (and publishers keep opening data streams) until the - // peer notices the FIN. Clearing `reported` keeps the read loop's - // own end notification paired: it fires on the same flag. - if (subscriber.reported) { - subscriber.reported = false; - hadReported = true; - - if (!this.#destroyed) this.#callbacks.onSubscribeEnd?.({ requestId: subscriber.requestId }); - } - } - - if (hadReported && !this.#destroyed) { - this.#callbacks.onTrackBinding?.({ trackName: track.trackName, trackAlias: undefined }); - } - - return Promise.all(writes).then(() => {}); - } - - openUniStream(options?: { sendOrder?: number }): Promise> { - // Refuse rather than touch the transport once the session is going - // away. Encoders keep producing frames for a beat after a peer kills - // the session, and hammering createUnidirectionalStream() on a - // 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. 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')); - } - - return this.#transport.createUnidirectionalStream(options); - } - - /** - * Whether a SUBSCRIBE or REQUEST_UPDATE carrying FILL_PARAMETERS calls for a fill fetch stream (§5.1.3.1): only while - * Forward State is 1, only for a subscription that is still live, and only when the fill range is nonempty. The fill - * range is the filter inside FILL_PARAMETERS — else the subscription's own — evaluated as a fetch against the track's - * Largest Object; an empty range, or one starting past Largest Object, opens no stream at all (§5.1.3), so a peer - * asking to fill from the Next Object, or before the track has content, is simply not answered. - */ - #fillRequested( - largestObject: Location | undefined, - subscriber: SubscriberStream, - subscription: MessageParameters, - fill: FillParameters | undefined - ): boolean { - if (fill === undefined || !subscriber.forwarding || subscriber.finished) return false; - - const filter = fill.locationFilter ?? subscription.locationFilter ?? { type: 'none' }; - - return !isEmptyFetchRange(filter, largestObject); - } - - #resetFills(subscriber: SubscriberStream): void { - for (const fill of subscriber.fills) { - void fill.writer?.abort(new Error('moq publish session: subscription ended')).catch(() => {}); - } - - subscriber.fills.clear(); - } - - /** - * Answer a nonempty fill request (see `#fillRequested`). This origin serves no fills, so it meets the §5.1.3.1 - * requirement the honest way: open a uni stream, write the FETCH_HEADER carrying the initiating Request ID so the - * subscriber can correlate the failure, then reset it. A reset is the fill-failure signal — a FIN would falsely claim - * the fill range was delivered in full. Moq-relay requests the current group this way (0.14.17 through 0.17.0) on - * every upstream SUBSCRIBE once the track has content. - * - * The header survives the reset only where the writer has WebTransport's `commit()` (RESET_STREAM_AT's reliable - * prefix). Without it (Chromium as of 147) the subscription is still served: the reset may discard the header, and - * the subscriber then sees no fill at all — which, like a failed one, leaves its join at the next group boundary. - * Refusing the SUBSCRIBE instead would fail every relay's second pull of a live track (the real subscribe after a - * cross-relay TRACK_INFO probe, or any re-subscribe after the last viewer left), so nothing would play across a relay - * mesh. - */ - #openAndResetFill(requestId: number, subscriber: SubscriberStream): void { - const fill: FillStream = {}; - - subscriber.fills.add(fill); - - void (async () => { - try { - const stream = await this.openUniStream(); - const writer = stream.getWriter(); - - fill.writer = writer; - - if (!subscriber.fills.has(fill) || subscriber.finished) return; - - // PUBLISH_DONE's Stream Count includes fill fetch streams - // (§10.12). Count in the same synchronous step that commits this - // stream to its FETCH_HEADER — the track publisher's rule for - // subgroup streams — so any PUBLISH_DONE covers every fill that - // carries a header. A fill still opening when the track ended - // was stopped by the guard above: it is reset with no header, so - // the subscriber cannot attribute it to this subscription and - // leaving it uncounted cannot put the subscriber over the count. - // A counted fill whose reset discards its header (no commit()) - // or whose write rejects over-counts by one; for that §10.12 has - // the subscriber fall back to a timeout. - subscriber.fillStreams++; - await writer.write(encodeFetchHeader(requestId)); - - if (!subscriber.fills.has(fill) || subscriber.finished) return; - - // write() only hands bytes to the transport. commit() includes - // them in the reliable prefix of RESET_STREAM_AT; without it the - // reset below is best-effort for the header. - if (hasMethods(writer, ['commit'])) writer.commit(); - } catch { - // Session closing or the peer went away before the header landed. - } finally { - subscriber.fills.delete(fill); - void fill.writer?.abort(new Error('moq publish session: fill fetch streams are not served')).catch(() => {}); - } - })(); - } - - // --------------------------------------------------------------------------- - // Incoming unidirectional streams (control, padding) - // --------------------------------------------------------------------------- - - async #acceptUnidirectionalStreams(): Promise { - const reader = this.#transport.incomingUnidirectionalStreams.getReader(); - - try { - while (true) { - const { done, value } = await reader.read(); - if (done) break; - - void this.#handleUnidirectionalStream(value).catch((error) => { - if (isMoqtProtocolError(error)) this.#fatal(error); - }); - } - } catch { - // Transport went away; `closed` handles the surfacing. - } finally { - reader.releaseLock(); - } - } - - async #handleUnidirectionalStream(stream: ReadableStream): Promise { - const reader = new StreamReader(stream); - const streamType = await reader.readVarint(); - - if (streamType === STREAM_TYPE.SETUP) { - await this.#runControlStream(reader); - return; - } - - if (streamType === STREAM_TYPE.PADDING) { - await reader.cancel(); - return; - } - - await reader.cancel(); - - if (isSubgroupHeaderType(streamType) || streamType === STREAM_TYPE.FETCH_HEADER) { - throw new MoqtProtocolError('publish session received a data stream'); - } - - throw new MoqtProtocolError(`unknown unidirectional stream type 0x${streamType.toString(16)}`); - } - - /** Read one control-message frame using the pull-based stream reader. */ - async #readControlFrame(reader: StreamReader, type: number): Promise { - const high = await reader.readUint8(); - const low = await reader.readUint8(); - const body = await reader.readBytes(high * 256 + low); - - return decodeControlMessage({ type, body }); - } - - async #runControlStream(reader: StreamReader): Promise { - // The stream-type varint (0x2F00) doubles as the first message's type. - const setup = await this.#readControlFrame(reader, MESSAGE_TYPE.SETUP); - if (setup.kind !== 'setup') throw new MoqtProtocolError('control stream did not begin with SETUP'); - - if (this.#receivedServerSetup) { - throw new MoqtProtocolError('received a second control stream'); - } - - this.#receivedServerSetup = true; - this.#resolveReady(); - this.#callbacks.onReady?.(setup.options); - - while (!(await reader.atEnd())) { - const type = await reader.readVarint(); - const message = await this.#readControlFrame(reader, type); - if (message.kind !== 'goaway') throw new MoqtProtocolError(`unexpected ${message.kind} on the control stream`); - - if (this.#receivedControlGoaway) { - throw new MoqtProtocolError('received more than one GOAWAY on the control stream'); - } - - this.#receivedControlGoaway = true; - this.#receivedGoaway = true; - this.#callbacks.onGoaway?.(message); - } - - // A closed control stream ends the session (§3.3). - if (!this.#destroyed) { - this.#fatal(new MoqtProtocolError('peer closed its control stream')); - } - } - - // --------------------------------------------------------------------------- - // Incoming bidirectional streams (peer-initiated requests) - // --------------------------------------------------------------------------- - - async #acceptBidirectionalStreams(): Promise { - const reader = this.#transport.incomingBidirectionalStreams.getReader(); - - try { - while (true) { - const { done, value } = await reader.read(); - if (done) break; - - void this.#handleIncomingRequest(value).catch((error) => { - if (isMoqtProtocolError(error)) this.#fatal(error); - }); - } - } catch { - // Transport went away. - } finally { - reader.releaseLock(); - } - } - - async #handleIncomingRequest(stream: BidirectionalStreamLike): Promise { - const reader = new StreamReader(stream.readable); - const type = await reader.readVarint(); - const message = await this.#readControlFrame(reader, type); - - // Reserve the request ID for EVERY request-initiating kind — the - // uniqueness invariant is session-wide, so an ID burned on a - // rejected PUBLISH or FETCH must not be reusable by a later - // SUBSCRIBE (whose alias it would become). - const initiatingRequestId = - message.kind === 'fetch' - ? message.request.requestId - : message.kind === 'subscribe' || - message.kind === 'subscribe-namespace' || - message.kind === 'publish' || - message.kind === 'publish-namespace' || - message.kind === 'track-status' - ? message.requestId - : undefined; - - if (initiatingRequestId !== undefined) this.#claimPeerRequestId(initiatingRequestId); - - if (message.kind === 'subscribe') { - await this.#handleIncomingSubscribe(stream, reader, message); - return; - } - - if (message.kind === 'subscribe-namespace') { - await this.#handleSubscribeNamespace(stream, reader, message); - return; - } - - // Everything else: this endpoint only serves its own published tracks. - const respond = async (bytes: Uint8Array) => { - const writer = stream.writable.getWriter(); - - try { - await writer.write(bytes); - await writer.close(); - } catch { - // Peer cancelled; nothing to clean up. - } - - await reader.cancel(); - }; - const errorCode = message.kind === 'publish' ? REQUEST_ERROR_CODE.UNINTERESTED : REQUEST_ERROR_CODE.NOT_SUPPORTED; - - await respond(encodeRequestError(errorCode, 'publish-only endpoint')); - } - - /** - * Request IDs are consumed once per session (§10.1) — by every request-initiating message and, since draft-20 gave it - * an id of its own, by REQUEST_UPDATE — and a reuse is session-fatal. - */ - #claimPeerRequestId(requestId: number): void { - if (this.#peerRequestIds.has(requestId)) { - throw new MoqtProtocolError(`peer reused request id ${requestId}`); - } - - this.#peerRequestIds.add(requestId); - } - - /** - * A peer's namespace solicitation — the announce carrier. Accepted with REQUEST_OK, then held open for the session's - * lifetime: NAMESPACE / NAMESPACE_DONE entries for every announced namespace under the prefix ride this stream. A - * clean requester-side FIN is half-closure, not withdrawal (§3.3.2); only a reset (or a rejected update, §10.9.1) - * ends the carrier, and its loss while the announce is live means the peer refused or withdrew the ingest path. - */ - async #handleSubscribeNamespace( - stream: BidirectionalStreamLike, - reader: StreamReader, - subscribeNamespace: Extract - ): Promise { - const writer = stream.writable.getWriter(); - const prefix = subscribeNamespace.trackNamespacePrefix; - - // §10.18: a solicitation overlapping an established one (either - // prefix containing the other) is refused with PREFIX_OVERLAP — - // announcing on both would hand the peer duplicate namespace state - // with inconsistent withdrawals. - const overlaps = - [...this.#namespaceStreams].some( - (existing) => isNamespacePrefix(existing.prefix, prefix) || isNamespacePrefix(prefix, existing.prefix) - ) || - [...this.#pendingNamespacePrefixes].some( - (pending) => isNamespacePrefix(pending, prefix) || isNamespacePrefix(prefix, pending) - ); - - if (overlaps) { - try { - await writer.write(encodeRequestError(REQUEST_ERROR_CODE.PREFIX_OVERLAP, 'overlapping namespace prefix')); - await writer.close(); - } catch { - // Peer cancelled. - } - - await reader.cancel(); - return; - } - - // Reserve the prefix across the acceptance write; the registration - // below happens in the same microtask as the release, so a racing - // overlapping solicitation always sees one or the other. - this.#pendingNamespacePrefixes.add(prefix); - let accepted = false; - - try { - await writer.write(encodeRequestOk()); - accepted = true; - } catch { - // Peer cancelled before the acceptance landed. - } finally { - this.#pendingNamespacePrefixes.delete(prefix); - } - - if (!accepted) { - await reader.cancel(); - return; - } - - const record: NamespaceStream = { - prefix, - writer, - announced: [], - }; - - this.#namespaceStreams.add(record); - this.#reconcileAnnounce(record); - - // Hold the stream. The known peers write nothing further on it. - let failedUpdate = false; - - try { - while (!(await reader.atEnd())) { - const type = await reader.readVarint(); - const message = await this.#readControlFrame(reader, type); - - if (message.kind === 'goaway') { - this.#receivedGoaway = true; - this.#callbacks.onGoaway?.(message); - } else if (message.kind === 'request-update') { - this.#claimPeerRequestId(message.requestId); - // Namespace subscriptions may legally be updated (§10.9). v1 - // applies none of it (a prefix change would re-base every - // entry), so per §10.9.1 the update is answered with an error - // and the request stream closes below — never session-fatal - // (only the reused Request ID above is). - this.#callbacks.onRequestUpdate?.({ - requestId: subscribeNamespace.requestId, - updateRequestId: message.requestId, - parameters: message.parameters, - }); - void writer - .write(encodeRequestError(REQUEST_ERROR_CODE.NOT_SUPPORTED, 'namespace update not supported')) - .catch(() => {}); - failedUpdate = true; - break; - } else { - throw new MoqtProtocolError(`unexpected ${message.kind} on an incoming subscribe-namespace stream`); - } - } - - if (!failedUpdate) { - // A clean requester-side FIN is NOT a cancellation (§3.3.2 — the - // peer merely commits to sending no updates): the response side - // keeps carrying NAMESPACE entries until a reset or the - // transport ends, so the carrier stays registered and open. - return; - } - } catch (error) { - // A protocol violation is session-fatal; #handleClosed sweeps the - // carrier state with everything else. - if (isMoqtProtocolError(error)) throw error; - // Reset — the peer withdrew the namespace subscription. - } - - // Withdrawal (reset) or a failed update: the carrier is over. - this.#namespaceStreams.delete(record); - void writer.close().catch(() => {}); - - if (record.announced.length > 0) this.#reportAnnounceLoss(); - } - - async #handleIncomingSubscribe( - stream: BidirectionalStreamLike, - reader: StreamReader, - subscribe: Extract - ): Promise { - const track = this.#tracks.get(trackKey(subscribe.trackNamespace, subscribe.trackName)); - const writer = stream.writable.getWriter(); - - if (!track || track.done) { - try { - await writer.write(encodeRequestError(REQUEST_ERROR_CODE.DOES_NOT_EXIST, 'unknown track')); - await writer.close(); - } catch { - // Peer cancelled. - } - - await reader.cancel(); - return; - } - - // The peer's request IDs are session-unique, so they double as the - // track alias — binding one alias to two live request IDs is a - // session-fatal Duplicate on moq-lite-rs. - const trackAlias = subscribe.requestId; - const subscriber: SubscriberStream = { - requestId: subscribe.requestId, - trackAlias, - fin: () => { - this.#resetFills(subscriber); - return writer.close(); - }, - done: async (statusCode, streamCount) => { - this.#resetFills(subscriber); - await writer.write(encodePublishDone(statusCode, streamCount)); - await writer.close(); - }, - cancel: async () => { - subscriber.finished = true; - this.#resetFills(subscriber); - writer.abort().catch(() => {}); - - try { - await reader.cancel(); - } catch { - // The stream already errored (e.g. the peer reset it first). - } - }, - accepted: false, - reported: false, - // Forward State defaults to 1; `forward: 0` subscribes without - // authorizing data until a REQUEST_UPDATE flips it. - forwarding: subscribe.parameters.forward !== 0, - finished: false, - fills: new Set(), - fillStreams: 0, - }; - - // Use one snapshot for both the response and its fill range, even if - // the response write is backpressured while live objects advance. - const largestObject = track.getLargestObject?.(); - const fillRequested = this.#fillRequested( - largestObject, - subscriber, - subscribe.parameters, - subscribe.parameters.fillParameters - ); - - track.subscribers.push(subscriber); - - // STOP_SENDING on the response direction cancels the subscription - // even when the request direction stays open and sends no updates. - void writer.closed.catch(() => subscriber.cancel()); - - try { - // Report the track's Largest Object once content exists (§10.2.17 - // MUST; two bare varints) so a `relative-group` - // subscriber can resolve its join. Declaring the timescale is what - // keeps object TIMESTAMP extensions flowing through moq-lite-rs - // relays — undeclared, they parse and discard them and re-stamp - // frames on arrival, and the viewer's clocks would sync to relay - // arrival time instead of capture time. LOC packaging stamps objects - // in microseconds. - await writer.write( - encodeSubscribeOk(trackAlias, largestObject ? { largestObject } : {}, [ - { type: TRACK_PROPERTY.TIMESCALE, value: MICROSECONDS_PER_SECOND }, - ]) - ); - subscriber.accepted = true; - } catch { - // Peer cancelled before the response landed. - track.subscribers = track.subscribers.filter((s) => s !== subscriber); - await reader.cancel(); - return; - } - - // Overlapping same-track subscriptions settle their SUBSCRIBE_OK - // writes independently, so a newer subscription may have replaced - // this one (marking it finished) while this acceptance was still in - // flight — a stale completion must not steal the binding back onto - // an alias whose stream is already ending, and a subscription that - // was never live is never reported (`onSubscribeEnd` pairs on the - // same flag, keeping subscriber counts balanced). - if (!subscriber.finished) { - subscriber.reported = true; - this.#callbacks.onSubscribe?.(subscribe); - - // The newest subscription wins the binding, and every live - // PREDECESSOR (arrival order — a successor may accept before an - // older backpressured write settles, and must not be swept by it) - // ends cleanly (FIN) so the peer's bookkeeping resolves. One live - // subscription per track is a deliberate v1 constraint: the spec - // permits concurrent same-track subscriptions, but serving them - // means writing every group once per alias, and the known peers - // (moq-lite-rs relays) hold at most one upstream subscription per - // track and fan out on their side — the sweep also covers their - // resubscribe races. - for (const other of track.subscribers.slice(0, track.subscribers.indexOf(subscriber))) { - if (other.finished) continue; - - other.finished = true; - const fin = other.fin().catch(() => {}); - - track.pendingFins.push(fin); - void fin.then(() => { - const index = track.pendingFins.indexOf(fin); - - if (index >= 0) track.pendingFins.splice(index, 1); - }); - } - - this.#callbacks.onTrackBinding?.({ - trackName: track.trackName, - trackAlias: subscriber.forwarding ? trackAlias : undefined, - }); - } - - // FILL_PARAMETERS on the SUBSCRIBE requests a fill fetch stream, but - // only while Forward State is 1 and only for a nonempty fill range - // (§5.1.3). We serve none — open and reset it rather than leave the - // peer waiting. - if (fillRequested && !subscriber.finished) { - this.#openAndResetFill(subscribe.requestId, subscriber); - } - - // Keep serving the request stream: REQUEST_UPDATEs arrive here. - try { - while (!(await reader.atEnd())) { - const type = await reader.readVarint(); - const message = await this.#readControlFrame(reader, type); - - if (message.kind === 'request-update') { - this.#claimPeerRequestId(message.requestId); - // FILL_PARAMETERS is a per-message fill request (§5.1.3), not a - // subscription-state change — pulled out so it neither counts as - // an unsupported update nor sticks to the subscription. - const { forward, subscriberPriority: _priority, fillParameters, ...unsupported } = message.parameters; - const largestObject = track.getLargestObject?.(); - - // Forward State toggles ride REQUEST_UPDATE; the binding must - // follow so data stops (or starts) with the subscription's - // authorization. Newest-wins keeps this subscriber the track's - // only live one, so its state IS the binding. - if (forward !== undefined) { - subscriber.forwarding = forward !== 0; - - if (!subscriber.finished && subscriber.accepted) { - this.#callbacks.onTrackBinding?.({ - trackName: track.trackName, - trackAlias: subscriber.forwarding ? subscriber.trackAlias : undefined, - }); - } - } - - // A nonempty fill requested while Forward State is 1 opens (and, - // here, immediately resets) a fill fetch stream keyed by the - // update's own Request ID (§5.1.3.1); an empty range opens none. - const fillRequested = this.#fillRequested(largestObject, subscriber, subscribe.parameters, fillParameters); - - this.#callbacks.onRequestUpdate?.({ - requestId: subscribe.requestId, - updateRequestId: message.requestId, - parameters: message.parameters, - }); - - if (!subscriber.finished) { - if (Object.keys(unsupported).length > 0) { - // Acknowledging an update we did not apply would leave the - // peer serving stale expectations (a filter or range it - // believes is in effect). Forward State is applied above - // and priority is advisory (the known relays discard ours - // too); anything else ends this request honestly. - subscriber.finished = true; - this.#resetFills(subscriber); - void writer - .write(encodeRequestError(REQUEST_ERROR_CODE.NOT_SUPPORTED, 'unsupported subscription update')) - .then(() => writer.close()) - .catch(() => {}); - - if (subscriber.reported) { - subscriber.reported = false; - this.#callbacks.onSubscribeEnd?.({ requestId: subscribe.requestId }); - const binding = track.subscribers.filter((s) => !s.finished && s.accepted && s.forwarding).at(-1); - - this.#callbacks.onTrackBinding?.({ trackName: track.trackName, trackAlias: binding?.trackAlias }); - } - } else { - // The subscribe driver treats REQUEST_OK as the update's - // completion (`onUpdateOk`). Strictly reactive: a peer that - // never sends REQUEST_UPDATE sees nothing here. - void writer.write(encodeRequestOk(largestObject ? { largestObject } : {})).catch(() => {}); - - if (fillRequested) this.#openAndResetFill(message.requestId, subscriber); - } - } - } else if (message.kind === 'goaway') { - this.#receivedGoaway = true; - this.#callbacks.onGoaway?.(message); - } else { - throw new MoqtProtocolError(`unexpected ${message.kind} on an incoming subscribe stream`); - } - } - } catch (error) { - if (isMoqtProtocolError(error)) throw error; - // Reset — the subscriber cancelled (§3.3.3); ordinary end-of-request. - } finally { - subscriber.finished = true; - this.#resetFills(subscriber); - track.subscribers = track.subscribers.filter((s) => s !== subscriber); - // The subscription is over both ways — mirror of the namespace - // stream's cleanup: when the peer FINed first, an unclosed response - // direction would leak a half-open stream per unsubscribe until the - // transport closes. Already-FINed/aborted writers reject harmlessly. - void writer.close().catch(() => {}); - - if (!this.#destroyed && subscriber.reported) { - this.#callbacks.onSubscribeEnd?.({ requestId: subscribe.requestId }); - // Only accepted, forwarding subscriptions may carry the binding: - // one whose SUBSCRIBE_OK is still in flight could yet fail (its - // removal would strand `trackBindings` on an alias the peer never - // registered), and one with Forward State 0 forbids data. When a - // pending one accepts, it emits its own binding. - const binding = track.subscribers.filter((s) => !s.finished && s.accepted && s.forwarding).at(-1); - - this.#callbacks.onTrackBinding?.({ trackName: track.trackName, trackAlias: binding?.trackAlias }); - } - } - } -} - -/** - * Create a publish-capable MOQT session driver over an established transport. - * - * @example - * ```ts - * const session = createMoqtPublishSession(transport, { - * callbacks: { onSubscribe: (s) => console.log('serving', s.trackName) }, - * }); - * await session.ready; - * session.announce(['live', 'abc123']); - * const track = session.registerTrack({ trackNamespace: ['live', 'abc123'], trackName: 'video' }); - * ```; - */ -export function createMoqtPublishSession( - transport: MoqtTransport, - config: MoqtPublishSessionConfig = {} -): MoqtPublishSession { - return new MoqtPublishSessionImpl(transport, config); -} - -// ============================================================================= -// Session actor — connect + drive the driver, reactive snapshot for behaviors -// ============================================================================= - /** Where to publish: a MoQ relay endpoint plus the track namespace. */ export interface PublishEndpoint { url: string; @@ -1347,9 +104,14 @@ export function composePublishConnectUrl(url: string, authToken?: string): strin } function connectWebTransport(endpoint: PublishEndpoint): { transport: MoqtTransport; ready: Promise } { - const transport = new WebTransport(composePublishConnectUrl(endpoint.url, endpoint.authToken), { - protocols: [MOQT_PROTOCOL_ID], - }); + // The session reads the negotiated version from `transport.protocol` (the + // `WT-Protocol` response). A browser without that attribute cannot say + // which version the relay picked, so it offers only the default one. + const protocols = 'protocol' in WebTransport.prototype ? [...MOQT_PROTOCOL_IDS] : [MOQT_PROTOCOL_ID]; + const transport: WebTransport & MoqtTransport = new WebTransport( + composePublishConnectUrl(endpoint.url, endpoint.authToken), + { protocols } + ); return { transport, ready: transport.ready.then(() => undefined) }; } @@ -1419,7 +181,7 @@ export function createPublishSessionActor(options: CreatePublishSessionActorOpti } session = createMoqtPublishSession(transport, { - implementationName: options.implementationName, + implementationName: options.implementationName ?? DEFAULT_IMPLEMENTATION_NAME, callbacks: { onGoaway: (goaway) => inner.send({ type: 'goaway', goaway }), onAnnounced: () => inner.send({ type: 'announced' }), 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 099e38f975..6633298ee5 100644 --- a/packages/spf/src/publish/session/tests/publish-session.test.ts +++ b/packages/spf/src/publish/session/tests/publish-session.test.ts @@ -1,1786 +1,114 @@ -import { describe, expect, it, vi } from 'vite-plus/test'; +import { createMoqtSession, type MoqtObject, type MoqtSession, SETUP_OPTION, utf8Decode } from '@caprid/moq-core'; +import { afterEach, describe, expect, it, vi } from 'vite-plus/test'; import { toLocFrame } from '../../../media/moq/loc'; import { packageLocFrame } from '../../../media/moq/loc-packaging'; import { applyMoqCatalogUpdate } from '../../../media/moq/parse-catalog'; -import { utf8Decode, utf8Encode } from '../../../network/moqt/bytes'; -import { StreamReader } from '../../../network/moqt/bytes'; import { - type ControlMessage, ControlMessageDeframer, decodeControlMessage, encodeGoaway, - encodePublish, - encodeRequestUpdate, encodeSetup, - encodeSubscribe, - PUBLISH_DONE_STATUS, - REQUEST_ERROR_CODE, - SETUP_OPTION, - TRACK_PROPERTY, - type TrackNamespace, -} from '../../../network/moqt/control-messages'; -import { type MoqtObject, readFetchHeader, STREAM_TYPE } from '../../../network/moqt/object-stream'; -import { createMoqtSession, type MoqtSession } from '../../../network/moqt/session'; + utf8Encode, +} from '../../../network/tests/helpers/moqt-wire'; +import { solicitNamespace } from '../../../network/tests/helpers/raw-peer'; import { - openRawRequest, - rawSubscribe as rawSubscribeTo, - solicitNamespace, -} from '../../../network/moqt/tests/helpers/raw-peer'; -import { createTransportPair } from '../../../network/moqt/tests/helpers/transport-pair'; + createTransportPair, + SERVER_REQUEST_ID_OFFSET, + withServerRequestIds, +} from '../../../network/tests/helpers/transport-pair'; import { createTrackPublisherActor } from '../../actors/track-publisher'; import { composePublishConnectUrl, - createMoqtPublishSession, createPublishSessionActor, - type IncomingSubscribe, - type MoqtPublishSessionCallbacks, type PublishSessionActorStatus, } from '../publish-session'; const NAMESPACE = ['live', 'abc123']; -/** The relay's per-track pull under the test namespace. */ -function rawSubscribe(server: Parameters[0], trackName: string, requestId: number) { - return rawSubscribeTo(server, NAMESPACE, trackName, requestId); -} - -function makePublishHarness(callbacks: MoqtPublishSessionCallbacks = {}) { - const pair = createTransportPair(); - const subscriber = createMoqtSession(pair.server, { unknownAliasTimeoutMs: 500 }); - const session = createMoqtPublishSession(pair.client, { callbacks }); - - return { pair, session, subscriber }; -} - -function collectTrack( - subscriber: MoqtSession, - trackName: string -): { objects: MoqtObject[]; aliases: number[]; subscription: ReturnType } { - const objects: MoqtObject[] = []; - const aliases: number[] = []; - const subscription = subscriber.subscribe( - { trackNamespace: NAMESPACE, trackName }, - { - onOk: (ok) => aliases.push(ok.trackAlias), - onObject: (object) => objects.push(object), - } - ); - - return { objects, aliases, subscription }; -} - -/** - * A publish session facing a raw peer with no subscribe driver: the peer completes SETUP by hand and watches the - * publisher's uni streams for fill fetch streams, recording each FETCH_HEADER's Request ID and whether the publisher - * reset the stream (the fill-failure signal) or FINed it. `finish()` destroys the session and releases the observer's - * reader — the transport pair never ends its incoming-stream queues, so a pending `read()` would otherwise outlive the - * test. - */ -async function makeFillHarness({ - reliableReset = true, - openFillStream, - callbacks, -}: { - reliableReset?: boolean; - openFillStream?: () => Promise>; - callbacks?: MoqtPublishSessionCallbacks; -} = {}) { - const pair = createTransportPair(); - const openUniStream = pair.client.createUnidirectionalStream.bind(pair.client); - let openedControl = false; - - pair.client.createUnidirectionalStream = async () => { - if (openedControl && openFillStream) return openFillStream(); - - openedControl = true; - const stream = await openUniStream(); - const getWriter = stream.getWriter.bind(stream); - - // This zero-buffer pipe settles writes only once the peer has read - // them, so its reliable prefix is already delivered at commit time. - if (reliableReset) stream.getWriter = () => Object.assign(getWriter(), { commit() {} }); - - return stream; - }; - - const session = createMoqtPublishSession(pair.client, { callbacks }); - const fills: { requestId: number; reset: boolean }[] = []; - const streams = pair.server.incomingUnidirectionalStreams.getReader(); - - void (async () => { - while (true) { - const { done, value } = await streams.read(); - if (done) break; - - void (async () => { - const reader = new StreamReader(value); - const type = await reader.readVarint().catch(() => -1); - if (type !== STREAM_TYPE.FETCH_HEADER) return; - - const { requestId } = await readFetchHeader(reader); - - // The publisher resets after the FETCH_HEADER; the drain throws. - try { - while (!(await reader.atEnd())) await reader.readUint8(); - - fills.push({ requestId, reset: false }); - } catch { - fills.push({ requestId, reset: true }); - } - })(); - } - })(); - - const control = await pair.server.createUnidirectionalStream(); - - await control.getWriter().write(encodeSetup()); - await session.ready; - - return { - pair, - session, - fills, - finish: async () => { - session.destroy(); - await streams.cancel(); - }, - }; -} - -/** - * A buffered send stream: reset discards everything except the explicitly committed prefix. Without `reliableReset` the - * writer has no `commit()` — a browser WebTransport today — so a reset discards everything still unread. - */ -function makeBufferedFillStream({ reliableReset = true }: { reliableReset?: boolean } = {}) { - const chunks: Uint8Array[] = []; - let committed = 0; - let readIndex = 0; - let reset: unknown; - let pendingRead: ReadableStreamDefaultController | undefined; - const deliver = () => { - if (!pendingRead) return; - - const controller = pendingRead; - const limit = reset ? committed : chunks.length; - - if (readIndex < limit) { - pendingRead = undefined; - controller.enqueue(chunks[readIndex++]!); - } else if (reset) { - pendingRead = undefined; - controller.error(reset); - } - }; - const readable = new ReadableStream( - { - pull(controller) { - pendingRead = controller; - deliver(); - }, - }, - { highWaterMark: 0 } - ); - const writable = new WritableStream({ - write(chunk) { - chunks.push(chunk); - deliver(); - }, - abort(reason) { - reset = reason; - deliver(); - }, - }); - const getWriter = writable.getWriter.bind(writable); - - if (reliableReset) { - writable.getWriter = () => - Object.assign(getWriter(), { - commit() { - committed = chunks.length; - }, - }); - } - - return { writable, readable, reset: () => reset }; -} - -describe('createMoqtPublishSession', () => { - it('completes SETUP both ways against the existing subscribe driver', async () => { - const { session, subscriber } = makePublishHarness(); - - await expect(session.ready).resolves.toBeUndefined(); - await expect(subscriber.ready).resolves.toBeUndefined(); - session.destroy(); - subscriber.destroy(); - }); - - it('accepts a namespace solicitation and announces the namespace on it', async () => { - const announced: TrackNamespace[] = []; - const { pair, session, subscriber } = makePublishHarness({ - onAnnounced: ({ namespace }) => announced.push(namespace), - }); - - await session.ready; - session.announce(NAMESPACE); - session.registerTrack({ trackNamespace: NAMESPACE, trackName: 'catalog' }); - - const solicitation = await solicitNamespace(pair.server, []); - - await vi.waitFor(() => { - expect(solicitation.received.map((m) => m.kind)).toEqual(['request-ok', 'namespace']); - }); - // Empty prefix → the suffix is the full namespace. - expect(solicitation.received[1]).toMatchObject({ kind: 'namespace', trackNamespaceSuffix: NAMESPACE }); - expect(announced).toEqual([NAMESPACE]); - session.destroy(); - subscriber.destroy(); - }); - - it('defers the announce until the first track is registered', async () => { - const { pair, session, subscriber } = makePublishHarness(); - - await session.ready; - session.announce(NAMESPACE); - - // Solicited and announced, but nothing to serve yet: an announce now - // would invite SUBSCRIBEs that DOES_NOT_EXIST terminally. - const solicitation = await solicitNamespace(pair.server, []); - - await vi.waitFor(() => { - expect(solicitation.received.map((m) => m.kind)).toEqual(['request-ok']); - }); - await new Promise((resolve) => setTimeout(resolve, 20)); - expect(solicitation.received).toHaveLength(1); - - // The first registration releases it. - session.registerTrack({ trackNamespace: NAMESPACE, trackName: 'catalog' }); - await vi.waitFor(() => { - expect(solicitation.received.map((m) => m.kind)).toEqual(['request-ok', 'namespace']); - }); - session.destroy(); - subscriber.destroy(); - }); - - it('announces on a solicitation that arrived before announce()', async () => { - const announced: TrackNamespace[] = []; - const { pair, session, subscriber } = makePublishHarness({ - onAnnounced: ({ namespace }) => announced.push(namespace), - }); - - await session.ready; - - const solicitation = await solicitNamespace(pair.server, []); - - await vi.waitFor(() => { - expect(solicitation.received.map((m) => m.kind)).toEqual(['request-ok']); - }); - - session.announce(NAMESPACE); - session.registerTrack({ trackNamespace: NAMESPACE, trackName: 'catalog' }); - await vi.waitFor(() => { - expect(solicitation.received.map((m) => m.kind)).toEqual(['request-ok', 'namespace']); - expect(announced).toEqual([NAMESPACE]); - }); - session.destroy(); - subscriber.destroy(); - }); - - it('announces the suffix relative to a non-empty solicited prefix', async () => { - const { pair, session, subscriber } = makePublishHarness(); - - await session.ready; - session.announce(NAMESPACE); - session.registerTrack({ trackNamespace: NAMESPACE, trackName: 'catalog' }); - - const solicitation = await solicitNamespace(pair.server, ['live']); - - await vi.waitFor(() => { - expect(solicitation.received).toHaveLength(2); - }); - expect(solicitation.received[1]).toMatchObject({ kind: 'namespace', trackNamespaceSuffix: ['abc123'] }); - session.destroy(); - subscriber.destroy(); - }); - - it('accepts but never announces on a solicitation whose prefix does not cover the namespace', async () => { - const announced: TrackNamespace[] = []; - const { pair, session, subscriber } = makePublishHarness({ - onAnnounced: ({ namespace }) => announced.push(namespace), - }); - - await session.ready; - session.announce(NAMESPACE); - session.registerTrack({ trackNamespace: NAMESPACE, trackName: 'catalog' }); - - const solicitation = await solicitNamespace(pair.server, ['other']); - - await vi.waitFor(() => { - expect(solicitation.received.map((m) => m.kind)).toEqual(['request-ok']); - }); - await new Promise((resolve) => setTimeout(resolve, 20)); - expect(solicitation.received).toHaveLength(1); - expect(announced).toEqual([]); - session.destroy(); - subscriber.destroy(); - }); - - it('reports onAnnounceEnded when the solicitation carrying the announce ends', async () => { - const endings: unknown[] = []; - const { pair, session, subscriber } = makePublishHarness({ - onAnnounceEnded: ({ error }) => endings.push(error), - }); - - await session.ready; - session.announce(NAMESPACE); - session.registerTrack({ trackNamespace: NAMESPACE, trackName: 'catalog' }); - - const solicitation = await solicitNamespace(pair.server, []); - - await vi.waitFor(() => { - expect(solicitation.received).toHaveLength(2); - }); - - // The peer withdrawing the namespace subscription (a reset — a clean - // FIN is only half-closure) takes the announce with it — the ingest - // path is gone. - void solicitation.reset(); - await vi.waitFor(() => { - expect(endings).toHaveLength(1); - }); - expect(endings[0]).toBeInstanceOf(Error); - session.destroy(); - subscriber.destroy(); - }); - - it('keeps the carrier alive across the requester half-closing its side', async () => { - const endings: unknown[] = []; - const { pair, session, subscriber } = makePublishHarness({ - onAnnounceEnded: ({ error }) => endings.push(error), - }); - - await session.ready; - session.announce(NAMESPACE); - session.registerTrack({ trackNamespace: NAMESPACE, trackName: 'catalog' }); - - const solicitation = await solicitNamespace(pair.server, []); - - await vi.waitFor(() => { - expect(solicitation.received.map((m) => m.kind)).toEqual(['request-ok', 'namespace']); - }); - - // §3.3.2: a clean requester FIN only commits to sending no updates — - // it is not a withdrawal, and the response side keeps carrying the - // announce. - void solicitation.fin(); - await new Promise((resolve) => setTimeout(resolve, 30)); - expect(endings).toEqual([]); - - // The carrier is still the retraction path at close(). - session.close(); - await vi.waitFor(() => { - expect(solicitation.received.map((m) => m.kind)).toEqual(['request-ok', 'namespace', 'namespace-done']); - }); - subscriber.destroy(); - }); - - it('rejects an overlapping namespace solicitation with PREFIX_OVERLAP', async () => { - const endings: unknown[] = []; - const { pair, session, subscriber } = makePublishHarness({ - onAnnounceEnded: ({ error }) => endings.push(error), - }); - - await session.ready; - session.announce(NAMESPACE); - session.registerTrack({ trackNamespace: NAMESPACE, trackName: 'catalog' }); - - const broad = await solicitNamespace(pair.server, [], 1); - - await vi.waitFor(() => { - expect(broad.received.map((m) => m.kind)).toEqual(['request-ok', 'namespace']); - }); - - // §10.18: a second solicitation whose prefix nests with an - // established one would produce duplicate namespace state — refused, - // and the established carrier is untouched. - const narrow = await solicitNamespace(pair.server, ['live'], 3); - - await vi.waitFor(() => { - expect(narrow.received.map((m) => m.kind)).toEqual(['request-error']); - expect(narrow.ended()).toBe(true); - }); - expect(narrow.received[0]).toMatchObject({ errorCode: REQUEST_ERROR_CODE.PREFIX_OVERLAP }); - await new Promise((resolve) => setTimeout(resolve, 20)); - expect(broad.ended()).toBe(false); - expect(endings).toEqual([]); - session.destroy(); - subscriber.destroy(); - }); - - it('holds the overlap guard across the acceptance write of a racing solicitation', async () => { - const endings: unknown[] = []; - const { pair, session, subscriber } = makePublishHarness({ - onAnnounceEnded: ({ error }) => endings.push(error), - }); - - await session.ready; - session.announce(NAMESPACE); - session.registerTrack({ trackNamespace: NAMESPACE, trackName: 'catalog' }); - - // Both solicitations are in flight before either REQUEST_OK write - // settles — request handlers run concurrently, so §10.18's - // single-carrier rule must hold across the acceptance await, not - // only at the synchronous check. - const [broad, narrow] = await Promise.all([ - solicitNamespace(pair.server, [], 1), - solicitNamespace(pair.server, ['live'], 3), - ]); - - await vi.waitFor(() => { - expect(broad.received.length).toBeGreaterThanOrEqual(1); - expect(narrow.received.length).toBeGreaterThanOrEqual(1); - }); - expect([broad.received[0]?.kind, narrow.received[0]?.kind].sort()).toEqual(['request-error', 'request-ok']); - const refused = broad.received[0]?.kind === 'request-error' ? broad : narrow; - const accepted = refused === broad ? narrow : broad; - - expect(refused.received[0]).toMatchObject({ errorCode: REQUEST_ERROR_CODE.PREFIX_OVERLAP }); - await vi.waitFor(() => { - expect(accepted.received.map((m) => m.kind)).toEqual(['request-ok', 'namespace']); - expect(refused.ended()).toBe(true); - }); - expect(endings).toEqual([]); - session.destroy(); - subscriber.destroy(); - }); - - it('answers inbound SUBSCRIBE with the request id as the alias and routes REQUEST_UPDATE', async () => { - const subscribes: IncomingSubscribe[] = []; - const updates: { requestId: number; updateRequestId: number }[] = []; - const bindings: { trackName: string; trackAlias: number | undefined }[] = []; - const { session, subscriber } = makePublishHarness({ - onSubscribe: (subscribe) => subscribes.push(subscribe), - onRequestUpdate: ({ requestId, updateRequestId }) => updates.push({ requestId, updateRequestId }), - onTrackBinding: (binding) => bindings.push(binding), - }); - - await session.ready; - session.registerTrack({ trackNamespace: NAMESPACE, trackName: 'video' }); - - const video = collectTrack(subscriber, 'video'); - - await vi.waitFor(() => { - // The peer's request ids are session-unique, so they double as the - // alias — two live request ids sharing an alias is a session-fatal - // Duplicate on moq-lite-rs. - expect(video.aliases).toEqual([video.subscription.requestId]); - expect(subscribes.map((s) => s.trackName)).toEqual(['video']); - expect(bindings).toEqual([{ trackName: 'video', trackAlias: video.subscription.requestId }]); - }); - - // The ack lands as the driver's update completion (`onUpdateOk` sits - // in the subscribe-time handlers). - const updateAcks: number[] = []; - const updated = subscriber.subscribe( - { trackNamespace: NAMESPACE, trackName: 'video' }, - { onUpdateOk: () => updateAcks.push(1) } - ); - - await vi.waitFor(() => { - expect(subscribes).toHaveLength(2); - }); - updated.update({ subscriberPriority: 9 }); - await vi.waitFor(() => { - // The update is attributed to the subscription it rode in on, while - // consuming a Request ID of its own (§10.1). - expect(updates).toEqual([{ requestId: updated.requestId, updateRequestId: expect.any(Number) }]); - expect(updates[0]?.updateRequestId).not.toBe(updated.requestId); - expect(updateAcks).toHaveLength(1); - }); - session.destroy(); - subscriber.destroy(); - }); - - it('declares the microsecond timescale in SUBSCRIBE_OK track properties', async () => { - const { pair, session, subscriber } = makePublishHarness(); - - await session.ready; - session.registerTrack({ trackNamespace: NAMESPACE, trackName: 'video' }); - - const subscribe = await rawSubscribe(pair.server, 'video', 11); - - await vi.waitFor(() => { - expect(subscribe.received).toHaveLength(1); - }); - // Undeclared, moq-lite-rs relays parse and DISCARD the objects' - // TIMESTAMP extensions and re-stamp frames on arrival — viewers would - // sync to relay arrival time instead of capture time. - expect(subscribe.received[0]).toMatchObject({ - kind: 'subscribe-ok', - trackAlias: 11, - trackProperties: [{ type: TRACK_PROPERTY.TIMESCALE, value: 1_000_000 }], - }); - session.destroy(); - subscriber.destroy(); - }); - - it('rejects inbound SUBSCRIBE for unknown tracks with DOES_NOT_EXIST', async () => { - const { session, subscriber } = makePublishHarness(); - - await session.ready; - - const errors: number[] = []; - - subscriber.subscribe( - { trackNamespace: NAMESPACE, trackName: 'nope' }, - { onError: (error) => errors.push(error.errorCode) } - ); - await vi.waitFor(() => { - expect(errors).toEqual([REQUEST_ERROR_CODE.DOES_NOT_EXIST]); - }); - session.destroy(); - subscriber.destroy(); - }); - - it('ends a track with PUBLISH_DONE (TRACK_ENDED and the stream count), then FIN', async () => { - const endedRequests: number[] = []; - const bindings: (number | undefined)[] = []; - const { pair, session, subscriber } = makePublishHarness({ - onSubscribeEnd: ({ requestId }) => endedRequests.push(requestId), - onTrackBinding: ({ trackAlias }) => bindings.push(trackAlias), - }); - - await session.ready; - const track = session.registerTrack({ - trackNamespace: NAMESPACE, - trackName: 'video', - getStreamCount: (trackAlias) => (trackAlias === 21 ? 4 : 0), - }); - - const subscribe = await rawSubscribe(pair.server, 'video', 21); - - await vi.waitFor(() => { - expect(subscribe.received).toHaveLength(1); - }); - - track.end(); - // The local end is authoritative: the subscription is reported ended - // and the binding cleared immediately — not when the peer eventually - // closes its request direction. - expect(endedRequests).toEqual([21]); - expect(bindings.at(-1)).toBeUndefined(); - await vi.waitFor(() => { - expect(subscribe.ended()).toBe(true); - }); - // moq-relay 0.17.0 forwards this as "track ended"; a bare FIN - // reaches viewers as "internal error". - expect(subscribe.received.map((m) => m.kind)).toEqual(['subscribe-ok', 'publish-done']); - expect(subscribe.received[1]).toMatchObject({ statusCode: PUBLISH_DONE_STATUS.TRACK_ENDED, streamCount: 4 }); - - // The peer closing its side afterwards must not double-report. - void subscribe.fin(); - await new Promise((resolve) => setTimeout(resolve, 30)); - expect(endedRequests).toEqual([21]); - session.destroy(); - 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); - }); - // No stream-count source registered: the count is the 2^64−1 - // "unknown" sentinel, which decodes as undefined. - expect(subscribe.received.map((m) => m.kind)).toEqual(['subscribe-ok', 'publish-done']); - expect(subscribe.received[1]).toMatchObject({ - statusCode: PUBLISH_DONE_STATUS.TRACK_ENDED, - streamCount: undefined, - }); - subscriber.destroy(); - }); - - it('hands the binding to the newest subscription and FINs the replaced stream', async () => { - const bindings: (number | undefined)[] = []; - const endedRequests: number[] = []; - const { pair, session, subscriber } = makePublishHarness({ - onTrackBinding: ({ trackAlias }) => bindings.push(trackAlias), - onSubscribeEnd: ({ requestId }) => endedRequests.push(requestId), - }); - - await session.ready; - session.registerTrack({ trackNamespace: NAMESPACE, trackName: 'video' }); - - const first = await rawSubscribe(pair.server, 'video', 31); - - await vi.waitFor(() => { - expect(first.received).toHaveLength(1); - }); - - const second = await rawSubscribe(pair.server, 'video', 33); - - await vi.waitFor(() => { - expect(second.received).toHaveLength(1); - // The replaced subscription ends cleanly (FIN, no trailing bytes). - expect(first.ended()).toBe(true); - }); - expect(first.received.map((m) => m.kind)).toEqual(['subscribe-ok']); - // The relay closes its own side after seeing ours; only then does the - // replaced subscription's stream fully end. - void first.fin(); - await vi.waitFor(() => { - expect(endedRequests).toEqual([31]); - }); - // Rebinding lands on the newest alias; the replaced stream's own end - // re-derives the same binding rather than clearing it. - expect(bindings[0]).toBe(31); - expect(bindings[bindings.length - 1]).toBe(33); - expect(bindings).not.toContain(undefined); - session.destroy(); - subscriber.destroy(); - }); - - it('converges on the newest subscription regardless of acceptance order', async () => { - const bindings: (number | undefined)[] = []; - const { pair, session, subscriber } = makePublishHarness({ - onTrackBinding: ({ trackAlias }) => bindings.push(trackAlias), - }); - - await session.ready; - session.registerTrack({ trackNamespace: NAMESPACE, trackName: 'video' }); - - // Both SUBSCRIBEs land with their acceptances backpressured (unread - // responses); the OLDER one is then released first. - const openHeld = async (requestId: number) => { - const stream = await pair.server.createBidirectionalStream(); - const writer = stream.writable.getWriter(); - - await writer.write(encodeSubscribe({ requestId, trackNamespace: NAMESPACE, trackName: 'video', parameters: {} })); - let ended = false; - - return { - ended: () => ended, - drain: () => { - void (async () => { - const reader = stream.readable.getReader(); - - while (true) { - const { done } = await reader.read(); - if (done) break; - } - })().then( - () => { - ended = true; - }, - () => { - ended = true; - } - ); - }, - }; - }; - const older = await openHeld(91); - - await new Promise((resolve) => setTimeout(resolve, 20)); - const newer = await openHeld(93); - - await new Promise((resolve) => setTimeout(resolve, 20)); - - // Older accepts first — it may bind transiently, but must not sweep - // the newer request that arrived after it. - older.drain(); - await vi.waitFor(() => { - expect(bindings.at(-1)).toBe(91); - }); - - // The newer acceptance lands and takes the binding; the older is - // FINed as its predecessor. - newer.drain(); - await vi.waitFor(() => { - expect(bindings.at(-1)).toBe(93); - expect(older.ended()).toBe(true); - }); - session.destroy(); - subscriber.destroy(); - }); - - it('a stale acceptance does not steal the binding from a newer subscription', async () => { - const bindings: (number | undefined)[] = []; - const subscribed: number[] = []; - const { pair, session, subscriber } = makePublishHarness({ - onTrackBinding: ({ trackAlias }) => bindings.push(trackAlias), - onSubscribe: ({ requestId }) => subscribed.push(requestId), - }); - - await session.ready; - session.registerTrack({ trackNamespace: NAMESPACE, trackName: 'video' }); - - // Subscription A: write the SUBSCRIBE but do NOT read the response — - // over the in-memory pair a write only settles once the far side - // reads, so A's SUBSCRIBE_OK hangs in flight. - const streamA = await pair.server.createBidirectionalStream(); - const writerA = streamA.writable.getWriter(); - - await writerA.write( - encodeSubscribe({ requestId: 61, trackNamespace: NAMESPACE, trackName: 'video', parameters: {} }) - ); - await new Promise((resolve) => setTimeout(resolve, 20)); - - // Subscription B reads immediately: its acceptance settles first, - // replaces A, and takes the binding. - const b = await rawSubscribe(pair.server, 'video', 63); - - await vi.waitFor(() => { - expect(b.received).toHaveLength(1); - expect(bindings.at(-1)).toBe(63); - }); - - // Now drain A: its stale acceptance completes against a subscription - // that was already replaced — it must not rebind the track. - const readerA = streamA.readable.getReader(); - - void (async () => { - while (true) { - const { done } = await readerA.read(); - if (done) break; - } - })().catch(() => {}); - await new Promise((resolve) => setTimeout(resolve, 50)); - expect(bindings).not.toContain(61); - expect(bindings.at(-1)).toBe(63); - // The swept-while-pending subscription was never live, so it is never - // reported — subscriber counts stay balanced. - expect(subscribed).toEqual([63]); - session.destroy(); - subscriber.destroy(); - }); - - it('withholds the binding while Forward State is 0 and follows REQUEST_UPDATE toggles', async () => { - const bindings: (number | undefined)[] = []; - const { pair, session, subscriber } = makePublishHarness({ - onTrackBinding: ({ trackAlias }) => bindings.push(trackAlias), - }); - - await session.ready; - session.registerTrack({ trackNamespace: NAMESPACE, trackName: 'video' }); - - // `forward: 0` subscribes without authorizing data. - const sub = await openRawRequest( - pair.server, - encodeSubscribe({ requestId: 81, trackNamespace: NAMESPACE, trackName: 'video', parameters: { forward: 0 } }) - ); - - await vi.waitFor(() => { - expect(sub.received.map((m) => m.kind)).toEqual(['subscribe-ok']); - expect(bindings).toEqual([undefined]); - }); - - // Each REQUEST_UPDATE consumes a Request ID of its own (§10.1). - await sub.send(encodeRequestUpdate(83, { forward: 1 })); - await vi.waitFor(() => { - expect(bindings.at(-1)).toBe(81); - }); - - await sub.send(encodeRequestUpdate(85, { forward: 0 })); - await vi.waitFor(() => { - expect(bindings.at(-1)).toBeUndefined(); - }); - // Each accepted update is acknowledged — the subscribe driver treats - // REQUEST_OK as the update's completion. (The binding update above is - // synchronous server-side while the ack rides the transport, so this - // must wait too.) - await vi.waitFor(() => { - expect(sub.received.map((m) => m.kind)).toEqual(['subscribe-ok', 'request-ok', 'request-ok']); - }); - session.destroy(); - subscriber.destroy(); - }); - - it('sweeps every live predecessor when a new subscription takes the binding', async () => { - const bindings: (number | undefined)[] = []; - const { pair, session, subscriber } = makePublishHarness({ - onTrackBinding: ({ trackAlias }) => bindings.push(trackAlias), - }); - - await session.ready; - session.registerTrack({ trackNamespace: NAMESPACE, trackName: 'video' }); - - // A: fully accepted and bound. - const a = await rawSubscribe(pair.server, 'video', 71); - - await vi.waitFor(() => { - expect(bindings.at(-1)).toBe(71); - }); - - // B: acceptance held in flight (unread response). - const streamB = await pair.server.createBidirectionalStream(); - const writerB = streamB.writable.getWriter(); - - await writerB.write( - encodeSubscribe({ requestId: 73, trackNamespace: NAMESPACE, trackName: 'video', parameters: {} }) - ); - await new Promise((resolve) => setTimeout(resolve, 20)); - - // C settles first and must sweep BOTH A and B — leaving A live would - // let it reclaim the binding when C ends. - const c = await rawSubscribe(pair.server, 'video', 75); - - await vi.waitFor(() => { - expect(c.received).toHaveLength(1); - expect(bindings.at(-1)).toBe(75); - expect(a.ended()).toBe(true); - }); - - // C ends (the relay closes both directions): the binding clears - // instead of falling back to the superseded A. - void c.fin(); - await vi.waitFor(() => { - expect(bindings.at(-1)).toBeUndefined(); - }); - expect(bindings.filter((alias) => alias === 71)).toEqual([71]); - session.destroy(); - subscriber.destroy(); - }); - - it('surfaces the announce loss when only the response half of the solicitation dies', async () => { - const endings: unknown[] = []; - const { pair, session, subscriber } = makePublishHarness({ - onAnnounceEnded: ({ error }) => endings.push(error), - }); - - await session.ready; - - const solicitation = await solicitNamespace(pair.server, []); - - await vi.waitFor(() => { - expect(solicitation.received.map((m) => m.kind)).toEqual(['request-ok']); - }); - - // The peer resets only the response direction; its request half — the - // read loop's end signal — stays open, so the entry write's failure - // is the only evidence the carrier is unusable. - await solicitation.abandonReads(); - session.announce(NAMESPACE); - session.registerTrack({ trackNamespace: NAMESPACE, trackName: 'catalog' }); - await vi.waitFor(() => { - expect(endings).toHaveLength(1); - }); - session.destroy(); - subscriber.destroy(); - }); - - it('accepts a replacement solicitation after the response half of the carrier dies', async () => { - const endings: unknown[] = []; - const { pair, session, subscriber } = makePublishHarness({ - onAnnounceEnded: ({ error }) => endings.push(error), - }); - - await session.ready; - - const dead = await solicitNamespace(pair.server, [], 1); - - await vi.waitFor(() => { - expect(dead.received.map((m) => m.kind)).toEqual(['request-ok']); - }); - await dead.abandonReads(); - session.announce(NAMESPACE); - session.registerTrack({ trackNamespace: NAMESPACE, trackName: 'catalog' }); - await vi.waitFor(() => { - expect(endings).toHaveLength(1); - }); - - // The write failure deregistered the dead carrier along with the - // loss report, so the relay's retry is a fresh start — not a - // PREFIX_OVERLAP refusal against a corpse. - const retry = await solicitNamespace(pair.server, [], 3); - - await vi.waitFor(() => { - expect(retry.received.map((m) => m.kind)).toEqual(['request-ok', 'namespace']); - }); - session.destroy(); - subscriber.destroy(); - }); - - it('rejects a namespace REQUEST_UPDATE and closes the carrier, never the session', async () => { - const updates: number[] = []; - const closes: unknown[] = []; - const endings: unknown[] = []; - const { pair, session, subscriber } = makePublishHarness({ - onRequestUpdate: ({ requestId }) => updates.push(requestId), - onClosed: (info) => closes.push(info), - onAnnounceEnded: ({ error }) => endings.push(error), - }); - - await session.ready; - session.announce(NAMESPACE); - session.registerTrack({ trackNamespace: NAMESPACE, trackName: 'catalog' }); - - const solicitation = await solicitNamespace(pair.server, []); - - await vi.waitFor(() => { - expect(solicitation.received).toHaveLength(2); - }); - - // A legal §10.9 update (on a fresh Request ID) must never be - // session-fatal; v1 applies no prefix changes, so per §10.9.1 the - // update is answered with an error and the request stream closes — - // which costs the announce carrier, surfaced as announce loss. - await solicitation.send(encodeRequestUpdate(3, { subscriberPriority: 5 })); - await vi.waitFor(() => { - expect(updates).toEqual([1]); - expect(solicitation.received.map((m) => m.kind)).toEqual(['request-ok', 'namespace', 'request-error']); - expect(solicitation.ended()).toBe(true); - expect(endings).toHaveLength(1); - }); - expect(closes).toEqual([]); - session.destroy(); - subscriber.destroy(); - }); - - it('closes the session when the peer reuses a request id', async () => { - const closes: unknown[] = []; - const { pair, session, subscriber } = makePublishHarness({ - onClosed: (info) => closes.push(info), - }); - - await session.ready; - session.registerTrack({ trackNamespace: NAMESPACE, trackName: 'video' }); - session.registerTrack({ trackNamespace: NAMESPACE, trackName: 'audio' }); - - const first = await rawSubscribe(pair.server, 'video', 101); - - await vi.waitFor(() => { - expect(first.received).toHaveLength(1); - }); - - // Aliases ARE the peer's request ids: a reused id would hand two - // tracks the same alias and make their subgroup streams - // indistinguishable — protocol violation, session-fatal. - await rawSubscribe(pair.server, 'audio', 101); - await vi.waitFor(() => { - expect(closes).toHaveLength(1); - }); - expect((closes[0] as { error?: unknown }).error).toBeInstanceOf(Error); - subscriber.destroy(); - }); - - it('closes the session when a REQUEST_UPDATE reuses a request id', async () => { - const closes: unknown[] = []; - const { pair, session, subscriber } = makePublishHarness({ - onClosed: (info) => closes.push(info), - }); - - await session.ready; - session.registerTrack({ trackNamespace: NAMESPACE, trackName: 'video' }); - - const sub = await rawSubscribe(pair.server, 'video', 111); - - await vi.waitFor(() => { - expect(sub.received.map((m) => m.kind)).toEqual(['subscribe-ok']); - }); - - // REQUEST_UPDATE consumes a Request ID of its own (§10.1); riding on - // the subscription's id is the same duplicate as a repeated SUBSCRIBE. - await sub.send(encodeRequestUpdate(111, { subscriberPriority: 9 })); - await vi.waitFor(() => { - expect(closes).toHaveLength(1); - }); - expect((closes[0] as { error?: unknown }).error).toBeInstanceOf(Error); - subscriber.destroy(); - }); - - it('reserves request ids across every inbound request kind', async () => { - const closes: unknown[] = []; - const { pair, session, subscriber } = makePublishHarness({ - onClosed: (info) => closes.push(info), - }); - - await session.ready; - session.registerTrack({ trackNamespace: NAMESPACE, trackName: 'video' }); - - // A rejected PUBLISH burns its id session-wide… - const publish = await openRawRequest( - pair.server, - encodePublish({ requestId: 121, trackNamespace: NAMESPACE, trackName: 'video', trackAlias: 9 }) - ); - - await vi.waitFor(() => { - expect(publish.received.map((m) => m.kind)).toEqual(['request-error']); - }); - expect(closes).toEqual([]); - - // …so a later SUBSCRIBE cannot reuse it as an alias. - await rawSubscribe(pair.server, 'video', 121); - await vi.waitFor(() => { - expect(closes).toHaveLength(1); - }); - subscriber.destroy(); - }); - - it('reports the track Largest Object in SUBSCRIBE_OK once content exists', async () => { - const { pair, session, subscriber } = makePublishHarness(); - - await session.ready; - let largest: { group: number; object: number } | undefined; - - session.registerTrack({ trackNamespace: NAMESPACE, trackName: 'video', getLargestObject: () => largest }); - - // No content yet — SUBSCRIBE_OK omits LARGEST_OBJECT (§10.2.17). - const early = await rawSubscribe(pair.server, 'video', 201); - - await vi.waitFor(() => { - expect(early.received.map((m) => m.kind)).toEqual(['subscribe-ok']); - }); - const earlyOk = early.received[0]; - - expect(earlyOk?.kind).toBe('subscribe-ok'); - - if (earlyOk?.kind === 'subscribe-ok') expect(earlyOk.parameters.largestObject).toBeUndefined(); - - // Once objects have been written, the next SUBSCRIBE_OK carries it - // (two bare varints, as moq-relay 0.14.17 decodes it). - largest = { group: 35, object: 28 }; - const later = await rawSubscribe(pair.server, 'video', 203); - - await vi.waitFor(() => { - expect(later.received.map((m) => m.kind)).toEqual(['subscribe-ok']); - }); - const laterOk = later.received[0]; - - expect(laterOk?.kind).toBe('subscribe-ok'); - - if (laterOk?.kind === 'subscribe-ok') expect(laterOk.parameters.largestObject).toEqual({ group: 35, object: 28 }); - - session.destroy(); - subscriber.destroy(); - }); - - it('opens and resets a fill fetch stream for an inbound FILL_PARAMETERS', async () => { - const { pair, session, fills, finish } = await makeFillHarness(); - - session.registerTrack({ - trackNamespace: NAMESPACE, - trackName: 'video', - getLargestObject: () => ({ group: 4, object: 2 }), - }); - - await openRawRequest( - pair.server, - encodeSubscribe({ - requestId: 205, - trackNamespace: NAMESPACE, - trackName: 'video', - parameters: { - forward: 1, - locationFilter: { type: 'next-object' }, - fillParameters: { locationFilter: { type: 'relative-group', groupsBeforeNext: 1 } }, - }, - }) - ); - - await vi.waitFor(() => { - expect(fills).toEqual([{ requestId: 205, reset: true }]); - }); - await finish(); - }); - - it('counts fill fetch streams in the PUBLISH_DONE Stream Count (§10.12)', async () => { - const { pair, session, fills, finish } = await makeFillHarness(); - const track = session.registerTrack({ - trackNamespace: NAMESPACE, - trackName: 'video', - getLargestObject: () => ({ group: 4, object: 2 }), - getStreamCount: () => 3, - }); - const request = await openRawRequest( - pair.server, - encodeSubscribe({ - requestId: 207, - trackNamespace: NAMESPACE, - trackName: 'video', - parameters: { - forward: 1, - locationFilter: { type: 'next-object' }, - fillParameters: { locationFilter: { type: 'relative-group', groupsBeforeNext: 1 } }, - }, - }) - ); - - await vi.waitFor(() => { - expect(fills).toEqual([{ requestId: 207, reset: true }]); - }); - - track.end(); - await vi.waitFor(() => { - expect(request.ended()).toBe(true); - }); - // Three data streams from the track publisher plus the reset fill. - expect(request.received.at(-1)).toMatchObject({ - kind: 'publish-done', - statusCode: PUBLISH_DONE_STATUS.TRACK_ENDED, - streamCount: 4, - }); - await finish(); - }); - - it('opens no fill fetch stream for an empty fill range (§5.1.3)', async () => { - const { pair, session, fills, finish } = await makeFillHarness(); - let largest: { group: number; object: number } | undefined; - - session.registerTrack({ trackNamespace: NAMESPACE, trackName: 'video', getLargestObject: () => largest }); - const subscribeWithFill = async (requestId: number, fill: Parameters[0]['parameters']) => { - const request = await openRawRequest( - pair.server, - encodeSubscribe({ - requestId, - trackNamespace: NAMESPACE, - trackName: 'video', - parameters: { forward: 1, locationFilter: { type: 'next-object' }, ...fill }, - }) - ); - - await vi.waitFor(() => { - expect(request.received.map((m) => m.kind)).toEqual(['subscribe-ok']); - }); - }; - - // Nothing published yet: there is nothing to fill, whatever the filter. - await subscribeWithFill(207, { - fillParameters: { locationFilter: { type: 'relative-group', groupsBeforeNext: 1 } }, - }); - - // With content, a fill from the Next Object or the Next Group starts - // past Largest Object, and an omitted fill filter inherits the - // subscription's Next Object filter. - largest = { group: 4, object: 2 }; - await subscribeWithFill(209, { fillParameters: { locationFilter: { type: 'next-object' } } }); - await subscribeWithFill(211, { - fillParameters: { locationFilter: { type: 'relative-group', groupsBeforeNext: 0 } }, - }); - await subscribeWithFill(213, { fillParameters: {} }); - - // Control: a fill of the current group is nonempty and is answered — - // and it is the only fill stream the peer ever saw. - await subscribeWithFill(215, { - fillParameters: { locationFilter: { type: 'relative-group', groupsBeforeNext: 1 } }, - }); - await vi.waitFor(() => { - expect(fills).toEqual([{ requestId: 215, reset: true }]); - }); - await finish(); - }); - - it('keys a fill requested by REQUEST_UPDATE to the update Request ID', async () => { - const { pair, session, fills, finish } = await makeFillHarness(); - let largest = { group: 4, object: 2 }; - - session.registerTrack({ - trackNamespace: NAMESPACE, - trackName: 'video', - getLargestObject: () => largest, - }); - const sub = await rawSubscribe(pair.server, 'video', 217); - - await vi.waitFor(() => { - expect(sub.received.map((m) => m.kind)).toEqual(['subscribe-ok']); - }); - - // An empty-range fill is acknowledged like any update but opens no - // stream; a nonempty one opens (and resets) a stream carrying the - // update's own Request ID, not the subscription's. - await sub.send(encodeRequestUpdate(219, { fillParameters: { locationFilter: { type: 'next-object' } } })); - await vi.waitFor(() => { - expect(sub.received.map((m) => m.kind)).toEqual(['subscribe-ok', 'request-ok']); - }); - largest = { group: 8, object: 3 }; - await sub.send( - encodeRequestUpdate(221, { fillParameters: { locationFilter: { type: 'relative-group', groupsBeforeNext: 1 } } }) - ); - await vi.waitFor(() => { - expect(fills).toEqual([{ requestId: 221, reset: true }]); - expect(sub.received.map((m) => m.kind)).toEqual(['subscribe-ok', 'request-ok', 'request-ok']); - }); - expect(sub.received[2]).toMatchObject({ parameters: { largestObject: { group: 8, object: 3 } } }); - await finish(); - }); - - it('preserves the fill header when the peer reads only after the reset', async () => { - const fill = makeBufferedFillStream(); - const { pair, session, finish } = await makeFillHarness({ openFillStream: async () => fill.writable }); - - session.registerTrack({ - trackNamespace: NAMESPACE, - trackName: 'video', - getLargestObject: () => ({ group: 4, object: 2 }), - }); - await openRawRequest( - pair.server, - encodeSubscribe({ - requestId: 223, - trackNamespace: NAMESPACE, - trackName: 'video', - parameters: { fillParameters: {} }, - }) - ); - await vi.waitFor(() => expect(fill.reset()).toBeDefined()); - - const reader = new StreamReader(fill.readable); - - expect(await reader.readVarint()).toBe(STREAM_TYPE.FETCH_HEADER); - expect(await readFetchHeader(reader)).toEqual({ requestId: 223 }); - await expect(reader.atEnd()).rejects.toThrow('fill fetch streams are not served'); - await finish(); - }); - - it.each(['cancel', 'stop-reading', 'replace', 'end', 'destroy'] as const)( - 'aborts backpressured fills when subscriptions %s', - async (action) => { - let writing = false; - const aborted = vi.fn(); - const writable = new WritableStream({ - write(_, controller) { - writing = true; - return new Promise((_, reject) => { - controller.signal.addEventListener('abort', () => reject(controller.signal.reason), { once: true }); - }); - }, - abort: aborted, - }); - const getWriter = writable.getWriter.bind(writable); - - writable.getWriter = () => Object.assign(getWriter(), { commit() {} }); - - const { pair, session, finish } = await makeFillHarness({ openFillStream: async () => writable }); - const track = session.registerTrack({ - trackNamespace: NAMESPACE, - trackName: 'video', - getLargestObject: () => ({ group: 4, object: 2 }), - }); - const sub = await rawSubscribe(pair.server, 'video', 225); - - await vi.waitFor(() => expect(sub.received[0]?.kind).toBe('subscribe-ok')); - await sub.send(encodeRequestUpdate(227, { fillParameters: {} })); - await vi.waitFor(() => expect(writing).toBe(true)); - - if (action === 'cancel') await sub.reset(); - else if (action === 'stop-reading') await sub.abandonReads(); - else if (action === 'replace') await rawSubscribe(pair.server, 'video', 229); - else if (action === 'destroy') session.destroy(); - else track.end(); - - await vi.waitFor(() => expect(aborted).toHaveBeenCalledOnce()); - await finish(); - } - ); - - it('resets a pending fill open that completes after cancellation without writing its header', async () => { - let resolveOpen!: (stream: WritableStream) => void; - const openFillStream = vi.fn( - () => - new Promise>((resolve) => { - resolveOpen = resolve; - }) - ); - const { pair, session, finish } = await makeFillHarness({ openFillStream }); - - session.registerTrack({ - trackNamespace: NAMESPACE, - trackName: 'video', - getLargestObject: () => ({ group: 4, object: 2 }), - }); - const sub = await rawSubscribe(pair.server, 'video', 231); - - await vi.waitFor(() => expect(sub.received[0]?.kind).toBe('subscribe-ok')); - await sub.send(encodeRequestUpdate(233, { fillParameters: {} })); - await vi.waitFor(() => expect(openFillStream).toHaveBeenCalledOnce()); - await sub.reset(); - await vi.waitFor(() => expect(sub.ended()).toBe(true)); - - const write = vi.fn(); - const abort = vi.fn(); - - resolveOpen(new WritableStream({ write, abort })); - await vi.waitFor(() => expect(abort).toHaveBeenCalledOnce()); - expect(write).not.toHaveBeenCalled(); - await finish(); - }); - - it.each([{ reliableReset: true }, { reliableReset: false }])( - 'leaves a fill still opening when the track ends out of the Stream Count, headerless (reliable reset: $reliableReset)', - async ({ reliableReset }) => { - let resolveOpen!: (stream: WritableStream) => void; - const openFillStream = vi.fn( - () => - new Promise>((resolve) => { - resolveOpen = resolve; - }) - ); - const { pair, session, finish } = await makeFillHarness({ reliableReset, openFillStream }); - const track = session.registerTrack({ - trackNamespace: NAMESPACE, - trackName: 'video', - getLargestObject: () => ({ group: 4, object: 2 }), - getStreamCount: () => 3, - }); - const sub = await rawSubscribe(pair.server, 'video', 245); - - await vi.waitFor(() => expect(sub.received[0]?.kind).toBe('subscribe-ok')); - await sub.send(encodeRequestUpdate(247, { fillParameters: {} })); - await vi.waitFor(() => expect(openFillStream).toHaveBeenCalledOnce()); - - // The track ends while the fill's stream is still opening. - track.end(); - await vi.waitFor(() => expect(sub.ended()).toBe(true)); - - const write = vi.fn(); - const abort = vi.fn(); - - resolveOpen(new WritableStream({ write, abort })); - await vi.waitFor(() => expect(abort).toHaveBeenCalledOnce()); - - // A fill is counted in the same step that commits it to its - // FETCH_HEADER, as the track publisher counts subgroup streams. - // This one opened after PUBLISH_DONE, so it gets no header and is - // reset bare: the peer cannot attribute it to the subscription, so - // leaving it out of the count cannot put the peer over it. - expect(write).not.toHaveBeenCalled(); - expect(sub.received.at(-1)).toMatchObject({ - kind: 'publish-done', - statusCode: PUBLISH_DONE_STATUS.TRACK_ENDED, - streamCount: 3, - }); - await finish(); - } - ); - - it.each([{ probeEnds: 'before' }, { probeEnds: 'after' }])( - "serves a relay's second pull of a live track without reliable reset support (probe ends $probeEnds the pull)", - async ({ probeEnds }) => { - const bindings: (number | undefined)[] = []; - const ended: number[] = []; - const { pair, session, fills, finish } = await makeFillHarness({ - reliableReset: false, - callbacks: { - onTrackBinding: ({ trackAlias }) => bindings.push(trackAlias), - onSubscribeEnd: ({ requestId }) => ended.push(requestId), - }, - }); - let largest: { group: number; object: number } | undefined; - - session.registerTrack({ trackNamespace: NAMESPACE, trackName: 'catalog', getLargestObject: () => largest }); - - // Moq-relay's upstream SUBSCRIBE (0.14.17 through 0.17.0): Next Object, - // plus a fill of the current group's head. - const relayPull = (requestId: number) => - openRawRequest( - pair.server, - encodeSubscribe({ - requestId, - trackNamespace: NAMESPACE, - trackName: 'catalog', - parameters: { - forward: 1, - subscriberPriority: 128, - locationFilter: { type: 'next-object' }, - fillParameters: { locationFilter: { type: 'relative-group', groupsBeforeNext: 1 } }, - groupOrder: 'descending', - includeProperties: 1, - }, - }) - ); - - // A cross-relay viewer's first pull is the relay's TRACK_INFO probe: - // nothing published yet, so there is nothing to fill. - const probe = await relayPull(235); - - await vi.waitFor(() => expect(probe.received.map((m) => m.kind)).toEqual(['subscribe-ok'])); - - // The probe's bind put the catalog on the wire, then the relay - // cancelled it and pulled again for the viewer — now with a nonempty - // fill this transport cannot fail reliably. The pull is served anyway. - largest = { group: 0, object: 0 }; - - if (probeEnds === 'before') await probe.reset(); - - const pull = await relayPull(237); - - await vi.waitFor(() => { - expect(pull.received.map((m) => m.kind)).toEqual(['subscribe-ok']); - expect(bindings.at(-1)).toBe(237); - expect(fills).toEqual([{ requestId: 237, reset: true }]); - }); - - // The probe's end may be handled after the pull is bound: it reports - // the newest live binding, not an unbind, so the pull keeps it. - if (probeEnds === 'after') await probe.reset(); - - await vi.waitFor(() => expect(ended).toContain(235)); - expect(bindings.at(-1)).toBe(237); - expect(pull.ended()).toBe(false); - - // A fill requested by REQUEST_UPDATE is acknowledged and failed the same way. - await pull.send( - encodeRequestUpdate(239, { - fillParameters: { locationFilter: { type: 'relative-group', groupsBeforeNext: 1 } }, - }) - ); - await vi.waitFor(() => { - expect(pull.received.map((m) => m.kind)).toEqual(['subscribe-ok', 'request-ok']); - expect(fills).toEqual([ - { requestId: 237, reset: true }, - { requestId: 239, reset: true }, - ]); - }); - expect(pull.ended()).toBe(false); - await finish(); - } +function collectTrack( + subscriber: MoqtSession, + trackName: string +): { objects: MoqtObject[]; subscription: ReturnType } { + const objects: MoqtObject[] = []; + const subscription = subscriber.subscribe( + { trackNamespace: NAMESPACE, trackName }, + { onObject: (object) => objects.push(object) } ); - it('still resets the fill when the reset may discard its header (no reliable reset)', async () => { - const fill = makeBufferedFillStream({ reliableReset: false }); - const { pair, session, finish } = await makeFillHarness({ - reliableReset: false, - openFillStream: async () => fill.writable, - }); - - session.registerTrack({ - trackNamespace: NAMESPACE, - trackName: 'video', - getLargestObject: () => ({ group: 4, object: 2 }), - }); - const sub = await openRawRequest( - pair.server, - encodeSubscribe({ - requestId: 241, - trackNamespace: NAMESPACE, - trackName: 'video', - parameters: { fillParameters: {} }, - }) - ); - - await vi.waitFor(() => { - expect(sub.received.map((m) => m.kind)).toEqual(['subscribe-ok']); - expect(fill.reset()).toBeDefined(); - }); - - // Nothing preserved the header through the reset: the peer sees only - // the reset, and the subscription is unaffected. - const reader = new StreamReader(fill.readable); + return { objects, subscription }; +} - await expect(reader.readVarint()).rejects.toThrow('fill fetch streams are not served'); - expect(sub.ended()).toBe(false); - await finish(); +describe('createPublishSessionActor', () => { + afterEach(() => { + vi.unstubAllGlobals(); }); - it.each([{ headerSurvives: true }, { headerSurvives: false }])( - 'counts a fill reset without reliable reset in the PUBLISH_DONE Stream Count (header survives: $headerSurvives)', - async ({ headerSurvives }) => { - const buffered = makeBufferedFillStream({ reliableReset: false }); - const { pair, session, fills, finish } = await makeFillHarness({ - reliableReset: false, - openFillStream: headerSurvives ? undefined : async () => buffered.writable, - }); - const track = session.registerTrack({ - trackNamespace: NAMESPACE, - trackName: 'video', - getLargestObject: () => ({ group: 4, object: 2 }), - getStreamCount: () => 3, - }); - const sub = await openRawRequest( - pair.server, - encodeSubscribe({ - requestId: 243, - trackNamespace: NAMESPACE, - trackName: 'video', - parameters: { fillParameters: {} }, - }) - ); - - await vi.waitFor(() => { - expect(sub.received.map((m) => m.kind)).toEqual(['subscribe-ok']); + it('offers moqt-22 first with a moqt-20 fallback on the default WebTransport connect', async () => { + const constructed: { url: string; protocols: string[] }[] = []; - if (headerSurvives) expect(fills).toEqual([{ requestId: 243, reset: true }]); - else expect(buffered.reset()).toBeDefined(); - }); + class FakeWebTransport { + readonly ready = Promise.reject(new Error('no relay in tests')); + readonly closed = new Promise(() => {}); - if (!headerSurvives) { - // The peer saw only the reset, so it cannot tell the stream - // belonged to this subscription. - await expect(new StreamReader(buffered.readable).readVarint()).rejects.toThrow( - 'fill fetch streams are not served' - ); + constructor(url: string, options: { protocols: string[] }) { + constructed.push({ url, protocols: options.protocols }); + this.ready.catch(() => {}); } - track.end(); - await vi.waitFor(() => { - expect(sub.ended()).toBe(true); - }); - // §10.12 counts the streams the publisher opened, fill fetch - // streams included: three from the track publisher plus the fill, - // whether or not its header outlived the reset. A subscriber waits - // out a timeout for a stream reset before its header, but one that - // receives more streams than the count may close the session. - expect(sub.received.at(-1)).toMatchObject({ - kind: 'publish-done', - statusCode: PUBLISH_DONE_STATUS.TRACK_ENDED, - streamCount: 4, - }); - await finish(); - } - ); - - it('rejects a subscription update it cannot apply instead of acknowledging it', async () => { - const endedRequests: number[] = []; - const bindings: (number | undefined)[] = []; - const { pair, session, subscriber } = makePublishHarness({ - onSubscribeEnd: ({ requestId }) => endedRequests.push(requestId), - onTrackBinding: ({ trackAlias }) => bindings.push(trackAlias), - }); - - await session.ready; - session.registerTrack({ trackNamespace: NAMESPACE, trackName: 'video' }); - - const sub = await rawSubscribe(pair.server, 'video', 111); - - await vi.waitFor(() => { - expect(bindings.at(-1)).toBe(111); - }); - - // A filter change is not applied — acknowledging it would leave the - // peer believing its new range is in effect. - await sub.send(encodeRequestUpdate(113, { locationFilter: { type: 'relative-group', groupsBeforeNext: 0 } })); - await vi.waitFor(() => { - expect(sub.received.map((m) => m.kind)).toEqual(['subscribe-ok', 'request-error']); - expect(sub.ended()).toBe(true); - expect(endedRequests).toEqual([111]); - expect(bindings.at(-1)).toBeUndefined(); - }); - session.destroy(); - subscriber.destroy(); - }); - - it('treats announce-carrier loss after a GOAWAY as migration, not failure', async () => { - const goaways: number[] = []; - const endings: unknown[] = []; - const { pair, session, subscriber } = makePublishHarness({ - onGoaway: (goaway) => goaways.push(goaway.timeout), - onAnnounceEnded: ({ error }) => endings.push(error), - }); - - await session.ready; - session.announce(NAMESPACE); - session.registerTrack({ trackNamespace: NAMESPACE, trackName: 'catalog' }); - - const solicitation = await solicitNamespace(pair.server, []); - - await vi.waitFor(() => { - expect(solicitation.received).toHaveLength(2); - }); - - // The peer migrates: GOAWAY, then its streams drain. The announce - // ending here is the orderly drain — surfacing it as a failure would - // override the actor's 'draining' with 'failed'. - await solicitation.send(encodeGoaway(1500)); - await vi.waitFor(() => { - expect(goaways).toEqual([1500]); - }); - void solicitation.reset(); - await new Promise((resolve) => setTimeout(resolve, 30)); - expect(endings).toEqual([]); - session.destroy(); - subscriber.destroy(); - }); - - it('clears the binding when the only subscription ends', async () => { - const bindings: (number | undefined)[] = []; - const { pair, session, subscriber } = makePublishHarness({ - onTrackBinding: ({ trackAlias }) => bindings.push(trackAlias), - }); - - await session.ready; - session.registerTrack({ trackNamespace: NAMESPACE, trackName: 'video' }); - - const subscribe = await rawSubscribe(pair.server, 'video', 41); - - await vi.waitFor(() => { - expect(bindings).toEqual([41]); - }); - - void subscribe.fin(); - await vi.waitFor(() => { - expect(bindings).toEqual([41, undefined]); - // The response direction closes too — a peer-initiated unsubscribe - // must not leak a half-open stream. - expect(subscribe.ended()).toBe(true); - }); - session.destroy(); - subscriber.destroy(); - }); - - it('close() drains the FINs and NAMESPACE_DONE to the wire without a GOAWAY', async () => { - const pair = createTransportPair(); - // A fully raw peer: complete SETUP and record every frame on the - // publisher's control stream — it must carry SETUP and nothing else - // (a client GOAWAY closes a moq-lite-rs session, code 17). - const controlFrames: ControlMessage[] = []; - - void (async () => { - const control = await pair.server.createUnidirectionalStream(); - const writer = control.getWriter(); - - await writer.write(encodeSetup([])); - const reader = pair.server.incomingUnidirectionalStreams.getReader(); - const { value: publisherControl } = await reader.read(); - const deframer = new ControlMessageDeframer(); - const streamReader = publisherControl!.getReader(); - - while (true) { - const { done, value } = await streamReader.read().catch(() => ({ done: true, value: undefined }) as const); - if (done) break; - - for (const frame of deframer.push(value!)) controlFrames.push(decodeControlMessage(frame)); + // On the prototype, where the connect looks for negotiation support. + get protocol(): string { + return 'moqt-22'; } - })(); - const session = createMoqtPublishSession(pair.client); - await session.ready; - session.announce(NAMESPACE); - session.registerTrack({ trackNamespace: NAMESPACE, trackName: 'catalog' }); - session.registerTrack({ trackNamespace: NAMESPACE, trackName: 'video' }); + close(): void {} + } - const solicitation = await solicitNamespace(pair.server, []); - const subscribe = await rawSubscribe(pair.server, 'video', 51); + vi.stubGlobal('WebTransport', FakeWebTransport); - await vi.waitFor(() => { - expect(solicitation.received).toHaveLength(2); - expect(subscribe.received).toHaveLength(1); + const actor = createPublishSessionActor({ + endpoint: { url: 'https://relay.example.com/', namespace: NAMESPACE, authToken: 'tok' }, }); - session.close(); await vi.waitFor(() => { - // The announce is retracted and the track ended cleanly before the - // transport goes away. - expect(solicitation.received.map((m) => m.kind)).toEqual(['request-ok', 'namespace', 'namespace-done']); - expect(subscribe.ended()).toBe(true); + expect(actor.snapshot.get().context.status).toBe('failed'); }); - expect(subscribe.received.map((m) => m.kind)).toEqual(['subscribe-ok', 'publish-done']); - expect(controlFrames.map((m) => m.kind)).toEqual(['setup']); - }); - - it('close() leaves no timer running', async () => { - vi.useFakeTimers(); - - try { - const pair = createTransportPair(); - - void (async () => { - const control = await pair.server.createUnidirectionalStream(); - const writer = control.getWriter(); - - await writer.write(encodeSetup([])); - })(); - const session = createMoqtPublishSession(pair.client); - - await session.ready; - session.close(); - // Room for the close drain's own (self-clearing) timers. - await vi.advanceTimersByTimeAsync(1_000); - expect(vi.getTimerCount()).toBe(0); - } finally { - vi.useRealTimers(); - } - }); - - it('registerTrack() after destroy is inert — no track state, end() safe', async () => { - const { session, subscriber } = makePublishHarness(); - - await session.ready; - session.destroy(); - - const handle = session.registerTrack({ trackNamespace: NAMESPACE, trackName: 'late' }); - - expect(handle.trackName).toBe('late'); - expect(() => handle.end()).not.toThrow(); - subscriber.destroy(); + expect(constructed).toEqual([{ url: 'https://relay.example.com/?jwt=tok', protocols: ['moqt-22', 'moqt-20'] }]); + actor.destroy(); }); - it('surfaces a control-stream GOAWAY', async () => { + it('delivers a parseable catalog and LOC frames end to end over solicited subscriptions', async () => { const pair = createTransportPair(); - - void (async () => { - const control = await pair.server.createUnidirectionalStream(); - const writer = control.getWriter(); - - await writer.write(encodeSetup([])); - await writer.write(encodeGoaway(1500)); - })(); - const goaways: number[] = []; - const session = createMoqtPublishSession(pair.client, { - callbacks: { onGoaway: (goaway) => goaways.push(goaway.timeout) }, + const subscriber = createMoqtSession(withServerRequestIds(pair.server), { unknownAliasTimeoutMs: 500 }); + const actor = createPublishSessionActor({ + endpoint: { url: 'https://relay.example.com/moq', namespace: NAMESPACE }, + connectTransport: () => ({ transport: pair.client, ready: Promise.resolve() }), }); - await session.ready; await vi.waitFor(() => { - expect(goaways).toEqual([1500]); - }); - session.destroy(); - }); - - // --------------------------------------------------------------------------- - // The end-to-end proof: publish session ↔ existing subscribe driver. - // --------------------------------------------------------------------------- - - it('delivers a parseable catalog and LOC frames end to end over solicited subscriptions', async () => { - const bindings = new Map(); - const { pair, session, subscriber } = makePublishHarness({ - onTrackBinding: ({ trackName, trackAlias }) => bindings.set(trackName, trackAlias), + expect(actor.snapshot.get().context.status).toBe('ready'); }); - - await session.ready; await subscriber.ready; - session.announce(NAMESPACE); - session.registerTrack({ trackNamespace: NAMESPACE, trackName: 'catalog' }); - const solicitation = await solicitNamespace(pair.server, []); + const session = actor.snapshot.get().context.session!; + session.registerTrack({ trackNamespace: NAMESPACE, trackName: 'catalog' }); + session.registerTrack({ trackNamespace: NAMESPACE, trackName: 'video' }); + void solicitNamespace(pair.server, []); await vi.waitFor(() => { - expect(solicitation.received.map((m) => m.kind)).toEqual(['request-ok', 'namespace']); + expect(actor.snapshot.get().context.status).toBe('live'); }); - session.registerTrack({ trackNamespace: NAMESPACE, trackName: 'video' }); - // Publishers start unbound — nothing may hit the wire until the peer // subscribes and the binding lands (the behavior layer's job; the // test wires it directly). const catalogPublisher = createTrackPublisherActor({ - openUniStream: () => session.openUniStream(), + openUniStream: (trackAlias) => session.openUniStream(trackAlias), groupPerFrame: true, replayLastGroupOnBind: true, }); const videoPublisher = createTrackPublisherActor({ - openUniStream: () => session.openUniStream(), + openUniStream: (trackAlias) => session.openUniStream(trackAlias), }); // The catalog frame goes out BEFORE any subscription exists — the @@ -1800,13 +128,14 @@ describe('createMoqtPublishSession', () => { const catalog = collectTrack(subscriber, 'catalog'); const video = collectTrack(subscriber, 'video'); + const bindings = () => actor.snapshot.get().context.trackBindings; await vi.waitFor(() => { - expect(bindings.get('catalog')).toBeDefined(); - expect(bindings.get('video')).toBeDefined(); + expect(bindings().catalog).toBeDefined(); + expect(bindings().video).toBeDefined(); }); - catalogPublisher.send({ type: 'bind', trackAlias: bindings.get('catalog')! }); - videoPublisher.send({ type: 'bind', trackAlias: bindings.get('video')! }); + catalogPublisher.send({ type: 'bind', trackAlias: bindings().catalog! }); + videoPublisher.send({ type: 'bind', trackAlias: bindings().video! }); // Two groups of LOC video frames (keyframe → new group). const frames = [ @@ -1865,15 +194,13 @@ describe('createMoqtPublishSession', () => { videoPublisher.destroy(); catalogPublisher.destroy(); - session.destroy(); + actor.destroy(); subscriber.destroy(); }); -}); -describe('createPublishSessionActor', () => { it('walks connecting → ready → live on the announce and tracks subscribers and bindings', async () => { const pair = createTransportPair(); - const subscriber = createMoqtSession(pair.server, {}); + const subscriber = createMoqtSession(withServerRequestIds(pair.server), {}); const statuses: PublishSessionActorStatus[] = []; const actor = createPublishSessionActor({ endpoint: { url: 'https://relay.example.com/moq', namespace: NAMESPACE }, @@ -1908,7 +235,9 @@ describe('createPublishSessionActor', () => { await vi.waitFor(() => { expect(actor.snapshot.get().context.subscriberCount).toBe(1); - expect(actor.snapshot.get().context.trackBindings).toEqual({ video: subscription.requestId }); + expect(actor.snapshot.get().context.trackBindings).toEqual({ + video: subscription.requestId + SERVER_REQUEST_ID_OFFSET, + }); }); actor.destroy(); diff --git a/packages/spf/src/publish/tests/helpers/relay-hub.ts b/packages/spf/src/publish/tests/helpers/relay-hub.ts index 644228ff54..37efb5c43f 100644 --- a/packages/spf/src/publish/tests/helpers/relay-hub.ts +++ b/packages/spf/src/publish/tests/helpers/relay-hub.ts @@ -1,8 +1,7 @@ /** * In-memory MoQ relay hub for cross-engine tests: real publish engine on one side, real playback engine(s) on the - * other, over `createTransportPair` transports. Each side speaks its engine's draft: the publisher's own draft-20 codec - * upstream, and `@caprid/moq-core`'s moqt-22 codec (through `moqt-wire`) toward the player, the way the real relay - * terminates each session in the version it negotiated. + * other, over `createTransportPair` transports. Both engines speak `@caprid/moq-core`'s moqt-22, and so does the hub, + * through the package's own relay-side codec (`moqt-wire`). * * Publisher side (`connectPublisher`) mirrors moq-relay 0.14.17's announce-and-serve ingest. After the SETUP exchange * the hub opens a bidi stream and solicits announces (SUBSCRIBE_NAMESPACE, empty prefix, odd server-side request ids) @@ -26,41 +25,35 @@ * Tracks and demand persist across publisher sessions (a reconnecting publisher is re-solicited and its demanded tracks * re-subscribed), so the hub can also observe teardown/reconnect churn instead of crashing on it. */ -import { createSubgroupWriter as createPlayerSubgroupWriter } from '@caprid/moq-core'; - -import { StreamReader } from '../../../network/moqt/bytes'; import { - type ControlMessage, - decodeControlMessage, - encodeRequestError, - encodeSetup, - encodeSubscribe, - encodeSubscribeNamespace, + type BidirectionalStreamLike, + createSubgroupWriter, type KeyValuePair, type Location, type LocationFilter, + type MoqtTransport, PUBLISH_DONE_STATUS, REQUEST_ERROR_CODE, type TrackNamespace, -} from '../../../network/moqt/control-messages'; +} from '@caprid/moq-core'; + import { + type ControlMessage, + decodeControlMessage, + encodePublishDone, + encodeRequestError, + encodeSetup, + encodeSubscribe, + encodeSubscribeNamespace, + encodeSubscribeOk, isSubgroupHeaderType, readFetchHeader, readSubgroupHeader, readSubgroupObjects, STREAM_TYPE, -} from '../../../network/moqt/object-stream'; -import type { BidirectionalStreamLike } from '../../../network/moqt/request-stream'; -import type { MoqtTransport } from '../../../network/moqt/session'; -import { createTransportPair } from '../../../network/moqt/tests/helpers/transport-pair'; -import { - decodeControlMessage as decodePlayerControlMessage, - encodePublishDone as encodePlayerPublishDone, - encodeRequestError as encodePlayerRequestError, - encodeSetup as encodePlayerSetup, - encodeSubscribeOk as encodePlayerSubscribeOk, - StreamReader as PlayerStreamReader, + StreamReader, } from '../../../network/tests/helpers/moqt-wire'; +import { createTransportPair } from '../../../network/tests/helpers/transport-pair'; import type { ConnectPublishTransport } from '../../session/publish-session'; // ============================================================================= @@ -163,7 +156,7 @@ function isAtOrAfter(a: Location, b: Location): boolean { /** * Where a new subscription starts, resolved against the track's Largest Object the way moq-relay 0.14.17 resolves a - * draft-20 Location Filter (§5.1.2): `next-object` is strict (nothing already published is replayed), `relative-group` + * Location Filter (moqt-22 §3.3.1): `next-object` is strict (nothing already published is replayed), `relative-group` * counts back from the next group (`0` = the next group, `1` = the current group from object 0), an absolute start is * honored as given (the hub never sees an end), and an unfiltered request starts at the current group like moq-lite. */ @@ -584,7 +577,7 @@ export function createRelayHub( void (async () => { try { const stream = await server.createUnidirectionalStream(); - const writer = createPlayerSubgroupWriter(stream, { + const writer = createSubgroupWriter(stream, { trackAlias, groupId: object.groupId, hasProperties: true, @@ -605,7 +598,7 @@ export function createRelayHub( const serveRequestStream = async (stream: BidirectionalStreamLike): Promise => { const writer = stream.writable.getWriter(); - const reader = new PlayerStreamReader(stream.readable); + const reader = new StreamReader(stream.readable); let subscription: Subscription | undefined; let subscribedTrack: TrackRecord | undefined; @@ -614,7 +607,7 @@ export function createRelayHub( const type = await reader.readVarint(); const high = await reader.readUint8(); const low = await reader.readUint8(); - const message = decodePlayerControlMessage({ type, body: await reader.readBytes(high * 256 + low) }); + const message = decodeControlMessage({ type, body: await reader.readBytes(high * 256 + low) }); if (message.kind === 'subscribe') { // Downstream demand is what makes the hub pull the track from @@ -625,9 +618,7 @@ export function createRelayHub( // Like the relay, SUBSCRIBE_OK reports the Largest Object once // the track has content. - await writer.write( - encodePlayerSubscribeOk(trackAlias, track.largest ? { largestObject: track.largest } : {}) - ); + await writer.write(encodeSubscribeOk(trackAlias, track.largest ? { largestObject: track.largest } : {})); subscription = { trackAlias, start: resolveStart(message.parameters.locationFilter, track.largest), @@ -648,7 +639,7 @@ export function createRelayHub( }, end: (statusCode) => { void writer - .write(encodePlayerPublishDone(statusCode, 0, '')) + .write(encodePublishDone(statusCode, 0, '')) .then(() => writer.close()) .catch(() => {}); }, @@ -667,7 +658,7 @@ export function createRelayHub( } else if (message.kind === 'fetch') { // The player never fetches (its joins are Location // Filters); anything asking for history is refused. - await writer.write(encodePlayerRequestError(REQUEST_ERROR_CODE.INVALID_RANGE, 'no history')); + await writer.write(encodeRequestError(REQUEST_ERROR_CODE.INVALID_RANGE, 'no history')); await writer.close(); return; } @@ -719,7 +710,7 @@ export function createRelayHub( try { const control = await server.createUnidirectionalStream(); - await control.getWriter().write(encodePlayerSetup()); + await control.getWriter().write(encodeSetup()); } catch { // Closed before SETUP could land. } diff --git a/packages/spf/src/publish/tests/relay-hub.test.ts b/packages/spf/src/publish/tests/relay-hub.test.ts index e0033621a3..abd77cb118 100644 --- a/packages/spf/src/publish/tests/relay-hub.test.ts +++ b/packages/spf/src/publish/tests/relay-hub.test.ts @@ -1,8 +1,6 @@ +import { createMoqtPublishSession, createSubgroupWriter, PUBLISH_DONE_STATUS } from '@caprid/moq-core'; import { describe, expect, it, vi } from 'vite-plus/test'; -import { PUBLISH_DONE_STATUS } from '../../network/moqt/control-messages'; -import { createSubgroupWriter } from '../../network/moqt/subgroup-writer'; -import { createMoqtPublishSession } from '../session/publish-session'; import { createRelayHub } from './helpers/relay-hub'; /** @@ -48,7 +46,7 @@ describe('createRelayHub', () => { }); const trackAlias = onTrackBinding.mock.calls[0]![0].trackAlias; - const stream = createSubgroupWriter(await session.openUniStream(), { + const stream = createSubgroupWriter(await session.openUniStream(trackAlias), { trackAlias, groupId: 256, endOfGroup: true, @@ -87,12 +85,12 @@ describe('createRelayHub', () => { }); // The publisher ends the track: PUBLISH_DONE + FIN on the hub's - // SUBSCRIBE stream, recorded as the churn signal. No stream-count - // source was registered, so the count is unknown. + // SUBSCRIBE stream, recorded as the churn signal. No data stream was + // opened for the subscription, and the session counts its own. first.end(); await vi.waitFor(() => { expect(hub.trackEnds).toEqual([ - { kind: 'track-end', trackName: 'video', statusCode: PUBLISH_DONE_STATUS.TRACK_ENDED, streamCount: undefined }, + { kind: 'track-end', trackName: 'video', statusCode: PUBLISH_DONE_STATUS.TRACK_ENDED, streamCount: 0 }, ]); }); From 259385a0f09adf0374ee944f8c6ae0309398ad8e Mon Sep 17 00:00:00 2001 From: Matt McClure Date: Wed, 28 Oct 2026 05:02:16 +0000 Subject: [PATCH 2/3] docs(spf): repoint publisher prose at @caprid/moq-core and draft-22 The spec README, the publish design notes and the migration plan named the deleted network/moqt modules or said the publisher still ran its own codec. The publisher sandbox's loopback relay cited draft-20 sections; its one Location Filter (relative start, StartGroup 1) encodes the same bytes on draft-22, so it now says so and uses draft-22 numbering, as the player's loopback already does. Claude-Session: https://claude.ai/code/session_01DaH4ifX9Vb6HuB2yg6TMt5 --- .agents/plans/moq-transport-20-migration.md | 5 +- .../templates/moq-publisher/loopback-relay.ts | 84 ++++++++++--------- internal/design/spf/features/clusters.md | 2 +- internal/design/spf/features/moq-publish.md | 40 +++------ internal/specs/moq/README.md | 4 +- 5 files changed, 62 insertions(+), 73 deletions(-) diff --git a/.agents/plans/moq-transport-20-migration.md b/.agents/plans/moq-transport-20-migration.md index 976496d08d..ab61775734 100644 --- a/.agents/plans/moq-transport-20-migration.md +++ b/.agents/plans/moq-transport-20-migration.md @@ -22,8 +22,9 @@ Temporary implementation notes — delete before merge per `AGENTS.md`. from `@caprid/moq-core`, which was extracted from `network/moqt/`. It offers `moqt-22` first and falls back to `moqt-20`. The local modules this plan names, and the vendored draft-20 text, are gone. `internal/specs/moq/` now -carries draft-22. Section numbers below are draft-20's. The publisher still -runs the local codec until its own move. +carries draft-22. Section numbers below are draft-20's. The publisher moved +onto the package's publish session on `feat/moq-publisher-caprid-core` +(2026-10-28), so no local codec remains on either branch. **Issue #45 verification (2026-09-16, moq-relay 0.14.17):** the shared codec uses bare Locations in both directions. Fixed-byte tests pin SUBSCRIBE_OK, diff --git a/apps/sandbox/templates/moq-publisher/loopback-relay.ts b/apps/sandbox/templates/moq-publisher/loopback-relay.ts index c8ef534155..aafc075b4b 100644 --- a/apps/sandbox/templates/moq-publisher/loopback-relay.ts +++ b/apps/sandbox/templates/moq-publisher/loopback-relay.ts @@ -17,19 +17,19 @@ * group, so joining is instant) and live-forwarding from there. Multiple sequential player sessions re-serve the latest * catalog. * - * The wire encoding is written from the specs rather than reusing `network/moqt`'s codecs (they are not public API); - * the byte-level shapes mirror `spf-moq-player/loopback-relay.ts`, extended with the publisher-facing decoders - * (draft-ietf-moq-transport-20 §10, §11.4.2). If this grows further, the pieces worth exporting properly from + * The wire encoding is written from the specs rather than reusing `@caprid/moq-core`'s codecs (it exports no relay + * side); the byte-level shapes mirror `spf-moq-player/loopback-relay.ts`, extended with the publisher-facing decoders + * (draft-ietf-moq-transport-22 §9, §11.3.1). If this grows further, the pieces worth exporting properly from * `@videojs/spf` are the control-message codec and a transport-pair helper. */ import type { CreateMoqTransport } from '@videojs/spf/moq'; import type { ConnectPublishTransport } from '@videojs/spf/moq-publish'; // ============================================================================ -// Wire primitives (draft-ietf-moq-transport-20) +// Wire primitives (draft-ietf-moq-transport-22) // ============================================================================ -/** Control/request message types (§10, Table 5). */ +/** Control/request message types (§9). */ const MESSAGE_TYPE = { SETUP: 0x2f00, SUBSCRIBE: 0x3, @@ -44,16 +44,16 @@ const MESSAGE_TYPE = { SUBSCRIBE_NAMESPACE: 0x50, } as const; -/** PUBLISH_DONE status codes (§10.12) this relay sends its players. */ +/** PUBLISH_DONE status codes (§9.9) this relay sends its players. */ const PUBLISH_DONE_INTERNAL_ERROR = 0x0; -/** REQUEST_ERROR code for "nothing published in that range" (§10.6.1). */ +/** REQUEST_ERROR code for "nothing published in that range" (§12.3). */ const ERROR_INVALID_RANGE = 0x11; /** REQUEST_ERROR code moq-relay 0.14.7 answers proactive PUBLISH with. */ const ERROR_PUBLISH_NOT_SUPPORTED = 400; -/** REQUEST_ERROR code for an unregistered track (§15.11.2). */ +/** REQUEST_ERROR code for an unregistered track (§12.3). */ const ERROR_DOES_NOT_EXIST = 0x10; /** @@ -63,7 +63,7 @@ const ERROR_DOES_NOT_EXIST = 0x10; */ const UPSTREAM_RETRY_DELAY_MS = 50; -/** Message parameter types the upstream SUBSCRIBE carries (§10.2). */ +/** Message parameter types the upstream SUBSCRIBE carries (§9.20). */ const SUBSCRIBE_PARAMETER = { FORWARD: 0x10, SUBSCRIBER_PRIORITY: 0x20, @@ -71,27 +71,29 @@ const SUBSCRIBE_PARAMETER = { GROUP_ORDER: 0x22, } as const; +/** Location Filter Type 0x01, Relative Start (§9.20.9): one StartGroup field, counted back from the next group. */ +const LOCATION_FILTER_RELATIVE_START = 0x1; + /** - * A one-field Location Filter (§5.1.2) is relative to the next group: `1` starts at the current group's object 0 — the - * join moq-relay 0.14.14 asks upstream publishers for, so an in-progress group is served whole rather than from the - * live edge. + * StartGroup `1` starts at the current group's object 0 (§3.3.1) — the join moq-relay asks upstream publishers for, so + * an in-progress group is served whole rather than from the live edge. */ -const LOCATION_FILTER_CURRENT_GROUP = 0x1; +const START_GROUP_CURRENT = 0x1; -/** GROUP_ORDER wire value for descending delivery (§10.2). */ +/** GROUP_ORDER wire value for descending delivery (§9.20). */ const GROUP_ORDER_DESCENDING = 0x2; -/** Track Property carrying the track's timestamp units-per-second (§10.8). */ +/** Track Property carrying the track's timestamp units-per-second (§9.7). */ const TRACK_PROPERTY_TIMESCALE = 0x08; /** * SUBGROUP_HEADER stream type used toward the _player_: subgroup-id mode `zero`, default publisher priority, objects - * carry a Properties field — `0b0011_0001` (§11.4.2), the same shape `spf-moq-player`'s loopback publishes and the + * carry a Properties field — `0b0011_0001` (§11.3.1), the same shape `spf-moq-player`'s loopback publishes and the * engine demonstrably consumes. */ const PLAYER_SUBGROUP_HEADER_TYPE = 0x31; -/** SUBGROUP_HEADER type-flag bits (§11.4.2) for parsing the publisher side. */ +/** SUBGROUP_HEADER type-flag bits (§11.3.1) for parsing the publisher side. */ const SUBGROUP_FLAG = { PROPERTIES: 0x01, SUBGROUP_ID_MODE_MASK: 0x06, @@ -108,8 +110,8 @@ function isSubgroupHeaderType(type: number): boolean { } /** - * The vi64 varint of draft-15+ (§1.4.1) — leading ones on the first byte give the encoded length minus one, so an - * L-byte encoding carries 7L value bits. NOT the QUIC RFC 9000 varint. + * The vi64 varint of draft-15+ (§8.1) — leading ones on the first byte give the encoded length minus one, so an L-byte + * encoding carries 7L value bits. NOT the QUIC RFC 9000 varint. */ function varintByteLength(value: number): number { for (let length = 1; length < 8; length++) { @@ -210,7 +212,7 @@ class Reader { /** * Pull-based reader over a byte stream, for the publisher's long-lived subgroup streams (a group's objects trickle in - * until FIN at the next keyframe). Minimal mirror of `network/moqt`'s `StreamReader`. + * until FIN at the next keyframe). Minimal mirror of `@caprid/moq-core`'s `StreamReader`. */ class StreamByteReader { #reader: ReadableStreamDefaultReader; @@ -293,12 +295,12 @@ class StreamByteReader { } } -/** Control message framing (§10.1): type varint + 16-bit length + body. */ +/** Control message framing (§9): type varint + 16-bit length + body. */ function frame(type: number, body: Uint8Array): Uint8Array { return new Writer().varint(type).u16(body.length).bytes(body).toBytes(); } -/** Read one framed control message (§10.1) off a pull-based stream reader. */ +/** Read one framed control message (§9) off a pull-based stream reader. */ async function readControlFrame(reader: StreamByteReader): Promise<{ type: number; body: Uint8Array }> { const type = await reader.readVarint(); const high = await reader.readUint8(); @@ -307,7 +309,7 @@ async function readControlFrame(reader: StreamByteReader): Promise<{ type: numbe return { type, body: await reader.readBytes(high * 256 + low) }; } -/** Namespace tuple (§10.7): varint field count + length-prefixed UTF-8 fields. */ +/** Namespace tuple (§8.7): varint field count + length-prefixed UTF-8 fields. */ function writeNamespaceTuple(writer: Writer, namespace: string[]): Writer { writer.varint(namespace.length); @@ -327,7 +329,7 @@ function readNamespaceTuple(reader: Reader): string[] { function encodeSetup(): Uint8Array { // Options-only, and we send none. A Key-Value-Pair block is bounded by its - // enclosing length rather than counted (§10.2), so "no options" is an empty + // enclosing length rather than counted (§9.20), so "no options" is an empty // body — not a zero count. return frame(MESSAGE_TYPE.SETUP, new Uint8Array(0)); } @@ -344,7 +346,7 @@ function encodePublishDone(statusCode: number, streamCount: number): Uint8Array } /** - * SUBSCRIBE_NAMESPACE toward the publisher (§10.18): the empty prefix solicits every namespace the publisher will + * SUBSCRIBE_NAMESPACE toward the publisher (§9.15): the empty prefix solicits every namespace the publisher will * announce — the same solicitation moq-relay 0.14.7 opens right after SETUP. */ function encodeSubscribeNamespace(requestId: number): Uint8Array { @@ -353,11 +355,11 @@ function encodeSubscribeNamespace(requestId: number): Uint8Array { } /** - * SUBSCRIBE toward the publisher (§10.7) — the exact request moq-relay 0.14.14 sends on draft-20 when pulling a track: - * forward on, subscriber priority 0, join at the current group (`relative-group 1`), descending group order. Message - * parameters are count-prefixed with delta-encoded types and per-type value encodings (§10.2), so the byte after each - * delta is what that type says it is — a raw uint8 for FORWARD / SUBSCRIBER_PRIORITY / GROUP_ORDER, a length-prefixed - * filter for LOCATION_FILTER. + * SUBSCRIBE toward the publisher (§9.6) — the request moq-relay sends when pulling a track: forward on, subscriber + * priority 0, join at the current group (`relative-group 1`), descending group order. Message parameters are + * count-prefixed with delta-encoded types and per-type value encodings (§9.20), so the byte after each delta is what + * that type says it is — a raw uint8 for FORWARD / SUBSCRIBER_PRIORITY / GROUP_ORDER, a Location Filter Type and its + * fields for LOCATION_FILTER. */ function encodeSubscribe(requestId: number, namespace: string[], trackName: string): Uint8Array { const body = new Writer().varint(requestId); @@ -369,8 +371,8 @@ function encodeSubscribe(requestId: number, namespace: string[], trackName: stri body.varint(SUBSCRIBE_PARAMETER.SUBSCRIBER_PRIORITY - SUBSCRIBE_PARAMETER.FORWARD).u8(0); body .varint(SUBSCRIBE_PARAMETER.LOCATION_FILTER - SUBSCRIBE_PARAMETER.SUBSCRIBER_PRIORITY) - .varint(1) - .varint(LOCATION_FILTER_CURRENT_GROUP); + .varint(LOCATION_FILTER_RELATIVE_START) + .varint(START_GROUP_CURRENT); body.varint(SUBSCRIBE_PARAMETER.GROUP_ORDER - SUBSCRIBE_PARAMETER.LOCATION_FILTER).u8(GROUP_ORDER_DESCENDING); return frame(MESSAGE_TYPE.SUBSCRIBE, body.toBytes()); } @@ -400,7 +402,7 @@ function encodeObjectStream( .lengthPrefixed(properties) .varint(payload.length); - // A zero-length payload carries an Object Status varint instead (§11.2.1.1). + // A zero-length payload carries an Object Status varint instead (§11.1.1). return (payload.length === 0 ? writer.varint(0) : writer.bytes(payload)).toBytes(); } @@ -423,7 +425,7 @@ interface PlayerSubscription { trackAlias: number; deliver(object: BufferedObject): void; /** - * End this subscription from the relay side: with a `statusCode`, PUBLISH_DONE (§10.12, counting the streams this + * End this subscription from the relay side: with a `statusCode`, PUBLISH_DONE (§9.9, 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. */ @@ -642,7 +644,7 @@ export function createPublisherLoopbackRelay({ onLog }: PublisherLoopbackRelayOp /** * The relay's control stream toward the publisher. It stays open for the session's lifetime — closing it ends the - * session (§3.3). + * session (§6.3). */ const sendServerSetup = (): void => { if (!sessionOpen || destroyed || !uniController) return; @@ -732,11 +734,11 @@ export function createPublisherLoopbackRelay({ onLog }: PublisherLoopbackRelayOp return; } - // SUBSCRIBE_OK (§10.8): track alias + message parameters + // SUBSCRIBE_OK (§9.7): track alias + message parameters // (count-prefixed) + track-property KVPs to the end of the body. // Both blocks are delta-typed with the same parity encoding — even // type → varint value, odd → length-prefixed bytes — so each skips - // cleanly. The publish engine sends LARGEST_OBJECT (§10.2.17, an + // cleanly. The publish engine sends LARGEST_OBJECT (§9.20.17, an // odd/length-prefixed parameter) in the parameter block once the // track has content; TIMESCALE (LOC's microsecond stamp) is the one // track property it declares. @@ -953,7 +955,7 @@ export function createPublisherLoopbackRelay({ onLog }: PublisherLoopbackRelayOp } }; - /** Parse one subgroup data stream (subgroup-writer's shape, §11.4.2). */ + /** Parse one subgroup data stream (subgroup-writer's shape, §11.3.1). */ const handleSubgroupStream = async (reader: StreamByteReader, type: number): Promise => { const hasProperties = (type & SUBGROUP_FLAG.PROPERTIES) !== 0; const explicitSubgroupId = (type & SUBGROUP_FLAG.SUBGROUP_ID_MODE_MASK) >> 1 === 0b10; @@ -972,7 +974,7 @@ export function createPublisherLoopbackRelay({ onLog }: PublisherLoopbackRelayOp return; } - // First object ID is absolute; the rest are `delta + 1` (§11.4.2). + // First object ID is absolute; the rest are `delta + 1` (§11.3.1). let previousObjectId: number | undefined; while (!(await reader.atEnd())) { @@ -1303,7 +1305,7 @@ export function createPublisherLoopbackRelay({ onLog }: PublisherLoopbackRelayOp if (message.type === MESSAGE_TYPE.SUBSCRIBE) { onSubscribe(message.body); } else if (message.type === MESSAGE_TYPE.FETCH) { - // The engine never fetches — a draft-20 join is a subscription + // The engine never fetches — a draft-22 join is a subscription // filter, and every subscription replays the newest group anyway. // Anything else asking for history is refused: nothing beyond // the ring buffer is retained. @@ -1316,7 +1318,7 @@ export function createPublisherLoopbackRelay({ onLog }: PublisherLoopbackRelayOp } const { value, done } = await reader.read(); - // Cancellation *is* the stream lifecycle (§3.3.3): the subscriber + // Cancellation *is* the stream lifecycle (§6.4.2.3): the subscriber // aborting its sending direction ends the subscription. if (done) break; diff --git a/internal/design/spf/features/clusters.md b/internal/design/spf/features/clusters.md index e320fd5ab1..ae259db31d 100644 --- a/internal/design/spf/features/clusters.md +++ b/internal/design/spf/features/clusters.md @@ -272,7 +272,7 @@ The publish direction — capture, encode, and MOQT publish composed as an engin **Docs.** `moq-publish`. -**Foundational primitives.** The publish session driver + actor (`publish/session/publish-session.ts`, publish-side sibling of the subscribe driver); `TrackPublisherActor` + `createSubgroupWriter` (packaged frames → MOQT groups/objects on the wire, with the stale-group drop policy); the WebCodecs encoder actor pair (`publish/actors/dom/`); LOC packaging + MSF catalog building (`media/moq/loc-packaging.ts`, `media/moq/build-catalog.ts` — encode complements of `loc.ts` / `parse-catalog.ts`, round-trip-tested against them). +**Foundational primitives.** The publish session actor (`publish/session/publish-session.ts`, driving `@caprid/moq-core`'s publish session); `TrackPublisherActor` + `@caprid/moq-core`'s `createSubgroupWriter` (packaged frames → MOQT groups/objects on the wire, with the stale-group drop policy); the WebCodecs encoder actor pair (`publish/actors/dom/`); LOC packaging + MSF catalog building (`media/moq/loc-packaging.ts`, `media/moq/build-catalog.ts` — encode complements of `loc.ts` / `parse-catalog.ts`, round-trip-tested against them). **Common cross-cluster touchpoints.** Engine lifecycle (the composition / machine-reactor / cleanup conventions transfer wholesale, but the gate is consumer intent — `captureSource`, `publishActivated` — rather than `preload` / `loadActivated`, and there is no presentation/resolver cascade: capture-selection identity plays `state.presentation`'s reset-driver role); capability probing (probe-before-commit transfers to the encode direction — `probeEncoderSupport`'s `isConfigSupported` ladder is `canPlayTrack`'s WebCodecs analog, landing as an async slot-writer per that cluster's sync-vs-async split); MSE / buffer management (deliberately none — the publish direction's DOM boundary is capture + WebCodecs, not `MediaSource`). diff --git a/internal/design/spf/features/moq-publish.md b/internal/design/spf/features/moq-publish.md index 8c69433b9a..907833e53a 100644 --- a/internal/design/spf/features/moq-publish.md +++ b/internal/design/spf/features/moq-publish.md @@ -155,20 +155,16 @@ Actors and session: |---|---|---| | Encoder actor core + video/audio specializations | `publish/actors/dom/{encoder-actor,video-encoder,audio-encoder}.ts` | Own one WebCodecs encoder; delta-drop backpressure; LOC-package output to the `chunkSink`; counter snapshots | | `TrackPublisherActor` | `publish/actors/track-publisher.ts` | One MOQT track → subgroup streams (one uni stream per group), demand-gated by the subscription binding; group-per-keyframe or group-per-frame; replay-on-bind for the catalog; stale-group drop policy | -| Publish session driver + actor | `publish/session/publish-session.ts` | Draft-19 publish-side protocol driver (callback-shaped, no signals) + the reactive session actor behaviors consume | +| Publish session actor | `publish/session/publish-session.ts` | Connects and drives `@caprid/moq-core`'s publish session (callback-shaped, no signals); the reactive snapshot behaviors consume | | Media-host adapter | `publish/engines/moq/adapter.ts` | `MoqPublishMediaMixin` — expresses the `@videojs/media` publisher capabilities structurally; owns contract events | Shared modules (consumed, not owned — encode-direction complements of the playback stack's decode direction): -- [`network/moqt/subgroup-writer.ts`](../../../../packages/spf/src/network/moqt/subgroup-writer.ts) - — subgroup data-stream writing; round-trips through `object-stream.ts`'s - reader. The only new `network/moqt` file: the parent-owned wire layer's - codec was already symmetric, so publish additions there stayed - additive. The announce-and-serve rework added exactly two encoders to - the existing codec module — `encodeNamespace` / `encodeNamespaceDone` - (their decoders predated them) — plus the `TRACK_PROPERTY.TIMESCALE` - constant. +- `@caprid/moq-core` — the MOQT wire layer both directions share: the + publish session (announce-and-serve, LARGEST_OBJECT, fills, PUBLISH_DONE + with its own Stream Count) and `createSubgroupWriter`. Its codec and + driver tests live in the package. - [`media/moq/loc-packaging.ts`](../../../../packages/spf/src/media/moq/loc-packaging.ts) / [`media/moq/build-catalog.ts`](../../../../packages/spf/src/media/moq/build-catalog.ts) — encode complements of `loc.ts` / `parse-catalog.ts`; each round-trips @@ -248,30 +244,20 @@ publisher initiates no requests, so there is no response to bound. ## Verification - **Unit** — one colocated test file per behavior, actor, and the session - driver (`publish/behaviors/dom/tests/`, `publish/behaviors/tests/`, + actor (`publish/behaviors/dom/tests/`, `publish/behaviors/tests/`, `publish/actors/dom/tests/`, `publish/actors/tests/`, `publish/session/tests/`), plus engine composition and adapter tests (`publish/engines/moq/tests/{engine,adapter}.test.ts`). - **Round-trips against the decode direction** — - `network/moqt/tests/publish-direction.test.ts` pins the publish-side - encode↔decode pairs against the existing decoders as golden reference, - plus byte-exact pins where moq-lite-rs's decoder is stricter than a - round-trip can prove (the parameterless NAMESPACE body, the bare - REQUEST_OK acceptance, a SUBSCRIBE laid out exactly as the relay - writes it — delta-typed parameters with raw-byte values); - `network/moqt/tests/subgroup-writer.test.ts` round-trips written - subgroups through the object-stream reader; `media/moq/tests/loc-packaging.test.ts` round-trips through `toLocFrame`; `media/moq/tests/build-catalog.test.ts` round-trips through `parseMoqCatalog` → presentation → decoder configs. - **The serve flow against a relay-shaped peer** — - `publish/session/tests/publish-session.test.ts` drives the announce - 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 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 + `publish/session/tests/publish-session.test.ts` drives the session + actor's lifecycle (connecting → ready → live, announce loss, GOAWAY) + and a catalog + LOC round trip, and `publish/tests/relay-hub.test.ts` + pins the hub's announce-and-serve contract, both through + `network/tests/helpers/raw-peer.ts` and `moqt-wire.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 @@ -314,7 +300,7 @@ publisher initiates no requests, so there is no response to bound. - **`[moq-playback]`** *(candidate — no feature doc yet)* — the subscribe direction this feature complements: `playback/engines/moq/`, the - `network/moqt` session/wire layer, and `media/moq`'s `loc.ts` / + `@caprid/moq-core` session/wire layer, and `media/moq`'s `loc.ts` / `parse-catalog.ts` that this feature's packaging/building round-trip against. - **[capability-probing](./capability-probing.md)** — pattern sibling, @@ -339,6 +325,6 @@ publisher initiates no requests, so there is no response to bound. - [`publish/engines/moq/engine.ts`](../../../../packages/spf/src/publish/engines/moq/engine.ts) (composition) · [`publish/session/publish-session.ts`](../../../../packages/spf/src/publish/session/publish-session.ts) - (protocol driver) · + (session actor) · [`publish/actors/track-publisher.ts`](../../../../packages/spf/src/publish/actors/track-publisher.ts) (group/backpressure mechanics) diff --git a/internal/specs/moq/README.md b/internal/specs/moq/README.md index 97e87d8550..e10d691760 100644 --- a/internal/specs/moq/README.md +++ b/internal/specs/moq/README.md @@ -4,11 +4,11 @@ Verbatim IETF Internet-Draft texts for the protocols the MoQ stack in `packages/ For a complete catalog example and the current player's media requirements, see [Publish a stream for the MoQ player](../../../packages/spf/docs/moq-publishing.md). -The version the code actually speaks is declared in code: the transport comes from the `@caprid/moq-core` dependency of `packages/spf` (its `MOQT_PROTOCOL_IDS` lists the versions the player offers, most preferred first; `moqt-20` is the fallback), and the header comments of `packages/spf/src/media/moq/loc.ts` and `parse-catalog.ts` for LOC and MSF. When the vendored text is newer than the code pin, the gap is tracked by a migration plan under `.agents/plans/`. +The version the code actually speaks is declared in code: the transport comes from the `@caprid/moq-core` dependency of `packages/spf` (its `MOQT_PROTOCOL_IDS` lists the versions the player and the publisher offer, most preferred first; `moqt-20` is the fallback), and the header comments of `packages/spf/src/media/moq/loc.ts` and `parse-catalog.ts` for LOC and MSF. When the vendored text is newer than the code pin, the gap is tracked by a migration plan under `.agents/plans/`. | Draft | Revision | Published | Implemented in | | --- | --- | --- | --- | -| Media over QUIC Transport | `draft-ietf-moq-transport-22` | 2026-10-01 | `@caprid/moq-core`, consumed by `packages/spf/src/playback/actors/moq-session.ts` | +| Media over QUIC Transport | `draft-ietf-moq-transport-22` | 2026-10-01 | `@caprid/moq-core`, consumed by `packages/spf/src/playback/actors/moq-session.ts` and `packages/spf/src/publish/session/publish-session.ts` | | Low Overhead Media Container (LOC) | `draft-ietf-moq-loc-04` | 2026-07-20 | `packages/spf/src/media/moq/loc.ts` | | MOQT Streaming Format (MSF) | `draft-ietf-moq-msf-01` | 2026-06-02 | `packages/spf/src/media/moq/parse-catalog.ts`, `parse-source.ts` | From ed92cbf99f8432545e1d9589bc76ba37f0608e9e Mon Sep 17 00:00:00 2001 From: Matt McClure Date: Wed, 28 Oct 2026 17:13:02 +0000 Subject: [PATCH 3/3] docs(spf): drop stale draft-19 references from the publish feature record Claude-Session: https://claude.ai/code/session_01DaH4ifX9Vb6HuB2yg6TMt5 --- internal/design/spf/features/moq-publish.md | 11 ++++++----- 1 file changed, 6 insertions(+), 5 deletions(-) diff --git a/internal/design/spf/features/moq-publish.md b/internal/design/spf/features/moq-publish.md index 907833e53a..315c897aae 100644 --- a/internal/design/spf/features/moq-publish.md +++ b/internal/design/spf/features/moq-publish.md @@ -11,8 +11,9 @@ WebCodecs encode → Media over QUIC (MOQT) publish to a relay. Implemented as its own composed engine, `createMoqPublishEngine`, in a new `publish/` SPF layer (peer of `playback/`), publishing one LOC-packaged video rendition plus one Opus audio track plus an MSF catalog track over -moq-transport draft-19 — the same dialect, wire layer, and media modules -the MoQ playback engine consumes from the other side. +moq-transport draft-22 (falling back to moqt-20) through `@caprid/moq-core` +— the same package and media modules the MoQ playback engine consumes from +the other side. **Classification note.** The [Media-src / Player / Borderline axis](./clusters.md#media-src-vs-player-vs-borderline) @@ -49,7 +50,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 = 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** | +| Transport | `@caprid/moq-core` publish session speaking draft-22 (moqt-20 fallback) 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) @@ -214,8 +215,8 @@ publisher initiates no requests, so there is no response to bound. **Constraints (v1, by design):** -- **At most one live subscription per track — newest wins.** Draft-19 - permits concurrent same-track subscriptions (e.g. disjoint filters), +- **At most one live subscription per track — newest wins.** The + transport draft permits concurrent same-track subscriptions (e.g. disjoint filters), but serving them means writing every group once per alias; the known peers (moq-lite-rs relays) hold one upstream subscription per track and fan out on their side, and the sweep doubles as the resubscribe