@moqtap/codec 0.7.0 → 0.8.1

package/dist/index.js

@@ -1,21 +1,21 @@
 import {
   createDraft18Codec
-} from "./chunk-5XZKO2U5.js";
+} from "./chunk-2XH6PHXR.js";
 import {
   createDraft19Codec
-} from "./chunk-APTV6F72.js";
+} from "./chunk-3YAR3I3S.js";
 import {
   createDraft14Codec
-} from "./chunk-DORX55MO.js";
+} from "./chunk-XQGEOFGE.js";
 import {
   createDraft15Codec
-} from "./chunk-MD2OA7SE.js";
+} from "./chunk-BV6MITLO.js";
 import {
   createDraft16Codec
-} from "./chunk-HEO2JG6C.js";
+} from "./chunk-TMXRYOBS.js";
 import {
   createDraft17Codec
-} from "./chunk-I55J3KXD.js";
+} from "./chunk-NH4L6NIY.js";
 import {
   createDraft10Codec
 } from "./chunk-N2V7Z37J.js";
@@ -24,7 +24,7 @@ import {
 } from "./chunk-JKMYAUGY.js";
 import {
   createDraft12Codec
-} from "./chunk-KNLPX3YA.js";
+} from "./chunk-H6DTAIWM.js";
 import {
   createDraft13Codec
 } from "./chunk-23KRITJ6.js";
@@ -41,6 +41,54 @@ import {
   DecodeError
 } from "./chunk-KLPWJU6W.js";
 
+// src/core/accessors.ts
+function pick(msg, names) {
+  for (const name of names) {
+    const value = msg[name];
+    if (value != null) return value;
+  }
+  return void 0;
+}
+function bigintOf(value) {
+  if (value == null) return void 0;
+  if (typeof value === "bigint") return value;
+  if (typeof value === "number" || typeof value === "string") {
+    try {
+      return BigInt(value);
+    } catch {
+      return void 0;
+    }
+  }
+  return void 0;
+}
+function requestIdOf(msg) {
+  return bigintOf(pick(msg, ["request_id", "requestId", "subscribe_id", "subscribeId"]));
+}
+function trackAliasOf(msg) {
+  return bigintOf(pick(msg, ["track_alias", "trackAlias"]));
+}
+function trackOf(msg) {
+  const source = pick(msg, ["standalone"]) ?? msg;
+  const name = pick(source, ["track_name", "trackName"]);
+  if (typeof name !== "string") return void 0;
+  const namespace = pick(source, ["track_namespace", "trackNamespace"]);
+  return {
+    namespace: Array.isArray(namespace) ? namespace.map(String) : [],
+    name
+  };
+}
+function joiningRequestIdOf(msg) {
+  const source = pick(msg, ["joining"]) ?? msg;
+  return bigintOf(
+    pick(source, [
+      "joining_request_id",
+      "joiningRequestId",
+      "joining_subscribe_id",
+      "joiningSubscribeId"
+    ])
+  );
+}
+
 // src/index.ts
 var DRAFT_VERSIONS = {
   "07": 0xff000007n,
@@ -99,5 +147,9 @@ Supported draft values: ${Object.keys(DRAFT_VERSIONS).join(", ")}`
 export {
   DRAFT_VERSIONS,
   DecodeError,
-  createCodec
+  createCodec,
+  joiningRequestIdOf,
+  requestIdOf,
+  trackAliasOf,
+  trackOf
 };

package/dist/session.d.cts

@@ -8,7 +8,7 @@ import { D as Draft10Message, a as Draft10MessageType } from './types-0IWbU9Z_.c
 import { D as Draft11Message, a as Draft11MessageType } from './types-Ck45Ex5S.cjs';
 import { D as Draft12Message, a as Draft12MessageType } from './types-Bio-91Rt.cjs';
 import { D as Draft13Message, a as Draft13MessageType } from './types-CXlSn0I9.cjs';
-import { D as Draft14Message, a as Draft14MessageType } from './types-DjmrHp_s.cjs';
+import { D as Draft14Message, a as Draft14MessageType } from './types-HI_bbXka.cjs';
 import { D as Draft15Message, a as Draft15MessageType } from './types-CPaYBsMG.cjs';
 import { D as Draft16Message, a as Draft16MessageType } from './types-Cm9fjeYC.cjs';
 import { D as Draft17Message, a as Draft17MessageType } from './types-D9eiB_9A.cjs';

package/dist/session.d.ts

@@ -8,7 +8,7 @@ import { D as Draft10Message, a as Draft10MessageType } from './types-0IWbU9Z_.j
 import { D as Draft11Message, a as Draft11MessageType } from './types-Ck45Ex5S.js';
 import { D as Draft12Message, a as Draft12MessageType } from './types-Bio-91Rt.js';
 import { D as Draft13Message, a as Draft13MessageType } from './types-CXlSn0I9.js';
-import { D as Draft14Message, a as Draft14MessageType } from './types-DjmrHp_s.js';
+import { D as Draft14Message, a as Draft14MessageType } from './types-HI_bbXka.js';
 import { D as Draft15Message, a as Draft15MessageType } from './types-CPaYBsMG.js';
 import { D as Draft16Message, a as Draft16MessageType } from './types-Cm9fjeYC.js';
 import { D as Draft17Message, a as Draft17MessageType } from './types-D9eiB_9A.js';

package/dist/{types-DjmrHp_s.d.cts → types-HI_bbXka.d.cts}

@@ -63,8 +63,8 @@ interface Draft14Subscribe extends Draft14BaseMessage {
     readonly request_id: bigint;
     readonly track_namespace: string[];
     readonly track_name: string;
-    readonly subscriber_priority: bigint;
-    readonly group_order: bigint;
+    readonly subscriber_priority: number;
+    readonly group_order: number;
     readonly forward: bigint;
     readonly filter_type: bigint;
     readonly start_group?: bigint;
@@ -77,7 +77,7 @@ interface Draft14SubscribeOk extends Draft14BaseMessage {
     readonly request_id: bigint;
     readonly track_alias: bigint;
     readonly expires: bigint;
-    readonly group_order: bigint;
+    readonly group_order: number;
     readonly content_exists: bigint;
     readonly largest_location?: Location;
     readonly parameters: Draft14Params;
@@ -89,7 +89,7 @@ interface Draft14SubscribeUpdate extends Draft14BaseMessage {
     readonly start_group: bigint;
     readonly start_object: bigint;
     readonly end_group: bigint;
-    readonly subscriber_priority: bigint;
+    readonly subscriber_priority: number;
     readonly forward: bigint;
     readonly parameters: Draft14Params;
 }
@@ -109,7 +109,7 @@ interface Draft14Publish extends Draft14BaseMessage {
     readonly track_namespace: string[];
     readonly track_name: string;
     readonly track_alias: bigint;
-    readonly group_order: bigint;
+    readonly group_order: number;
     readonly content_exists: bigint;
     readonly largest_location?: Location;
     readonly forward: bigint;
@@ -119,8 +119,8 @@ interface Draft14PublishOk extends Draft14BaseMessage {
     readonly type: 'publish_ok';
     readonly request_id: bigint;
     readonly forward: bigint;
-    readonly subscriber_priority: bigint;
-    readonly group_order: bigint;
+    readonly subscriber_priority: number;
+    readonly group_order: number;
     readonly filter_type: bigint;
     readonly start_group?: bigint;
     readonly start_object?: bigint;
@@ -149,7 +149,6 @@ interface Draft14PublishNamespace extends Draft14BaseMessage {
 interface Draft14PublishNamespaceOk extends Draft14BaseMessage {
     readonly type: 'publish_namespace_ok';
     readonly request_id: bigint;
-    readonly parameters: Draft14Params;
 }
 interface Draft14PublishNamespaceError extends Draft14BaseMessage {
     readonly type: 'publish_namespace_error';
@@ -176,7 +175,6 @@ interface Draft14SubscribeNamespace extends Draft14BaseMessage {
 interface Draft14SubscribeNamespaceOk extends Draft14BaseMessage {
     readonly type: 'subscribe_namespace_ok';
     readonly request_id: bigint;
-    readonly parameters: Draft14Params;
 }
 interface Draft14SubscribeNamespaceError extends Draft14BaseMessage {
     readonly type: 'subscribe_namespace_error';
@@ -188,26 +186,34 @@ interface Draft14UnsubscribeNamespace extends Draft14BaseMessage {
     readonly type: 'unsubscribe_namespace';
     readonly track_namespace_prefix: string[];
 }
+interface StandaloneFetch {
+    readonly track_namespace: string[];
+    readonly track_name: string;
+    readonly start_group: bigint;
+    readonly start_object: bigint;
+    readonly end_group: bigint;
+    readonly end_object: bigint;
+}
+interface JoiningFetch {
+    readonly joining_request_id: bigint;
+    readonly joining_start: bigint;
+}
 interface Draft14Fetch extends Draft14BaseMessage {
     readonly type: 'fetch';
     readonly request_id: bigint;
-    readonly subscriber_priority: bigint;
-    readonly group_order: bigint;
+    readonly subscriber_priority: number;
+    readonly group_order: number;
     readonly fetch_type: bigint;
-    readonly track_namespace?: string[];
-    readonly track_name?: string;
-    readonly start_group?: bigint;
-    readonly start_object?: bigint;
-    readonly end_group?: bigint;
-    readonly end_object?: bigint;
-    readonly joining_request_id?: bigint;
-    readonly joining_start?: bigint;
+    /** Present when fetch_type = 1 */
+    readonly standalone?: StandaloneFetch;
+    /** Present when fetch_type = 2 or 3 */
+    readonly joining?: JoiningFetch;
     readonly parameters: Draft14Params;
 }
 interface Draft14FetchOk extends Draft14BaseMessage {
     readonly type: 'fetch_ok';
     readonly request_id: bigint;
-    readonly group_order: bigint;
+    readonly group_order: number;
     readonly end_of_track: bigint;
     readonly end_location: Location;
     readonly parameters: Draft14Params;
@@ -227,8 +233,8 @@ interface Draft14TrackStatus extends Draft14BaseMessage {
     readonly request_id: bigint;
     readonly track_namespace: string[];
     readonly track_name: string;
-    readonly subscriber_priority: bigint;
-    readonly group_order: bigint;
+    readonly subscriber_priority: number;
+    readonly group_order: number;
     readonly forward: bigint;
     readonly filter_type: bigint;
     readonly start_group?: bigint;
@@ -240,7 +246,7 @@ interface Draft14TrackStatusOk extends Draft14BaseMessage {
     readonly request_id: bigint;
     readonly track_alias: bigint;
     readonly expires: bigint;
-    readonly group_order: bigint;
+    readonly group_order: number;
     readonly content_exists: bigint;
     readonly largest_location?: Location;
     readonly parameters: Draft14Params;

package/dist/{types-DjmrHp_s.d.ts → types-HI_bbXka.d.ts}

@@ -63,8 +63,8 @@ interface Draft14Subscribe extends Draft14BaseMessage {
     readonly request_id: bigint;
     readonly track_namespace: string[];
     readonly track_name: string;
-    readonly subscriber_priority: bigint;
-    readonly group_order: bigint;
+    readonly subscriber_priority: number;
+    readonly group_order: number;
     readonly forward: bigint;
     readonly filter_type: bigint;
     readonly start_group?: bigint;
@@ -77,7 +77,7 @@ interface Draft14SubscribeOk extends Draft14BaseMessage {
     readonly request_id: bigint;
     readonly track_alias: bigint;
     readonly expires: bigint;
-    readonly group_order: bigint;
+    readonly group_order: number;
     readonly content_exists: bigint;
     readonly largest_location?: Location;
     readonly parameters: Draft14Params;
@@ -89,7 +89,7 @@ interface Draft14SubscribeUpdate extends Draft14BaseMessage {
     readonly start_group: bigint;
     readonly start_object: bigint;
     readonly end_group: bigint;
-    readonly subscriber_priority: bigint;
+    readonly subscriber_priority: number;
     readonly forward: bigint;
     readonly parameters: Draft14Params;
 }
@@ -109,7 +109,7 @@ interface Draft14Publish extends Draft14BaseMessage {
     readonly track_namespace: string[];
     readonly track_name: string;
     readonly track_alias: bigint;
-    readonly group_order: bigint;
+    readonly group_order: number;
     readonly content_exists: bigint;
     readonly largest_location?: Location;
     readonly forward: bigint;
@@ -119,8 +119,8 @@ interface Draft14PublishOk extends Draft14BaseMessage {
     readonly type: 'publish_ok';
     readonly request_id: bigint;
     readonly forward: bigint;
-    readonly subscriber_priority: bigint;
-    readonly group_order: bigint;
+    readonly subscriber_priority: number;
+    readonly group_order: number;
     readonly filter_type: bigint;
     readonly start_group?: bigint;
     readonly start_object?: bigint;
@@ -149,7 +149,6 @@ interface Draft14PublishNamespace extends Draft14BaseMessage {
 interface Draft14PublishNamespaceOk extends Draft14BaseMessage {
     readonly type: 'publish_namespace_ok';
     readonly request_id: bigint;
-    readonly parameters: Draft14Params;
 }
 interface Draft14PublishNamespaceError extends Draft14BaseMessage {
     readonly type: 'publish_namespace_error';
@@ -176,7 +175,6 @@ interface Draft14SubscribeNamespace extends Draft14BaseMessage {
 interface Draft14SubscribeNamespaceOk extends Draft14BaseMessage {
     readonly type: 'subscribe_namespace_ok';
     readonly request_id: bigint;
-    readonly parameters: Draft14Params;
 }
 interface Draft14SubscribeNamespaceError extends Draft14BaseMessage {
     readonly type: 'subscribe_namespace_error';
@@ -188,26 +186,34 @@ interface Draft14UnsubscribeNamespace extends Draft14BaseMessage {
     readonly type: 'unsubscribe_namespace';
     readonly track_namespace_prefix: string[];
 }
+interface StandaloneFetch {
+    readonly track_namespace: string[];
+    readonly track_name: string;
+    readonly start_group: bigint;
+    readonly start_object: bigint;
+    readonly end_group: bigint;
+    readonly end_object: bigint;
+}
+interface JoiningFetch {
+    readonly joining_request_id: bigint;
+    readonly joining_start: bigint;
+}
 interface Draft14Fetch extends Draft14BaseMessage {
     readonly type: 'fetch';
     readonly request_id: bigint;
-    readonly subscriber_priority: bigint;
-    readonly group_order: bigint;
+    readonly subscriber_priority: number;
+    readonly group_order: number;
     readonly fetch_type: bigint;
-    readonly track_namespace?: string[];
-    readonly track_name?: string;
-    readonly start_group?: bigint;
-    readonly start_object?: bigint;
-    readonly end_group?: bigint;
-    readonly end_object?: bigint;
-    readonly joining_request_id?: bigint;
-    readonly joining_start?: bigint;
+    /** Present when fetch_type = 1 */
+    readonly standalone?: StandaloneFetch;
+    /** Present when fetch_type = 2 or 3 */
+    readonly joining?: JoiningFetch;
     readonly parameters: Draft14Params;
 }
 interface Draft14FetchOk extends Draft14BaseMessage {
     readonly type: 'fetch_ok';
     readonly request_id: bigint;
-    readonly group_order: bigint;
+    readonly group_order: number;
     readonly end_of_track: bigint;
     readonly end_location: Location;
     readonly parameters: Draft14Params;
@@ -227,8 +233,8 @@ interface Draft14TrackStatus extends Draft14BaseMessage {
     readonly request_id: bigint;
     readonly track_namespace: string[];
     readonly track_name: string;
-    readonly subscriber_priority: bigint;
-    readonly group_order: bigint;
+    readonly subscriber_priority: number;
+    readonly group_order: number;
     readonly forward: bigint;
     readonly filter_type: bigint;
     readonly start_group?: bigint;
@@ -240,7 +246,7 @@ interface Draft14TrackStatusOk extends Draft14BaseMessage {
     readonly request_id: bigint;
     readonly track_alias: bigint;
     readonly expires: bigint;
-    readonly group_order: bigint;
+    readonly group_order: number;
     readonly content_exists: bigint;
     readonly largest_location?: Location;
     readonly parameters: Draft14Params;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@moqtap/codec",
-  "version": "0.7.0",
+  "version": "0.8.1",
   "description": "MoQT wire-format codec and session state machine — multi-draft, zero dependencies",
   "type": "module",
   "license": "MIT",
@@ -208,7 +208,7 @@
     "test": "vitest run"
   },
   "devDependencies": {
-    "@moqtap/test-vectors": "^0.11.0",
+    "@moqtap/test-vectors": "^0.12.1",
     "tsup": "^8.0.0",
     "typescript": "^5.5.0",
     "vitest": "^3.0.0"

package/src/core/accessors.ts

@@ -0,0 +1,120 @@
+/**
+ * Draft-agnostic readers for decoded control messages.
+ *
+ * The codec keeps one message model per draft, because the drafts genuinely
+ * disagree: a track alias travels in SUBSCRIBE through draft-11 and in
+ * SUBSCRIBE_OK from draft-12; a request was a `subscribe_id` through draft-10
+ * and a `request_id` after it; a joining FETCH points at a
+ * `joining_subscribe_id` through draft-13 and a `joining_request_id` after it.
+ * Faithfulness to each draft is the point of the codec.
+ *
+ * What consumers usually want is the answer, not the archaeology — and every
+ * one of them that has asked has written the same field-spelling ladder by
+ * hand. These accessors are that ladder, written once.
+ *
+ * Each returns `undefined` when the message does not carry the field, which
+ * includes the cases where the draft has not assigned it yet: `trackAliasOf`
+ * on a draft-14 SUBSCRIBE is `undefined` because the publisher has not chosen
+ * the alias until SUBSCRIBE_OK.
+ *
+ * Both snake_case (what this codec emits) and camelCase spellings are read, so
+ * these also work on messages recovered from qlog-style traces written by
+ * other tools.
+ */
+
+/** Any decoded control message, from any draft. */
+export type AnyMessage = Readonly<Record<string, unknown>>
+
+/** A track's full identity: the namespace tuple plus the name within it. */
+export interface TrackIdentity {
+  readonly namespace: string[]
+  readonly name: string
+}
+
+/** First defined value among several spellings of one field. */
+function pick(msg: AnyMessage, names: readonly string[]): unknown {
+  for (const name of names) {
+    const value = msg[name]
+    if (value != null) return value
+  }
+  return undefined
+}
+
+function bigintOf(value: unknown): bigint | undefined {
+  if (value == null) return undefined
+  if (typeof value === 'bigint') return value
+  if (typeof value === 'number' || typeof value === 'string') {
+    try {
+      return BigInt(value)
+    } catch {
+      return undefined
+    }
+  }
+  return undefined
+}
+
+/**
+ * The request this message belongs to.
+ *
+ * Named `subscribe_id` through draft-10 and `request_id` from draft-11, when
+ * the id space widened to cover every request type rather than subscriptions
+ * alone.
+ *
+ * Returns `undefined` for draft-17+ responses, which carry no id at all: each
+ * request there has its own bidirectional stream, and that stream — not a
+ * field — is what ties a response to its request.
+ */
+export function requestIdOf(msg: AnyMessage): bigint | undefined {
+  return bigintOf(pick(msg, ['request_id', 'requestId', 'subscribe_id', 'subscribeId']))
+}
+
+/**
+ * The track alias this message assigns or refers to, if any.
+ *
+ * Which message carries it moved: SUBSCRIBE through draft-11, then SUBSCRIBE_OK
+ * from draft-12, when assigning the alias became the publisher's job. PUBLISH
+ * carries it alongside the track name in every draft that has PUBLISH.
+ */
+export function trackAliasOf(msg: AnyMessage): bigint | undefined {
+  return bigintOf(pick(msg, ['track_alias', 'trackAlias']))
+}
+
+/**
+ * The track this message names, or `undefined` if it names none.
+ *
+ * Covers SUBSCRIBE, PUBLISH, TRACK_STATUS and a standalone FETCH — whose track
+ * sits under `standalone` in most drafts and flat in draft-07, which predates
+ * joining fetch. A joining FETCH names no track of its own; use
+ * {@link joiningRequestIdOf} to find the request whose track it continues.
+ *
+ * PUBLISH_NAMESPACE and its relatives are namespace-only and yield
+ * `undefined`: a namespace is not a track.
+ */
+export function trackOf(msg: AnyMessage): TrackIdentity | undefined {
+  const source = (pick(msg, ['standalone']) ?? msg) as AnyMessage
+  const name = pick(source, ['track_name', 'trackName'])
+  if (typeof name !== 'string') return undefined
+  const namespace = pick(source, ['track_namespace', 'trackNamespace'])
+  return {
+    namespace: Array.isArray(namespace) ? namespace.map(String) : [],
+    name,
+  }
+}
+
+/**
+ * For a joining FETCH, the request whose track it continues.
+ *
+ * Spelled `joining_subscribe_id` through draft-13 and `joining_request_id`
+ * after it, nested under `joining` in every draft that has one.
+ */
+export function joiningRequestIdOf(msg: AnyMessage): bigint | undefined {
+  const source = (pick(msg, ['joining']) ?? msg) as AnyMessage
+  return bigintOf(
+    pick(source, [
+      'joining_request_id',
+      'joiningRequestId',
+      'joining_subscribe_id',
+      'joiningSubscribeId',
+    ]),
+  )
+}

package/src/drafts/draft12/data-streams.ts

@@ -56,7 +56,7 @@ export function encodeDatagram(dg: DatagramObject): Uint8Array {
     w.writeVarInt(extData.byteLength)
     if (extData.byteLength > 0) w.writeBytes(extData)
   }
-  const isStatus = dg.streamTypeId === 0x02 || dg.streamTypeId === 0x03
+  const isStatus = dg.streamTypeId >= 0x04
   if (isStatus) {
     w.writeVarInt(dg.objectStatus ?? 0n)
   } else {
@@ -182,18 +182,26 @@ export function decodeDatagram(bytes: Uint8Array): DecodeResult<DatagramObject>
   try {
     const r = new BufferReader(bytes)
     const streamTypeId = Number(r.readVarInt())
-    if (streamTypeId < 0x00 || streamTypeId > 0x03) {
+    if (streamTypeId < 0x00 || streamTypeId > 0x05) {
       return {
         ok: false,
         error: new DecodeError(
           'CONSTRAINT_VIOLATION',
-          `Expected datagram type 0x00-0x03, got 0x${streamTypeId.toString(16)}`,
+          `Expected datagram type 0x00-0x05, got 0x${streamTypeId.toString(16)}`,
           0,
         ),
       }
     }
     const extensionsPresent = (streamTypeId & 0x01) !== 0
-    const isStatus = streamTypeId === 0x02 || streamTypeId === 0x03
+    // Draft-12 states its datagram types twice and the two disagree. Table 12
+    // gives OBJECT_DATAGRAM four values and puts the End of Group marker on
+    // 0x02/0x03; the OBJECT_DATAGRAM_STATUS paragraph still says "0x02 to
+    // 0x03", which is the sentence draft-11 wrote before an End of Group
+    // marker existed. Both cannot hold, and the table is the half that
+    // changed. Draft-13 repeats the contradiction verbatim and draft-14
+    // resolves it the same way: payload below 0x04, status at and above it.
+    const endOfGroup = (streamTypeId & 0x02) !== 0 && streamTypeId < 0x04
+    const isStatus = streamTypeId >= 0x04
     const trackAlias = r.readVarInt()
     const groupId = r.readVarInt()
     const objectId = r.readVarInt()
@@ -225,6 +233,7 @@ export function decodeDatagram(bytes: Uint8Array): DecodeResult<DatagramObject>
       payloadLength: payload.byteLength,
       payload,
     }
+    if (endOfGroup) (result as unknown as Record<string, unknown>).endOfGroup = true
     if (extensionHeadersLength !== undefined)
       (result as unknown as Record<string, unknown>).extensionHeadersLength = extensionHeadersLength
     if (extensionData !== undefined)