@moqtap/trace 0.1.0

package/dist/index.cjs

@@ -0,0 +1,493 @@
+"use strict";Object.defineProperty(exports, "__esModule", {value: true}); function _nullishCoalesce(lhs, rhsFn) { if (lhs != null) { return lhs; } else { return rhsFn(); } }// src/binary.ts
+var _cborx = require('cbor-x');
+var MAGIC = new Uint8Array([77, 79, 81, 84, 82, 65, 67, 69]);
+var FORMAT_VERSION = 1;
+var PREAMBLE_SIZE = 16;
+var EVENT_TYPE_TO_INT = {
+  "control": 0,
+  "stream-opened": 1,
+  "stream-closed": 2,
+  "object-header": 3,
+  "object-payload": 4,
+  "state-change": 5,
+  "error": 6,
+  "annotation": 7
+};
+var INT_TO_EVENT_TYPE = {
+  0: "control",
+  1: "stream-opened",
+  2: "stream-closed",
+  3: "object-header",
+  4: "object-payload",
+  5: "state-change",
+  6: "error",
+  7: "annotation"
+};
+function headerToCbor(header) {
+  const map = {
+    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) {
+  return {
+    protocol: obj.protocol,
+    perspective: obj.perspective,
+    detail: obj.detail,
+    startTime: obj.startTime,
+    ...obj.endTime != null ? { endTime: obj.endTime } : {},
+    ...obj.transport != null ? { transport: obj.transport } : {},
+    ...obj.source != null ? { source: obj.source } : {},
+    ...obj.endpoint != null ? { endpoint: obj.endpoint } : {},
+    ...obj.sessionId != null ? { sessionId: obj.sessionId } : {},
+    ...obj.custom != null ? { custom: obj.custom } : {}
+  };
+}
+function eventToCbor(event) {
+  const base = {
+    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 !== void 0) base.data = event.data;
+      break;
+    }
+  }
+  return base;
+}
+function cborToEvent(obj) {
+  const eventType = INT_TO_EVENT_TYPE[obj.e];
+  if (eventType == null) {
+    return {
+      type: "annotation",
+      seq: Number(_nullishCoalesce(obj.n, () => ( 0))),
+      timestamp: Number(_nullishCoalesce(obj.t, () => ( 0))),
+      label: `unknown-event-${obj.e}`,
+      data: obj
+    };
+  }
+  const seq = Number(_nullishCoalesce(obj.n, () => ( 0)));
+  const timestamp = Number(_nullishCoalesce(obj.t, () => ( 0)));
+  switch (eventType) {
+    case "control":
+      return {
+        type: "control",
+        seq,
+        timestamp,
+        direction: obj.d,
+        messageType: Number(_nullishCoalesce(obj.mt, () => ( 0))),
+        message: _nullishCoalesce(obj.msg, () => ( {})),
+        ...obj.raw != null ? { raw: obj.raw } : {}
+      };
+    case "stream-opened":
+      return {
+        type: "stream-opened",
+        seq,
+        timestamp,
+        streamId: BigInt(obj.sid),
+        direction: obj.d,
+        streamType: obj.st
+      };
+    case "stream-closed":
+      return {
+        type: "stream-closed",
+        seq,
+        timestamp,
+        streamId: BigInt(obj.sid),
+        errorCode: Number(_nullishCoalesce(obj.ec, () => ( 0)))
+      };
+    case "object-header":
+      return {
+        type: "object-header",
+        seq,
+        timestamp,
+        streamId: BigInt(obj.sid),
+        groupId: BigInt(obj.g),
+        objectId: BigInt(obj.o),
+        publisherPriority: Number(_nullishCoalesce(obj.pp, () => ( 0))),
+        objectStatus: Number(_nullishCoalesce(obj.os, () => ( 0)))
+      };
+    case "object-payload":
+      return {
+        type: "object-payload",
+        seq,
+        timestamp,
+        streamId: BigInt(obj.sid),
+        groupId: BigInt(obj.g),
+        objectId: BigInt(obj.o),
+        size: Number(_nullishCoalesce(obj.sz, () => ( 0))),
+        ...obj.pl != null ? { payload: obj.pl } : {}
+      };
+    case "state-change":
+      return {
+        type: "state-change",
+        seq,
+        timestamp,
+        from: obj.from,
+        to: obj.to
+      };
+    case "error":
+      return {
+        type: "error",
+        seq,
+        timestamp,
+        errorCode: Number(_nullishCoalesce(obj.ec, () => ( 0))),
+        reason: _nullishCoalesce(obj.reason, () => ( ""))
+      };
+    case "annotation":
+      return {
+        type: "annotation",
+        seq,
+        timestamp,
+        label: _nullishCoalesce(obj.label, () => ( "")),
+        data: obj.data
+      };
+  }
+}
+function writePreamble(headerCbor) {
+  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) {
+  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 };
+}
+function writeMoqtrace(trace) {
+  const headerCbor = _cborx.encode.call(void 0, headerToCbor(trace.header));
+  const preamble = writePreamble(headerCbor);
+  const eventChunks = [];
+  let totalEventBytes = 0;
+  for (const event of trace.events) {
+    const chunk = _cborx.encode.call(void 0, 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;
+}
+function readMoqtrace(bytes) {
+  const { headerLength } = validatePreamble(bytes);
+  const headerBytes = bytes.slice(PREAMBLE_SIZE, PREAMBLE_SIZE + headerLength);
+  const header = cborToHeader(_cborx.decode.call(void 0, headerBytes));
+  const eventBytes = bytes.slice(PREAMBLE_SIZE + headerLength);
+  const events = [];
+  if (eventBytes.length > 0) {
+    _cborx.decodeMultiple.call(void 0, eventBytes, (obj) => {
+      events.push(cborToEvent(obj));
+    });
+  }
+  return { header, events };
+}
+function readMoqtraceHeader(bytes) {
+  const { headerLength } = validatePreamble(bytes);
+  const headerBytes = bytes.slice(PREAMBLE_SIZE, PREAMBLE_SIZE + headerLength);
+  return cborToHeader(_cborx.decode.call(void 0, headerBytes));
+}
+function createMoqtraceWriter(header) {
+  const headerCbor = _cborx.encode.call(void 0, headerToCbor(header));
+  const preambleBytes = writePreamble(headerCbor);
+  return {
+    preamble() {
+      return preambleBytes;
+    },
+    writeEvent(event) {
+      return _cborx.encode.call(void 0, eventToCbor(event));
+    }
+  };
+}
+
+// src/recorder.ts
+var DETAIL_RANK = {
+  "control": 0,
+  "headers": 1,
+  "headers+sizes": 2,
+  "headers+data": 3,
+  "full": 4
+};
+function createRecorder(options) {
+  const detail = options.detail;
+  const detailRank = DETAIL_RANK[detail];
+  const maxEvents = _nullishCoalesce(options.maxEvents, () => ( 1e5));
+  const clock = _nullishCoalesce(options.clock, () => ( (() => Math.round(performance.now() * 1e3))));
+  const messageTypeId = _nullishCoalesce(options.messageTypeId, () => ( (() => 0)));
+  const events = [];
+  let _recording = true;
+  let _seq = 0;
+  const startTime = Date.now();
+  function addEvent(event) {
+    if (!_recording) return;
+    if (events.length >= maxEvents) {
+      events.shift();
+    }
+    events.push(event);
+  }
+  function nextSeq() {
+    return _seq++;
+  }
+  function wrapSession(session) {
+    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) {
+        const prevPhase = session.phase;
+        const result = session.receive(message);
+        addEvent({
+          type: "control",
+          seq: nextSeq(),
+          timestamp: clock(),
+          direction: 1,
+          // rx
+          messageType: messageTypeId(message.type),
+          message
+        });
+        if (result.ok && result.phase !== prevPhase) {
+          addEvent({
+            type: "state-change",
+            seq: nextSeq(),
+            timestamp: clock(),
+            from: prevPhase,
+            to: result.phase
+          });
+        }
+        return result;
+      },
+      validateOutgoing(message) {
+        return session.validateOutgoing(message);
+      },
+      send(message) {
+        const prevPhase = session.phase;
+        const result = session.send(message);
+        addEvent({
+          type: "control",
+          seq: nextSeq(),
+          timestamp: clock(),
+          direction: 0,
+          // tx
+          messageType: messageTypeId(message.type),
+          message
+        });
+        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 = {
+        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() {
+      _recording = false;
+      const header = {
+        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;
+    }
+  };
+}
+
+// src/json.ts
+function traceToJSON(trace) {
+  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);
+}
+
+
+
+
+
+
+
+exports.createMoqtraceWriter = createMoqtraceWriter; exports.createRecorder = createRecorder; exports.readMoqtrace = readMoqtrace; exports.readMoqtraceHeader = readMoqtraceHeader; exports.traceToJSON = traceToJSON; exports.writeMoqtrace = writeMoqtrace;

package/dist/index.d.cts

@@ -0,0 +1,146 @@
+import { SessionState } from '@moqtap/codec/session';
+
+type DetailLevel = 'control' | 'headers' | 'headers+sizes' | 'headers+data' | 'full';
+type Perspective = 'client' | 'server' | 'observer';
+interface TraceHeader {
+    readonly protocol: string;
+    readonly perspective: Perspective;
+    readonly detail: DetailLevel;
+    readonly startTime: number;
+    readonly endTime?: number;
+    readonly transport?: string;
+    readonly source?: string;
+    readonly endpoint?: string;
+    readonly sessionId?: string;
+    readonly custom?: Record<string, unknown>;
+}
+interface BaseEvent {
+    readonly seq: number;
+    readonly timestamp: number;
+}
+interface ControlMessageEvent extends BaseEvent {
+    readonly type: 'control';
+    readonly direction: 0 | 1;
+    readonly messageType: number;
+    readonly message: Record<string, unknown>;
+    readonly raw?: Uint8Array;
+}
+interface StreamOpenedEvent extends BaseEvent {
+    readonly type: 'stream-opened';
+    readonly streamId: bigint;
+    readonly direction: 0 | 1;
+    readonly streamType: 0 | 1 | 2;
+}
+interface StreamClosedEvent extends BaseEvent {
+    readonly type: 'stream-closed';
+    readonly streamId: bigint;
+    readonly errorCode: number;
+}
+interface ObjectHeaderEvent extends BaseEvent {
+    readonly type: 'object-header';
+    readonly streamId: bigint;
+    readonly groupId: bigint;
+    readonly objectId: bigint;
+    readonly publisherPriority: number;
+    readonly objectStatus: number;
+}
+interface ObjectPayloadEvent extends BaseEvent {
+    readonly type: 'object-payload';
+    readonly streamId: bigint;
+    readonly groupId: bigint;
+    readonly objectId: bigint;
+    readonly size: number;
+    readonly payload?: Uint8Array;
+}
+interface StateChangeEvent extends BaseEvent {
+    readonly type: 'state-change';
+    readonly from: string;
+    readonly to: string;
+}
+interface TraceErrorEvent extends BaseEvent {
+    readonly type: 'error';
+    readonly errorCode: number;
+    readonly reason: string;
+}
+interface AnnotationEvent extends BaseEvent {
+    readonly type: 'annotation';
+    readonly label: string;
+    readonly data: unknown;
+}
+type TraceEvent = ControlMessageEvent | StreamOpenedEvent | StreamClosedEvent | ObjectHeaderEvent | ObjectPayloadEvent | StateChangeEvent | TraceErrorEvent | AnnotationEvent;
+interface Trace {
+    readonly header: TraceHeader;
+    readonly events: TraceEvent[];
+}
+interface RecorderOptions {
+    readonly detail: DetailLevel;
+    readonly protocol: string;
+    readonly perspective: Perspective;
+    readonly transport?: string;
+    readonly source?: string;
+    readonly endpoint?: string;
+    readonly sessionId?: string;
+    readonly maxEvents?: number;
+    readonly clock?: () => number;
+    /** Map message type name (e.g. 'subscribe') to wire ID (e.g. 0x03). Required for session-layer recording. */
+    readonly messageTypeId?: (name: string) => number;
+}
+
+/**
+ * Write a complete trace to .moqtrace binary format.
+ */
+declare function writeMoqtrace(trace: Trace): Uint8Array;
+/**
+ * Read a complete .moqtrace file from bytes.
+ */
+declare function readMoqtrace(bytes: Uint8Array): Trace;
+/**
+ * Read only the header from a .moqtrace file (fast metadata peek).
+ */
+declare function readMoqtraceHeader(bytes: Uint8Array): TraceHeader;
+/**
+ * Streaming writer for building .moqtrace files incrementally.
+ */
+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;
+}
+declare function createMoqtraceWriter(header: TraceHeader): MoqtraceWriter;
+
+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;
+}
+declare function createRecorder(options: RecorderOptions): TraceRecorder;
+
+/**
+ * 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`).
+ */
+declare function traceToJSON(trace: Trace): string;
+
+export { type AnnotationEvent, type ControlMessageEvent, type DetailLevel, type MoqtraceWriter, type ObjectHeaderEvent, type ObjectPayloadEvent, type Perspective, type RecorderOptions, type StateChangeEvent, type StreamClosedEvent, type StreamOpenedEvent, type Trace, type TraceErrorEvent, type TraceEvent, type TraceHeader, type TraceRecorder, createMoqtraceWriter, createRecorder, readMoqtrace, readMoqtraceHeader, traceToJSON, writeMoqtrace };