@moqtap/codec 0.11.0 → 0.12.0

package/dist/types-DDwidj2d.d.ts

@@ -0,0 +1,371 @@
+interface UnknownParam {
+    readonly id: string;
+    readonly length: number;
+    readonly raw_hex: string;
+}
+interface AuthorizationToken {
+    readonly alias_type: bigint;
+    readonly token_alias?: bigint;
+    readonly token_type?: bigint;
+    readonly token_value?: Uint8Array;
+}
+interface Draft21SetupOptions {
+    path?: string;
+    authorization_token?: readonly AuthorizationToken[];
+    max_auth_token_cache_size?: bigint;
+    authority?: string;
+    max_filter_ranges?: bigint;
+    moqt_implementation?: string;
+    max_request_updates?: bigint;
+    unknown?: UnknownParam[];
+}
+/**
+ * LOCATION_FILTER (0x21) — draft-21 Section 3.3.1.
+ *
+ * The draft-19 `Filter Type` discriminator (0x1 Next Group Start / 0x2 Largest
+ * Object / 0x3 AbsoluteStart / 0x4 AbsoluteRange) is gone; the shape is the
+ * number of vi64 fields the value holds. The fields below carry the wire
+ * values verbatim, unresolved:
+ *
+ *  - 1 field  → `start_group` alone is RELATIVE: start is
+ *               {Largest Object.Group + 1 - start_group, 0}. Open-ended.
+ *  - 2 fields → absolute start {start_group, start_object}, except that
+ *               {0, 0} means the Next Object. Open-ended.
+ *  - 3 fields → end group is `start_group + end_group_delta`; `end_object`
+ *               omitted means every object in that group.
+ *  - 4 fields → the fully specified INCLUSIVE range
+ *               {start_group, start_object} … {start_group + end_group_delta,
+ *               end_object}.
+ *
+ * `removed: true` is the `Length == 0` form, which in REQUEST_UPDATE removes an
+ * existing filter.
+ *
+ * The range is inclusive at both ends. draft-19's "last Object, plus 1" and
+ * "Object == 0 means the whole group" conventions are gone, so nothing here is
+ * ever incremented or decremented on the way in or out.
+ */
+interface LocationFilter {
+    readonly start_group?: bigint;
+    readonly start_object?: bigint;
+    readonly end_group_delta?: bigint;
+    readonly end_object?: bigint;
+    readonly removed?: boolean;
+}
+interface RangeFilterRange {
+    readonly start: bigint;
+    readonly end?: bigint;
+}
+interface RangeFilter {
+    readonly set_id?: bigint;
+    readonly property_type?: bigint;
+    readonly ranges?: RangeFilterRange[];
+    readonly removed?: boolean;
+}
+interface LargestObject {
+    readonly group: bigint;
+    readonly object: bigint;
+}
+/**
+ * FILL_PARAMETERS (0x23) value — NEW in draft-20 (Section 9.20.16).
+ *
+ * A separate parameter scope carrying only the settings that differ from the
+ * subscription's. Table 6 closes the list to exactly these eight types;
+ * TRACK_PROPERTY_FILTER (0x29) is deliberately excluded.
+ *
+ * The mere presence of the parameter is what requests a fill fetch stream, so
+ * an empty value is meaningful — it asks for a fill with everything inherited.
+ */
+interface Draft21FillParameters {
+    fill_timeout?: bigint;
+    subscriber_priority?: bigint;
+    location_filter?: LocationFilter;
+    group_order?: bigint;
+    subgroup_filter?: readonly RangeFilter[];
+    objectid_filter?: readonly RangeFilter[];
+    priority_filter?: readonly RangeFilter[];
+    object_property_filter?: readonly RangeFilter[];
+}
+interface Draft21Params {
+    object_delivery_timeout?: bigint;
+    authorization_token?: readonly AuthorizationToken[];
+    rendezvous_timeout?: bigint;
+    subgroup_delivery_timeout?: bigint;
+    expires?: bigint;
+    largest_object?: LargestObject;
+    fill_timeout?: bigint;
+    forward?: bigint;
+    subscriber_priority?: bigint;
+    location_filter?: LocationFilter;
+    group_order?: bigint;
+    fill_parameters?: Draft21FillParameters;
+    subgroup_filter?: readonly RangeFilter[];
+    objectid_filter?: readonly RangeFilter[];
+    priority_filter?: readonly RangeFilter[];
+    object_property_filter?: readonly RangeFilter[];
+    track_property_filter?: readonly RangeFilter[];
+    new_group_request?: bigint;
+    track_namespace_prefix?: string[];
+    include_properties?: bigint;
+    unknown?: UnknownParam[];
+}
+interface Draft21TrackProperties {
+    object_delivery_timeout?: bigint;
+    max_cache_duration?: bigint;
+    subgroup_delivery_timeout?: bigint;
+    immutable_properties?: Uint8Array;
+    default_publisher_priority?: bigint;
+    default_publisher_group_order?: bigint;
+    dynamic_groups?: bigint;
+    unknown?: UnknownParam[];
+}
+type Draft21MessageType = 'setup' | 'subscribe' | 'subscribe_ok' | 'request_update' | 'publish_state_notify' | 'publish' | 'publish_done' | 'publish_namespace' | 'namespace' | 'namespace_done' | 'subscribe_namespace' | 'subscribe_tracks' | 'publish_skipped' | 'fetch' | 'fetch_ok' | 'track_status' | 'request_ok' | 'request_error' | 'goaway';
+interface Draft21BaseMessage {
+    readonly type: Draft21MessageType;
+}
+interface Draft21Setup extends Draft21BaseMessage {
+    readonly type: 'setup';
+    readonly options: Draft21SetupOptions;
+}
+interface Draft21Subscribe extends Draft21BaseMessage {
+    readonly type: 'subscribe';
+    readonly request_id: bigint;
+    readonly track_namespace: string[];
+    readonly track_name: string;
+    readonly parameters: Draft21Params;
+}
+interface Draft21SubscribeOk extends Draft21BaseMessage {
+    readonly type: 'subscribe_ok';
+    readonly track_alias: bigint;
+    readonly parameters: Draft21Params;
+    readonly track_properties: Draft21TrackProperties;
+}
+interface Draft21RequestUpdate extends Draft21BaseMessage {
+    readonly type: 'request_update';
+    readonly request_id: bigint;
+    readonly parameters: Draft21Params;
+}
+/**
+ * PUBLISH_STATE_NOTIFY (0x22) — NEW in draft-20, Section 9.10.
+ *
+ * No Request ID: the message is identified by the subscription's bidirectional
+ * stream it arrives on, like SUBSCRIBE_OK, PUBLISH_DONE and FETCH_OK.
+ */
+interface Draft21PublishStateNotify extends Draft21BaseMessage {
+    readonly type: 'publish_state_notify';
+    readonly parameters: Draft21Params;
+}
+interface Draft21Publish extends Draft21BaseMessage {
+    readonly type: 'publish';
+    readonly request_id: bigint;
+    readonly track_namespace: string[];
+    readonly track_name: string;
+    readonly track_alias: bigint;
+    readonly parameters: Draft21Params;
+    readonly track_properties: Draft21TrackProperties;
+}
+interface Draft21PublishDone extends Draft21BaseMessage {
+    readonly type: 'publish_done';
+    readonly status_code: bigint;
+    /**
+     * Number of streams opened for the subscription, including empty subgroups
+     * and — new in draft-20 — fill fetch streams (Section 9.9), or the
+     * `UNKNOWN_STREAM_COUNT` sentinel exported from `codec.ts` (2^64 - 1, raised
+     * from draft-19's 2^62 - 1) when the publisher cannot state it exactly.
+     *
+     * `bigint`, not `number`: the sentinel does not fit a double.
+     */
+    readonly stream_count: bigint;
+    readonly reason_phrase: string;
+}
+interface Draft21PublishNamespace extends Draft21BaseMessage {
+    readonly type: 'publish_namespace';
+    readonly request_id: bigint;
+    readonly track_namespace: string[];
+    readonly parameters: Draft21Params;
+}
+interface Draft21Namespace extends Draft21BaseMessage {
+    readonly type: 'namespace';
+    readonly namespace_suffix: string[];
+}
+interface Draft21NamespaceDone extends Draft21BaseMessage {
+    readonly type: 'namespace_done';
+    readonly namespace_suffix: string[];
+}
+interface Draft21SubscribeNamespace extends Draft21BaseMessage {
+    readonly type: 'subscribe_namespace';
+    readonly request_id: bigint;
+    readonly namespace_prefix: string[];
+    readonly parameters: Draft21Params;
+}
+interface Draft21SubscribeTracks extends Draft21BaseMessage {
+    readonly type: 'subscribe_tracks';
+    readonly request_id: bigint;
+    readonly namespace_prefix: string[];
+    readonly parameters: Draft21Params;
+}
+interface Draft21PublishSkipped extends Draft21BaseMessage {
+    readonly type: 'publish_skipped';
+    readonly namespace_suffix: string[];
+    readonly track_name: string;
+}
+/**
+ * FETCH (0x16) — the byte layout was rewritten in draft-20 (Section 9.11).
+ *
+ * Gone: the `Fetch Type` field and its enum, the `Standalone Fetch` and
+ * `Joining Fetch` structures, and the inline `Start Location` / `End Location`.
+ * Track Namespace and Track Name are inline fields of FETCH itself, and the
+ * range travels in the LOCATION_FILTER parameter. A FETCH with no
+ * LOCATION_FILTER covers {0,0} through Largest Object, inclusive.
+ *
+ * The codepoint did not change, so a draft-19 decoder fed one of these reads
+ * the Number of Track Namespace Fields count as a Fetch Type and mis-parses in
+ * silence. There is no in-band version signal that catches it.
+ */
+interface Draft21Fetch extends Draft21BaseMessage {
+    readonly type: 'fetch';
+    readonly request_id: bigint;
+    readonly track_namespace: string[];
+    readonly track_name: string;
+    readonly parameters: Draft21Params;
+}
+/**
+ * FETCH_OK (0x18) — bytes identical to draft-19, meaning changed.
+ *
+ * `end_group` / `end_object` are the INCLUSIVE end of the range the response
+ * covers: the last Object actually covered. draft-19's "the last Object, plus
+ * 1; or 0 to indicate the entire Group" is gone (draft-21 Section 9.12 with
+ * Section 3.3.1). The same bytes mean a different object under the two drafts,
+ * and nothing on the wire distinguishes them.
+ */
+interface Draft21FetchOk extends Draft21BaseMessage {
+    readonly type: 'fetch_ok';
+    readonly end_of_track: number;
+    readonly end_group: bigint;
+    readonly end_object: bigint;
+    readonly parameters: Draft21Params;
+    readonly track_properties: Draft21TrackProperties;
+}
+interface Draft21TrackStatus extends Draft21BaseMessage {
+    readonly type: 'track_status';
+    readonly request_id: bigint;
+    readonly track_namespace: string[];
+    readonly track_name: string;
+    readonly parameters: Draft21Params;
+}
+interface Draft21RequestOk extends Draft21BaseMessage {
+    readonly type: 'request_ok';
+    readonly parameters: Draft21Params;
+    readonly track_properties: Draft21TrackProperties;
+}
+/**
+ * Redirect structure, used inside REQUEST_ERROR when error_code = REDIRECT (0x34).
+ *
+ * draft-21 Section 9.4.1 names the namespace/name pair "the Redirect target"
+ * and dropped draft-19's rule that a zero-length pair meant "reuse the values
+ * from the original request". An empty namespace and name are now a literal
+ * empty namespace and name.
+ */
+interface Redirect {
+    readonly connect_uri: string;
+    readonly track_namespace: string[];
+    readonly track_name: string;
+}
+interface Draft21RequestError extends Draft21BaseMessage {
+    readonly type: 'request_error';
+    readonly error_code: bigint;
+    readonly retry_interval: bigint;
+    readonly reason_phrase: string;
+    readonly redirect?: Redirect;
+}
+interface Draft21GoAway extends Draft21BaseMessage {
+    readonly type: 'goaway';
+    readonly new_session_uri: string;
+    readonly timeout: bigint;
+}
+type Draft21Message = Draft21Setup | Draft21Subscribe | Draft21SubscribeOk | Draft21RequestUpdate | Draft21PublishStateNotify | Draft21Publish | Draft21PublishDone | Draft21PublishNamespace | Draft21Namespace | Draft21NamespaceDone | Draft21SubscribeNamespace | Draft21SubscribeTracks | Draft21PublishSkipped | Draft21Fetch | Draft21FetchOk | Draft21TrackStatus | Draft21RequestOk | Draft21RequestError | Draft21GoAway;
+interface ObjectPayload {
+    readonly type: 'object';
+    readonly byteOffset: number;
+    readonly payloadByteOffset: number;
+    readonly objectId: bigint;
+    /** The Object ID Delta as it appeared on the wire, before delta resolution. */
+    readonly objectIdDelta?: bigint;
+    readonly payloadLength: number;
+    readonly status?: bigint;
+    readonly extensionData: Uint8Array;
+    readonly objectProperties?: Record<string, bigint>;
+    readonly payload: Uint8Array;
+}
+interface SubgroupStream {
+    readonly type: 'subgroup';
+    /** SUBGROUP_HEADER `Type Flags` (draft-21 Section 11.3.1). */
+    readonly headerType: number;
+    readonly trackAlias: bigint;
+    readonly groupId: bigint;
+    readonly subgroupId: bigint;
+    readonly publisherPriority: number;
+    readonly endOfGroup?: boolean;
+    readonly firstObject?: boolean;
+    readonly objects: ObjectPayload[];
+}
+interface DatagramObject {
+    readonly type: 'datagram';
+    /** OBJECT_DATAGRAM `Type Flags` (draft-21 Section 11.2.1). */
+    readonly datagramType: number;
+    readonly trackAlias: bigint;
+    readonly groupId: bigint;
+    readonly objectId: bigint;
+    readonly publisherPriority: number;
+    readonly endOfGroup?: boolean;
+    readonly objectStatus?: bigint;
+    readonly objectProperties?: Record<string, bigint>;
+    readonly payloadLength: number;
+    readonly payload: Uint8Array;
+}
+interface FetchObjectPayload extends ObjectPayload {
+    readonly serializationFlags: number;
+    readonly groupId: bigint;
+    /** The Group ID Delta as it appeared on the wire, before delta resolution. */
+    readonly groupIdDelta?: bigint;
+    readonly subgroupId: bigint;
+    readonly publisherPriority: number;
+    readonly objectProperties?: Record<string, bigint>;
+}
+interface FetchStream {
+    readonly type: 'fetch';
+    /**
+     * The Request ID of the message that opened the stream. In draft-21 that is
+     * not necessarily a FETCH: a fill fetch stream (Section 3.4) carries the
+     * Request ID of the SUBSCRIBE or REQUEST_UPDATE that requested the fill.
+     */
+    readonly requestId: bigint;
+    readonly objects: FetchObjectPayload[];
+}
+type Draft21DataStream = SubgroupStream | DatagramObject | FetchStream;
+interface SubgroupStreamHeader {
+    readonly type: 'subgroup_header';
+    /**
+     * SUBGROUP_HEADER `Type Flags`, the same value `SubgroupStream.headerType`
+     * carries. It is reported so the incremental decoder does not drop the flags
+     * the header encodes, which is what lets a consumer tell the modes apart.
+     */
+    readonly headerType: number;
+    readonly trackAlias: bigint;
+    readonly groupId: bigint;
+    /**
+     * Under Subgroup Mode 0b01 this is the first Object's ID, which is why the
+     * header is not emitted until that Object has been read.
+     */
+    readonly subgroupId: bigint;
+    readonly publisherPriority: number;
+    readonly endOfGroup?: boolean;
+    readonly firstObject?: boolean;
+}
+interface FetchStreamHeader {
+    readonly type: 'fetch_header';
+    readonly requestId: bigint;
+}
+type DataStreamHeader = SubgroupStreamHeader | FetchStreamHeader;
+type DataStreamEvent = DataStreamHeader | ObjectPayload;
+
+export type { Draft21SubscribeNamespace as A, Draft21SubscribeOk as B, Draft21SubscribeTracks as C, Draft21Message as D, Draft21TrackProperties as E, FetchStreamHeader as F, Draft21TrackStatus as G, FetchObjectPayload as H, LocationFilter as I, RangeFilterRange as J, Redirect as K, LargestObject as L, ObjectPayload as O, RangeFilter as R, SubgroupStreamHeader as S, UnknownParam as U, Draft21MessageType as a, DataStreamEvent as b, Draft21DataStream as c, DatagramObject as d, FetchStream as e, SubgroupStream as f, DataStreamHeader as g, Draft21BaseMessage as h, Draft21Fetch as i, Draft21FetchOk as j, Draft21FillParameters as k, Draft21GoAway as l, Draft21Namespace as m, Draft21NamespaceDone as n, Draft21Params as o, Draft21Publish as p, Draft21PublishDone as q, Draft21PublishNamespace as r, Draft21PublishSkipped as s, Draft21PublishStateNotify as t, Draft21RequestError as u, Draft21RequestOk as v, Draft21RequestUpdate as w, Draft21Setup as x, Draft21SetupOptions as y, Draft21Subscribe as z };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@moqtap/codec",
-  "version": "0.11.0",
+  "version": "0.12.0",
   "description": "MoQT wire-format codec and session state machine — multi-draft, zero dependencies",
   "type": "module",
   "license": "MIT",
@@ -208,6 +208,18 @@
       "types": "./dist/draft20-session.d.ts",
       "import": "./dist/draft20-session.js",
       "require": "./dist/draft20-session.cjs"
+    },
+    "./draft21": {
+      "bun": "./src/drafts/draft21/index.ts",
+      "types": "./dist/draft21.d.ts",
+      "import": "./dist/draft21.js",
+      "require": "./dist/draft21.cjs"
+    },
+    "./draft21/session": {
+      "bun": "./src/drafts/draft21/session.ts",
+      "types": "./dist/draft21-session.d.ts",
+      "import": "./dist/draft21-session.js",
+      "require": "./dist/draft21-session.cjs"
     }
   },
   "files": [
@@ -221,7 +233,7 @@
     "test": "vitest run"
   },
   "devDependencies": {
-    "@moqtap/test-vectors": "^0.16.0",
+    "@moqtap/test-vectors": "^0.17.0",
     "tsup": "^8.0.0",
     "typescript": "^5.5.0",
     "vitest": "^3.2.7"

package/src/core/auth-redaction.ts

@@ -46,8 +46,6 @@
  * the capture, runs one decode to completion, and closes it in a `finally`.
  * There is no `await` between those points, so no second capture can interleave
  * with the first.
- *
- * Spec of record: `wt-logging-1-collector.md` Section 1.6.
  */
 
 /**

package/src/core/types.ts

@@ -14,6 +14,7 @@ export type Draft =
   | '18'
   | '19'
   | '20'
+  | '21'
 
 // Base codec interface — draft-specific codecs extend this
 export interface BaseCodec<M> {

package/src/drafts/draft19/codec.ts

@@ -234,7 +234,7 @@ function encodeAuthorizationToken(token: AuthorizationToken, w: BufferWriter): v
 
 /**
  * Record where a Token Value sits, so it can be overwritten before the frame
- * reaches anything that keeps it (Section 1.6).
+ * reaches anything that keeps it.
  *
  * The span falls out of the decode with no second walk. The Token Value is the
  * tail of the Token structure — draft-19 Section 10.2.2, Figure 5: it is NOT

package/src/drafts/draft20/codec.ts

@@ -264,7 +264,7 @@ function encodeAuthorizationToken(token: AuthorizationToken, w: BufferWriter): v
 
 /**
  * Record where a Token Value sits, so it can be overwritten before the frame
- * reaches anything that keeps it (Section 1.6).
+ * reaches anything that keeps it.
  *
  * The span falls out of the decode with no second walk. The Token Value is the
  * tail of the Token structure — draft-20 Section 10.2.2, Figure 5: it is NOT