@moqtap/trace 0.1.2 → 0.2.0

package/SPEC.md

@@ -117,12 +117,27 @@ Short key names are used intentionally — traces can contain hundreds of thousa
 
 #### Event 0: Control Message
 
-| Key     | Type        | Detail Level | Description                                       |
-| ------- | ----------- | ------------ | ------------------------------------------------- |
-| `"d"`   | integer     | `control`+   | Direction: `0` = sent (tx), `1` = received (rx)   |
-| `"mt"`  | integer     | `control`+   | Wire message type ID (e.g., `0x03` for SUBSCRIBE) |
-| `"msg"` | map         | `control`+   | Decoded message fields (draft-specific structure) |
-| `"raw"` | byte string | `full` only  | Raw wire bytes (including type and length prefix) |
+| Key     | Type        | Detail Level | Description                                                    |
+| ------- | ----------- | ------------ | ---------------------------------------------------------------- |
+| `"d"`   | integer     | `control`+   | Direction: `0` = sent (tx), `1` = received (rx)                |
+| `"mt"`  | integer     | `control`+   | Wire message type ID (e.g., `0x03` for SUBSCRIBE)              |
+| `"msg"` | map         | `control`+   | Decoded message fields (draft-specific structure)              |
+| `"sid"` | integer     | `control`+   | QUIC stream ID the message travelled on. Optional (see below). |
+| `"raw"` | byte string | `full` only  | Raw wire bytes (including type and length prefix)              |
+
+`"sid"` is optional: a recorder that sits at the session level rather than the
+stream level has no stream to report, and omitting the key says so. Readers
+MUST distinguish an absent `"sid"` from stream `0`.
+
+Recorders SHOULD write it. From draft-17 the control plane is no longer a
+single stream — the session control stream became a pair of unidirectional
+streams, and every request (SUBSCRIBE, PUBLISH, FETCH, …) gets its own
+bidirectional stream. Responses on those streams carry no request ID, because
+the stream itself is the correlation, so a trace without `"sid"` cannot tie a
+SUBSCRIBE_OK back to its SUBSCRIBE, and everything derived from that pairing —
+track names, aliases, request outcomes — is lost to the reader. Through
+draft-16 all control messages share one stream and the field is merely
+informative.
 
 #### Event 1: Stream Opened
 
@@ -215,6 +230,10 @@ Object header events and object payload events (event 4) for the same object sha
 - **Version 1** is defined by this document.
 - Readers MUST check the format version before parsing.
 - Unknown keys in header maps or event maps MUST be ignored (forward-compatible).
+- Optional keys MAY be added to an existing event type without a version bump —
+  `"sid"` on event 0 was added this way. A reader must therefore treat any
+  optional key as absent-by-default rather than assuming files of a given
+  version all carry the same keys.
 - New event types (`"e"` values) MAY be added in future versions; readers SHOULD skip unknown event types.
 - The detail level in the header is informational — readers MUST handle missing fields gracefully regardless of declared level.
 

package/dist/index.cjs

@@ -1,5 +1,11 @@
 "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 codec = new (0, _cborx.Encoder)({ useRecords: false, mapsAsObjects: true });
+var encode = (value) => codec.encode(value);
+var decode = (bytes) => codec.decode(bytes);
+var decodeMultiple = (bytes, cb) => {
+  codec.decodeMultiple(bytes, cb);
+};
 var MAGIC = new Uint8Array([77, 79, 81, 84, 82, 65, 67, 69]);
 var FORMAT_VERSION = 1;
 var PREAMBLE_SIZE = 16;
@@ -63,6 +69,7 @@ function eventToCbor(event) {
       base.d = event.direction;
       base.mt = event.messageType;
       base.msg = event.message;
+      if (event.streamId != null) base.sid = event.streamId;
       if (event.raw != null) base.raw = event.raw;
       break;
     }
@@ -133,6 +140,7 @@ function cborToEvent(obj) {
         direction: obj.d,
         messageType: Number(_nullishCoalesce(obj.mt, () => ( 0))),
         message: _nullishCoalesce(obj.msg, () => ( {})),
+        ...obj.sid != null ? { streamId: BigInt(obj.sid) } : {},
         ...obj.raw != null ? { raw: obj.raw } : {}
       };
     case "stream-opened":
@@ -230,12 +238,12 @@ function validatePreamble(bytes) {
   return { version, headerLength };
 }
 function writeMoqtrace(trace) {
-  const headerCbor = _cborx.encode.call(void 0, headerToCbor(trace.header));
+  const headerCbor = encode(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));
+    const chunk = encode(eventToCbor(event));
     eventChunks.push(chunk);
     totalEventBytes += chunk.length;
   }
@@ -251,11 +259,11 @@ function writeMoqtrace(trace) {
 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 header = cborToHeader(decode(headerBytes));
   const eventBytes = bytes.slice(PREAMBLE_SIZE + headerLength);
   const events = [];
   if (eventBytes.length > 0) {
-    _cborx.decodeMultiple.call(void 0, eventBytes, (obj) => {
+    decodeMultiple(eventBytes, (obj) => {
       events.push(cborToEvent(obj));
     });
   }
@@ -264,17 +272,17 @@ function readMoqtrace(bytes) {
 function readMoqtraceHeader(bytes) {
   const { headerLength } = validatePreamble(bytes);
   const headerBytes = bytes.slice(PREAMBLE_SIZE, PREAMBLE_SIZE + headerLength);
-  return cborToHeader(_cborx.decode.call(void 0, headerBytes));
+  return cborToHeader(decode(headerBytes));
 }
 function createMoqtraceWriter(header) {
-  const headerCbor = _cborx.encode.call(void 0, headerToCbor(header));
+  const headerCbor = encode(headerToCbor(header));
   const preambleBytes = writePreamble(headerCbor);
   return {
     preamble() {
       return preambleBytes;
     },
     writeEvent(event) {
-      return _cborx.encode.call(void 0, eventToCbor(event));
+      return encode(eventToCbor(event));
     }
   };
 }

package/dist/index.d.cts

@@ -24,6 +24,15 @@ interface ControlMessageEvent extends BaseEvent {
     readonly messageType: number;
     readonly message: Record<string, unknown>;
     readonly raw?: Uint8Array;
+    /**
+     * QUIC stream the message travelled on.
+     *
+     * Optional, and only meaningful for a recorder that knows it. It matters
+     * from draft-17, where the control plane is no longer one stream: each
+     * request gets its own bidirectional stream and responses carry no request
+     * id, so the stream is the only thing tying a response to its request.
+     */
+    readonly streamId?: bigint;
 }
 interface StreamOpenedEvent extends BaseEvent {
     readonly type: 'stream-opened';

package/dist/index.d.ts

@@ -24,6 +24,15 @@ interface ControlMessageEvent extends BaseEvent {
     readonly messageType: number;
     readonly message: Record<string, unknown>;
     readonly raw?: Uint8Array;
+    /**
+     * QUIC stream the message travelled on.
+     *
+     * Optional, and only meaningful for a recorder that knows it. It matters
+     * from draft-17, where the control plane is no longer one stream: each
+     * request gets its own bidirectional stream and responses carry no request
+     * id, so the stream is the only thing tying a response to its request.
+     */
+    readonly streamId?: bigint;
 }
 interface StreamOpenedEvent extends BaseEvent {
     readonly type: 'stream-opened';

package/dist/index.js

@@ -1,5 +1,11 @@
 // src/binary.ts
-import { decode, decodeMultiple, encode } from "cbor-x";
+import { Encoder } from "cbor-x";
+var codec = new Encoder({ useRecords: false, mapsAsObjects: true });
+var encode = (value) => codec.encode(value);
+var decode = (bytes) => codec.decode(bytes);
+var decodeMultiple = (bytes, cb) => {
+  codec.decodeMultiple(bytes, cb);
+};
 var MAGIC = new Uint8Array([77, 79, 81, 84, 82, 65, 67, 69]);
 var FORMAT_VERSION = 1;
 var PREAMBLE_SIZE = 16;
@@ -63,6 +69,7 @@ function eventToCbor(event) {
       base.d = event.direction;
       base.mt = event.messageType;
       base.msg = event.message;
+      if (event.streamId != null) base.sid = event.streamId;
       if (event.raw != null) base.raw = event.raw;
       break;
     }
@@ -133,6 +140,7 @@ function cborToEvent(obj) {
         direction: obj.d,
         messageType: Number(obj.mt ?? 0),
         message: obj.msg ?? {},
+        ...obj.sid != null ? { streamId: BigInt(obj.sid) } : {},
         ...obj.raw != null ? { raw: obj.raw } : {}
       };
     case "stream-opened":

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@moqtap/trace",
-  "version": "0.1.2",
+  "version": "0.2.0",
   "description": "MoQT session trace format — record, serialize, and analyze .moqtrace files",
   "type": "module",
   "license": "MIT",
@@ -47,7 +47,7 @@
     "test": "vitest run"
   },
   "peerDependencies": {
-    "@moqtap/codec": "^0.1.0"
+    "@moqtap/codec": "^0.3.0"
   },
   "dependencies": {
     "cbor-x": "^1.6.0"

package/src/binary.ts

@@ -1,6 +1,20 @@
-import { decode, decodeMultiple, encode } from 'cbor-x'
+import { Encoder } from 'cbor-x'
 import type { DetailLevel, Perspective, Trace, TraceEvent, TraceHeader } from './types.js'
 
+// Use a CBOR codec configured for cross-language interop.
+// Why: cbor-x's default `useRecords: true` enables a proprietary "record
+// extension" that encodes JS objects as tagged structures rather than standard
+// CBOR maps — unreadable by ciborium (Rust) and other spec-compliant decoders.
+// The .moqtrace spec requires standard CBOR, so we disable records and encode
+// as plain maps. `mapsAsObjects` is set so decoded maps come back as plain
+// JS objects (matching the code that accesses fields via `obj.protocol`).
+const codec = new Encoder({ useRecords: false, mapsAsObjects: true })
+const encode = (value: unknown): Uint8Array => codec.encode(value)
+const decode = (bytes: Uint8Array): unknown => codec.decode(bytes)
+const decodeMultiple = (bytes: Uint8Array, cb: (value: unknown) => void): void => {
+  codec.decodeMultiple(bytes, cb as (value: unknown) => boolean | undefined)
+}
+
 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
@@ -75,6 +89,7 @@ function eventToCbor(event: TraceEvent): Record<string, unknown> {
       base.d = event.direction
       base.mt = event.messageType
       base.msg = event.message
+      if (event.streamId != null) base.sid = event.streamId
       if (event.raw != null) base.raw = event.raw
       break
     }
@@ -150,6 +165,7 @@ function cborToEvent(obj: Record<string, unknown>): TraceEvent {
         direction: obj.d as 0 | 1,
         messageType: Number(obj.mt ?? 0),
         message: (obj.msg ?? {}) as Record<string, unknown>,
+        ...(obj.sid != null ? { streamId: BigInt(obj.sid as bigint | number) } : {}),
         ...(obj.raw != null ? { raw: obj.raw as Uint8Array } : {}),
       }
 

package/src/types.ts

@@ -25,6 +25,15 @@ export interface ControlMessageEvent extends BaseEvent {
   readonly messageType: number
   readonly message: Record<string, unknown>
   readonly raw?: Uint8Array
+  /**
+   * QUIC stream the message travelled on.
+   *
+   * Optional, and only meaningful for a recorder that knows it. It matters
+   * from draft-17, where the control plane is no longer one stream: each
+   * request gets its own bidirectional stream and responses carry no request
+   * id, so the stream is the only thing tying a response to its request.
+   */
+  readonly streamId?: bigint
 }
 
 export interface StreamOpenedEvent extends BaseEvent {