@moqtap/codec 0.8.0 → 0.9.0

package/CHANGELOG.md

@@ -0,0 +1,49 @@
+# Changelog
+
+All notable changes to `@moqtap/codec` will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+This file starts at 0.9.0. Earlier releases are in the git history.
+
+## [0.9.0] - 2026-09-03
+
+Draft-20 support, and a fix to draft-19 that changes which state machine a
+draft-19 session runs.
+
+### Added
+
+- **Draft-20**: codec, message and data-stream tables, wire rules, error codes
+  and session FSM, exported as `@moqtap/codec/draft20` and
+  `@moqtap/codec/draft20/session`. `createCodec({ draft: '20' })` and
+  `createDraft20Codec()` both reach it.
+- `PUBLISH_STATE_NOTIFY` (`0x22`), the one control message draft-20 adds. It is
+  unilateral and not subject to `MAX_REQUEST_UPDATES`.
+- Draft-20's rewritten `FETCH`. The message keeps codepoint `0x16` but drops the
+  Fetch Type discriminator, carries Track Namespace and Track Name inline, and
+  moves its range into a `LOCATION_FILTER` parameter. Nothing on the wire
+  distinguishes it from a draft-19 `FETCH` at the type byte, so a session
+  decoded under the wrong draft will silently misparse it — pick the draft from
+  the negotiated `moqt-NN` protocol string, not from message content.
+- `INCLUDE_PROPERTIES` (`0x35`), a uint8 boolean defaulting to `1`.
+
+### Fixed
+
+- **`createDraft19Codec()` reported `draft: '18'`.** Since `createSessionState()`
+  keys off `codec.draft`, every draft-19 session was validated by the draft-18
+  FSM. Draft-19 sessions now run the draft-19 FSM, which enforces rules the
+  draft-18 one does not — a session that passed validation on 0.8.1 may now be
+  rejected, correctly.
+
+### Changed
+
+- Draft-20 ranges are **inclusive**. An end location names the last object, not
+  one past it; do not carry a draft-19 `+ 1` forward.
+- Retired error codes decode rather than being refused. Draft-20 Section 14
+  requires an unknown error code in any error context to be treated as
+  `INTERNAL_ERROR`, and forbids closing the session over one in `REQUEST_ERROR`
+  or `PUBLISH_DONE`. The `RETIRED_*` sets remain exported as advisory
+  diagnostics — useful for "this peer looks like draft-19" — but are no longer
+  decode gates.
+- `@moqtap/test-vectors` dependency raised to `^0.13.0` for the draft-20 corpus.

package/README.md

@@ -2,7 +2,7 @@
 
 MoQT (Media over QUIC Transport) wire-format codec and session state machine for JavaScript/TypeScript.
 
-- Multi-draft support (drafts 07 through 19)
+- Multi-draft support (drafts 07 through 20)
 - Stateless encode/decode of all MoQT control messages and data streams
 - Protocol session state machine with FSM-based validation per draft
 - Zero runtime dependencies
@@ -43,10 +43,11 @@ Or use the factory if your application supports multiple drafts:
 ```typescript
 import { createCodec, DRAFT_VERSIONS } from '@moqtap/codec'
 
-const codec = createCodec({ draft: '19' }) // '07' through '19'
+const codec = createCodec({ draft: '20' }) // '07' through '20'
 
-// DRAFT_VERSIONS provides wire version numbers under short aliases:
-//   DRAFT_VERSIONS['07'] — 0xff000007n
+// DRAFT_VERSIONS provides version identifiers under short aliases:
+//   DRAFT_VERSIONS['07'] — 0xff000007n, a real draft-07 wire value
+//   DRAFT_VERSIONS['20'] — 0xff000014n, derived; see the note below
 ```
 
 ## Subpath Exports
@@ -69,10 +70,21 @@ Each draft is available as a subpath import with its own codec and session state
 | `@moqtap/codec/draft17`          | Draft-17 codec                                    |
 | `@moqtap/codec/draft18`          | Draft-18 codec                                    |
 | `@moqtap/codec/draft19`          | Draft-19 codec                                    |
+| `@moqtap/codec/draft20`          | Draft-20 codec                                    |
 | `@moqtap/codec/draft{N}/session` | Session state machine for draft N                 |
 
 > **Note:** A default (versionless) codec will be available once the MoQT specification reaches RFC status. Until then, always specify a draft version.
 
+`DRAFT_VERSIONS` is a table of numeric keys, and only the entries up to `'14'` are values a peer
+ever puts on the wire. From draft-15 the version is negotiated by ALPN (raw QUIC) or
+`WT-Available-Protocols` (WebTransport) as the string `moqt-NN`, and no version number is sent at
+all — so `DRAFT_VERSIONS['20']` is a derived identifier, not something observed. Each draft module
+from 15 on exports the real one:
+
+```typescript
+import { PROTOCOL_STRING } from '@moqtap/codec/draft20' // 'moqt-20'
+```
+
 ## Draft-Specific Imports
 
 For applications targeting a single draft version:

package/dist/{chunk-5XZKO2U5.js → chunk-2XH6PHXR.js}

@@ -1103,6 +1103,33 @@ var PARAM_SUBSCRIPTION_FILTER = 0x21n;
 var PARAM_GROUP_ORDER = 0x22n;
 var PARAM_NEW_GROUP_REQUEST = 0x32n;
 var PARAM_TRACK_NAMESPACE_PREFIX = 0x34n;
+var PARAMETER_SCOPE = /* @__PURE__ */ new Map([
+  [0x02n, /* @__PURE__ */ new Set(["request_ok", "subscribe", "request_update"])],
+  [
+    0x03n,
+    /* @__PURE__ */ new Set([
+      "publish",
+      "subscribe",
+      "request_update",
+      "subscribe_namespace",
+      "subscribe_tracks",
+      "publish_namespace",
+      "track_status",
+      "fetch"
+    ])
+  ],
+  [0x04n, /* @__PURE__ */ new Set(["subscribe"])],
+  [0x06n, /* @__PURE__ */ new Set(["request_ok", "subscribe", "request_update"])],
+  [0x08n, /* @__PURE__ */ new Set(["subscribe_ok", "publish", "request_ok"])],
+  [0x09n, /* @__PURE__ */ new Set(["subscribe_ok", "publish", "request_ok"])],
+  [0x0an, /* @__PURE__ */ new Set(["fetch"])],
+  [0x10n, /* @__PURE__ */ new Set(["subscribe", "request_update", "publish", "request_ok", "subscribe_tracks"])],
+  [0x20n, /* @__PURE__ */ new Set(["subscribe", "fetch", "request_update", "request_ok"])],
+  [0x21n, /* @__PURE__ */ new Set(["subscribe", "request_ok", "request_update"])],
+  [0x22n, /* @__PURE__ */ new Set(["subscribe", "request_ok", "fetch"])],
+  [0x32n, /* @__PURE__ */ new Set(["request_ok", "subscribe", "request_update"])],
+  [0x34n, /* @__PURE__ */ new Set(["request_update"])]
+]);
 function encodeParams(params, writer) {
   const entries = [];
   if (params.object_delivery_timeout !== void 0) {
@@ -1144,13 +1171,12 @@ function encodeParams(params, writer) {
   if (params.largest_object !== void 0) {
     entries.push({
       type: PARAM_LARGEST_OBJECT,
+      // A Location is "Two consecutive varints (Group, Object)", which is a
+      // different value encoding from "Length-prefixed". Nothing states the
+      // length, so nothing writes one.
       encode: (w) => {
-        const tmpW = new MoqtBufferWriter(16);
-        tmpW.writeVarInt(params.largest_object.group);
-        tmpW.writeVarInt(params.largest_object.object);
-        const raw = tmpW.finish();
-        w.writeVarInt(BigInt(raw.byteLength));
-        w.writeBytes(raw);
+        w.writeVarInt(params.largest_object.group);
+        w.writeVarInt(params.largest_object.object);
       }
     });
   }
@@ -1207,12 +1233,11 @@ function encodeParams(params, writer) {
   if (params.track_namespace_prefix !== void 0) {
     entries.push({
       type: PARAM_TRACK_NAMESPACE_PREFIX,
+      // The parameter "uses the Track Namespace encoding", which is a tuple
+      // that states its own field count. That is not the Length-prefixed
+      // encoding, so there is no byte length ahead of it.
       encode: (w) => {
-        const tmpW = new MoqtBufferWriter(32);
-        encodeNamespaceTuple(params.track_namespace_prefix, tmpW);
-        const raw = tmpW.finish();
-        w.writeVarInt(BigInt(raw.byteLength));
-        w.writeBytes(raw);
+        encodeNamespaceTuple(params.track_namespace_prefix, w);
       }
     });
   }
@@ -1237,15 +1262,22 @@ function encodeParams(params, writer) {
     prevType = entry.type;
   }
 }
-function decodeParams(reader) {
+function decodeParams(reader, messageType) {
   const count = Number(reader.readVarInt());
   const result = {};
-  const unknown = [];
   let prevType = 0n;
   for (let i = 0; i < count; i++) {
     const delta = reader.readVarInt();
     const paramType = prevType + delta;
     prevType = paramType;
+    const scope = PARAMETER_SCOPE.get(paramType);
+    if (scope !== void 0 && !scope.has(messageType)) {
+      throw new DecodeError(
+        "CONSTRAINT_VIOLATION",
+        `Message Parameter 0x${paramType.toString(16)} may not appear in ${messageType}`,
+        reader.offset
+      );
+    }
     if (paramType === PARAM_OBJECT_DELIVERY_TIMEOUT) {
       result.object_delivery_timeout = reader.readVarInt();
     } else if (paramType === PARAM_AUTHORIZATION_TOKEN) {
@@ -1259,12 +1291,8 @@ function decodeParams(reader) {
     } else if (paramType === PARAM_EXPIRES) {
       result.expires = reader.readVarInt();
     } else if (paramType === PARAM_LARGEST_OBJECT) {
-      const length = Number(reader.readVarInt());
-      const startOff = reader.offset;
       const group = reader.readVarInt();
       const object = reader.readVarInt();
-      const consumed = reader.offset - startOff;
-      if (consumed < length) reader.readBytes(length - consumed);
       result.largest_object = { group, object };
     } else if (paramType === PARAM_FILL_TIMEOUT) {
       result.fill_timeout = reader.readVarInt();
@@ -1292,32 +1320,15 @@ function decodeParams(reader) {
     } else if (paramType === PARAM_NEW_GROUP_REQUEST) {
       result.new_group_request = reader.readVarInt();
     } else if (paramType === PARAM_TRACK_NAMESPACE_PREFIX) {
-      const length = Number(reader.readVarInt());
-      const bytes = reader.readBytes(length);
-      result.track_namespace_prefix = decodeNamespaceTuple(new MoqtBufferReader(bytes));
+      result.track_namespace_prefix = decodeNamespaceTuple(reader);
     } else {
-      if (paramType % 2n === 0n) {
-        const value = reader.readVarInt();
-        const tmpWriter = new MoqtBufferWriter(16);
-        tmpWriter.writeVarInt(value);
-        const raw = tmpWriter.finish();
-        unknown.push({
-          id: `0x${paramType.toString(16)}`,
-          length: raw.byteLength,
-          raw_hex: bytesToHex(raw)
-        });
-      } else {
-        const length = Number(reader.readVarInt());
-        const bytes = reader.readBytes(length);
-        unknown.push({
-          id: `0x${paramType.toString(16)}`,
-          length,
-          raw_hex: bytesToHex(bytes)
-        });
-      }
+      throw new DecodeError(
+        "INVALID_PARAMETER",
+        `Unknown Message Parameter type 0x${paramType.toString(16)}`,
+        reader.offset
+      );
     }
   }
-  if (unknown.length > 0) result.unknown = unknown;
   return result;
 }
 var TPROP_OBJECT_DELIVERY_TIMEOUT = 0x02n;
@@ -1579,7 +1590,7 @@ function decodeSubscribePayload(r) {
   const request_id = r.readVarInt();
   const track_namespace = r.readTuple();
   const track_name = r.readString();
-  const parameters = decodeParams(r);
+  const parameters = decodeParams(r, "subscribe");
   return {
     type: "subscribe",
     request_id,
@@ -1590,13 +1601,13 @@ function decodeSubscribePayload(r) {
 }
 function decodeSubscribeOkPayload(r, payloadEnd) {
   const track_alias = r.readVarInt();
-  const parameters = decodeParams(r);
+  const parameters = decodeParams(r, "subscribe_ok");
   const track_properties = decodeTrackProperties(r, payloadEnd);
   return { type: "subscribe_ok", track_alias, parameters, track_properties };
 }
 function decodeRequestUpdatePayload(r) {
   const request_id = r.readVarInt();
-  const parameters = decodeParams(r);
+  const parameters = decodeParams(r, "request_update");
   return {
     type: "request_update",
     request_id,
@@ -1608,7 +1619,7 @@ function decodePublishPayload(r, payloadEnd) {
   const track_namespace = r.readTuple();
   const track_name = r.readString();
   const track_alias = r.readVarInt();
-  const parameters = decodeParams(r);
+  const parameters = decodeParams(r, "publish");
   const track_properties = decodeTrackProperties(r, payloadEnd);
   return {
     type: "publish",
@@ -1629,7 +1640,7 @@ function decodePublishDonePayload(r) {
 function decodePublishNamespacePayload(r) {
   const request_id = r.readVarInt();
   const track_namespace = r.readTuple();
-  const parameters = decodeParams(r);
+  const parameters = decodeParams(r, "publish_namespace");
   return {
     type: "publish_namespace",
     request_id,
@@ -1648,7 +1659,7 @@ function decodeNamespaceDonePayload(r) {
 function decodeSubscribeNamespacePayload(r) {
   const request_id = r.readVarInt();
   const namespace_prefix = r.readTuple();
-  const parameters = decodeParams(r);
+  const parameters = decodeParams(r, "subscribe_namespace");
   return {
     type: "subscribe_namespace",
     request_id,
@@ -1659,7 +1670,7 @@ function decodeSubscribeNamespacePayload(r) {
 function decodeSubscribeTracksPayload(r) {
   const request_id = r.readVarInt();
   const namespace_prefix = r.readTuple();
-  const parameters = decodeParams(r);
+  const parameters = decodeParams(r, "subscribe_tracks");
   return {
     type: "subscribe_tracks",
     request_id,
@@ -1701,7 +1712,7 @@ function decodeFetchPayload(r) {
     const joining_start = r.readVarInt();
     joining = { joining_request_id, joining_start };
   }
-  const parameters = decodeParams(r);
+  const parameters = decodeParams(r, "fetch");
   return {
     type: "fetch",
     request_id,
@@ -1715,7 +1726,7 @@ function decodeFetchOkPayload(r, payloadEnd) {
   const end_of_track = r.readUint8();
   const end_group = r.readVarInt();
   const end_object = r.readVarInt();
-  const parameters = decodeParams(r);
+  const parameters = decodeParams(r, "fetch_ok");
   const track_properties = decodeTrackProperties(r, payloadEnd);
   return {
     type: "fetch_ok",
@@ -1730,7 +1741,7 @@ function decodeTrackStatusPayload(r) {
   const request_id = r.readVarInt();
   const track_namespace = r.readTuple();
   const track_name = r.readString();
-  const parameters = decodeParams(r);
+  const parameters = decodeParams(r, "track_status");
   return {
     type: "track_status",
     request_id,
@@ -1740,7 +1751,7 @@ function decodeTrackStatusPayload(r) {
   };
 }
 function decodeRequestOkPayload(r, payloadEnd) {
-  const parameters = decodeParams(r);
+  const parameters = decodeParams(r, "request_ok");
   const track_properties = decodeTrackProperties(r, payloadEnd);
   return { type: "request_ok", parameters, track_properties };
 }

package/dist/{chunk-BQHLUT37.cjs → chunk-7ENEWAMZ.cjs}

@@ -1121,7 +1121,6 @@ function encodePublishNamespacePayload(msg, w) {
 }
 function encodePublishNamespaceOkPayload(msg, w) {
   w.writeVarInt(msg.request_id);
-  encodeMessageParams(msg.parameters, w);
 }
 function encodePublishNamespaceErrorPayload(msg, w) {
   w.writeVarInt(msg.request_id);
@@ -1143,7 +1142,6 @@ function encodeSubscribeNamespacePayload(msg, w) {
 }
 function encodeSubscribeNamespaceOkPayload(msg, w) {
   w.writeVarInt(msg.request_id);
-  encodeMessageParams(msg.parameters, w);
 }
 function encodeSubscribeNamespaceErrorPayload(msg, w) {
   w.writeVarInt(msg.request_id);
@@ -1431,8 +1429,7 @@ function decodePublishNamespacePayload(r) {
 }
 function decodePublishNamespaceOkPayload(r) {
   const request_id = r.readVarInt();
-  const parameters = decodeMessageParams(r);
-  return { type: "publish_namespace_ok", request_id, parameters };
+  return { type: "publish_namespace_ok", request_id };
 }
 function decodePublishNamespaceErrorPayload(r) {
   const request_id = r.readVarInt();
@@ -1473,8 +1470,7 @@ function decodeSubscribeNamespacePayload(r) {
 }
 function decodeSubscribeNamespaceOkPayload(r) {
   const request_id = r.readVarInt();
-  const parameters = decodeMessageParams(r);
-  return { type: "subscribe_namespace_ok", request_id, parameters };
+  return { type: "subscribe_namespace_ok", request_id };
 }
 function decodeSubscribeNamespaceErrorPayload(r) {
   const request_id = r.readVarInt();