@moqtap/trace 0.1.1 → 0.1.2

package/src/recorder.ts

@@ -1,19 +1,20 @@
-import type { MoqtMessage } from "@moqtap/codec";
-import type { SessionState } from "@moqtap/codec/session";
-import type { DetailLevel, RecorderOptions, Trace, TraceEvent, TraceHeader } from "./types.js";
+import type { SessionState } from '@moqtap/codec/session'
+import type { DetailLevel, RecorderOptions, Trace, TraceEvent, TraceHeader } from './types.js'
 
 export interface TraceRecorder {
   /** Wrap a SessionState to auto-record control messages and state changes. */
-  wrapSession(session: SessionState): SessionState;
+  wrapSession<M extends { type: string }, T extends string>(
+    session: SessionState<M, T>,
+  ): SessionState<M, T>
 
   /** Record an arbitrary event manually. */
-  record(event: TraceEvent): void;
+  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;
+  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;
+  recordStreamClosed(streamId: bigint, errorCode?: number): void
 
   /** Record an object header event. Ignored below 'headers' detail level. */
   recordObjectHeader(
@@ -22,7 +23,7 @@ export interface TraceRecorder {
     objectId: bigint,
     publisherPriority: number,
     objectStatus: number,
-  ): void;
+  ): void
 
   /** Record an object payload event. Ignored below 'headers+sizes' detail level. */
   recordObjectPayload(
@@ -31,134 +32,136 @@ export interface TraceRecorder {
     objectId: bigint,
     size: number,
     payload?: Uint8Array,
-  ): void;
+  ): void
 
   /** Record a protocol error. */
-  recordError(errorCode: number, reason: string): void;
+  recordError(errorCode: number, reason: string): void
 
   /** Record a user-defined annotation. */
-  annotate(label: string, data?: unknown): void;
+  annotate(label: string, data?: unknown): void
 
   /** Finalize the trace. Stops recording and returns the trace. */
-  finalize(): Trace;
+  finalize(): Trace
 
   /** Whether the recorder is still accepting events. */
-  readonly recording: boolean;
+  readonly recording: boolean
 }
 
 const DETAIL_RANK: Record<DetailLevel, number> = {
   control: 0,
   headers: 1,
-  "headers+sizes": 2,
-  "headers+data": 3,
+  '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 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();
+  const events: TraceEvent[] = []
+  let _recording = true
+  let _seq = 0
+  const startTime = Date.now()
 
   function addEvent(event: TraceEvent): void {
-    if (!_recording) return;
+    if (!_recording) return
     if (events.length >= maxEvents) {
-      events.shift();
+      events.shift()
     }
-    events.push(event);
+    events.push(event)
   }
 
   function nextSeq(): number {
-    return _seq++;
+    return _seq++
   }
 
-  function wrapSession(session: SessionState): SessionState {
+  function wrapSession<M extends { type: string }, T extends string>(
+    session: SessionState<M, T>,
+  ): SessionState<M, T> {
     return {
       get phase() {
-        return session.phase;
+        return session.phase
       },
       get role() {
-        return session.role;
+        return session.role
       },
       get subscriptions() {
-        return session.subscriptions;
+        return session.subscriptions
       },
       get announces() {
-        return session.announces;
+        return session.announces
       },
       get legalOutgoing() {
-        return session.legalOutgoing;
+        return session.legalOutgoing
       },
       get legalIncoming() {
-        return session.legalIncoming;
+        return session.legalIncoming
       },
 
-      receive(message: MoqtMessage) {
-        const prevPhase = session.phase;
-        const result = session.receive(message);
+      receive(message: M) {
+        const prevPhase = session.phase
+        const result = session.receive(message)
 
         addEvent({
-          type: "control",
+          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",
+            type: 'state-change',
             seq: nextSeq(),
             timestamp: clock(),
             from: prevPhase,
             to: result.phase,
-          });
+          })
         }
 
-        return result;
+        return result
       },
 
-      validateOutgoing(message: MoqtMessage) {
-        return session.validateOutgoing(message);
+      validateOutgoing(message: M) {
+        return session.validateOutgoing(message)
       },
 
-      send(message: MoqtMessage) {
-        const prevPhase = session.phase;
-        const result = session.send(message);
+      send(message: M) {
+        const prevPhase = session.phase
+        const result = session.send(message)
 
         addEvent({
-          type: "control",
+          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",
+            type: 'state-change',
             seq: nextSeq(),
             timestamp: clock(),
             from: prevPhase,
             to: result.phase,
-          });
+          })
         }
 
-        return result;
+        return result
       },
 
       reset() {
-        session.reset();
+        session.reset()
       },
-    };
+    }
   }
 
   return {
@@ -167,32 +170,32 @@ export function createRecorder(options: RecorderOptions): TraceRecorder {
     record: addEvent,
 
     recordStreamOpened(streamId, direction, streamType) {
-      if (detailRank < DETAIL_RANK.headers) return;
+      if (detailRank < DETAIL_RANK.headers) return
       addEvent({
-        type: "stream-opened",
+        type: 'stream-opened',
         seq: nextSeq(),
         timestamp: clock(),
         streamId,
         direction,
         streamType,
-      });
+      })
     },
 
     recordStreamClosed(streamId, errorCode = 0) {
-      if (detailRank < DETAIL_RANK.headers) return;
+      if (detailRank < DETAIL_RANK.headers) return
       addEvent({
-        type: "stream-closed",
+        type: 'stream-closed',
         seq: nextSeq(),
         timestamp: clock(),
         streamId,
         errorCode,
-      });
+      })
     },
 
     recordObjectHeader(streamId, groupId, objectId, publisherPriority, objectStatus) {
-      if (detailRank < DETAIL_RANK.headers) return;
+      if (detailRank < DETAIL_RANK.headers) return
       addEvent({
-        type: "object-header",
+        type: 'object-header',
         seq: nextSeq(),
         timestamp: clock(),
         streamId,
@@ -200,46 +203,46 @@ export function createRecorder(options: RecorderOptions): TraceRecorder {
         objectId,
         publisherPriority,
         objectStatus,
-      });
+      })
     },
 
     recordObjectPayload(streamId, groupId, objectId, size, payload) {
-      if (detailRank < DETAIL_RANK["headers+sizes"]) return;
+      if (detailRank < DETAIL_RANK['headers+sizes']) return
       const event: TraceEvent = {
-        type: "object-payload",
+        type: 'object-payload',
         seq: nextSeq(),
         timestamp: clock(),
         streamId,
         groupId,
         objectId,
         size,
-        ...(detailRank >= DETAIL_RANK["headers+data"] && payload != null ? { payload } : {}),
-      };
-      addEvent(event);
+        ...(detailRank >= DETAIL_RANK['headers+data'] && payload != null ? { payload } : {}),
+      }
+      addEvent(event)
     },
 
     recordError(errorCode, reason) {
       addEvent({
-        type: "error",
+        type: 'error',
         seq: nextSeq(),
         timestamp: clock(),
         errorCode,
         reason,
-      });
+      })
     },
 
     annotate(label, data) {
       addEvent({
-        type: "annotation",
+        type: 'annotation',
         seq: nextSeq(),
         timestamp: clock(),
         label,
         data,
-      });
+      })
     },
 
     finalize(): Trace {
-      _recording = false;
+      _recording = false
       const header: TraceHeader = {
         protocol: options.protocol,
         perspective: options.perspective,
@@ -250,12 +253,12 @@ export function createRecorder(options: RecorderOptions): TraceRecorder {
         ...(options.source != null ? { source: options.source } : {}),
         ...(options.endpoint != null ? { endpoint: options.endpoint } : {}),
         ...(options.sessionId != null ? { sessionId: options.sessionId } : {}),
-      };
-      return { header, events: [...events] };
+      }
+      return { header, events: [...events] }
     },
 
     get recording() {
-      return _recording;
+      return _recording
     },
-  };
+  }
 }

package/src/types.ts

@@ -1,79 +1,79 @@
-export type DetailLevel = "control" | "headers" | "headers+sizes" | "headers+data" | "full";
-export type Perspective = "client" | "server" | "observer";
+export type DetailLevel = 'control' | 'headers' | 'headers+sizes' | 'headers+data' | 'full'
+export type Perspective = 'client' | 'server' | 'observer'
 
 export 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>;
+  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;
+  readonly seq: number
+  readonly timestamp: number
 }
 
 export interface ControlMessageEvent extends BaseEvent {
-  readonly type: "control";
-  readonly direction: 0 | 1;
-  readonly messageType: number;
-  readonly message: Record<string, unknown>;
-  readonly raw?: Uint8Array;
+  readonly type: 'control'
+  readonly direction: 0 | 1
+  readonly messageType: number
+  readonly message: Record<string, unknown>
+  readonly raw?: Uint8Array
 }
 
 export interface StreamOpenedEvent extends BaseEvent {
-  readonly type: "stream-opened";
-  readonly streamId: bigint;
-  readonly direction: 0 | 1;
-  readonly streamType: 0 | 1 | 2;
+  readonly type: 'stream-opened'
+  readonly streamId: bigint
+  readonly direction: 0 | 1
+  readonly streamType: 0 | 1 | 2
 }
 
 export interface StreamClosedEvent extends BaseEvent {
-  readonly type: "stream-closed";
-  readonly streamId: bigint;
-  readonly errorCode: number;
+  readonly type: 'stream-closed'
+  readonly streamId: bigint
+  readonly errorCode: number
 }
 
 export interface ObjectHeaderEvent extends BaseEvent {
-  readonly type: "object-header";
-  readonly streamId: bigint;
-  readonly groupId: bigint;
-  readonly objectId: bigint;
-  readonly publisherPriority: number;
-  readonly objectStatus: number;
+  readonly type: 'object-header'
+  readonly streamId: bigint
+  readonly groupId: bigint
+  readonly objectId: bigint
+  readonly publisherPriority: number
+  readonly objectStatus: number
 }
 
 export interface ObjectPayloadEvent extends BaseEvent {
-  readonly type: "object-payload";
-  readonly streamId: bigint;
-  readonly groupId: bigint;
-  readonly objectId: bigint;
-  readonly size: number;
-  readonly payload?: Uint8Array;
+  readonly type: 'object-payload'
+  readonly streamId: bigint
+  readonly groupId: bigint
+  readonly objectId: bigint
+  readonly size: number
+  readonly payload?: Uint8Array
 }
 
 export interface StateChangeEvent extends BaseEvent {
-  readonly type: "state-change";
-  readonly from: string;
-  readonly to: string;
+  readonly type: 'state-change'
+  readonly from: string
+  readonly to: string
 }
 
 export interface TraceErrorEvent extends BaseEvent {
-  readonly type: "error";
-  readonly errorCode: number;
-  readonly reason: string;
+  readonly type: 'error'
+  readonly errorCode: number
+  readonly reason: string
 }
 
 export interface AnnotationEvent extends BaseEvent {
-  readonly type: "annotation";
-  readonly label: string;
-  readonly data: unknown;
+  readonly type: 'annotation'
+  readonly label: string
+  readonly data: unknown
 }
 
 export type TraceEvent =
@@ -84,23 +84,23 @@ export type TraceEvent =
   | ObjectPayloadEvent
   | StateChangeEvent
   | TraceErrorEvent
-  | AnnotationEvent;
+  | AnnotationEvent
 
 export interface Trace {
-  readonly header: TraceHeader;
-  readonly events: TraceEvent[];
+  readonly header: TraceHeader
+  readonly events: TraceEvent[]
 }
 
 export 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;
+  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;
+  readonly messageTypeId?: (name: string) => number
 }