@moqtap/codec 0.1.1 → 0.2.1

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

@@ -0,0 +1,359 @@
+import { BufferReader } from "../../core/buffer-reader.js";
+import { BufferWriter } from "../../core/buffer-writer.js";
+import type { DecodeResult } from "../../core/types.js";
+import { DecodeError } from "../../core/types.js";
+import type {
+  DatagramObject,
+  DatagramStatusObject,
+  Draft08DataStream,
+  FetchObjectPayload,
+  FetchStream,
+  ObjectPayload,
+  SubgroupStream,
+} from "./types.js";
+
+// ─── Data Stream Encoding/Decoding ─────────────────────────────────────────────
+
+// Stream type IDs for draft-08
+const SUBGROUP_STREAM_TYPE = 0x04n;
+const DATAGRAM_TYPE = 0x01n;
+const DATAGRAM_STATUS_TYPE = 0x02n;
+const FETCH_STREAM_TYPE = 0x05n;
+
+export function encodeSubgroupStream(stream: SubgroupStream): Uint8Array {
+  const w = new BufferWriter();
+  w.writeVarInt(SUBGROUP_STREAM_TYPE);
+  w.writeVarInt(stream.trackAlias);
+  w.writeVarInt(stream.groupId);
+  w.writeVarInt(stream.subgroupId);
+  w.writeUint8(stream.publisherPriority);
+  for (const obj of stream.objects) {
+    w.writeVarInt(obj.objectId);
+    w.writeVarInt(obj.extensionCount);
+    if (obj.extensionData.length > 0) w.writeBytes(obj.extensionData);
+    w.writeVarInt(obj.payloadLength);
+    if (obj.payloadLength === 0 && obj.status !== undefined) {
+      w.writeVarInt(obj.status);
+    } else {
+      w.writeBytes(obj.payload);
+    }
+  }
+  return w.finish();
+}
+
+export function encodeDatagram(dg: DatagramObject): Uint8Array {
+  const w = new BufferWriter();
+  w.writeVarInt(DATAGRAM_TYPE);
+  w.writeVarInt(dg.trackAlias);
+  w.writeVarInt(dg.groupId);
+  w.writeVarInt(dg.objectId);
+  w.writeUint8(dg.publisherPriority);
+  w.writeVarInt(dg.extensionCount);
+  if (dg.extensionData.length > 0) w.writeBytes(dg.extensionData);
+  w.writeVarInt(dg.payloadLength);
+  if (dg.payloadLength === 0 && dg.objectStatus !== undefined) {
+    w.writeVarInt(dg.objectStatus);
+  } else {
+    w.writeBytes(dg.payload);
+  }
+  return w.finish();
+}
+
+export function encodeDatagramStatus(dg: DatagramStatusObject): Uint8Array {
+  const w = new BufferWriter();
+  w.writeVarInt(DATAGRAM_STATUS_TYPE);
+  w.writeVarInt(dg.trackAlias);
+  w.writeVarInt(dg.groupId);
+  w.writeVarInt(dg.objectId);
+  w.writeUint8(dg.publisherPriority);
+  w.writeVarInt(dg.objectStatus);
+  return w.finish();
+}
+
+export function encodeFetchStream(stream: FetchStream): Uint8Array {
+  const w = new BufferWriter();
+  w.writeVarInt(FETCH_STREAM_TYPE);
+  w.writeVarInt(stream.subscribeId);
+  for (const obj of stream.objects) {
+    w.writeVarInt(obj.groupId);
+    w.writeVarInt(obj.subgroupId);
+    w.writeVarInt(obj.objectId);
+    w.writeUint8(obj.publisherPriority);
+    w.writeVarInt(obj.extensionCount);
+    if (obj.extensionData.length > 0) w.writeBytes(obj.extensionData);
+    w.writeVarInt(obj.payloadLength);
+    if (obj.payloadLength === 0 && obj.status !== undefined) {
+      w.writeVarInt(obj.status);
+    } else {
+      w.writeBytes(obj.payload);
+    }
+  }
+  return w.finish();
+}
+
+export function decodeSubgroupStream(bytes: Uint8Array): DecodeResult<SubgroupStream> {
+  try {
+    const r = new BufferReader(bytes);
+    const streamType = Number(r.readVarInt());
+    if (streamType !== 0x04) {
+      return {
+        ok: false,
+        error: new DecodeError(
+          "CONSTRAINT_VIOLATION",
+          `Expected subgroup type 0x04, got 0x${streamType.toString(16)}`,
+          0,
+        ),
+      };
+    }
+    const trackAlias = r.readVarInt();
+    const groupId = r.readVarInt();
+    const subgroupId = r.readVarInt();
+    const publisherPriority = r.readUint8();
+    const objects: ObjectPayload[] = [];
+    while (r.remaining > 0) {
+      const byteOffset = r.offset;
+      const objectId = r.readVarInt();
+      // Parse extensions (even type = varint value, odd type = length-prefixed)
+      const extensionCount = Number(r.readVarInt());
+      const extStart = r.offset;
+      for (let i = 0; i < extensionCount; i++) {
+        const extType = Number(r.readVarInt());
+        if (extType % 2 === 0) {
+          r.readVarInt(); // even: single varint value
+        } else {
+          const extLen = Number(r.readVarInt());
+          if (extLen > 0) r.readBytes(extLen); // odd: length-prefixed
+        }
+      }
+      const extensionData = r.buffer.slice(extStart, r.offset);
+      const payloadLength = Number(r.readVarInt());
+      let payload: Uint8Array;
+      let status: bigint | undefined;
+      let payloadByteOffset: number;
+      if (payloadLength === 0) {
+        status = r.readVarInt();
+        payloadByteOffset = r.offset;
+        payload = new Uint8Array(0);
+      } else {
+        payloadByteOffset = r.offset;
+        payload = r.readBytes(payloadLength);
+      }
+      const obj: ObjectPayload = {
+        type: "object",
+        byteOffset,
+        payloadByteOffset,
+        objectId,
+        extensionCount: BigInt(extensionCount),
+        extensionData,
+        payloadLength,
+        payload,
+      };
+      if (status !== undefined) (obj as unknown as Record<string, unknown>).status = status;
+      objects.push(obj);
+    }
+    return {
+      ok: true,
+      value: {
+        type: "subgroup",
+        streamTypeId: 0x04,
+        trackAlias,
+        groupId,
+        subgroupId,
+        publisherPriority,
+        objects,
+      },
+      bytesRead: r.offset,
+    };
+  } catch (e) {
+    if (e instanceof DecodeError) return { ok: false, error: e };
+    throw e;
+  }
+}
+
+export function decodeDatagram(bytes: Uint8Array): DecodeResult<DatagramObject> {
+  try {
+    const r = new BufferReader(bytes);
+    const streamType = Number(r.readVarInt());
+    if (streamType !== 0x01) {
+      return {
+        ok: false,
+        error: new DecodeError(
+          "CONSTRAINT_VIOLATION",
+          `Expected datagram type 0x01, got 0x${streamType.toString(16)}`,
+          0,
+        ),
+      };
+    }
+    const trackAlias = r.readVarInt();
+    const groupId = r.readVarInt();
+    const objectId = r.readVarInt();
+    const publisherPriority = r.readUint8();
+    // Parse extensions (even type = varint value, odd type = length-prefixed)
+    const extensionCount = Number(r.readVarInt());
+    const extStart = r.offset;
+    for (let i = 0; i < extensionCount; i++) {
+      const extType = Number(r.readVarInt());
+      if (extType % 2 === 0) {
+        r.readVarInt(); // even: single varint value
+      } else {
+        const extLen = Number(r.readVarInt());
+        if (extLen > 0) r.readBytes(extLen); // odd: length-prefixed
+      }
+    }
+    const extensionData = r.buffer.slice(extStart, r.offset);
+    const payloadLength = Number(r.readVarInt());
+    let objectStatus: bigint | undefined;
+    let payload: Uint8Array;
+    if (payloadLength === 0) {
+      objectStatus = r.readVarInt();
+      payload = new Uint8Array(0);
+    } else {
+      payload = r.readBytes(payloadLength);
+    }
+    const result: DatagramObject = {
+      type: "datagram",
+      streamTypeId: 0x01,
+      trackAlias,
+      groupId,
+      objectId,
+      publisherPriority,
+      extensionCount: BigInt(extensionCount),
+      extensionData,
+      objectStatus: objectStatus ?? 0n,
+      payloadLength,
+      payload,
+    };
+    return { ok: true, value: result, bytesRead: r.offset };
+  } catch (e) {
+    if (e instanceof DecodeError) return { ok: false, error: e };
+    throw e;
+  }
+}
+
+export function decodeDatagramStatus(bytes: Uint8Array): DecodeResult<DatagramStatusObject> {
+  try {
+    const r = new BufferReader(bytes);
+    const streamType = Number(r.readVarInt());
+    if (streamType !== 0x02) {
+      return {
+        ok: false,
+        error: new DecodeError(
+          "CONSTRAINT_VIOLATION",
+          `Expected datagram_status type 0x02, got 0x${streamType.toString(16)}`,
+          0,
+        ),
+      };
+    }
+    const trackAlias = r.readVarInt();
+    const groupId = r.readVarInt();
+    const objectId = r.readVarInt();
+    const publisherPriority = r.readUint8();
+    const objectStatus = r.readVarInt();
+    return {
+      ok: true,
+      value: {
+        type: "datagram_status",
+        streamTypeId: 0x02,
+        trackAlias,
+        groupId,
+        objectId,
+        publisherPriority,
+        objectStatus,
+      },
+      bytesRead: r.offset,
+    };
+  } catch (e) {
+    if (e instanceof DecodeError) return { ok: false, error: e };
+    throw e;
+  }
+}
+
+export function decodeFetchStream(bytes: Uint8Array): DecodeResult<FetchStream> {
+  try {
+    const r = new BufferReader(bytes);
+    const streamType = r.readVarInt();
+    if (streamType !== FETCH_STREAM_TYPE) {
+      return {
+        ok: false,
+        error: new DecodeError(
+          "CONSTRAINT_VIOLATION",
+          `Expected fetch type 0x05, got 0x${streamType.toString(16)}`,
+          0,
+        ),
+      };
+    }
+    const subscribeId = r.readVarInt();
+    const objects: FetchObjectPayload[] = [];
+    while (r.remaining > 0) {
+      const byteOffset = r.offset;
+      const groupId = r.readVarInt();
+      const subgroupId = r.readVarInt();
+      const objectId = r.readVarInt();
+      const publisherPriority = r.readUint8();
+      // Parse extensions (even type = varint value, odd type = length-prefixed)
+      const extensionCount = Number(r.readVarInt());
+      const extStart = r.offset;
+      for (let i = 0; i < extensionCount; i++) {
+        const extType = Number(r.readVarInt());
+        if (extType % 2 === 0) {
+          r.readVarInt(); // even: single varint value
+        } else {
+          const extLen = Number(r.readVarInt());
+          if (extLen > 0) r.readBytes(extLen); // odd: length-prefixed
+        }
+      }
+      const extensionData = r.buffer.slice(extStart, r.offset);
+      const payloadLength = Number(r.readVarInt());
+      let payload: Uint8Array;
+      let status: bigint | undefined;
+      let payloadByteOffset: number;
+      if (payloadLength === 0) {
+        status = r.readVarInt();
+        payloadByteOffset = r.offset;
+        payload = new Uint8Array(0);
+      } else {
+        payloadByteOffset = r.offset;
+        payload = r.readBytes(payloadLength);
+      }
+      const obj: FetchObjectPayload = {
+        type: "object",
+        byteOffset,
+        payloadByteOffset,
+        groupId,
+        subgroupId,
+        objectId,
+        publisherPriority,
+        extensionCount: BigInt(extensionCount),
+        extensionData,
+        payloadLength,
+        payload,
+      };
+      if (status !== undefined) (obj as unknown as Record<string, unknown>).status = status;
+      objects.push(obj);
+    }
+    return { ok: true, value: { type: "fetch", subscribeId, objects }, bytesRead: r.offset };
+  } catch (e) {
+    if (e instanceof DecodeError) return { ok: false, error: e };
+    throw e;
+  }
+}
+
+export function decodeDataStream(
+  streamType: "subgroup" | "datagram" | "datagram_status" | "fetch",
+  bytes: Uint8Array,
+): DecodeResult<Draft08DataStream> {
+  switch (streamType) {
+    case "subgroup":
+      return decodeSubgroupStream(bytes);
+    case "datagram":
+      return decodeDatagram(bytes);
+    case "datagram_status":
+      return decodeDatagramStatus(bytes);
+    case "fetch":
+      return decodeFetchStream(bytes);
+    default: {
+      const _: never = streamType;
+      throw new Error(`Unknown: ${_}`);
+    }
+  }
+}

package/src/drafts/draft08/index.ts

@@ -0,0 +1,125 @@
+export type { Draft08Codec } from "./codec.js";
+export {
+  createDraft08Codec,
+  createStreamDecoder,
+  decodeDatagram,
+  decodeDatagramStatus,
+  decodeDataStream,
+  decodeFetchStream,
+  decodeMessage,
+  decodeSubgroupStream,
+  encodeDatagram,
+  encodeDatagramStatus,
+  encodeFetchStream,
+  encodeMessage,
+  encodeSubgroupStream,
+} from "./codec.js";
+export {
+  MESSAGE_ID_MAP,
+  MESSAGE_TYPE_MAP,
+  MSG_ANNOUNCE,
+  MSG_ANNOUNCE_CANCEL,
+  MSG_ANNOUNCE_ERROR,
+  MSG_ANNOUNCE_OK,
+  MSG_CLIENT_SETUP,
+  MSG_FETCH,
+  MSG_FETCH_CANCEL,
+  MSG_FETCH_ERROR,
+  MSG_FETCH_OK,
+  MSG_GOAWAY,
+  MSG_MAX_SUBSCRIBE_ID,
+  MSG_SERVER_SETUP,
+  MSG_SUBSCRIBE,
+  MSG_SUBSCRIBE_ANNOUNCES,
+  MSG_SUBSCRIBE_ANNOUNCES_ERROR,
+  MSG_SUBSCRIBE_ANNOUNCES_OK,
+  MSG_SUBSCRIBE_DONE,
+  MSG_SUBSCRIBE_ERROR,
+  MSG_SUBSCRIBE_OK,
+  MSG_SUBSCRIBE_UPDATE,
+  MSG_SUBSCRIBES_BLOCKED,
+  MSG_TRACK_STATUS,
+  MSG_TRACK_STATUS_REQUEST,
+  MSG_UNANNOUNCE,
+  MSG_UNSUBSCRIBE,
+  MSG_UNSUBSCRIBE_ANNOUNCES,
+  PARAM_AUTHORIZATION_INFO,
+  PARAM_DELIVERY_TIMEOUT,
+  PARAM_MAX_CACHE_DURATION,
+  SETUP_PARAM_MAX_SUBSCRIBE_ID,
+  SETUP_PARAM_PATH,
+} from "./messages.js";
+export {
+  BIDIRECTIONAL_MESSAGES,
+  CLIENT_ONLY_MESSAGES,
+  CONTROL_MESSAGES,
+  getLegalIncoming,
+  getLegalOutgoing,
+  SERVER_ONLY_MESSAGES,
+} from "./rules.js";
+export type {
+  AnnouncePhase,
+  AnnounceState,
+  FetchPhase,
+  FetchState,
+  ProtocolViolation,
+  ProtocolViolationCode,
+  SessionPhase,
+  SessionState,
+  SessionStateOptions,
+  SideEffect,
+  SubscriptionPhase,
+  SubscriptionState,
+  TransitionResult,
+  ValidationResult,
+} from "./session.js";
+// Session state machine
+export { createDraft08SessionState } from "./session.js";
+export { Draft08SessionFSM } from "./session-fsm.js";
+export type {
+  DatagramObject,
+  DatagramStatusObject,
+  DataStreamEvent,
+  DataStreamHeader,
+  Draft08Announce,
+  Draft08AnnounceCancel,
+  Draft08AnnounceError,
+  Draft08AnnounceOk,
+  Draft08BaseMessage,
+  Draft08ClientSetup,
+  Draft08DataStream,
+  Draft08Fetch,
+  Draft08FetchCancel,
+  Draft08FetchError,
+  Draft08FetchOk,
+  Draft08GoAway,
+  Draft08MaxSubscribeId,
+  Draft08Message,
+  Draft08MessageType,
+  Draft08Params,
+  Draft08ServerSetup,
+  Draft08SetupParams,
+  Draft08Subscribe,
+  Draft08SubscribeAnnounces,
+  Draft08SubscribeAnnouncesError,
+  Draft08SubscribeAnnouncesOk,
+  Draft08SubscribeDone,
+  Draft08SubscribeError,
+  Draft08SubscribeOk,
+  Draft08SubscribesBlocked,
+  Draft08SubscribeUpdate,
+  Draft08TrackStatus,
+  Draft08TrackStatusRequest,
+  Draft08Unannounce,
+  Draft08Unsubscribe,
+  Draft08UnsubscribeAnnounces,
+  FetchObjectPayload,
+  FetchStream,
+  FetchStreamHeader,
+  JoiningFetch,
+  ObjectPayload,
+  StandaloneFetch,
+  SubgroupStream,
+  SubgroupStreamHeader,
+  UnknownParam,
+} from "./types.js";

package/src/drafts/draft08/messages.ts

@@ -0,0 +1,72 @@
+// Draft-08 message type wire IDs
+
+export const MSG_SUBSCRIBE_UPDATE = 0x02n;
+export const MSG_SUBSCRIBE = 0x03n;
+export const MSG_SUBSCRIBE_OK = 0x04n;
+export const MSG_SUBSCRIBE_ERROR = 0x05n;
+export const MSG_ANNOUNCE = 0x06n;
+export const MSG_ANNOUNCE_OK = 0x07n;
+export const MSG_ANNOUNCE_ERROR = 0x08n;
+export const MSG_UNANNOUNCE = 0x09n;
+export const MSG_UNSUBSCRIBE = 0x0an;
+export const MSG_SUBSCRIBE_DONE = 0x0bn;
+export const MSG_ANNOUNCE_CANCEL = 0x0cn;
+export const MSG_TRACK_STATUS_REQUEST = 0x0dn;
+export const MSG_TRACK_STATUS = 0x0en;
+export const MSG_GOAWAY = 0x10n;
+export const MSG_SUBSCRIBE_ANNOUNCES = 0x11n;
+export const MSG_SUBSCRIBE_ANNOUNCES_OK = 0x12n;
+export const MSG_SUBSCRIBE_ANNOUNCES_ERROR = 0x13n;
+export const MSG_UNSUBSCRIBE_ANNOUNCES = 0x14n;
+export const MSG_MAX_SUBSCRIBE_ID = 0x15n;
+export const MSG_FETCH = 0x16n;
+export const MSG_FETCH_CANCEL = 0x17n;
+export const MSG_FETCH_OK = 0x18n;
+export const MSG_FETCH_ERROR = 0x19n;
+export const MSG_SUBSCRIBES_BLOCKED = 0x1an;
+export const MSG_CLIENT_SETUP = 0x40n;
+export const MSG_SERVER_SETUP = 0x41n;
+
+// Setup parameter type IDs
+export const SETUP_PARAM_PATH = 0x01n;
+export const SETUP_PARAM_MAX_SUBSCRIBE_ID = 0x02n;
+
+// Version-specific parameter type IDs
+export const PARAM_AUTHORIZATION_INFO = 0x02n;
+export const PARAM_DELIVERY_TIMEOUT = 0x03n;
+export const PARAM_MAX_CACHE_DURATION = 0x04n;
+
+// Map from wire ID to message type name
+export const MESSAGE_TYPE_MAP: ReadonlyMap<bigint, string> = new Map([
+  [MSG_CLIENT_SETUP, "client_setup"],
+  [MSG_SERVER_SETUP, "server_setup"],
+  [MSG_SUBSCRIBE, "subscribe"],
+  [MSG_SUBSCRIBE_OK, "subscribe_ok"],
+  [MSG_SUBSCRIBE_ERROR, "subscribe_error"],
+  [MSG_SUBSCRIBE_UPDATE, "subscribe_update"],
+  [MSG_SUBSCRIBE_DONE, "subscribe_done"],
+  [MSG_UNSUBSCRIBE, "unsubscribe"],
+  [MSG_ANNOUNCE, "announce"],
+  [MSG_ANNOUNCE_OK, "announce_ok"],
+  [MSG_ANNOUNCE_ERROR, "announce_error"],
+  [MSG_UNANNOUNCE, "unannounce"],
+  [MSG_ANNOUNCE_CANCEL, "announce_cancel"],
+  [MSG_SUBSCRIBE_ANNOUNCES, "subscribe_announces"],
+  [MSG_SUBSCRIBE_ANNOUNCES_OK, "subscribe_announces_ok"],
+  [MSG_SUBSCRIBE_ANNOUNCES_ERROR, "subscribe_announces_error"],
+  [MSG_UNSUBSCRIBE_ANNOUNCES, "unsubscribe_announces"],
+  [MSG_FETCH, "fetch"],
+  [MSG_FETCH_OK, "fetch_ok"],
+  [MSG_FETCH_ERROR, "fetch_error"],
+  [MSG_FETCH_CANCEL, "fetch_cancel"],
+  [MSG_TRACK_STATUS_REQUEST, "track_status_request"],
+  [MSG_TRACK_STATUS, "track_status"],
+  [MSG_GOAWAY, "goaway"],
+  [MSG_MAX_SUBSCRIBE_ID, "max_subscribe_id"],
+  [MSG_SUBSCRIBES_BLOCKED, "subscribes_blocked"],
+]);
+
+// Reverse map
+export const MESSAGE_ID_MAP: ReadonlyMap<string, bigint> = new Map(
+  [...MESSAGE_TYPE_MAP.entries()].map(([id, name]) => [name, id]),
+);

package/src/drafts/draft08/rules.ts

@@ -0,0 +1,91 @@
+import type { Draft08MessageType } from "./types.js";
+
+// All draft-08 control messages
+export const CONTROL_MESSAGES: ReadonlySet<Draft08MessageType> = new Set([
+  "client_setup",
+  "server_setup",
+  "subscribe",
+  "subscribe_ok",
+  "subscribe_error",
+  "subscribe_update",
+  "subscribe_done",
+  "unsubscribe",
+  "announce",
+  "announce_ok",
+  "announce_error",
+  "unannounce",
+  "announce_cancel",
+  "subscribe_announces",
+  "subscribe_announces_ok",
+  "subscribe_announces_error",
+  "unsubscribe_announces",
+  "fetch",
+  "fetch_ok",
+  "fetch_error",
+  "fetch_cancel",
+  "track_status_request",
+  "track_status",
+  "goaway",
+  "max_subscribe_id",
+  "subscribes_blocked",
+]);
+
+export const CLIENT_ONLY_MESSAGES: ReadonlySet<Draft08MessageType> = new Set(["client_setup"]);
+export const SERVER_ONLY_MESSAGES: ReadonlySet<Draft08MessageType> = new Set(["server_setup"]);
+
+export const BIDIRECTIONAL_MESSAGES: ReadonlySet<Draft08MessageType> = new Set([
+  "subscribe",
+  "subscribe_ok",
+  "subscribe_error",
+  "subscribe_update",
+  "subscribe_done",
+  "unsubscribe",
+  "announce",
+  "announce_ok",
+  "announce_error",
+  "unannounce",
+  "announce_cancel",
+  "subscribe_announces",
+  "subscribe_announces_ok",
+  "subscribe_announces_error",
+  "unsubscribe_announces",
+  "fetch",
+  "fetch_ok",
+  "fetch_error",
+  "fetch_cancel",
+  "track_status_request",
+  "track_status",
+  "goaway",
+  "max_subscribe_id",
+  "subscribes_blocked",
+]);
+
+export function getLegalOutgoing(
+  phase: string,
+  role: "client" | "server",
+): Set<Draft08MessageType> {
+  const legal = new Set<Draft08MessageType>();
+  switch (phase) {
+    case "idle":
+      if (role === "client") legal.add("client_setup");
+      break;
+    case "setup":
+      if (role === "server") legal.add("server_setup");
+      break;
+    case "ready":
+      legal.add("goaway");
+      for (const msg of BIDIRECTIONAL_MESSAGES) legal.add(msg);
+      break;
+    case "draining":
+      break;
+  }
+  return legal;
+}
+
+export function getLegalIncoming(
+  phase: string,
+  role: "client" | "server",
+): Set<Draft08MessageType> {
+  const remoteRole = role === "client" ? "server" : "client";
+  return getLegalOutgoing(phase, remoteRole);
+}