@moqtap/codec 0.11.0 → 0.12.0

package/src/drafts/draft21/session.ts

@@ -0,0 +1,21 @@
+import { Draft21SessionFSM } from './session-fsm.js'
+
+export type {
+  ProtocolViolation,
+  SessionPhase,
+  SideEffect,
+  TransitionResult,
+  ValidationResult,
+} from '../../core/session-types.js'
+export type {
+  FillFetchStreamPhase,
+  FillFetchStreamState,
+  PublisherSide,
+  RequestKind,
+} from './session-fsm.js'
+
+export function createDraft21SessionState(role: 'client' | 'server'): Draft21SessionFSM {
+  return new Draft21SessionFSM(role)
+}
+
+export { Draft21SessionFSM }

package/src/drafts/draft21/types.ts

@@ -0,0 +1,473 @@
+// Draft-21 specific message types
+
+// Unknown parameter for passthrough
+export interface UnknownParam {
+  readonly id: string // e.g. "0x21"
+  readonly length: number
+  readonly raw_hex: string
+}
+
+// Authorization token parameter (nested structure within length-prefixed param)
+export interface AuthorizationToken {
+  readonly alias_type: bigint // 0=DELETE, 1=REGISTER, 2=USE_ALIAS, 3=USE_VALUE
+  readonly token_alias?: bigint // present for DELETE(0), REGISTER(1), USE_ALIAS(2)
+  readonly token_type?: bigint // present for REGISTER(1), USE_VALUE(3)
+  readonly token_value?: Uint8Array // present for REGISTER(1), USE_VALUE(3)
+}
+
+// Setup options (KVP encoding, no count prefix) — unchanged from draft-19
+export interface Draft21SetupOptions {
+  path?: string // 0x01 odd
+  authorization_token?: readonly AuthorizationToken[] // 0x03 odd
+  max_auth_token_cache_size?: bigint // 0x04 even
+  authority?: string // 0x05 odd
+  max_filter_ranges?: bigint // 0x06 even
+  moqt_implementation?: string // 0x07 odd
+  max_request_updates?: bigint // 0x08 even
+  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.
+ */
+export interface LocationFilter {
+  readonly start_group?: bigint
+  readonly start_object?: bigint
+  readonly end_group_delta?: bigint
+  readonly end_object?: bigint
+  readonly removed?: boolean // Length == 0: no filter / remove the filter
+}
+
+// Range Filter parameter (0x25-0x29). Selects Objects/Tracks by integer
+// ranges over Object header fields or Property values.
+export interface RangeFilterRange {
+  readonly start: bigint
+  readonly end?: bigint // omitted on the final Range = open-ended (no upper bound)
+}
+
+export interface RangeFilter {
+  readonly set_id?: bigint
+  readonly property_type?: bigint // only for OBJECT_PROPERTY_FILTER / TRACK_PROPERTY_FILTER
+  readonly ranges?: RangeFilterRange[]
+  readonly removed?: boolean // REQUEST_UPDATE length-0 form: remove this filter
+}
+
+// Largest object location parameter
+export 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.
+ */
+export interface Draft21FillParameters {
+  fill_timeout?: bigint // 0x0a varint
+  subscriber_priority?: bigint // 0x20 uint8
+  location_filter?: LocationFilter // 0x21 length-prefixed — selects the FILL range
+  group_order?: bigint // 0x22 uint8
+  // Section 3.3.2 permits each of the five more than once in a message: a
+  // filter parameter carries one SetID, so two alternatives over the same
+  // field need two parameters. A single filter is a one-element list.
+  subgroup_filter?: readonly RangeFilter[] // 0x25 length-prefixed
+  objectid_filter?: readonly RangeFilter[] // 0x26 length-prefixed
+  priority_filter?: readonly RangeFilter[] // 0x27 length-prefixed
+  object_property_filter?: readonly RangeFilter[] // 0x28 length-prefixed
+}
+
+// Message Parameters (delta-encoded types, count-prefixed)
+export interface Draft21Params {
+  object_delivery_timeout?: bigint // 0x02 varint
+  authorization_token?: readonly AuthorizationToken[] // 0x03 length-prefixed nested
+  rendezvous_timeout?: bigint // 0x04 varint
+  subgroup_delivery_timeout?: bigint // 0x06 varint
+  expires?: bigint // 0x08 varint
+  largest_object?: LargestObject // 0x09 Location (2 bare varints, NOT length-prefixed)
+  fill_timeout?: bigint // 0x0a varint
+  forward?: bigint // 0x10 uint8
+  subscriber_priority?: bigint // 0x20 uint8
+  location_filter?: LocationFilter // 0x21 length-prefixed; see LocationFilter for the draft-21 shape
+  group_order?: bigint // 0x22 uint8
+  fill_parameters?: Draft21FillParameters // 0x23 length-prefixed nested (NEW in draft-20)
+  // Section 3.3.2 permits each of the five more than once in a message: a
+  // filter parameter carries one SetID, so two alternatives over the same
+  // field need two parameters. A single filter is a one-element list.
+  subgroup_filter?: readonly RangeFilter[] // 0x25 length-prefixed
+  objectid_filter?: readonly RangeFilter[] // 0x26 length-prefixed
+  priority_filter?: readonly RangeFilter[] // 0x27 length-prefixed
+  object_property_filter?: readonly RangeFilter[] // 0x28 length-prefixed
+  track_property_filter?: readonly RangeFilter[] // 0x29 length-prefixed
+  new_group_request?: bigint // 0x32 varint
+  track_namespace_prefix?: string[] // 0x34 Track Namespace encoding
+  include_properties?: bigint // 0x35 uint8, 0 or 1, default 1 (NEW in draft-20)
+  unknown?: UnknownParam[]
+}
+
+// Track properties (KVP encoding, no count prefix, read until end of payload)
+export interface Draft21TrackProperties {
+  object_delivery_timeout?: bigint // 0x02 even varint
+  max_cache_duration?: bigint // 0x04 even varint
+  subgroup_delivery_timeout?: bigint // 0x06 even varint
+  immutable_properties?: Uint8Array // 0x0b odd length-prefixed
+  default_publisher_priority?: bigint // 0x0e even varint
+  default_publisher_group_order?: bigint // 0x22 even varint
+  dynamic_groups?: bigint // 0x30 even varint
+  unknown?: UnknownParam[]
+}
+
+// Draft-21 message type tag union
+export 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'
+
+// Base
+export interface Draft21BaseMessage {
+  readonly type: Draft21MessageType
+}
+
+// Setup — single unified message (0x2F00)
+export interface Draft21Setup extends Draft21BaseMessage {
+  readonly type: 'setup'
+  readonly options: Draft21SetupOptions
+}
+
+export interface Draft21Subscribe extends Draft21BaseMessage {
+  readonly type: 'subscribe'
+  readonly request_id: bigint
+  readonly track_namespace: string[]
+  readonly track_name: string
+  readonly parameters: Draft21Params
+}
+
+export interface Draft21SubscribeOk extends Draft21BaseMessage {
+  readonly type: 'subscribe_ok'
+  readonly track_alias: bigint
+  readonly parameters: Draft21Params
+  readonly track_properties: Draft21TrackProperties
+}
+
+export 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.
+ */
+export interface Draft21PublishStateNotify extends Draft21BaseMessage {
+  readonly type: 'publish_state_notify'
+  readonly parameters: Draft21Params
+}
+
+export 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
+}
+
+export 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
+}
+
+export interface Draft21PublishNamespace extends Draft21BaseMessage {
+  readonly type: 'publish_namespace'
+  readonly request_id: bigint
+  readonly track_namespace: string[]
+  readonly parameters: Draft21Params
+}
+
+export interface Draft21Namespace extends Draft21BaseMessage {
+  readonly type: 'namespace'
+  readonly namespace_suffix: string[]
+}
+
+export interface Draft21NamespaceDone extends Draft21BaseMessage {
+  readonly type: 'namespace_done'
+  readonly namespace_suffix: string[]
+}
+
+export interface Draft21SubscribeNamespace extends Draft21BaseMessage {
+  readonly type: 'subscribe_namespace'
+  readonly request_id: bigint
+  readonly namespace_prefix: string[]
+  readonly parameters: Draft21Params
+}
+
+export interface Draft21SubscribeTracks extends Draft21BaseMessage {
+  readonly type: 'subscribe_tracks'
+  readonly request_id: bigint
+  readonly namespace_prefix: string[]
+  readonly parameters: Draft21Params
+}
+
+export 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.
+ */
+export 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.
+ */
+export interface Draft21FetchOk extends Draft21BaseMessage {
+  readonly type: 'fetch_ok'
+  readonly end_of_track: number // uint8
+  readonly end_group: bigint
+  readonly end_object: bigint
+  readonly parameters: Draft21Params
+  readonly track_properties: Draft21TrackProperties
+}
+
+// Track Status — same format as SUBSCRIBE with the type set to 0xD
+export interface Draft21TrackStatus extends Draft21BaseMessage {
+  readonly type: 'track_status'
+  readonly request_id: bigint
+  readonly track_namespace: string[]
+  readonly track_name: string
+  readonly parameters: Draft21Params
+}
+
+// REQUEST_OK — also the PUBLISH_OK / REQUEST_UPDATE_OK / TRACK_STATUS_OK alias
+export 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.
+ */
+export interface Redirect {
+  readonly connect_uri: string
+  readonly track_namespace: string[]
+  readonly track_name: string
+}
+
+export interface Draft21RequestError extends Draft21BaseMessage {
+  readonly type: 'request_error'
+  readonly error_code: bigint
+  readonly retry_interval: bigint
+  readonly reason_phrase: string
+  readonly redirect?: Redirect
+}
+
+export interface Draft21GoAway extends Draft21BaseMessage {
+  readonly type: 'goaway'
+  readonly new_session_uri: string
+  readonly timeout: bigint
+}
+
+// Union of all draft-21 control messages
+export type Draft21Message =
+  | Draft21Setup
+  | Draft21Subscribe
+  | Draft21SubscribeOk
+  | Draft21RequestUpdate
+  | Draft21PublishStateNotify
+  | Draft21Publish
+  | Draft21PublishDone
+  | Draft21PublishNamespace
+  | Draft21Namespace
+  | Draft21NamespaceDone
+  | Draft21SubscribeNamespace
+  | Draft21SubscribeTracks
+  | Draft21PublishSkipped
+  | Draft21Fetch
+  | Draft21FetchOk
+  | Draft21TrackStatus
+  | Draft21RequestOk
+  | Draft21RequestError
+  | Draft21GoAway
+
+// ─── Data stream types ──────────────────────────────────────────────────────
+
+export 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
+}
+
+export 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[]
+}
+
+export 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
+}
+
+export 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>
+}
+
+export 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[]
+}
+
+export type Draft21DataStream = SubgroupStream | DatagramObject | FetchStream
+
+// Streaming data stream decoder types
+export 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
+}
+
+export interface FetchStreamHeader {
+  readonly type: 'fetch_header'
+  readonly requestId: bigint
+}
+
+export type DataStreamHeader = SubgroupStreamHeader | FetchStreamHeader
+export type DataStreamEvent = DataStreamHeader | ObjectPayload

package/src/index.ts

@@ -40,6 +40,8 @@ import type { Draft19Codec } from './drafts/draft19/codec.js'
 import { createDraft19Codec } from './drafts/draft19/codec.js'
 import type { Draft20Codec } from './drafts/draft20/codec.js'
 import { createDraft20Codec } from './drafts/draft20/codec.js'
+import type { Draft21Codec } from './drafts/draft21/codec.js'
+import { createDraft21Codec } from './drafts/draft21/codec.js'
 
 /**
  * Version identifiers for each MoQT draft, keyed by short aliases.
@@ -69,6 +71,7 @@ export const DRAFT_VERSIONS: Record<string, bigint> = {
   '18': 0xff000012n,
   '19': 0xff000013n,
   '20': 0xff000014n,
+  '21': 0xff000015n,
 }
 
 export function createCodec(options: CodecOptions & { draft: '07' }): Draft07Codec
@@ -85,6 +88,7 @@ export function createCodec(options: CodecOptions & { draft: '17' }): Draft17Cod
 export function createCodec(options: CodecOptions & { draft: '18' }): Draft18Codec
 export function createCodec(options: CodecOptions & { draft: '19' }): Draft19Codec
 export function createCodec(options: CodecOptions & { draft: '20' }): Draft20Codec
+export function createCodec(options: CodecOptions & { draft: '21' }): Draft21Codec
 
 /**
  * Create a codec for the specified draft version.
@@ -109,6 +113,7 @@ export function createCodec(
   | Draft18Codec
   | Draft19Codec
   | Draft20Codec
+  | Draft21Codec
 export function createCodec(
   options: CodecOptions,
 ):
@@ -125,7 +130,8 @@ export function createCodec(
   | Draft17Codec
   | Draft18Codec
   | Draft19Codec
-  | Draft20Codec {
+  | Draft20Codec
+  | Draft21Codec {
   const draft = DRAFT_VERSIONS[options.draft]
   if (!draft) {
     throw new Error(
@@ -164,6 +170,8 @@ export function createCodec(
       return createDraft19Codec()
     case '20':
       return createDraft20Codec()
+    case '21':
+      return createDraft21Codec()
     default:
       throw new Error(`Unsupported draft: ${draft}`)
   }

package/src/session.ts

@@ -36,6 +36,8 @@ import { createDraft19SessionState } from './drafts/draft19/session.js'
 import type { Draft19Message, Draft19MessageType } from './drafts/draft19/types.js'
 import { createDraft20SessionState } from './drafts/draft20/session.js'
 import type { Draft20Message, Draft20MessageType } from './drafts/draft20/types.js'
+import { createDraft21SessionState } from './drafts/draft21/session.js'
+import type { Draft21Message, Draft21MessageType } from './drafts/draft21/types.js'
 
 type DraftSessionStateMap = {
   '07': SessionState<Draft07Message, Draft07MessageType>
@@ -52,6 +54,7 @@ type DraftSessionStateMap = {
   '18': SessionState<Draft18Message, Draft18MessageType>
   '19': SessionState<Draft19Message, Draft19MessageType>
   '20': SessionState<Draft20Message, Draft20MessageType>
+  '21': SessionState<Draft21Message, Draft21MessageType>
 }
 
 /**
@@ -77,6 +80,7 @@ export function createSessionState<T extends Draft>(
     '18': createDraft18SessionState,
     '19': createDraft19SessionState,
     '20': createDraft20SessionState,
+    '21': createDraft21SessionState,
   }
 
   const factory = factories[draft]