@moqtap/codec 0.8.1 → 0.9.0

package/src/drafts/draft20/error-codes.ts

@@ -0,0 +1,135 @@
+// Draft-20 error and status code registries.
+//
+// Three codes were removed relative to draft-19 and none was added or
+// renumbered. Each removal leaves an unassigned hole at the old codepoint,
+// so the constants below are gone and the value is listed in the matching
+// RETIRED_* set.
+//
+// The draft DOES say what a receiver does with an unassigned code, in
+// Section 14: treat it as INTERNAL_ERROR for its context, and MUST NOT close
+// the session over it in a REQUEST_ERROR or PUBLISH_DONE. So none of the sets
+// below is a decode gate -- see the note above them.
+
+/** draft-20 Section 15.11.1, Table 18 (prose Section 3.5). */
+export const SessionTerminationCode = {
+  NoError: 0x0n,
+  InternalError: 0x1n,
+  Unauthorized: 0x2n,
+  ProtocolViolation: 0x3n,
+  InvalidRequestId: 0x4n,
+  DuplicateTrackAlias: 0x5n,
+  KeyValueFormattingError: 0x6n,
+  InvalidPath: 0x8n,
+  MalformedPath: 0x9n,
+  GoawayTimeout: 0x10n,
+  ControlMessageTimeout: 0x11n,
+  DataStreamTimeout: 0x12n,
+  AuthTokenCacheOverflow: 0x13n,
+  DuplicateAuthTokenAlias: 0x14n,
+  // 0x15 VERSION_NEGOTIATION_FAILED — REMOVED in draft-20. Version negotiation
+  // moved to ALPN / WT-Available-Protocols in draft-15, so there is no longer a
+  // SETUP-time negotiation that can fail. See RETIRED_SESSION_TERMINATION_CODES.
+  MalformedAuthToken: 0x16n,
+  UnknownAuthTokenAlias: 0x17n,
+  ExpiredAuthToken: 0x18n,
+  InvalidAuthority: 0x19n,
+  MalformedAuthority: 0x1an,
+  TooManyRequestUpdates: 0x1bn,
+} as const
+export type SessionTerminationCodeValue =
+  (typeof SessionTerminationCode)[keyof typeof SessionTerminationCode]
+
+/** draft-20 Section 15.11.2, Table 19 (prose Section 10.6.2). */
+export const RequestErrorCode = {
+  InternalError: 0x0n,
+  Unauthorized: 0x1n,
+  Timeout: 0x2n,
+  NotSupported: 0x3n,
+  MalformedAuthToken: 0x4n,
+  ExpiredAuthToken: 0x5n,
+  GoingAway: 0x6n,
+  ExcessiveLoad: 0x9n,
+  DoesNotExist: 0x10n,
+  InvalidRange: 0x11n,
+  MalformedTrack: 0x12n,
+  Uninterested: 0x20n,
+  PrefixOverlap: 0x30n,
+  NamespaceTooLarge: 0x31n,
+  // 0x32 INVALID_JOINING_REQUEST_ID — REMOVED in draft-20 along with the whole
+  // joining-fetch mechanism (draft-19 Section 10.12.2). A draft-20 FETCH names
+  // its own track inline and never references another request, so there is no
+  // joining Request ID left to be invalid. See RETIRED_REQUEST_ERROR_CODES.
+  UnsupportedExtension: 0x33n,
+  Redirect: 0x34n,
+  ConflictingFilters: 0x35n,
+  InvalidFilter: 0x36n,
+} as const
+export type RequestErrorCodeValue = (typeof RequestErrorCode)[keyof typeof RequestErrorCode]
+
+/** draft-20 Section 15.11.3, Table 20 (prose Section 10.12). */
+export const PublishDoneCode = {
+  InternalError: 0x0n,
+  Unauthorized: 0x1n,
+  TrackEnded: 0x2n,
+  // 0x3 SUBSCRIPTION_ENDED — REMOVED in draft-20. The behaviour went with it:
+  // Section 5.1.2 now says "A publisher does not end a subscription solely
+  // because the Largest Object advances past the end of the current Location
+  // Filter", which is the only thing this code used to report.
+  // See RETIRED_PUBLISH_DONE_CODES.
+  GoingAway: 0x4n,
+  TooFarBehind: 0x5n,
+  Expired: 0x6n,
+  UpdateFailed: 0x8n,
+  ExcessiveLoad: 0x9n,
+  MalformedTrack: 0x12n,
+} as const
+export type PublishDoneCodeValue = (typeof PublishDoneCode)[keyof typeof PublishDoneCode]
+
+/** draft-20 Section 15.11.4, Table 21 (prose Section 3.3.4) — unchanged from draft-19. */
+export const DataStreamResetCode = {
+  InternalError: 0x0n,
+  Cancelled: 0x1n,
+  DeliveryTimeout: 0x2n,
+  SessionClosed: 0x3n,
+  GoingAway: 0x4n,
+  TooFarBehind: 0x5n,
+  UnknownObjectStatus: 0x6n,
+  ExpiredAuthToken: 0x7n,
+  ExcessiveLoad: 0x9n,
+  MalformedTrack: 0x12n,
+} as const
+export type DataStreamResetCodeValue =
+  (typeof DataStreamResetCode)[keyof typeof DataStreamResetCode]
+
+/*
+ * Retired codepoints.
+ *
+ * draft-20 states no rule for what a receiver does with a code that is not in
+ * a registry, so the decoder does not police the registries in general: an
+ * unrecognised-but-unassigned code may well be a codepoint a later draft
+ * assigns, and refusing it would make this codec useless as an observer of a
+ * newer peer.
+ *
+ * A code draft-19 assigned and draft-20 deleted is not refused either. It is
+ * tempting to: such a code is not merely "unknown to us" but known to be wrong
+ * for this version, and seeing one suggests the peer is speaking an older draft
+ * on a connection that negotiated moqt-20. But Section 14's "MUST NOT close the
+ * session because it received an unknown error code in a REQUEST_ERROR or
+ * PUBLISH_DONE" draws no distinction between a code that was never assigned and
+ * one that used to be, and the same paragraph is in draft-19 verbatim.
+ *
+ * So the sets below are advisory. They name what a caller may want to surface
+ * — "this peer looks like draft-19" is a genuinely useful diagnostic — and
+ * nothing in the decode path consults them.
+ */
+export const RETIRED_SESSION_TERMINATION_CODES: ReadonlySet<bigint> = new Set([
+  0x15n, // VERSION_NEGOTIATION_FAILED (draft-19 Section 3.5)
+])
+
+export const RETIRED_REQUEST_ERROR_CODES: ReadonlySet<bigint> = new Set([
+  0x32n, // INVALID_JOINING_REQUEST_ID (draft-19 Section 10.6.2)
+])
+
+export const RETIRED_PUBLISH_DONE_CODES: ReadonlySet<bigint> = new Set([
+  0x3n, // SUBSCRIPTION_ENDED (draft-19 Section 10.11)
+])

package/src/drafts/draft20/index.ts

@@ -0,0 +1,165 @@
+// Draft-20 codec entry point
+
+/**
+ * Draft-20's real identifier is the protocol string `moqt-20`.
+ *
+ * draft-20 Section 3.1: "MOQT uses ALPN in QUIC and 'WT-Available-Protocols' in
+ * WebTransport to perform version negotiation. […] ALPNs used to identify IETF
+ * drafts are created by appending the draft number to 'moqt-'. […] Note: Draft
+ * versions prior to -15 all used moq-00 ALPN, followed by version negotiation
+ * in the SETUP messages."
+ *
+ * So this is what a draft-20 peer actually negotiates with, and it is the only
+ * identifier that appears anywhere in a draft-20 session.
+ */
+export const PROTOCOL_STRING = 'moqt-20'
+
+/**
+ * The `0xff000000 + N` identifier for draft 20.
+ *
+ * **This is a derived identifier, not an observed wire value.** No draft-20
+ * peer ever sends it. The `0xff0000NN` scheme belonged to the SETUP-time
+ * version negotiation that drafts before -15 used; from draft-15 on the version
+ * is negotiated by ALPN / `WT-Available-Protocols` and no version number
+ * appears on the wire at all. It is kept only so that code indexing drafts by a
+ * numeric key — {@link DRAFT_VERSIONS} in the package root, trace formats,
+ * anything that predates the change — has a stable key for draft-20.
+ *
+ * Anything that reports a version to a user should report
+ * {@link PROTOCOL_STRING} instead, and should not claim to have observed this
+ * number.
+ */
+export const DRAFT_VERSION = 0xff000014n
+
+export type { Draft20Codec } from './codec.js'
+export {
+  createDataStreamDecoder,
+  createDraft20Codec,
+  createFetchStreamDecoder,
+  createStreamDecoder,
+  createSubgroupStreamDecoder,
+  decodeDatagram,
+  decodeDataStream,
+  decodeFetchStream,
+  decodeMessage,
+  decodeSubgroupStream,
+  encodeDatagram,
+  encodeFetchStream,
+  encodeMessage,
+  encodeSubgroupStream,
+  UNKNOWN_STREAM_COUNT,
+} from './codec.js'
+export type {
+  DataStreamResetCodeValue,
+  PublishDoneCodeValue,
+  RequestErrorCodeValue,
+  SessionTerminationCodeValue,
+} from './error-codes.js'
+export {
+  DataStreamResetCode,
+  PublishDoneCode,
+  RETIRED_PUBLISH_DONE_CODES,
+  RETIRED_REQUEST_ERROR_CODES,
+  RETIRED_SESSION_TERMINATION_CODES,
+  RequestErrorCode,
+  SessionTerminationCode,
+} from './error-codes.js'
+
+export {
+  MESSAGE_ID_MAP,
+  MESSAGE_TYPE_MAP,
+  MSG_FETCH,
+  MSG_FETCH_OK,
+  MSG_GOAWAY,
+  MSG_NAMESPACE,
+  MSG_NAMESPACE_DONE,
+  MSG_PUBLISH,
+  MSG_PUBLISH_DONE,
+  MSG_PUBLISH_NAMESPACE,
+  MSG_PUBLISH_OK,
+  MSG_PUBLISH_SKIPPED,
+  MSG_PUBLISH_STATE_NOTIFY,
+  MSG_REQUEST_ERROR,
+  MSG_REQUEST_OK,
+  MSG_REQUEST_UPDATE,
+  MSG_SETUP,
+  MSG_SUBSCRIBE,
+  MSG_SUBSCRIBE_NAMESPACE,
+  MSG_SUBSCRIBE_OK,
+  MSG_SUBSCRIBE_TRACKS,
+  MSG_TRACK_STATUS,
+  SETUP_OPT_AUTHORITY,
+  SETUP_OPT_AUTHORIZATION_TOKEN,
+  SETUP_OPT_MAX_AUTH_TOKEN_CACHE_SIZE,
+  SETUP_OPT_MAX_FILTER_RANGES,
+  SETUP_OPT_MAX_REQUEST_UPDATES,
+  SETUP_OPT_MOQT_IMPLEMENTATION,
+  SETUP_OPT_PATH,
+} from './messages.js'
+
+export {
+  BIDIRECTIONAL_MESSAGES,
+  CLIENT_ONLY_MESSAGES,
+  CONTROL_MESSAGES,
+  getLegalIncoming,
+  getLegalOutgoing,
+  REQUEST_STREAM_OPENERS,
+  SERVER_ONLY_MESSAGES,
+} from './rules.js'
+export type {
+  FillFetchStreamPhase,
+  FillFetchStreamState,
+  ProtocolViolation,
+  PublisherSide,
+  RequestKind,
+  SessionPhase,
+  SideEffect,
+  TransitionResult,
+  ValidationResult,
+} from './session.js'
+export { createDraft20SessionState, Draft20SessionFSM } from './session.js'
+
+export type {
+  DatagramObject,
+  DataStreamEvent,
+  DataStreamHeader,
+  Draft20BaseMessage,
+  Draft20DataStream,
+  Draft20Fetch,
+  Draft20FetchOk,
+  Draft20FillParameters,
+  Draft20GoAway,
+  Draft20Message,
+  Draft20MessageType,
+  Draft20Namespace,
+  Draft20NamespaceDone,
+  Draft20Params,
+  Draft20Publish,
+  Draft20PublishDone,
+  Draft20PublishNamespace,
+  Draft20PublishSkipped,
+  Draft20PublishStateNotify,
+  Draft20RequestError,
+  Draft20RequestOk,
+  Draft20RequestUpdate,
+  Draft20Setup,
+  Draft20SetupOptions,
+  Draft20Subscribe,
+  Draft20SubscribeNamespace,
+  Draft20SubscribeOk,
+  Draft20SubscribeTracks,
+  Draft20TrackProperties,
+  Draft20TrackStatus,
+  FetchObjectPayload,
+  FetchStream,
+  FetchStreamHeader,
+  LargestObject,
+  LocationFilter,
+  ObjectPayload,
+  RangeFilter,
+  RangeFilterRange,
+  Redirect,
+  SubgroupStream,
+  SubgroupStreamHeader,
+  UnknownParam,
+} from './types.js'

package/src/drafts/draft20/messages.ts

@@ -0,0 +1,68 @@
+// Draft-20 message type wire IDs (draft-20 Section 10, Table 5).
+//
+// No codepoint moved between draft-19 and draft-20 and none was removed.
+// Exactly one row was added: PUBLISH_STATE_NOTIFY (0x22).
+
+export const MSG_REQUEST_UPDATE = 0x02n
+export const MSG_SUBSCRIBE = 0x03n
+export const MSG_SUBSCRIBE_OK = 0x04n
+export const MSG_REQUEST_ERROR = 0x05n
+export const MSG_PUBLISH_NAMESPACE = 0x06n
+export const MSG_REQUEST_OK = 0x07n
+export const MSG_NAMESPACE = 0x08n
+export const MSG_PUBLISH_DONE = 0x0bn
+export const MSG_TRACK_STATUS = 0x0dn
+export const MSG_NAMESPACE_DONE = 0x0en
+export const MSG_PUBLISH_SKIPPED = 0x0fn
+export const MSG_GOAWAY = 0x10n
+export const MSG_FETCH = 0x16n
+export const MSG_FETCH_OK = 0x18n
+export const MSG_PUBLISH = 0x1dn
+/** NEW in draft-20 — Section 10.10. Unilateral publisher→subscriber notification. */
+export const MSG_PUBLISH_STATE_NOTIFY = 0x22n
+// PUBLISH_OK is not a codepoint of its own: it is a REQUEST_OK (0x07) sent in
+// reply to a PUBLISH (draft-20 Section 10.5). Same for REQUEST_UPDATE_OK,
+// TRACK_STATUS_OK, SUBSCRIBE_NAMESPACE_OK, SUBSCRIBE_TRACKS_OK and
+// PUBLISH_NAMESPACE_OK.
+export const MSG_PUBLISH_OK = MSG_REQUEST_OK
+export const MSG_SUBSCRIBE_NAMESPACE = 0x50n
+export const MSG_SUBSCRIBE_TRACKS = 0x51n
+export const MSG_SETUP = 0x2f00n
+
+// Setup option type IDs (KVP encoding, version-independent namespace).
+// Unchanged from draft-19 (draft-20 Section 15.4, Table 10).
+export const SETUP_OPT_PATH = 0x01n
+export const SETUP_OPT_AUTHORIZATION_TOKEN = 0x03n
+export const SETUP_OPT_MAX_AUTH_TOKEN_CACHE_SIZE = 0x04n
+export const SETUP_OPT_AUTHORITY = 0x05n
+export const SETUP_OPT_MAX_FILTER_RANGES = 0x06n
+export const SETUP_OPT_MOQT_IMPLEMENTATION = 0x07n
+export const SETUP_OPT_MAX_REQUEST_UPDATES = 0x08n
+
+// Map from wire ID to message type name
+export const MESSAGE_TYPE_MAP: ReadonlyMap<bigint, string> = new Map([
+  [MSG_SETUP, 'setup'],
+  [MSG_SUBSCRIBE, 'subscribe'],
+  [MSG_SUBSCRIBE_OK, 'subscribe_ok'],
+  [MSG_REQUEST_UPDATE, 'request_update'],
+  [MSG_PUBLISH_STATE_NOTIFY, 'publish_state_notify'],
+  [MSG_PUBLISH, 'publish'],
+  [MSG_PUBLISH_DONE, 'publish_done'],
+  [MSG_PUBLISH_NAMESPACE, 'publish_namespace'],
+  [MSG_NAMESPACE, 'namespace'],
+  [MSG_NAMESPACE_DONE, 'namespace_done'],
+  [MSG_SUBSCRIBE_NAMESPACE, 'subscribe_namespace'],
+  [MSG_SUBSCRIBE_TRACKS, 'subscribe_tracks'],
+  [MSG_PUBLISH_SKIPPED, 'publish_skipped'],
+  [MSG_FETCH, 'fetch'],
+  [MSG_FETCH_OK, 'fetch_ok'],
+  [MSG_TRACK_STATUS, 'track_status'],
+  [MSG_REQUEST_OK, 'request_ok'],
+  [MSG_REQUEST_ERROR, 'request_error'],
+  [MSG_GOAWAY, 'goaway'],
+])
+
+// Reverse map from message type name to wire ID
+export const MESSAGE_ID_MAP: ReadonlyMap<string, bigint> = new Map(
+  [...MESSAGE_TYPE_MAP.entries()].map(([id, name]) => [name, id]),
+)

package/src/drafts/draft20/rules.ts

@@ -0,0 +1,107 @@
+import type { Draft20MessageType } from './types.js'
+
+// All draft-20 control messages (draft-20 Section 10, Table 5)
+export const CONTROL_MESSAGES: ReadonlySet<Draft20MessageType> = new Set([
+  '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',
+])
+
+// Draft-20 has a single SETUP message — both roles can send it
+export const CLIENT_ONLY_MESSAGES: ReadonlySet<Draft20MessageType> = new Set<Draft20MessageType>()
+
+export const SERVER_ONLY_MESSAGES: ReadonlySet<Draft20MessageType> = new Set<Draft20MessageType>()
+
+// Messages that are bidirectional (both client and server can send)
+export const BIDIRECTIONAL_MESSAGES: ReadonlySet<Draft20MessageType> = new Set([
+  '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',
+])
+
+/**
+ * The seven message types that may be the FIRST message on a new bidirectional
+ * (request) stream — draft-20 Section 3.3, and the rows marked "First" in the
+ * Section 10 registry. Unchanged from draft-19.
+ *
+ * "Bidirectional streams MUST NOT begin with any other message type unless
+ * negotiated. If they do, the peer MUST close the Session with a
+ * PROTOCOL_VIOLATION." Note GOAWAY (0x10) is marked "Control, Request" but not
+ * "First": it may travel on either kind of stream but may never open one.
+ */
+export const REQUEST_STREAM_OPENERS: ReadonlySet<Draft20MessageType> = new Set([
+  'subscribe',
+  'publish',
+  'fetch',
+  'track_status',
+  'publish_namespace',
+  'subscribe_namespace',
+  'subscribe_tracks',
+])
+
+// Messages legal in each session phase
+export function getLegalOutgoing(
+  phase: string,
+  _role: 'client' | 'server',
+): Set<Draft20MessageType> {
+  const legal = new Set<Draft20MessageType>()
+
+  switch (phase) {
+    case 'idle':
+      legal.add('setup')
+      break
+    case 'setup':
+      legal.add('setup')
+      break
+    case 'ready': {
+      for (const msg of BIDIRECTIONAL_MESSAGES) {
+        legal.add(msg)
+      }
+      break
+    }
+    case 'draining':
+      break
+  }
+
+  return legal
+}
+
+export function getLegalIncoming(
+  phase: string,
+  role: 'client' | 'server',
+): Set<Draft20MessageType> {
+  const remoteRole = role === 'client' ? 'server' : 'client'
+  return getLegalOutgoing(phase, remoteRole)
+}