@moqtap/codec 0.1.0

package/src/core/buffer-writer.ts

@@ -0,0 +1,91 @@
+export class BufferWriter {
+  private buffer: Uint8Array;
+  private view: DataView;
+  private pos: number;
+
+  constructor(initialSize = 256) {
+    this.buffer = new Uint8Array(initialSize);
+    this.view = new DataView(this.buffer.buffer);
+    this.pos = 0;
+  }
+
+  get offset(): number {
+    return this.pos;
+  }
+
+  private ensureCapacity(needed: number): void {
+    const required = this.pos + needed;
+    if (required <= this.buffer.byteLength) return;
+
+    let newSize = this.buffer.byteLength * 2;
+    while (newSize < required) newSize *= 2;
+
+    const newBuffer = new Uint8Array(newSize);
+    newBuffer.set(this.buffer);
+    this.buffer = newBuffer;
+    this.view = new DataView(this.buffer.buffer);
+  }
+
+  writeUint8(value: number): void {
+    this.ensureCapacity(1);
+    this.view.setUint8(this.pos, value);
+    this.pos += 1;
+  }
+
+  writeBytes(bytes: Uint8Array): void {
+    this.ensureCapacity(bytes.byteLength);
+    this.buffer.set(bytes, this.pos);
+    this.pos += bytes.byteLength;
+  }
+
+  writeVarInt(value: number | bigint): void {
+    const v = BigInt(value);
+    if (v < 0n) throw new Error('VarInt value must be non-negative');
+
+    if (v < 0x40n) {
+      this.ensureCapacity(1);
+      this.view.setUint8(this.pos, Number(v));
+      this.pos += 1;
+    } else if (v < 0x4000n) {
+      this.ensureCapacity(2);
+      this.view.setUint16(this.pos, Number(v) | 0x4000);
+      this.pos += 2;
+    } else if (v < 0x40000000n) {
+      this.ensureCapacity(4);
+      this.view.setUint32(this.pos, Number(v) | 0x80000000);
+      this.pos += 4;
+    } else if (v < 0x4000000000000000n) {
+      this.ensureCapacity(8);
+      this.view.setBigUint64(this.pos, v | 0xc000000000000000n);
+      this.pos += 8;
+    } else {
+      throw new Error('VarInt value exceeds 62-bit range');
+    }
+  }
+
+  writeString(str: string): void {
+    const encoded = new TextEncoder().encode(str);
+    this.writeVarInt(encoded.byteLength);
+    this.writeBytes(encoded);
+  }
+
+  writeTuple(values: string[]): void {
+    this.writeVarInt(values.length);
+    for (const v of values) {
+      this.writeString(v);
+    }
+  }
+
+  writeParameters(params: Map<bigint, Uint8Array>): void {
+    this.writeVarInt(params.size);
+    for (const [key, value] of params) {
+      this.writeVarInt(key);
+      this.writeVarInt(value.byteLength);
+      this.writeBytes(value);
+    }
+  }
+
+  finish(): Uint8Array {
+    return this.buffer.slice(0, this.pos);
+  }
+}

package/src/core/errors.ts

@@ -0,0 +1 @@
+export { DecodeError, type DecodeErrorCode } from './types.js';

package/src/core/session-types.ts

@@ -0,0 +1,103 @@
+import type { Codec, MoqtMessage, MoqtMessageType } from './types.js';
+
+export type SessionPhase =
+  | 'idle'
+  | 'setup'
+  | 'ready'
+  | 'draining'
+  | 'closed'
+  | 'error';
+
+export type SubscriptionPhase =
+  | 'pending'
+  | 'active'
+  | 'error'
+  | 'done';
+
+export type AnnouncePhase =
+  | 'pending'
+  | 'active'
+  | 'error';
+
+export type PublishPhase = 'pending' | 'active' | 'error' | 'done';
+
+export type FetchPhase = 'pending' | 'active' | 'error' | 'cancelled';
+
+export interface SubscriptionState {
+  readonly subscribeId: bigint;
+  readonly phase: SubscriptionPhase;
+  readonly trackNamespace: string[];
+  readonly trackName: string;
+}
+
+export interface AnnounceState {
+  readonly namespace: string[];
+  readonly phase: AnnouncePhase;
+}
+
+export interface PublishState {
+  readonly requestId: bigint;
+  readonly phase: PublishPhase;
+}
+
+export interface FetchState {
+  readonly requestId: bigint;
+  readonly phase: FetchPhase;
+}
+
+export interface SessionStateOptions {
+  codec: { draft: string };
+  role: 'client' | 'server';
+}
+
+export interface SessionState<M = MoqtMessage, T extends string = MoqtMessageType> {
+  readonly phase: SessionPhase;
+  readonly role: 'client' | 'server';
+  receive(message: M): TransitionResult<T>;
+  validateOutgoing(message: M): ValidationResult<T>;
+  send(message: M): TransitionResult<T>;
+  readonly subscriptions: ReadonlyMap<bigint, SubscriptionState>;
+  readonly announces: ReadonlyMap<string, AnnounceState>;
+  readonly legalOutgoing: ReadonlySet<T>;
+  readonly legalIncoming: ReadonlySet<T>;
+  reset(): void;
+}
+
+export type TransitionResult<T extends string = MoqtMessageType> =
+  | { ok: true; phase: SessionPhase; sideEffects: SideEffect[] }
+  | { ok: false; violation: ProtocolViolation<T> };
+
+export type ValidationResult<T extends string = MoqtMessageType> =
+  | { ok: true }
+  | { ok: false; violation: ProtocolViolation<T> };
+
+export interface ProtocolViolation<T extends string = MoqtMessageType> {
+  readonly code: ProtocolViolationCode;
+  readonly message: string;
+  readonly currentPhase: SessionPhase;
+  readonly offendingMessage: T;
+}
+
+export type ProtocolViolationCode =
+  | 'MESSAGE_BEFORE_SETUP'
+  | 'UNEXPECTED_MESSAGE'
+  | 'DUPLICATE_SUBSCRIBE_ID'
+  | 'UNKNOWN_SUBSCRIBE_ID'
+  | 'DUPLICATE_REQUEST_ID'
+  | 'UNKNOWN_REQUEST_ID'
+  | 'ROLE_VIOLATION'
+  | 'STATE_VIOLATION'
+  | 'SETUP_VIOLATION';
+
+export type SideEffect =
+  | { type: 'subscription-activated'; subscribeId: bigint }
+  | { type: 'subscription-ended'; subscribeId: bigint; reason: string }
+  | { type: 'announce-activated'; namespace: string[] }
+  | { type: 'announce-ended'; namespace: string[] }
+  | { type: 'publish-activated'; requestId: bigint }
+  | { type: 'publish-ended'; requestId: bigint; reason: string }
+  | { type: 'fetch-activated'; requestId: bigint }
+  | { type: 'fetch-ended'; requestId: bigint; reason: string }
+  | { type: 'session-ready' }
+  | { type: 'session-draining'; goAwayUri: string }
+  | { type: 'session-closed' };

package/src/core/types.ts

@@ -0,0 +1,363 @@
+// Draft identifiers
+export type Draft = 'draft-ietf-moq-transport-07' | 'draft-ietf-moq-transport-14';
+export type DraftShorthand = '07' | '14';
+
+// All MoQT message type tags
+export type MoqtMessageType =
+  | 'client_setup'
+  | 'server_setup'
+  | 'subscribe'
+  | 'subscribe_ok'
+  | 'subscribe_error'
+  | 'subscribe_done'
+  | 'subscribe_update'
+  | 'unsubscribe'
+  | 'announce'
+  | 'announce_ok'
+  | 'announce_error'
+  | 'announce_cancel'
+  | 'unannounce'
+  | 'track_status_request'
+  | 'track_status'
+  | 'object_stream'
+  | 'object_datagram'
+  | 'stream_header_track'
+  | 'stream_header_group'
+  | 'stream_header_subgroup'
+  | 'goaway'
+  | 'subscribe_announces'
+  | 'subscribe_announces_ok'
+  | 'subscribe_announces_error'
+  | 'unsubscribe_announces'
+  | 'max_subscribe_id'
+  | 'fetch'
+  | 'fetch_ok'
+  | 'fetch_error'
+  | 'fetch_cancel';
+
+// Base message interface
+export interface BaseMessage {
+  readonly type: MoqtMessageType;
+}
+
+// Setup messages
+export interface ClientSetup extends BaseMessage {
+  readonly type: 'client_setup';
+  readonly supportedVersions: bigint[];
+  readonly parameters: Map<bigint, Uint8Array>;
+}
+
+export interface ServerSetup extends BaseMessage {
+  readonly type: 'server_setup';
+  readonly selectedVersion: bigint;
+  readonly parameters: Map<bigint, Uint8Array>;
+}
+
+// Subscribe messages
+export interface Subscribe extends BaseMessage {
+  readonly type: 'subscribe';
+  readonly subscribeId: bigint;
+  readonly trackAlias: bigint;
+  readonly trackNamespace: string[];
+  readonly trackName: string;
+  readonly subscriberPriority: number;
+  readonly groupOrder: GroupOrderValue;
+  readonly filterType: FilterType;
+  readonly startGroup?: bigint;
+  readonly startObject?: bigint;
+  readonly endGroup?: bigint;
+  readonly endObject?: bigint;
+  readonly parameters: Map<bigint, Uint8Array>;
+}
+
+export type FilterType = 'latest_group' | 'latest_object' | 'absolute_start' | 'absolute_range';
+
+export interface SubscribeOk extends BaseMessage {
+  readonly type: 'subscribe_ok';
+  readonly subscribeId: bigint;
+  readonly expires: bigint;
+  readonly groupOrder: GroupOrderValue;
+  readonly contentExists: boolean;
+  readonly largestGroupId?: bigint;
+  readonly largestObjectId?: bigint;
+  readonly parameters: Map<bigint, Uint8Array>;
+}
+
+export type GroupOrderValue = 'ascending' | 'descending' | 'original';
+
+export interface SubscribeError extends BaseMessage {
+  readonly type: 'subscribe_error';
+  readonly subscribeId: bigint;
+  readonly errorCode: bigint;
+  readonly reasonPhrase: string;
+  readonly trackAlias: bigint;
+}
+
+export interface SubscribeDone extends BaseMessage {
+  readonly type: 'subscribe_done';
+  readonly subscribeId: bigint;
+  readonly statusCode: bigint;
+  readonly reasonPhrase: string;
+  readonly contentExists: boolean;
+  readonly finalGroupId?: bigint;
+  readonly finalObjectId?: bigint;
+}
+
+export interface SubscribeUpdate extends BaseMessage {
+  readonly type: 'subscribe_update';
+  readonly subscribeId: bigint;
+  readonly startGroup: bigint;
+  readonly startObject: bigint;
+  readonly endGroup: bigint;
+  readonly endObject: bigint;
+  readonly subscriberPriority: number;
+  readonly parameters: Map<bigint, Uint8Array>;
+}
+
+export interface Unsubscribe extends BaseMessage {
+  readonly type: 'unsubscribe';
+  readonly subscribeId: bigint;
+}
+
+// Announce messages
+export interface Announce extends BaseMessage {
+  readonly type: 'announce';
+  readonly trackNamespace: string[];
+  readonly parameters: Map<bigint, Uint8Array>;
+}
+
+export interface AnnounceOk extends BaseMessage {
+  readonly type: 'announce_ok';
+  readonly trackNamespace: string[];
+}
+
+export interface AnnounceError extends BaseMessage {
+  readonly type: 'announce_error';
+  readonly trackNamespace: string[];
+  readonly errorCode: bigint;
+  readonly reasonPhrase: string;
+}
+
+export interface AnnounceCancel extends BaseMessage {
+  readonly type: 'announce_cancel';
+  readonly trackNamespace: string[];
+  readonly errorCode: bigint;
+  readonly reasonPhrase: string;
+}
+
+export interface Unannounce extends BaseMessage {
+  readonly type: 'unannounce';
+  readonly trackNamespace: string[];
+}
+
+// Track status
+export interface TrackStatusRequest extends BaseMessage {
+  readonly type: 'track_status_request';
+  readonly trackNamespace: string[];
+  readonly trackName: string;
+}
+
+export interface TrackStatus extends BaseMessage {
+  readonly type: 'track_status';
+  readonly trackNamespace: string[];
+  readonly trackName: string;
+  readonly statusCode: bigint;
+  readonly lastGroupId: bigint;
+  readonly lastObjectId: bigint;
+}
+
+// Object/stream messages
+export interface ObjectStream extends BaseMessage {
+  readonly type: 'object_stream';
+  readonly subscribeId: bigint;
+  readonly trackAlias: bigint;
+  readonly groupId: bigint;
+  readonly objectId: bigint;
+  readonly publisherPriority: number;
+  readonly objectStatus?: number;
+  readonly payload: Uint8Array;
+}
+
+export interface ObjectDatagram extends BaseMessage {
+  readonly type: 'object_datagram';
+  readonly subscribeId: bigint;
+  readonly trackAlias: bigint;
+  readonly groupId: bigint;
+  readonly objectId: bigint;
+  readonly publisherPriority: number;
+  readonly objectStatus?: number;
+  readonly payload: Uint8Array;
+}
+
+export interface StreamHeaderTrack extends BaseMessage {
+  readonly type: 'stream_header_track';
+  readonly subscribeId: bigint;
+  readonly trackAlias: bigint;
+  readonly publisherPriority: number;
+}
+
+export interface StreamHeaderGroup extends BaseMessage {
+  readonly type: 'stream_header_group';
+  readonly subscribeId: bigint;
+  readonly trackAlias: bigint;
+  readonly groupId: bigint;
+  readonly publisherPriority: number;
+}
+
+export interface StreamHeaderSubgroup extends BaseMessage {
+  readonly type: 'stream_header_subgroup';
+  readonly subscribeId: bigint;
+  readonly trackAlias: bigint;
+  readonly groupId: bigint;
+  readonly subgroupId: bigint;
+  readonly publisherPriority: number;
+}
+
+// GoAway
+export interface GoAway extends BaseMessage {
+  readonly type: 'goaway';
+  readonly newSessionUri: string;
+}
+
+// Subscribe Announces
+export interface SubscribeAnnounces extends BaseMessage {
+  readonly type: 'subscribe_announces';
+  readonly trackNamespace: string[];
+  readonly parameters: Map<bigint, Uint8Array>;
+}
+
+export interface SubscribeAnnouncesOk extends BaseMessage {
+  readonly type: 'subscribe_announces_ok';
+  readonly trackNamespace: string[];
+}
+
+export interface SubscribeAnnouncesError extends BaseMessage {
+  readonly type: 'subscribe_announces_error';
+  readonly trackNamespace: string[];
+  readonly errorCode: bigint;
+  readonly reasonPhrase: string;
+}
+
+// Unsubscribe Announces
+export interface UnsubscribeAnnounces extends BaseMessage {
+  readonly type: 'unsubscribe_announces';
+  readonly trackNamespace: string[];
+}
+
+// Max Subscribe ID
+export interface MaxSubscribeId extends BaseMessage {
+  readonly type: 'max_subscribe_id';
+  readonly subscribeId: bigint;
+}
+
+// Fetch
+export interface Fetch extends BaseMessage {
+  readonly type: 'fetch';
+  readonly subscribeId: bigint;
+  readonly trackNamespace: string[];
+  readonly trackName: string;
+  readonly subscriberPriority: number;
+  readonly groupOrder: GroupOrderValue;
+  readonly startGroup: bigint;
+  readonly startObject: bigint;
+  readonly endGroup: bigint;
+  readonly endObject: bigint;
+  readonly parameters: Map<bigint, Uint8Array>;
+}
+
+export interface FetchOk extends BaseMessage {
+  readonly type: 'fetch_ok';
+  readonly subscribeId: bigint;
+  readonly groupOrder: GroupOrderValue;
+  readonly endOfTrack: boolean;
+  readonly largestGroupId: bigint;
+  readonly largestObjectId: bigint;
+  readonly parameters: Map<bigint, Uint8Array>;
+}
+
+export interface FetchError extends BaseMessage {
+  readonly type: 'fetch_error';
+  readonly subscribeId: bigint;
+  readonly errorCode: bigint;
+  readonly reasonPhrase: string;
+}
+
+export interface FetchCancel extends BaseMessage {
+  readonly type: 'fetch_cancel';
+  readonly subscribeId: bigint;
+}
+
+// Union type of all messages
+export type MoqtMessage =
+  | ClientSetup
+  | ServerSetup
+  | Subscribe
+  | SubscribeOk
+  | SubscribeError
+  | SubscribeDone
+  | SubscribeUpdate
+  | Unsubscribe
+  | Announce
+  | AnnounceOk
+  | AnnounceError
+  | AnnounceCancel
+  | Unannounce
+  | TrackStatusRequest
+  | TrackStatus
+  | ObjectStream
+  | ObjectDatagram
+  | StreamHeaderTrack
+  | StreamHeaderGroup
+  | StreamHeaderSubgroup
+  | GoAway
+  | SubscribeAnnounces
+  | SubscribeAnnouncesOk
+  | SubscribeAnnouncesError
+  | UnsubscribeAnnounces
+  | MaxSubscribeId
+  | Fetch
+  | FetchOk
+  | FetchError
+  | FetchCancel;
+
+// Base codec interface — draft-specific codecs extend this
+export interface BaseCodec<M = MoqtMessage> {
+  readonly draft: Draft;
+  encodeMessage(message: M): Uint8Array;
+  decodeMessage(bytes: Uint8Array): DecodeResult<M>;
+}
+
+// Full codec interface for drafts that support varint + stream decode
+export interface Codec extends BaseCodec<MoqtMessage> {
+  encodeVarInt(value: number | bigint): Uint8Array;
+  decodeVarInt(bytes: Uint8Array, offset?: number): DecodeResult<bigint>;
+  createStreamDecoder(): TransformStream<Uint8Array, MoqtMessage>;
+}
+
+export interface CodecOptions {
+  draft: Draft | DraftShorthand;
+}
+
+// Result types
+export type DecodeResult<T> =
+  | { ok: true; value: T; bytesRead: number }
+  | { ok: false; error: DecodeError };
+
+export type DecodeErrorCode =
+  | 'UNEXPECTED_END'
+  | 'INVALID_VARINT'
+  | 'UNKNOWN_MESSAGE_TYPE'
+  | 'INVALID_PARAMETER'
+  | 'CONSTRAINT_VIOLATION';
+
+export class DecodeError extends Error {
+  readonly code: DecodeErrorCode;
+  readonly offset: number;
+
+  constructor(code: DecodeErrorCode, message: string, offset: number) {
+    super(message);
+    this.name = 'DecodeError';
+    this.code = code;
+    this.offset = offset;
+  }
+}

package/src/drafts/draft07/announce-fsm.ts

@@ -0,0 +1,2 @@
+// Announce state tracking is integrated into SessionFSM.
+export type { AnnounceState, AnnouncePhase } from '../../core/session-types.js';