@moqtap/trace 0.4.2 → 0.5.0

package/README.md

@@ -23,7 +23,7 @@ import { MESSAGE_ID_MAP } from '@moqtap/codec/draft21'
 import { createDraft21SessionState } from '@moqtap/codec/draft21/session'
 
 const recorder = createRecorder({
-  protocol: 'moqt-21',
+  protocol: 'moq-transport-21',
   perspective: 'client',
   detail: 'control',
   messageTypeId: (name) => Number(MESSAGE_ID_MAP.get(name) ?? 0),

package/SPEC.md

@@ -44,7 +44,9 @@ and Event 4's `"pl"` begins after the object header, so the bytes of a
 including `"full"`. What those headers carry is recorded as decoded fields
 instead — see [Event 1](#event-1-stream-opened). Closing that gap needs a new
 key and is not in this revision; the level's description no longer implies
-otherwise.
+otherwise. The one part of an object's framing recorded as bytes is its
+property block, [Event 3's `"props"`](#event-3-object-header), because the
+block's encoding is the draft's and has no decoded form this format could hold.
 
 At any detail level, the recorder MAY be configured to **mask payloads** — replacing payload bytes with zeroes before writing. This preserves payload sizes for bandwidth analysis while stripping media content. Sources MUST advertise masking via `"payloadMasked": true` in the header's `"custom"` map when active.
 
@@ -261,6 +263,33 @@ Object header events and object payload events (event 4) for the same object sha
 | `"o"`   | integer | `headers`+   | Object ID                                                                  |
 | `"pp"`  | integer | `headers`+   | Publisher priority                                                         |
 | `"os"`  | integer | `headers`+   | Object status (0=normal, 1=end-of-group, 2=end-of-track, 3=does-not-exist) |
+| `"props"` | byte string | `headers`+ | The object's property block as the wire carried it, past its length field. **Optional.** See below. |
+
+#### `"props"` — the property block
+
+Object Properties — called Extension Headers before draft-17 — are the part of
+an object a consumer reads before its payload: a LOC object's timestamp, frame
+marking and codec configuration, the gaps a publisher signals after a restart,
+the key ID of an encrypted object. Before this key no level recorded them, and
+none of them can be recovered from the payload, so a trace could show an
+object's bytes but not what decided how they were decoded.
+
+- **Bytes, not a decoded list.** Every draft encodes the block differently —
+  absolute or delta types, two varint encodings — and a reader already holds
+  the codec for the session's draft. A decoded form would freeze one draft's
+  rules into this format, and the block MUST be recorded byte for byte so a
+  reader decodes exactly what the endpoint saw. Immutable Properties, which an
+  encrypted object authenticates, depend on that.
+- **Absent and empty differ.** A writer MUST omit the key when the object had no
+  properties field, and MUST write an empty byte string when the field was
+  present with a length of 0 — on a subgroup stream with the PROPERTIES flag,
+  every object without properties carries one. A reader MUST keep the
+  distinction.
+- **`headers`+, not payload-bearing.** The block is object metadata, not media.
+  A property value can still carry application data — a codec configuration is
+  a few dozen bytes of it — so a source that must not share any object content
+  MAY drop the key along with the payload. Dropping it does not change the
+  trace's detail level.
 
 ### Event 4: Object Payload
 

package/dist/index.cjs

@@ -404,6 +404,7 @@ function eventToCbor(event) {
       base.o = event.objectId;
       base.pp = int(event.publisherPriority);
       base.os = int(event.objectStatus);
+      if (event.properties != null) base.props = event.properties;
       break;
     }
     case "object-payload": {
@@ -661,7 +662,8 @@ function decodeEvent(src) {
         groupId: requireUint(src, "g"),
         objectId: requireUint(src, "o"),
         publisherPriority: Number(_nullishCoalesce(take(src, "pp"), () => ( 0))),
-        objectStatus: Number(_nullishCoalesce(take(src, "os"), () => ( 0)))
+        objectStatus: Number(_nullishCoalesce(take(src, "os"), () => ( 0))),
+        ...optional(src, "props", "properties", asByteString)
       };
     case "object-payload":
       return {
@@ -1215,7 +1217,7 @@ function createRecorder(options) {
         errorCode
       });
     },
-    recordObjectHeader(streamId, groupId, objectId, publisherPriority, objectStatus) {
+    recordObjectHeader(streamId, groupId, objectId, publisherPriority, objectStatus, properties) {
       if (detailRank < DETAIL_RANK.headers) return;
       addEvent({
         type: "object-header",
@@ -1225,7 +1227,8 @@ function createRecorder(options) {
         groupId,
         objectId,
         publisherPriority,
-        objectStatus
+        objectStatus,
+        ...properties !== void 0 ? { properties } : {}
       });
     },
     recordObjectPayload(streamId, groupId, objectId, size, payload) {

package/dist/index.d.cts

@@ -298,6 +298,23 @@ interface ObjectHeaderEvent extends BaseEvent {
     readonly objectId: bigint;
     readonly publisherPriority: number;
     readonly objectStatus: number;
+    /**
+     * The Object's property block — Object Properties, Extension Headers before
+     * draft-17 — exactly as the wire carried it, past its length field.
+     *
+     * Absent when the Object had no properties field, which is not the same as an
+     * empty block: a subgroup stream with the PROPERTIES flag carries a zero
+     * length on every Object that has none. Kept as bytes rather than decoded
+     * because the encoding is the draft's, and a reader decodes it with the codec
+     * that reads the rest of the session; a decoded form would freeze one draft's
+     * rules into the format.
+     *
+     * Recorded from `'headers'` up. It is object metadata a payload's consumer
+     * reads before the payload — timestamps, frame marking, a codec
+     * configuration — and before this key no level recorded it, so a trace could
+     * not show what decided how its media was decoded.
+     */
+    readonly properties?: Uint8Array;
 }
 interface ObjectPayloadEvent extends BaseEvent {
     readonly type: 'object-payload';
@@ -917,8 +934,13 @@ interface TraceRecorder {
     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 header event. Ignored below 'headers' detail level.
+     *
+     * `properties` is the Object's property block as the wire carried it; omit it
+     * when the Object had no properties field.
+     */
+    recordObjectHeader(streamId: bigint, groupId: bigint, objectId: bigint, publisherPriority: number, objectStatus: number, properties?: Uint8Array): void;
     /** Record an object payload event. Ignored below 'headers+sizes' detail level. */
     recordObjectPayload(streamId: bigint, groupId: bigint, objectId: bigint, size: number, payload?: Uint8Array): void;
     /**

package/dist/index.d.ts

@@ -298,6 +298,23 @@ interface ObjectHeaderEvent extends BaseEvent {
     readonly objectId: bigint;
     readonly publisherPriority: number;
     readonly objectStatus: number;
+    /**
+     * The Object's property block — Object Properties, Extension Headers before
+     * draft-17 — exactly as the wire carried it, past its length field.
+     *
+     * Absent when the Object had no properties field, which is not the same as an
+     * empty block: a subgroup stream with the PROPERTIES flag carries a zero
+     * length on every Object that has none. Kept as bytes rather than decoded
+     * because the encoding is the draft's, and a reader decodes it with the codec
+     * that reads the rest of the session; a decoded form would freeze one draft's
+     * rules into the format.
+     *
+     * Recorded from `'headers'` up. It is object metadata a payload's consumer
+     * reads before the payload — timestamps, frame marking, a codec
+     * configuration — and before this key no level recorded it, so a trace could
+     * not show what decided how its media was decoded.
+     */
+    readonly properties?: Uint8Array;
 }
 interface ObjectPayloadEvent extends BaseEvent {
     readonly type: 'object-payload';
@@ -917,8 +934,13 @@ interface TraceRecorder {
     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 header event. Ignored below 'headers' detail level.
+     *
+     * `properties` is the Object's property block as the wire carried it; omit it
+     * when the Object had no properties field.
+     */
+    recordObjectHeader(streamId: bigint, groupId: bigint, objectId: bigint, publisherPriority: number, objectStatus: number, properties?: Uint8Array): void;
     /** Record an object payload event. Ignored below 'headers+sizes' detail level. */
     recordObjectPayload(streamId: bigint, groupId: bigint, objectId: bigint, size: number, payload?: Uint8Array): void;
     /**

package/dist/index.js

@@ -404,6 +404,7 @@ function eventToCbor(event) {
       base.o = event.objectId;
       base.pp = int(event.publisherPriority);
       base.os = int(event.objectStatus);
+      if (event.properties != null) base.props = event.properties;
       break;
     }
     case "object-payload": {
@@ -661,7 +662,8 @@ function decodeEvent(src) {
         groupId: requireUint(src, "g"),
         objectId: requireUint(src, "o"),
         publisherPriority: Number(take(src, "pp") ?? 0),
-        objectStatus: Number(take(src, "os") ?? 0)
+        objectStatus: Number(take(src, "os") ?? 0),
+        ...optional(src, "props", "properties", asByteString)
       };
     case "object-payload":
       return {
@@ -1215,7 +1217,7 @@ function createRecorder(options) {
         errorCode
       });
     },
-    recordObjectHeader(streamId, groupId, objectId, publisherPriority, objectStatus) {
+    recordObjectHeader(streamId, groupId, objectId, publisherPriority, objectStatus, properties) {
       if (detailRank < DETAIL_RANK.headers) return;
       addEvent({
         type: "object-header",
@@ -1225,7 +1227,8 @@ function createRecorder(options) {
         groupId,
         objectId,
         publisherPriority,
-        objectStatus
+        objectStatus,
+        ...properties !== void 0 ? { properties } : {}
       });
     },
     recordObjectPayload(streamId, groupId, objectId, size, payload) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@moqtap/trace",
-  "version": "0.4.2",
+  "version": "0.5.0",
   "description": "MoQT session trace format — record, serialize, and analyze .moqtrace files",
   "type": "module",
   "license": "MIT",

package/src/binary.ts

@@ -542,6 +542,7 @@ function eventToCbor(event: TraceEvent): Record<string, unknown> {
       base.o = event.objectId
       base.pp = int(event.publisherPriority)
       base.os = int(event.objectStatus)
+      if (event.properties != null) base.props = event.properties
       break
     }
     case 'object-payload': {
@@ -986,6 +987,7 @@ function decodeEvent(src: Decoding): TraceEvent {
         objectId: requireUint(src, 'o'),
         publisherPriority: Number(take(src, 'pp') ?? 0),
         objectStatus: Number(take(src, 'os') ?? 0),
+        ...optional(src, 'props', 'properties', asByteString),
       }
 
     case 'object-payload':

package/src/recorder.ts

@@ -104,13 +104,19 @@ export interface TraceRecorder {
   /** 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. */
+  /**
+   * Record an object header event. Ignored below 'headers' detail level.
+   *
+   * `properties` is the Object's property block as the wire carried it; omit it
+   * when the Object had no properties field.
+   */
   recordObjectHeader(
     streamId: bigint,
     groupId: bigint,
     objectId: bigint,
     publisherPriority: number,
     objectStatus: number,
+    properties?: Uint8Array,
   ): void
 
   /** Record an object payload event. Ignored below 'headers+sizes' detail level. */
@@ -342,7 +348,7 @@ export function createRecorder(options: RecorderOptions): TraceRecorder {
       })
     },
 
-    recordObjectHeader(streamId, groupId, objectId, publisherPriority, objectStatus) {
+    recordObjectHeader(streamId, groupId, objectId, publisherPriority, objectStatus, properties) {
       if (detailRank < DETAIL_RANK.headers) return
       addEvent({
         type: 'object-header',
@@ -353,6 +359,7 @@ export function createRecorder(options: RecorderOptions): TraceRecorder {
         objectId,
         publisherPriority,
         objectStatus,
+        ...(properties !== undefined ? { properties } : {}),
       })
     },
 

package/src/types.ts

@@ -319,6 +319,23 @@ export interface ObjectHeaderEvent extends BaseEvent {
   readonly objectId: bigint
   readonly publisherPriority: number
   readonly objectStatus: number
+  /**
+   * The Object's property block — Object Properties, Extension Headers before
+   * draft-17 — exactly as the wire carried it, past its length field.
+   *
+   * Absent when the Object had no properties field, which is not the same as an
+   * empty block: a subgroup stream with the PROPERTIES flag carries a zero
+   * length on every Object that has none. Kept as bytes rather than decoded
+   * because the encoding is the draft's, and a reader decodes it with the codec
+   * that reads the rest of the session; a decoded form would freeze one draft's
+   * rules into the format.
+   *
+   * Recorded from `'headers'` up. It is object metadata a payload's consumer
+   * reads before the payload — timestamps, frame marking, a codec
+   * configuration — and before this key no level recorded it, so a trace could
+   * not show what decided how its media was decoded.
+   */
+  readonly properties?: Uint8Array
 }
 
 export interface ObjectPayloadEvent extends BaseEvent {