@moqtap/codec 0.8.1 → 0.9.0

package/dist/types-CWCQwuvy.d.ts

@@ -0,0 +1,359 @@
+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 Draft20SetupOptions {
+    path?: string;
+    authorization_token?: 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) — restructured in draft-20 (Section 5.1.2).
+ *
+ * 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 10.2.15).
+ *
+ * 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 Draft20FillParameters {
+    fill_timeout?: bigint;
+    subscriber_priority?: bigint;
+    location_filter?: LocationFilter;
+    group_order?: bigint;
+    subgroup_filter?: RangeFilter;
+    objectid_filter?: RangeFilter;
+    priority_filter?: RangeFilter;
+    object_property_filter?: RangeFilter;
+}
+interface Draft20Params {
+    object_delivery_timeout?: bigint;
+    authorization_token?: 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?: Draft20FillParameters;
+    subgroup_filter?: RangeFilter;
+    objectid_filter?: RangeFilter;
+    priority_filter?: RangeFilter;
+    object_property_filter?: RangeFilter;
+    track_property_filter?: RangeFilter;
+    new_group_request?: bigint;
+    track_namespace_prefix?: string[];
+    include_properties?: bigint;
+    unknown?: UnknownParam[];
+}
+interface Draft20TrackProperties {
+    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 Draft20MessageType = '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 Draft20BaseMessage {
+    readonly type: Draft20MessageType;
+}
+interface Draft20Setup extends Draft20BaseMessage {
+    readonly type: 'setup';
+    readonly options: Draft20SetupOptions;
+}
+interface Draft20Subscribe extends Draft20BaseMessage {
+    readonly type: 'subscribe';
+    readonly request_id: bigint;
+    readonly track_namespace: string[];
+    readonly track_name: string;
+    readonly parameters: Draft20Params;
+}
+interface Draft20SubscribeOk extends Draft20BaseMessage {
+    readonly type: 'subscribe_ok';
+    readonly track_alias: bigint;
+    readonly parameters: Draft20Params;
+    readonly track_properties: Draft20TrackProperties;
+}
+interface Draft20RequestUpdate extends Draft20BaseMessage {
+    readonly type: 'request_update';
+    readonly request_id: bigint;
+    readonly parameters: Draft20Params;
+}
+/**
+ * PUBLISH_STATE_NOTIFY (0x22) — NEW in draft-20, Section 10.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 Draft20PublishStateNotify extends Draft20BaseMessage {
+    readonly type: 'publish_state_notify';
+    readonly parameters: Draft20Params;
+}
+interface Draft20Publish extends Draft20BaseMessage {
+    readonly type: 'publish';
+    readonly request_id: bigint;
+    readonly track_namespace: string[];
+    readonly track_name: string;
+    readonly track_alias: bigint;
+    readonly parameters: Draft20Params;
+    readonly track_properties: Draft20TrackProperties;
+}
+interface Draft20PublishDone extends Draft20BaseMessage {
+    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 10.12), 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 Draft20PublishNamespace extends Draft20BaseMessage {
+    readonly type: 'publish_namespace';
+    readonly request_id: bigint;
+    readonly track_namespace: string[];
+    readonly parameters: Draft20Params;
+}
+interface Draft20Namespace extends Draft20BaseMessage {
+    readonly type: 'namespace';
+    readonly namespace_suffix: string[];
+}
+interface Draft20NamespaceDone extends Draft20BaseMessage {
+    readonly type: 'namespace_done';
+    readonly namespace_suffix: string[];
+}
+interface Draft20SubscribeNamespace extends Draft20BaseMessage {
+    readonly type: 'subscribe_namespace';
+    readonly request_id: bigint;
+    readonly namespace_prefix: string[];
+    readonly parameters: Draft20Params;
+}
+interface Draft20SubscribeTracks extends Draft20BaseMessage {
+    readonly type: 'subscribe_tracks';
+    readonly request_id: bigint;
+    readonly namespace_prefix: string[];
+    readonly parameters: Draft20Params;
+}
+interface Draft20PublishSkipped extends Draft20BaseMessage {
+    readonly type: 'publish_skipped';
+    readonly namespace_suffix: string[];
+    readonly track_name: string;
+}
+/**
+ * FETCH (0x16) — the byte layout was rewritten in draft-20 (Section 10.13).
+ *
+ * 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 Draft20Fetch extends Draft20BaseMessage {
+    readonly type: 'fetch';
+    readonly request_id: bigint;
+    readonly track_namespace: string[];
+    readonly track_name: string;
+    readonly parameters: Draft20Params;
+}
+/**
+ * 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-20 Section 10.14 with
+ * Section 5.1.2). The same bytes mean a different object under the two drafts,
+ * and nothing on the wire distinguishes them.
+ */
+interface Draft20FetchOk extends Draft20BaseMessage {
+    readonly type: 'fetch_ok';
+    readonly end_of_track: number;
+    readonly end_group: bigint;
+    readonly end_object: bigint;
+    readonly parameters: Draft20Params;
+    readonly track_properties: Draft20TrackProperties;
+}
+interface Draft20TrackStatus extends Draft20BaseMessage {
+    readonly type: 'track_status';
+    readonly request_id: bigint;
+    readonly track_namespace: string[];
+    readonly track_name: string;
+    readonly parameters: Draft20Params;
+}
+interface Draft20RequestOk extends Draft20BaseMessage {
+    readonly type: 'request_ok';
+    readonly parameters: Draft20Params;
+    readonly track_properties: Draft20TrackProperties;
+}
+/**
+ * Redirect structure, used inside REQUEST_ERROR when error_code = REDIRECT (0x34).
+ *
+ * draft-20 Section 10.6.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 Draft20RequestError extends Draft20BaseMessage {
+    readonly type: 'request_error';
+    readonly error_code: bigint;
+    readonly retry_interval: bigint;
+    readonly reason_phrase: string;
+    readonly redirect?: Redirect;
+}
+interface Draft20GoAway extends Draft20BaseMessage {
+    readonly type: 'goaway';
+    readonly new_session_uri: string;
+    readonly timeout: bigint;
+}
+type Draft20Message = Draft20Setup | Draft20Subscribe | Draft20SubscribeOk | Draft20RequestUpdate | Draft20PublishStateNotify | Draft20Publish | Draft20PublishDone | Draft20PublishNamespace | Draft20Namespace | Draft20NamespaceDone | Draft20SubscribeNamespace | Draft20SubscribeTracks | Draft20PublishSkipped | Draft20Fetch | Draft20FetchOk | Draft20TrackStatus | Draft20RequestOk | Draft20RequestError | Draft20GoAway;
+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-20 Section 11.4.2). */
+    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-20 Section 11.3.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-20 that is
+     * not necessarily a FETCH: a fill fetch stream (Section 5.1.3) carries the
+     * Request ID of the SUBSCRIBE or REQUEST_UPDATE that requested the fill.
+     */
+    readonly requestId: bigint;
+    readonly objects: FetchObjectPayload[];
+}
+type Draft20DataStream = SubgroupStream | DatagramObject | FetchStream;
+interface SubgroupStreamHeader {
+    readonly type: 'subgroup_header';
+    readonly trackAlias: bigint;
+    readonly groupId: bigint;
+    readonly subgroupId: bigint;
+    readonly publisherPriority: number;
+}
+interface FetchStreamHeader {
+    readonly type: 'fetch_header';
+    readonly requestId: bigint;
+}
+type DataStreamHeader = SubgroupStreamHeader | FetchStreamHeader;
+type DataStreamEvent = DataStreamHeader | ObjectPayload;
+
+export type { Draft20SubscribeNamespace as A, Draft20SubscribeOk as B, Draft20SubscribeTracks as C, Draft20Message as D, Draft20TrackProperties as E, FetchStreamHeader as F, Draft20TrackStatus 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, Draft20MessageType as a, DataStreamEvent as b, Draft20DataStream as c, DatagramObject as d, FetchStream as e, SubgroupStream as f, DataStreamHeader as g, Draft20BaseMessage as h, Draft20Fetch as i, Draft20FetchOk as j, Draft20FillParameters as k, Draft20GoAway as l, Draft20Namespace as m, Draft20NamespaceDone as n, Draft20Params as o, Draft20Publish as p, Draft20PublishDone as q, Draft20PublishNamespace as r, Draft20PublishSkipped as s, Draft20PublishStateNotify as t, Draft20RequestError as u, Draft20RequestOk as v, Draft20RequestUpdate as w, Draft20Setup as x, Draft20SetupOptions as y, Draft20Subscribe as z };

package/dist/{types-CdCSIfvI.d.cts → types-DG5_iKuv.d.cts}

@@ -1,4 +1,4 @@
-type Draft = '07' | '08' | '09' | '10' | '11' | '12' | '13' | '14' | '15' | '16' | '17' | '18' | '19';
+type Draft = '07' | '08' | '09' | '10' | '11' | '12' | '13' | '14' | '15' | '16' | '17' | '18' | '19' | '20';
 interface BaseCodec<M> {
     readonly draft: Draft;
     encodeMessage(message: M): Uint8Array;

package/dist/{types-CdCSIfvI.d.ts → types-DG5_iKuv.d.ts}

@@ -1,4 +1,4 @@
-type Draft = '07' | '08' | '09' | '10' | '11' | '12' | '13' | '14' | '15' | '16' | '17' | '18' | '19';
+type Draft = '07' | '08' | '09' | '10' | '11' | '12' | '13' | '14' | '15' | '16' | '17' | '18' | '19' | '20';
 interface BaseCodec<M> {
     readonly draft: Draft;
     encodeMessage(message: M): Uint8Array;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@moqtap/codec",
-  "version": "0.8.1",
+  "version": "0.9.0",
   "description": "MoQT wire-format codec and session state machine — multi-draft, zero dependencies",
   "type": "module",
   "license": "MIT",
@@ -196,19 +196,32 @@
       "types": "./dist/draft19-session.d.ts",
       "import": "./dist/draft19-session.js",
       "require": "./dist/draft19-session.cjs"
+    },
+    "./draft20": {
+      "bun": "./src/drafts/draft20/index.ts",
+      "types": "./dist/draft20.d.ts",
+      "import": "./dist/draft20.js",
+      "require": "./dist/draft20.cjs"
+    },
+    "./draft20/session": {
+      "bun": "./src/drafts/draft20/session.ts",
+      "types": "./dist/draft20-session.d.ts",
+      "import": "./dist/draft20-session.js",
+      "require": "./dist/draft20-session.cjs"
     }
   },
   "files": [
     "dist",
     "src",
-    "!src/__tests__"
+    "!src/__tests__",
+    "CHANGELOG.md"
   ],
   "scripts": {
     "build": "tsup",
     "test": "vitest run"
   },
   "devDependencies": {
-    "@moqtap/test-vectors": "^0.12.1",
+    "@moqtap/test-vectors": "^0.13.0",
     "tsup": "^8.0.0",
     "typescript": "^5.5.0",
     "vitest": "^3.0.0"

package/src/core/session-types.ts

@@ -81,6 +81,13 @@ export type ProtocolViolationCode =
 export type SideEffect =
   | { type: 'subscription-activated'; subscribeId: bigint }
   | { type: 'subscription-ended'; subscribeId: bigint; reason: string }
+  // draft-20 fill fetch streams (Section 5.1.3). A subscription can have
+  // several open at once, each keyed by the Request ID of the SUBSCRIBE or
+  // REQUEST_UPDATE that opened it; opening one does not close another.
+  | { type: 'fill-fetch-stream-opened'; subscribeId: bigint; requestId: bigint }
+  | { type: 'fill-fetch-stream-closed'; subscribeId: bigint; requestId: bigint; reason: string }
+  // draft-20 PUBLISH_STATE_NOTIFY (Section 10.10) — unilateral, no response.
+  | { type: 'subscription-state-notified'; subscribeId: bigint }
   | { type: 'announce-activated'; namespace: string[] }
   | { type: 'announce-ended'; namespace: string[] }
   | { type: 'publish-activated'; requestId: bigint }

package/src/core/types.ts

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

package/src/drafts/draft19/codec.ts

@@ -1429,7 +1429,7 @@ export function createStreamDecoder(): TransformStream<Uint8Array, Draft19Messag
 // ─── Codec Factory ─────────────────────────────────────────────────────────────
 
 export interface Draft19Codec extends BaseCodec<Draft19Message> {
-  readonly draft: '18'
+  readonly draft: '19'
   encodeSubgroupStream(stream: SubgroupStream): Uint8Array
   encodeDatagram(dg: DatagramObject): Uint8Array
   encodeFetchStream(stream: FetchStream): Uint8Array
@@ -1448,7 +1448,9 @@ export interface Draft19Codec extends BaseCodec<Draft19Message> {
 
 export function createDraft19Codec(): Draft19Codec {
   return {
-    draft: '18',
+    // Was '18' — a copy-paste from draft18/codec.ts. createSessionState() keys
+    // off codec.draft, so a draft-19 codec was handing back a draft-18 FSM.
+    draft: '19',
     encodeMessage,
     decodeMessage,
     encodeSubgroupStream,