@moqtap/trace 0.1.0 → 0.1.2

package/src/recorder.ts

@@ -1,95 +1,110 @@
-import type { MoqtMessage } from '@moqtap/codec';
-import type { SessionState } from '@moqtap/codec/session';
-import type {
-  Trace,
-  TraceHeader,
-  TraceEvent,
-  RecorderOptions,
-  DetailLevel,
-} 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(
-    streamId: bigint, groupId: bigint, objectId: bigint,
-    publisherPriority: number, objectStatus: number,
-  ): void;
+    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;
+    streamId: bigint,
+    groupId: bigint,
+    objectId: bigint,
+    size: number,
+    payload?: Uint8Array,
+  ): 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,
+  control: 0,
+  headers: 1,
   'headers+sizes': 2,
   'headers+data': 3,
-  'full': 4,
-};
+  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; },
-      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; },
+      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);
+      receive(message: M) {
+        const prevPhase = session.phase
+        const result = session.receive(message)
 
         addEvent({
           type: 'control',
@@ -98,7 +113,7 @@ export function createRecorder(options: RecorderOptions): TraceRecorder {
           direction: 1, // rx
           messageType: messageTypeId(message.type),
           message: message as unknown as Record<string, unknown>,
-        });
+        })
 
         if (result.ok && result.phase !== prevPhase) {
           addEvent({
@@ -107,19 +122,19 @@ export function createRecorder(options: RecorderOptions): TraceRecorder {
             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',
@@ -128,7 +143,7 @@ export function createRecorder(options: RecorderOptions): TraceRecorder {
           direction: 0, // tx
           messageType: messageTypeId(message.type),
           message: message as unknown as Record<string, unknown>,
-        });
+        })
 
         if (result.ok && result.phase !== prevPhase) {
           addEvent({
@@ -137,16 +152,16 @@ export function createRecorder(options: RecorderOptions): TraceRecorder {
             timestamp: clock(),
             from: prevPhase,
             to: result.phase,
-          });
+          })
         }
 
-        return result;
+        return result
       },
 
       reset() {
-        session.reset();
+        session.reset()
       },
-    };
+    }
   }
 
   return {
@@ -155,7 +170,7 @@ 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',
         seq: nextSeq(),
@@ -163,22 +178,22 @@ export function createRecorder(options: RecorderOptions): TraceRecorder {
         streamId,
         direction,
         streamType,
-      });
+      })
     },
 
     recordStreamClosed(streamId, errorCode = 0) {
-      if (detailRank < DETAIL_RANK['headers']) return;
+      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;
+      if (detailRank < DETAIL_RANK.headers) return
       addEvent({
         type: 'object-header',
         seq: nextSeq(),
@@ -188,11 +203,11 @@ 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',
         seq: nextSeq(),
@@ -202,8 +217,8 @@ export function createRecorder(options: RecorderOptions): TraceRecorder {
         objectId,
         size,
         ...(detailRank >= DETAIL_RANK['headers+data'] && payload != null ? { payload } : {}),
-      };
-      addEvent(event);
+      }
+      addEvent(event)
     },
 
     recordError(errorCode, reason) {
@@ -213,7 +228,7 @@ export function createRecorder(options: RecorderOptions): TraceRecorder {
         timestamp: clock(),
         errorCode,
         reason,
-      });
+      })
     },
 
     annotate(label, data) {
@@ -223,11 +238,11 @@ export function createRecorder(options: RecorderOptions): TraceRecorder {
         timestamp: clock(),
         label,
         data,
-      });
+      })
     },
 
     finalize(): Trace {
-      _recording = false;
+      _recording = false
       const header: TraceHeader = {
         protocol: options.protocol,
         perspective: options.perspective,
@@ -238,10 +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; },
-  };
+    get 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
 }