@moqtap/trace 0.1.0

package/src/binary.ts

@@ -0,0 +1,351 @@
+import { encode, decode, decodeMultiple } from 'cbor-x';
+import type {
+  Trace,
+  TraceHeader,
+  TraceEvent,
+  DetailLevel,
+  Perspective,
+} from './types.js';
+
+const MAGIC = new Uint8Array([0x4d, 0x4f, 0x51, 0x54, 0x52, 0x41, 0x43, 0x45]); // "MOQTRACE"
+const FORMAT_VERSION = 1;
+const PREAMBLE_SIZE = 16; // 8 magic + 4 version + 4 header length
+
+// Event type string ↔ integer mapping
+const EVENT_TYPE_TO_INT: Record<TraceEvent['type'], number> = {
+  'control': 0,
+  'stream-opened': 1,
+  'stream-closed': 2,
+  'object-header': 3,
+  'object-payload': 4,
+  'state-change': 5,
+  'error': 6,
+  'annotation': 7,
+};
+
+const INT_TO_EVENT_TYPE: Record<number, TraceEvent['type']> = {
+  0: 'control',
+  1: 'stream-opened',
+  2: 'stream-closed',
+  3: 'object-header',
+  4: 'object-payload',
+  5: 'state-change',
+  6: 'error',
+  7: 'annotation',
+};
+
+// --- Header serialization ---
+
+function headerToCbor(header: TraceHeader): Record<string, unknown> {
+  const map: Record<string, unknown> = {
+    protocol: header.protocol,
+    perspective: header.perspective,
+    detail: header.detail,
+    startTime: header.startTime,
+  };
+  if (header.endTime != null) map.endTime = header.endTime;
+  if (header.transport != null) map.transport = header.transport;
+  if (header.source != null) map.source = header.source;
+  if (header.endpoint != null) map.endpoint = header.endpoint;
+  if (header.sessionId != null) map.sessionId = header.sessionId;
+  if (header.custom != null) map.custom = header.custom;
+  return map;
+}
+
+function cborToHeader(obj: Record<string, unknown>): TraceHeader {
+  return {
+    protocol: obj.protocol as string,
+    perspective: obj.perspective as Perspective,
+    detail: obj.detail as DetailLevel,
+    startTime: obj.startTime as number,
+    ...(obj.endTime != null ? { endTime: obj.endTime as number } : {}),
+    ...(obj.transport != null ? { transport: obj.transport as string } : {}),
+    ...(obj.source != null ? { source: obj.source as string } : {}),
+    ...(obj.endpoint != null ? { endpoint: obj.endpoint as string } : {}),
+    ...(obj.sessionId != null ? { sessionId: obj.sessionId as string } : {}),
+    ...(obj.custom != null ? { custom: obj.custom as Record<string, unknown> } : {}),
+  };
+}
+
+// --- Event serialization ---
+
+function eventToCbor(event: TraceEvent): Record<string, unknown> {
+  const base: Record<string, unknown> = {
+    n: event.seq,
+    t: event.timestamp,
+    e: EVENT_TYPE_TO_INT[event.type],
+  };
+
+  switch (event.type) {
+    case 'control': {
+      base.d = event.direction;
+      base.mt = event.messageType;
+      base.msg = event.message;
+      if (event.raw != null) base.raw = event.raw;
+      break;
+    }
+    case 'stream-opened': {
+      base.sid = event.streamId;
+      base.d = event.direction;
+      base.st = event.streamType;
+      break;
+    }
+    case 'stream-closed': {
+      base.sid = event.streamId;
+      base.ec = event.errorCode;
+      break;
+    }
+    case 'object-header': {
+      base.sid = event.streamId;
+      base.g = event.groupId;
+      base.o = event.objectId;
+      base.pp = event.publisherPriority;
+      base.os = event.objectStatus;
+      break;
+    }
+    case 'object-payload': {
+      base.sid = event.streamId;
+      base.g = event.groupId;
+      base.o = event.objectId;
+      base.sz = event.size;
+      if (event.payload != null) base.pl = event.payload;
+      break;
+    }
+    case 'state-change': {
+      base.from = event.from;
+      base.to = event.to;
+      break;
+    }
+    case 'error': {
+      base.ec = event.errorCode;
+      base.reason = event.reason;
+      break;
+    }
+    case 'annotation': {
+      base.label = event.label;
+      if (event.data !== undefined) base.data = event.data;
+      break;
+    }
+  }
+
+  return base;
+}
+
+function cborToEvent(obj: Record<string, unknown>): TraceEvent {
+  const eventType = INT_TO_EVENT_TYPE[obj.e as number];
+  if (eventType == null) {
+    // Unknown event type — skip per spec (return annotation as fallback)
+    return {
+      type: 'annotation',
+      seq: Number(obj.n ?? 0),
+      timestamp: Number(obj.t ?? 0),
+      label: `unknown-event-${obj.e}`,
+      data: obj,
+    };
+  }
+
+  const seq = Number(obj.n ?? 0);
+  const timestamp = Number(obj.t ?? 0);
+
+  switch (eventType) {
+    case 'control':
+      return {
+        type: 'control' as const,
+        seq,
+        timestamp,
+        direction: obj.d as 0 | 1,
+        messageType: Number(obj.mt ?? 0),
+        message: (obj.msg ?? {}) as Record<string, unknown>,
+        ...(obj.raw != null ? { raw: obj.raw as Uint8Array } : {}),
+      };
+
+    case 'stream-opened':
+      return {
+        type: 'stream-opened' as const,
+        seq,
+        timestamp,
+        streamId: BigInt(obj.sid as bigint | number),
+        direction: obj.d as 0 | 1,
+        streamType: obj.st as 0 | 1 | 2,
+      };
+
+    case 'stream-closed':
+      return {
+        type: 'stream-closed' as const,
+        seq,
+        timestamp,
+        streamId: BigInt(obj.sid as bigint | number),
+        errorCode: Number(obj.ec ?? 0),
+      };
+
+    case 'object-header':
+      return {
+        type: 'object-header' as const,
+        seq,
+        timestamp,
+        streamId: BigInt(obj.sid as bigint | number),
+        groupId: BigInt(obj.g as bigint | number),
+        objectId: BigInt(obj.o as bigint | number),
+        publisherPriority: Number(obj.pp ?? 0),
+        objectStatus: Number(obj.os ?? 0),
+      };
+
+    case 'object-payload':
+      return {
+        type: 'object-payload' as const,
+        seq,
+        timestamp,
+        streamId: BigInt(obj.sid as bigint | number),
+        groupId: BigInt(obj.g as bigint | number),
+        objectId: BigInt(obj.o as bigint | number),
+        size: Number(obj.sz ?? 0),
+        ...(obj.pl != null ? { payload: obj.pl as Uint8Array } : {}),
+      };
+
+    case 'state-change':
+      return {
+        type: 'state-change' as const,
+        seq,
+        timestamp,
+        from: obj.from as string,
+        to: obj.to as string,
+      };
+
+    case 'error':
+      return {
+        type: 'error' as const,
+        seq,
+        timestamp,
+        errorCode: Number(obj.ec ?? 0),
+        reason: (obj.reason ?? '') as string,
+      };
+
+    case 'annotation':
+      return {
+        type: 'annotation' as const,
+        seq,
+        timestamp,
+        label: (obj.label ?? '') as string,
+        data: obj.data,
+      };
+  }
+}
+
+// --- Preamble helpers ---
+
+function writePreamble(headerCbor: Uint8Array): Uint8Array {
+  const buf = new Uint8Array(PREAMBLE_SIZE + headerCbor.length);
+  buf.set(MAGIC, 0);
+  const view = new DataView(buf.buffer, buf.byteOffset, buf.byteLength);
+  view.setUint32(8, FORMAT_VERSION, true);
+  view.setUint32(12, headerCbor.length, true);
+  buf.set(headerCbor, PREAMBLE_SIZE);
+  return buf;
+}
+
+function validatePreamble(bytes: Uint8Array): { version: number; headerLength: number } {
+  if (bytes.length < PREAMBLE_SIZE) {
+    throw new Error('File too short: expected at least 16 bytes');
+  }
+
+  for (let i = 0; i < 8; i++) {
+    if (bytes[i] !== MAGIC[i]) {
+      throw new Error('Invalid magic bytes: not a .moqtrace file');
+    }
+  }
+
+  const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+  const version = view.getUint32(8, true);
+  if (version !== FORMAT_VERSION) {
+    throw new Error(`Unsupported format version: ${version} (expected ${FORMAT_VERSION})`);
+  }
+
+  const headerLength = view.getUint32(12, true);
+  if (PREAMBLE_SIZE + headerLength > bytes.length) {
+    throw new Error('File truncated: header extends beyond file');
+  }
+
+  return { version, headerLength };
+}
+
+// --- Public API ---
+
+/**
+ * Write a complete trace to .moqtrace binary format.
+ */
+export function writeMoqtrace(trace: Trace): Uint8Array {
+  const headerCbor = encode(headerToCbor(trace.header));
+  const preamble = writePreamble(headerCbor);
+
+  const eventChunks: Uint8Array[] = [];
+  let totalEventBytes = 0;
+  for (const event of trace.events) {
+    const chunk = encode(eventToCbor(event));
+    eventChunks.push(chunk);
+    totalEventBytes += chunk.length;
+  }
+
+  const result = new Uint8Array(preamble.length + totalEventBytes);
+  result.set(preamble, 0);
+  let offset = preamble.length;
+  for (const chunk of eventChunks) {
+    result.set(chunk, offset);
+    offset += chunk.length;
+  }
+
+  return result;
+}
+
+/**
+ * Read a complete .moqtrace file from bytes.
+ */
+export function readMoqtrace(bytes: Uint8Array): Trace {
+  const { headerLength } = validatePreamble(bytes);
+
+  const headerBytes = bytes.slice(PREAMBLE_SIZE, PREAMBLE_SIZE + headerLength);
+  const header = cborToHeader(decode(headerBytes) as Record<string, unknown>);
+
+  const eventBytes = bytes.slice(PREAMBLE_SIZE + headerLength);
+  const events: TraceEvent[] = [];
+
+  if (eventBytes.length > 0) {
+    decodeMultiple(eventBytes, (obj: unknown) => {
+      events.push(cborToEvent(obj as Record<string, unknown>));
+    });
+  }
+
+  return { header, events };
+}
+
+/**
+ * Read only the header from a .moqtrace file (fast metadata peek).
+ */
+export function readMoqtraceHeader(bytes: Uint8Array): TraceHeader {
+  const { headerLength } = validatePreamble(bytes);
+  const headerBytes = bytes.slice(PREAMBLE_SIZE, PREAMBLE_SIZE + headerLength);
+  return cborToHeader(decode(headerBytes) as Record<string, unknown>);
+}
+
+/**
+ * Streaming writer for building .moqtrace files incrementally.
+ */
+export interface MoqtraceWriter {
+  /** Returns the file preamble (magic + version + header). Write this first. */
+  preamble(): Uint8Array;
+  /** Encode a single event. Append the returned bytes after the preamble. */
+  writeEvent(event: TraceEvent): Uint8Array;
+}
+
+export function createMoqtraceWriter(header: TraceHeader): MoqtraceWriter {
+  const headerCbor = encode(headerToCbor(header));
+  const preambleBytes = writePreamble(headerCbor);
+
+  return {
+    preamble(): Uint8Array {
+      return preambleBytes;
+    },
+    writeEvent(event: TraceEvent): Uint8Array {
+      return encode(eventToCbor(event));
+    },
+  };
+}

package/src/index.ts

@@ -0,0 +1,33 @@
+// Binary .moqtrace format
+export {
+  writeMoqtrace,
+  readMoqtrace,
+  readMoqtraceHeader,
+  createMoqtraceWriter,
+} from './binary.js';
+export type { MoqtraceWriter } from './binary.js';
+
+// Recorder
+export { createRecorder } from './recorder.js';
+export type { TraceRecorder } from './recorder.js';
+
+// JSON (convenience)
+export { traceToJSON } from './json.js';
+
+// Types
+export type {
+  Trace,
+  TraceHeader,
+  TraceEvent,
+  ControlMessageEvent,
+  StreamOpenedEvent,
+  StreamClosedEvent,
+  ObjectHeaderEvent,
+  ObjectPayloadEvent,
+  StateChangeEvent,
+  TraceErrorEvent,
+  AnnotationEvent,
+  DetailLevel,
+  Perspective,
+  RecorderOptions,
+} from './types.js';

package/src/json.ts

@@ -0,0 +1,21 @@
+import type { Trace } from './types.js';
+
+/**
+ * Serialize a trace to human-readable JSON.
+ *
+ * Handles bigint → hex string and Uint8Array → hex string.
+ * This is a one-way export for human inspection and debugging.
+ * For lossless round-tripping, use the binary .moqtrace format
+ * (`writeMoqtrace` / `readMoqtrace`).
+ */
+export function traceToJSON(trace: Trace): string {
+  return JSON.stringify(trace, (_key, value) => {
+    if (typeof value === 'bigint') {
+      return `0x${value.toString(16)}`;
+    }
+    if (value instanceof Uint8Array) {
+      return Array.from(value).map(b => b.toString(16).padStart(2, '0')).join('');
+    }
+    return value;
+  }, 2);
+}

package/src/recorder.ts

@@ -0,0 +1,247 @@
+import type { MoqtMessage } from '@moqtap/codec';
+import type { SessionState } from '@moqtap/codec/session';
+import type {
+  Trace,
+  TraceHeader,
+  TraceEvent,
+  RecorderOptions,
+  DetailLevel,
+} from './types.js';
+
+export interface TraceRecorder {
+  /** Wrap a SessionState to auto-record control messages and state changes. */
+  wrapSession(session: SessionState): SessionState;
+
+  /** Record an arbitrary event manually. */
+  record(event: TraceEvent): void;
+
+  /** Record a stream-opened event. Ignored at 'control' detail level. */
+  recordStreamOpened(streamId: bigint, direction: 0 | 1, streamType: 0 | 1 | 2): void;
+
+  /** Record a stream-closed event. Ignored at 'control' detail level. */
+  recordStreamClosed(streamId: bigint, errorCode?: number): void;
+
+  /** Record an object header event. Ignored below 'headers' detail level. */
+  recordObjectHeader(
+    streamId: bigint, groupId: bigint, objectId: bigint,
+    publisherPriority: number, objectStatus: number,
+  ): void;
+
+  /** Record an object payload event. Ignored below 'headers+sizes' detail level. */
+  recordObjectPayload(
+    streamId: bigint, groupId: bigint, objectId: bigint,
+    size: number, payload?: Uint8Array,
+  ): void;
+
+  /** Record a protocol error. */
+  recordError(errorCode: number, reason: string): void;
+
+  /** Record a user-defined annotation. */
+  annotate(label: string, data?: unknown): void;
+
+  /** Finalize the trace. Stops recording and returns the trace. */
+  finalize(): Trace;
+
+  /** Whether the recorder is still accepting events. */
+  readonly recording: boolean;
+}
+
+const DETAIL_RANK: Record<DetailLevel, number> = {
+  'control': 0,
+  'headers': 1,
+  'headers+sizes': 2,
+  'headers+data': 3,
+  'full': 4,
+};
+
+export function createRecorder(options: RecorderOptions): TraceRecorder {
+  const detail = options.detail;
+  const detailRank = DETAIL_RANK[detail];
+  const maxEvents = options.maxEvents ?? 100_000;
+  const clock = options.clock ?? (() => Math.round(performance.now() * 1000));
+  const messageTypeId = options.messageTypeId ?? (() => 0);
+
+  const events: TraceEvent[] = [];
+  let _recording = true;
+  let _seq = 0;
+  const startTime = Date.now();
+
+  function addEvent(event: TraceEvent): void {
+    if (!_recording) return;
+    if (events.length >= maxEvents) {
+      events.shift();
+    }
+    events.push(event);
+  }
+
+  function nextSeq(): number {
+    return _seq++;
+  }
+
+  function wrapSession(session: SessionState): SessionState {
+    return {
+      get phase() { return session.phase; },
+      get role() { return session.role; },
+      get subscriptions() { return session.subscriptions; },
+      get announces() { return session.announces; },
+      get legalOutgoing() { return session.legalOutgoing; },
+      get legalIncoming() { return session.legalIncoming; },
+
+      receive(message: MoqtMessage) {
+        const prevPhase = session.phase;
+        const result = session.receive(message);
+
+        addEvent({
+          type: 'control',
+          seq: nextSeq(),
+          timestamp: clock(),
+          direction: 1, // rx
+          messageType: messageTypeId(message.type),
+          message: message as unknown as Record<string, unknown>,
+        });
+
+        if (result.ok && result.phase !== prevPhase) {
+          addEvent({
+            type: 'state-change',
+            seq: nextSeq(),
+            timestamp: clock(),
+            from: prevPhase,
+            to: result.phase,
+          });
+        }
+
+        return result;
+      },
+
+      validateOutgoing(message: MoqtMessage) {
+        return session.validateOutgoing(message);
+      },
+
+      send(message: MoqtMessage) {
+        const prevPhase = session.phase;
+        const result = session.send(message);
+
+        addEvent({
+          type: 'control',
+          seq: nextSeq(),
+          timestamp: clock(),
+          direction: 0, // tx
+          messageType: messageTypeId(message.type),
+          message: message as unknown as Record<string, unknown>,
+        });
+
+        if (result.ok && result.phase !== prevPhase) {
+          addEvent({
+            type: 'state-change',
+            seq: nextSeq(),
+            timestamp: clock(),
+            from: prevPhase,
+            to: result.phase,
+          });
+        }
+
+        return result;
+      },
+
+      reset() {
+        session.reset();
+      },
+    };
+  }
+
+  return {
+    wrapSession,
+
+    record: addEvent,
+
+    recordStreamOpened(streamId, direction, streamType) {
+      if (detailRank < DETAIL_RANK['headers']) return;
+      addEvent({
+        type: 'stream-opened',
+        seq: nextSeq(),
+        timestamp: clock(),
+        streamId,
+        direction,
+        streamType,
+      });
+    },
+
+    recordStreamClosed(streamId, errorCode = 0) {
+      if (detailRank < DETAIL_RANK['headers']) return;
+      addEvent({
+        type: 'stream-closed',
+        seq: nextSeq(),
+        timestamp: clock(),
+        streamId,
+        errorCode,
+      });
+    },
+
+    recordObjectHeader(streamId, groupId, objectId, publisherPriority, objectStatus) {
+      if (detailRank < DETAIL_RANK['headers']) return;
+      addEvent({
+        type: 'object-header',
+        seq: nextSeq(),
+        timestamp: clock(),
+        streamId,
+        groupId,
+        objectId,
+        publisherPriority,
+        objectStatus,
+      });
+    },
+
+    recordObjectPayload(streamId, groupId, objectId, size, payload) {
+      if (detailRank < DETAIL_RANK['headers+sizes']) return;
+      const event: TraceEvent = {
+        type: 'object-payload',
+        seq: nextSeq(),
+        timestamp: clock(),
+        streamId,
+        groupId,
+        objectId,
+        size,
+        ...(detailRank >= DETAIL_RANK['headers+data'] && payload != null ? { payload } : {}),
+      };
+      addEvent(event);
+    },
+
+    recordError(errorCode, reason) {
+      addEvent({
+        type: 'error',
+        seq: nextSeq(),
+        timestamp: clock(),
+        errorCode,
+        reason,
+      });
+    },
+
+    annotate(label, data) {
+      addEvent({
+        type: 'annotation',
+        seq: nextSeq(),
+        timestamp: clock(),
+        label,
+        data,
+      });
+    },
+
+    finalize(): Trace {
+      _recording = false;
+      const header: TraceHeader = {
+        protocol: options.protocol,
+        perspective: options.perspective,
+        detail,
+        startTime,
+        endTime: Date.now(),
+        ...(options.transport != null ? { transport: options.transport } : {}),
+        ...(options.source != null ? { source: options.source } : {}),
+        ...(options.endpoint != null ? { endpoint: options.endpoint } : {}),
+        ...(options.sessionId != null ? { sessionId: options.sessionId } : {}),
+      };
+      return { header, events: [...events] };
+    },
+
+    get recording() { return _recording; },
+  };
+}