@moqtap/trace 0.2.0 → 0.4.1

package/dist/index.js

@@ -1,13 +1,155 @@
 // src/binary.ts
 import { Encoder } from "cbor-x";
-var codec = new Encoder({ useRecords: false, mapsAsObjects: true });
+
+// src/cbor-scan.ts
+var INCOMPLETE = null;
+var MalformedCborError = class extends Error {
+  offset;
+  constructor(message, offset) {
+    super(`${message} at byte ${offset}`);
+    this.name = "MalformedCborError";
+    this.offset = offset;
+  }
+};
+var MAJOR_UNSIGNED = 0;
+var MAJOR_NEGATIVE = 1;
+var MAJOR_BYTES = 2;
+var MAJOR_TEXT = 3;
+var MAJOR_ARRAY = 4;
+var MAJOR_MAP = 5;
+var MAJOR_TAG = 6;
+var MAJOR_SIMPLE = 7;
+var AI_ONE_BYTE = 24;
+var AI_TWO_BYTES = 25;
+var AI_FOUR_BYTES = 26;
+var AI_EIGHT_BYTES = 27;
+var AI_INDEFINITE = 31;
+var BREAK = 255;
+function headerExtraBytes(additionalInfo, offset) {
+  if (additionalInfo < AI_ONE_BYTE) return 0;
+  switch (additionalInfo) {
+    case AI_ONE_BYTE:
+      return 1;
+    case AI_TWO_BYTES:
+      return 2;
+    case AI_FOUR_BYTES:
+      return 4;
+    case AI_EIGHT_BYTES:
+      return 8;
+    case AI_INDEFINITE:
+      return 0;
+    default:
+      throw new MalformedCborError(`reserved additional information ${additionalInfo}`, offset);
+  }
+}
+function readArgument(bytes, offset, additionalInfo) {
+  if (additionalInfo < AI_ONE_BYTE) return additionalInfo;
+  const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+  switch (additionalInfo) {
+    case AI_ONE_BYTE:
+      return view.getUint8(offset + 1);
+    case AI_TWO_BYTES:
+      return view.getUint16(offset + 1, false);
+    case AI_FOUR_BYTES:
+      return view.getUint32(offset + 1, false);
+    case AI_EIGHT_BYTES: {
+      const value = view.getBigUint64(offset + 1, false);
+      return Number(value);
+    }
+    default:
+      throw new MalformedCborError(`reserved additional information ${additionalInfo}`, offset);
+  }
+}
+function skipItem(bytes, offset, allowBreak) {
+  if (offset >= bytes.length) return INCOMPLETE;
+  const initial = bytes[offset];
+  if (initial === BREAK) {
+    if (!allowBreak) {
+      throw new MalformedCborError("break outside an indefinite-length item", offset);
+    }
+    return offset + 1;
+  }
+  const major = initial >> 5;
+  const additionalInfo = initial & 31;
+  const extra = headerExtraBytes(additionalInfo, offset);
+  if (offset + 1 + extra > bytes.length) return INCOMPLETE;
+  const indefinite = additionalInfo === AI_INDEFINITE;
+  if (indefinite && (major === MAJOR_UNSIGNED || major === MAJOR_NEGATIVE || major === MAJOR_TAG)) {
+    throw new MalformedCborError(`major type ${major} cannot be indefinite-length`, offset);
+  }
+  const afterHeader = offset + 1 + extra;
+  switch (major) {
+    case MAJOR_UNSIGNED:
+    case MAJOR_NEGATIVE:
+      return afterHeader;
+    case MAJOR_BYTES:
+    case MAJOR_TEXT: {
+      if (!indefinite) {
+        const length = readArgument(bytes, offset, additionalInfo);
+        const end = afterHeader + length;
+        return end > bytes.length ? INCOMPLETE : end;
+      }
+      let cursor = afterHeader;
+      for (; ; ) {
+        if (cursor >= bytes.length) return INCOMPLETE;
+        if (bytes[cursor] === BREAK) return cursor + 1;
+        const next = skipItem(bytes, cursor, false);
+        if (next === INCOMPLETE) return INCOMPLETE;
+        cursor = next;
+      }
+    }
+    case MAJOR_ARRAY:
+    case MAJOR_MAP: {
+      const perEntry = major === MAJOR_MAP ? 2 : 1;
+      if (!indefinite) {
+        const count = readArgument(bytes, offset, additionalInfo) * perEntry;
+        let cursor2 = afterHeader;
+        for (let i = 0; i < count; i++) {
+          const next = skipItem(bytes, cursor2, false);
+          if (next === INCOMPLETE) return INCOMPLETE;
+          cursor2 = next;
+        }
+        return cursor2;
+      }
+      let cursor = afterHeader;
+      for (; ; ) {
+        if (cursor >= bytes.length) return INCOMPLETE;
+        if (bytes[cursor] === BREAK) return cursor + 1;
+        for (let i = 0; i < perEntry; i++) {
+          const next = skipItem(bytes, cursor, false);
+          if (next === INCOMPLETE) return INCOMPLETE;
+          cursor = next;
+        }
+      }
+    }
+    case MAJOR_TAG:
+      return skipItem(bytes, afterHeader, false);
+    case MAJOR_SIMPLE:
+      return afterHeader;
+    default:
+      throw new MalformedCborError(`unknown major type ${major}`, offset);
+  }
+}
+function cborItemLength(bytes, start) {
+  const end = skipItem(bytes, start, false);
+  return end === INCOMPLETE ? INCOMPLETE : end - start;
+}
+
+// src/types.ts
+var TRACE_ID_LENGTH = 16;
+function controlMessageFields(message) {
+  if (message === null || typeof message !== "object") return void 0;
+  if (Array.isArray(message) || ArrayBuffer.isView(message)) return void 0;
+  return message;
+}
+
+// src/binary.ts
+var codec = new Encoder({ useRecords: false, mapsAsObjects: true, tagUint8Array: false });
 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 FORMAT_VERSION = 2;
+var SUPPORTED_VERSIONS = [1, FORMAT_VERSION];
 var PREAMBLE_SIZE = 16;
 var EVENT_TYPE_TO_INT = {
   control: 0,
@@ -17,7 +159,10 @@ var EVENT_TYPE_TO_INT = {
   "object-payload": 4,
   "state-change": 5,
   error: 6,
-  annotation: 7
+  annotation: 7,
+  "peer-connected": 8,
+  "peer-disconnected": 9,
+  "subscription-derivation": 10
 };
 var INT_TO_EVENT_TYPE = {
   0: "control",
@@ -27,48 +172,213 @@ var INT_TO_EVENT_TYPE = {
   4: "object-payload",
   5: "state-change",
   6: "error",
-  7: "annotation"
+  7: "annotation",
+  8: "peer-connected",
+  9: "peer-disconnected",
+  10: "subscription-derivation"
 };
+var COMMON_EVENT_KEYS = /* @__PURE__ */ new Set(["n", "t", "p", "e"]);
+function setKey(target, key, value) {
+  Object.defineProperty(target, key, {
+    value,
+    writable: true,
+    enumerable: true,
+    configurable: true
+  });
+}
+function unrecognisedKeys(src) {
+  let extra;
+  for (const [key, value] of Object.entries(src.obj)) {
+    if (src.used.has(key)) continue;
+    extra ??= {};
+    setKey(extra, key, value);
+  }
+  return extra;
+}
+function withStore(map, store) {
+  if (store == null) return map;
+  for (const [key, value] of Object.entries(store)) {
+    if (Object.hasOwn(map, key)) continue;
+    setKey(map, key, value);
+  }
+  return map;
+}
+var TruncatedTraceError = class extends Error {
+  /** Byte offset at which the incomplete item begins. */
+  offset;
+  /**
+   * Everything that decoded before the cut, one entry per segment. A
+   * truncated trace is still evidence, and the events before the cut are
+   * exactly as valid as they were.
+   */
+  segments;
+  constructor(offset, segments) {
+    super(`Trace truncated: the item starting at byte ${offset} is incomplete`);
+    this.name = "TruncatedTraceError";
+    this.offset = offset;
+    this.segments = segments;
+  }
+  /** What decoded, flattened as {@link readMoqtrace} would return it. */
+  get trace() {
+    return flatten(this.segments);
+  }
+};
+var MalformedHeaderError = class extends Error {
+  /** The key at fault, dotted for one inside `"segment"`. */
+  key;
+  /**
+   * @param key the key at fault
+   * @param fault what was wrong with it, as a predicate on the key
+   */
+  constructor(key, fault) {
+    super(`Malformed header: ${JSON.stringify(key)} ${fault}`);
+    this.name = "MalformedHeaderError";
+    this.key = key;
+  }
+};
+function requiredUint(value, reportedAs) {
+  if (!Number.isInteger(value) || value < 0 || value > Number.MAX_SAFE_INTEGER) {
+    throw new MalformedHeaderError(reportedAs, "must be an unsigned integer");
+  }
+  return int(value);
+}
+function segmentToCbor(segment) {
+  const map = {
+    sequence: requiredUint(segment.sequence, "segment.sequence")
+  };
+  if (segment.durationMs != null) map.durationMs = int(segment.durationMs);
+  if (segment.streamId != null) map.streamId = segment.streamId;
+  if (segment.continues != null) map.continues = segment.continues;
+  return withStore(map, segment.extra);
+}
+function cborToSegment(value) {
+  const obj = asMap(value);
+  if (obj == null) return void 0;
+  const src = { obj, used: /* @__PURE__ */ new Set() };
+  const segment = {
+    sequence: requireHeaderUint(src, "sequence", "segment.sequence"),
+    ...optional(src, "durationMs", "durationMs", asUintNumber),
+    ...optional(src, "streamId", "streamId", asText),
+    ...optional(src, "continues", "continues", asBoolean)
+  };
+  const extra = unrecognisedKeys(src);
+  return extra == null ? segment : { ...segment, extra };
+}
+function samplingToCbor(sampling) {
+  const map = {};
+  if (sampling.effectiveRate != null) map.effectiveRate = sampling.effectiveRate;
+  if (sampling.maxEventsPerSec != null) map.maxEventsPerSec = int(sampling.maxEventsPerSec);
+  if (sampling.dropPolicy != null) map.dropPolicy = sampling.dropPolicy;
+  if (sampling.droppedTotal != null) map.droppedTotal = int(sampling.droppedTotal);
+  if (sampling.droppedSegment != null) map.droppedSegment = int(sampling.droppedSegment);
+  if (sampling.rule != null) map.rule = sampling.rule;
+  if (sampling.ruleLang != null) map.ruleLang = sampling.ruleLang;
+  if (sampling.appliesTo != null) map.appliesTo = sampling.appliesTo.map(int);
+  return withStore(map, sampling.extra);
+}
+function cborToSampling(value) {
+  const obj = asMap(value);
+  if (obj == null) return void 0;
+  const src = { obj, used: /* @__PURE__ */ new Set() };
+  const sampling = {
+    // A rate is a fraction, so this is the one header number that is not an
+    // integer — and the one whose range the format states, so it is the one
+    // key here checked for more than its type. It is tested rather than
+    // converted: `Number('half')` is `NaN`, a rate no file carried and none
+    // can be written back from.
+    ...optional(src, "effectiveRate", "effectiveRate", asRate),
+    ...optional(src, "maxEventsPerSec", "maxEventsPerSec", asUintNumber),
+    ...optional(src, "dropPolicy", "dropPolicy", asText),
+    ...optional(src, "droppedTotal", "droppedTotal", asUintNumber),
+    ...optional(src, "droppedSegment", "droppedSegment", asUintNumber),
+    ...optional(src, "rule", "rule", asText),
+    ...optional(src, "ruleLang", "ruleLang", asText),
+    ...optional(src, "appliesTo", "appliesTo", asUintNumbers)
+  };
+  const extra = unrecognisedKeys(src);
+  return extra == null ? sampling : { ...sampling, extra };
+}
 function headerToCbor(header) {
   const map = {
     protocol: header.protocol,
     perspective: header.perspective,
     detail: header.detail,
-    startTime: header.startTime
+    startTime: requiredUint(header.startTime, "startTime")
   };
-  if (header.endTime != null) map.endTime = header.endTime;
+  if (header.endTime != null) map.endTime = int(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.segment != null) map.segment = segmentToCbor(header.segment);
+  if (header.sampling != null) map.sampling = samplingToCbor(header.sampling);
   if (header.custom != null) map.custom = header.custom;
-  return map;
+  return withStore(map, header.extra);
 }
 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 } : {}
+  const src = { obj, used: /* @__PURE__ */ new Set() };
+  const header = {
+    protocol: requireHeaderText(src, "protocol"),
+    perspective: requireHeaderText(src, "perspective"),
+    detail: requireHeaderText(src, "detail"),
+    startTime: requireHeaderUint(src, "startTime"),
+    ...optional(src, "endTime", "endTime", asUintNumber),
+    ...optional(src, "transport", "transport", asText),
+    ...optional(src, "source", "source", asText),
+    ...optional(src, "endpoint", "endpoint", asText),
+    ...optional(src, "sessionId", "sessionId", asText),
+    ...optional(src, "segment", "segment", cborToSegment),
+    ...optional(src, "sampling", "sampling", cborToSampling),
+    // Not `Record<string, unknown>` by assertion but by test. A `"custom"`
+    // that is not a map used to reach this field wearing that type, so the
+    // first caller to iterate its keys met a shape it was told could not
+    // occur. The bytes survive either way; only one of the two keeps the
+    // field's type true.
+    ...optional(src, "custom", "custom", asMap)
   };
+  const extra = unrecognisedKeys(src);
+  return extra == null ? header : { ...header, extra };
+}
+function subscriptionRefToCbor(ref) {
+  return [ref.peer, ref.requestId];
+}
+function cborToSubscriptionRef(value) {
+  if (!Array.isArray(value) || value.length !== 2) {
+    throw new Error("Subscription reference must be [peer, requestId]");
+  }
+  const peer = asText(value[0]);
+  const requestId = asUint(value[1]);
+  if (peer == null || requestId == null) {
+    throw new Error("Subscription reference must be a [text, unsigned integer] pair");
+  }
+  return { peer, requestId };
+}
+function toBytes(value) {
+  return value instanceof Uint8Array ? new Uint8Array(value) : new Uint8Array(value);
+}
+function int(value) {
+  const outsideInt32 = value > 4294967295 || value < -2147483648;
+  return Number.isInteger(value) && outsideInt32 ? BigInt(value) : value;
+}
+function checkTraceId(value) {
+  const bytes = toBytes(value);
+  if (bytes.length !== TRACE_ID_LENGTH) {
+    throw new Error(`traceId is ${bytes.length} bytes, must be ${TRACE_ID_LENGTH}`);
+  }
+  return bytes;
 }
 function eventToCbor(event) {
   const base = {
-    n: event.seq,
-    t: event.timestamp,
-    e: EVENT_TYPE_TO_INT[event.type]
+    n: int(event.seq),
+    t: int(event.timestamp)
   };
+  if (event.peer != null) base.p = event.peer;
+  if (event.type !== "unknown") base.e = EVENT_TYPE_TO_INT[event.type];
   switch (event.type) {
     case "control": {
       base.d = event.direction;
-      base.mt = event.messageType;
-      base.msg = event.message;
+      base.mt = int(event.messageType);
+      base.msg = event.message === void 0 ? {} : event.message;
       if (event.streamId != null) base.sid = event.streamId;
       if (event.raw != null) base.raw = event.raw;
       break;
@@ -77,26 +387,30 @@ function eventToCbor(event) {
       base.sid = event.streamId;
       base.d = event.direction;
       base.st = event.streamType;
+      if (event.trackAlias != null) base.ta = event.trackAlias;
+      if (event.subgroupId != null) base.sg = event.subgroupId;
+      if (event.fetchRequestId != null) base.fri = event.fetchRequestId;
+      if (event.groupId != null) base.g = event.groupId;
       break;
     }
     case "stream-closed": {
       base.sid = event.streamId;
-      base.ec = event.errorCode;
+      base.ec = int(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;
+      base.pp = int(event.publisherPriority);
+      base.os = int(event.objectStatus);
       break;
     }
     case "object-payload": {
       base.sid = event.streamId;
       base.g = event.groupId;
       base.o = event.objectId;
-      base.sz = event.size;
+      base.sz = int(event.size);
       if (event.payload != null) base.pl = event.payload;
       break;
     }
@@ -106,8 +420,12 @@ function eventToCbor(event) {
       break;
     }
     case "error": {
-      base.ec = event.errorCode;
+      base.ec = int(event.errorCode);
       base.reason = event.reason;
+      if (event.streamId != null) base.sid = event.streamId;
+      if (event.errorKind != null) base.ek = event.errorKind;
+      if (event.rawLength != null) base.rawlen = int(event.rawLength);
+      if (event.raw != null) base.raw = event.raw;
       break;
     }
     case "annotation": {
@@ -115,96 +433,330 @@ function eventToCbor(event) {
       if (event.data !== void 0) base.data = event.data;
       break;
     }
+    case "peer-connected": {
+      if (event.endpoint != null) base.endpoint = event.endpoint;
+      if (event.transport != null) base.transport = event.transport;
+      if (event.role != null) base.role = event.role;
+      if (event.side != null) base.side = event.side;
+      break;
+    }
+    case "peer-disconnected": {
+      base.ec = int(event.errorCode);
+      if (event.reason != null) base.reason = event.reason;
+      break;
+    }
+    case "subscription-derivation": {
+      base.u = subscriptionRefToCbor(event.upstream);
+      base.d = event.downstream.map(subscriptionRefToCbor);
+      base.kind = event.kind;
+      if (event.traceId != null) base.traceId = checkTraceId(event.traceId);
+      if (event.namespace != null) base.ns = event.namespace;
+      if (event.trackName != null) base.tn = event.trackName;
+      if (event.tDownstreamReceived != null) base.tdr = int(event.tDownstreamReceived);
+      if (event.tUpstreamSent != null) base.tus = int(event.tUpstreamSent);
+      if (event.tUpstreamOkReceived != null) base.tuo = int(event.tUpstreamOkReceived);
+      if (event.tDownstreamOkSent != null) base.tdo = int(event.tDownstreamOkSent);
+      break;
+    }
+    case "unknown": {
+      base.e = event.eventType;
+      for (const [key, value] of Object.entries(event.fields)) {
+        setKey(base, key, value);
+      }
+      break;
+    }
+  }
+  if (event.type !== "unknown" && event.extra != null) {
+    for (const [key, value] of Object.entries(event.extra)) {
+      if (COMMON_EVENT_KEYS.has(key) || Object.hasOwn(base, key)) continue;
+      setKey(base, key, value);
+    }
   }
   return base;
 }
+function asUint(value) {
+  if (typeof value === "bigint") return value >= 0n ? value : void 0;
+  if (typeof value !== "number" || !Number.isInteger(value) || value < 0) return void 0;
+  return BigInt(value);
+}
+function asUintNumber(value) {
+  const int2 = asUint(value);
+  return int2 == null || int2 > BigInt(Number.MAX_SAFE_INTEGER) ? void 0 : Number(int2);
+}
+function asText(value) {
+  return typeof value === "string" ? value : void 0;
+}
+function asBoolean(value) {
+  return typeof value === "boolean" ? value : void 0;
+}
+function asNumber(value) {
+  return typeof value === "number" && Number.isFinite(value) ? value : void 0;
+}
+function asRate(value) {
+  const rate = asNumber(value);
+  return rate != null && rate > 0 && rate <= 1 ? rate : void 0;
+}
+function asUintNumbers(value) {
+  if (!Array.isArray(value)) return void 0;
+  const ids = [];
+  for (const item of value) {
+    const id = asUintNumber(item);
+    if (id == null) return void 0;
+    ids.push(id);
+  }
+  return ids;
+}
+function asMap(value) {
+  if (value === null || typeof value !== "object") return void 0;
+  const proto = Object.getPrototypeOf(value);
+  if (proto !== Object.prototype && proto !== null) return void 0;
+  return value;
+}
+function asByteString(value) {
+  return value instanceof Uint8Array ? toBytes(value) : void 0;
+}
+function asByteStrings(value) {
+  if (!Array.isArray(value)) return void 0;
+  const parts = [];
+  for (const item of value) {
+    const bytes = asByteString(item);
+    if (bytes == null) return void 0;
+    parts.push(bytes);
+  }
+  return parts;
+}
+function asTraceId(value) {
+  const bytes = asByteString(value);
+  return bytes?.length === TRACE_ID_LENGTH ? bytes : void 0;
+}
+function take(src, key) {
+  src.used.add(key);
+  return src.obj[key];
+}
+function requireUint(src, key) {
+  const value = asUint(take(src, key));
+  if (value == null) {
+    throw new Error(`Event key ${JSON.stringify(key)} must be an unsigned integer`);
+  }
+  return value;
+}
+function requireHeaderText(src, key) {
+  const present = Object.hasOwn(src.obj, key);
+  const value = asText(take(src, key));
+  if (value == null) {
+    throw new MalformedHeaderError(key, present ? "must be a text string" : "is missing");
+  }
+  return value;
+}
+function requireHeaderUint(src, key, reportedAs = key) {
+  const present = Object.hasOwn(src.obj, key);
+  const value = asUintNumber(take(src, key));
+  if (value == null) {
+    throw new MalformedHeaderError(
+      reportedAs,
+      present ? "must be an unsigned integer" : "is missing"
+    );
+  }
+  return value;
+}
+function optional(src, key, name, read) {
+  const usable = read(src.obj[key]);
+  if (usable === void 0) return {};
+  src.used.add(key);
+  return { [name]: usable };
+}
 function cborToEvent(obj) {
+  const src = { obj, used: new Set(COMMON_EVENT_KEYS) };
+  const event = decodeEvent(src);
+  if (event.type === "unknown") return event;
+  const extra = unrecognisedKeys(src);
+  return extra == null ? event : { ...event, extra };
+}
+function decodeEvent(src) {
+  const obj = src.obj;
+  const seq = Number(obj.n ?? 0);
+  const timestamp = Number(obj.t ?? 0);
+  const peerFields = obj.p != null ? { peer: obj.p } : {};
   const eventType = INT_TO_EVENT_TYPE[obj.e];
   if (eventType == null) {
+    const fields = {};
+    for (const [key, value] of Object.entries(obj)) {
+      if (!COMMON_EVENT_KEYS.has(key)) setKey(fields, key, value);
+    }
     return {
-      type: "annotation",
-      seq: Number(obj.n ?? 0),
-      timestamp: Number(obj.t ?? 0),
-      label: `unknown-event-${obj.e}`,
-      data: obj
+      type: "unknown",
+      seq,
+      timestamp,
+      ...peerFields,
+      eventType: Number(obj.e ?? -1),
+      fields
     };
   }
-  const seq = Number(obj.n ?? 0);
-  const timestamp = Number(obj.t ?? 0);
   switch (eventType) {
     case "control":
       return {
         type: "control",
         seq,
         timestamp,
-        direction: obj.d,
-        messageType: Number(obj.mt ?? 0),
-        message: obj.msg ?? {},
-        ...obj.sid != null ? { streamId: BigInt(obj.sid) } : {},
-        ...obj.raw != null ? { raw: obj.raw } : {}
+        ...peerFields,
+        direction: take(src, "d"),
+        messageType: Number(take(src, "mt") ?? 0),
+        // Handed over exactly as it decoded. A `"msg"` that is not a map is
+        // still the only decode the recording has — the corpus captures carry
+        // a Rust `Debug` string here — and the format requires a reader to
+        // preserve it rather than reject the event or substitute a map. That
+        // includes `null`, which is a value a writer chose to put on the wire,
+        // not an absence; absence is the single case normalised, to `{}`, so
+        // that a caller reading keys off a conforming file never meets
+        // `undefined`. It is the one key with no unusable shape: the field's
+        // type is `unknown`, so every value is one it can hold.
+        message: Object.hasOwn(obj, "msg") ? take(src, "msg") : {},
+        ...optional(src, "sid", "streamId", asUint),
+        ...optional(src, "raw", "raw", asByteString)
       };
     case "stream-opened":
       return {
         type: "stream-opened",
         seq,
         timestamp,
-        streamId: BigInt(obj.sid),
-        direction: obj.d,
-        streamType: obj.st
+        ...peerFields,
+        streamId: requireUint(src, "sid"),
+        direction: take(src, "d"),
+        streamType: take(src, "st"),
+        // `bigint`, not `number`, even though a writer that used a narrow CBOR
+        // integer hands these back as JS numbers. They are the same
+        // identifiers an object-header event carries, and that event converts;
+        // leaving one a number here makes `opened.groupId === header.groupId`
+        // read `42 === 42n` and answer `false` for values that match.
+        //
+        // Tested rather than converted, and optional rather than required.
+        // `BigInt(obj.ta)` threw on a text or fractional value and took the
+        // whole file down with it, since nothing catches one event's decode; it
+        // answered `1n` for `true` and `4n` for `"4"`, inventing an identifier
+        // the file never carried; and the owned-key list then kept the
+        // survivors out of `extra`, so adding these four keys *lost* values
+        // this reader had preserved before it knew them. A value of any other
+        // shape now stays where it was, on the event as an unrecognised key.
+        ...optional(src, "ta", "trackAlias", asUint),
+        ...optional(src, "sg", "subgroupId", asUint),
+        ...optional(src, "fri", "fetchRequestId", asUint),
+        ...optional(src, "g", "groupId", asUint)
       };
     case "stream-closed":
       return {
         type: "stream-closed",
         seq,
         timestamp,
-        streamId: BigInt(obj.sid),
-        errorCode: Number(obj.ec ?? 0)
+        ...peerFields,
+        streamId: requireUint(src, "sid"),
+        errorCode: Number(take(src, "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(obj.pp ?? 0),
-        objectStatus: Number(obj.os ?? 0)
+        ...peerFields,
+        streamId: requireUint(src, "sid"),
+        groupId: requireUint(src, "g"),
+        objectId: requireUint(src, "o"),
+        publisherPriority: Number(take(src, "pp") ?? 0),
+        objectStatus: Number(take(src, "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(obj.sz ?? 0),
-        ...obj.pl != null ? { payload: obj.pl } : {}
+        ...peerFields,
+        streamId: requireUint(src, "sid"),
+        groupId: requireUint(src, "g"),
+        objectId: requireUint(src, "o"),
+        size: Number(take(src, "sz") ?? 0),
+        ...optional(src, "pl", "payload", asByteString)
       };
     case "state-change":
       return {
         type: "state-change",
         seq,
         timestamp,
-        from: obj.from,
-        to: obj.to
+        ...peerFields,
+        from: take(src, "from"),
+        to: take(src, "to")
       };
     case "error":
       return {
         type: "error",
         seq,
         timestamp,
-        errorCode: Number(obj.ec ?? 0),
-        reason: obj.reason ?? ""
+        ...peerFields,
+        errorCode: Number(take(src, "ec") ?? 0),
+        reason: take(src, "reason") ?? "",
+        // Optional, so an unusable value costs the key and not the event: the
+        // error code and reason are the point of the event and are fine.
+        // `asUint` rather than a conversion, for the reason Event 1 gives —
+        // `BigInt(true)` is `1n`, a stream this file never named.
+        ...optional(src, "sid", "streamId", asUint),
+        // An error kind this version has never heard of is still text, and
+        // still kept: the vocabulary is open and `ErrorKind` widens to any
+        // string for exactly that. What `asText` refuses is a value that is
+        // not text at all.
+        ...optional(src, "ek", "errorKind", asText),
+        ...optional(src, "rawlen", "rawLength", asUintNumber),
+        // No length check. The 4096-byte cap binds a recorder; a reader that
+        // refused a longer value — or shortened it — would reject a file it was
+        // required to accept, or destroy the evidence the field exists to
+        // carry.
+        ...optional(src, "raw", "raw", asByteString)
       };
     case "annotation":
       return {
         type: "annotation",
         seq,
         timestamp,
-        label: obj.label ?? "",
-        data: obj.data
+        ...peerFields,
+        label: take(src, "label") ?? "",
+        data: take(src, "data")
+      };
+    case "peer-connected":
+      return {
+        type: "peer-connected",
+        seq,
+        timestamp,
+        ...peerFields,
+        ...optional(src, "endpoint", "endpoint", asText),
+        ...optional(src, "transport", "transport", asText),
+        // A role or side this version has never heard of is still text, and
+        // still kept: the unions they widen to exist for exactly that. What
+        // `asText` refuses is a value that is not text at all.
+        ...optional(src, "role", "role", asText),
+        ...optional(src, "side", "side", asText)
+      };
+    case "peer-disconnected":
+      return {
+        type: "peer-disconnected",
+        seq,
+        timestamp,
+        ...peerFields,
+        errorCode: Number(take(src, "ec") ?? 0),
+        ...optional(src, "reason", "reason", asText)
+      };
+    case "subscription-derivation":
+      return {
+        type: "subscription-derivation",
+        seq,
+        timestamp,
+        ...peerFields,
+        upstream: cborToSubscriptionRef(take(src, "u")),
+        downstream: (take(src, "d") ?? []).map(cborToSubscriptionRef),
+        kind: take(src, "kind") ?? "",
+        ...optional(src, "traceId", "traceId", asTraceId),
+        ...optional(src, "ns", "namespace", asByteStrings),
+        ...optional(src, "tn", "trackName", asByteString),
+        ...optional(src, "tdr", "tDownstreamReceived", asUintNumber),
+        ...optional(src, "tus", "tUpstreamSent", asUintNumber),
+        ...optional(src, "tuo", "tUpstreamOkReceived", asUintNumber),
+        ...optional(src, "tdo", "tDownstreamOkSent", asUintNumber)
       };
   }
 }
@@ -217,26 +769,104 @@ function writePreamble(headerCbor) {
   buf.set(headerCbor, PREAMBLE_SIZE);
   return buf;
 }
-function validatePreamble(bytes) {
-  if (bytes.length < PREAMBLE_SIZE) {
+function startsWithMagic(bytes, offset) {
+  if (offset + MAGIC.length > bytes.length) return false;
+  for (let i = 0; i < MAGIC.length; i++) {
+    if (bytes[offset + i] !== MAGIC[i]) return false;
+  }
+  return true;
+}
+function validatePreamble(bytes, offset = 0) {
+  if (bytes.length - offset < 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");
-    }
+  if (!startsWithMagic(bytes, offset)) {
+    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 version = view.getUint32(offset + 8, true);
+  if (!SUPPORTED_VERSIONS.includes(version)) {
+    throw new Error(
+      `Unsupported format version: ${version} (supported: ${SUPPORTED_VERSIONS.join(", ")})`
+    );
   }
-  const headerLength = view.getUint32(12, true);
-  if (PREAMBLE_SIZE + headerLength > bytes.length) {
+  const headerLength = view.getUint32(offset + 12, true);
+  if (offset + PREAMBLE_SIZE + headerLength > bytes.length) {
     throw new Error("File truncated: header extends beyond file");
   }
   return { version, headerLength };
 }
+function flatten(segments) {
+  const first = segments[0];
+  if (first == null) return void 0;
+  if (segments.length === 1) return first;
+  return { header: first.header, events: segments.flatMap((segment) => segment.events) };
+}
+function findNextSegment(bytes, from) {
+  for (let offset = from; offset + MAGIC.length <= bytes.length; offset++) {
+    if (startsWithMagic(bytes, offset)) return offset;
+  }
+  return -1;
+}
+function readSegments(bytes, options) {
+  const recover = options?.recover ?? false;
+  const segments = [];
+  let events = [];
+  let offset = 0;
+  const skip = (from, kind, cause) => {
+    const next = findNextSegment(bytes, from + 1);
+    options?.onRecovered?.({ offset: from, kind, resumedAt: next < 0 ? void 0 : next, cause });
+    return next;
+  };
+  validatePreamble(bytes, 0);
+  while (offset < bytes.length) {
+    if (startsWithMagic(bytes, offset)) {
+      const { headerLength } = validatePreamble(bytes, offset);
+      const start = offset + PREAMBLE_SIZE;
+      const headerBytes = bytes.subarray(start, start + headerLength);
+      let header;
+      try {
+        header = cborToHeader(decode(headerBytes));
+      } catch (error) {
+        if (!recover) throw error;
+        const next2 = skip(offset, "header", error);
+        if (next2 < 0) return segments;
+        offset = next2;
+        continue;
+      }
+      events = [];
+      segments.push({ header, events });
+      offset = start + headerLength;
+      continue;
+    }
+    let length;
+    let failure;
+    try {
+      length = cborItemLength(bytes, offset);
+    } catch (error) {
+      if (!recover || !(error instanceof MalformedCborError)) throw error;
+      length = null;
+      failure = error;
+    }
+    if (length != null) {
+      try {
+        const item = decode(bytes.subarray(offset, offset + length));
+        events.push(cborToEvent(item));
+        offset += length;
+        continue;
+      } catch (error) {
+        if (!recover) throw error;
+        failure = error;
+      }
+    } else if (!recover) {
+      throw new TruncatedTraceError(offset, segments);
+    }
+    const next = skip(offset, failure === void 0 ? "truncated" : "event", failure);
+    if (next < 0) return segments;
+    offset = next;
+  }
+  return segments;
+}
 function writeMoqtrace(trace) {
   const headerCbor = encode(headerToCbor(trace.header));
   const preamble = writePreamble(headerCbor);
@@ -256,22 +886,35 @@ function writeMoqtrace(trace) {
   }
   return result;
 }
-function readMoqtrace(bytes) {
-  const { headerLength } = validatePreamble(bytes);
-  const headerBytes = bytes.slice(PREAMBLE_SIZE, PREAMBLE_SIZE + headerLength);
-  const header = cborToHeader(decode(headerBytes));
-  const eventBytes = bytes.slice(PREAMBLE_SIZE + headerLength);
-  const events = [];
-  if (eventBytes.length > 0) {
-    decodeMultiple(eventBytes, (obj) => {
-      events.push(cborToEvent(obj));
-    });
+function writeMoqtraceSegments(segments) {
+  const chunks = segments.map((segment, index) => {
+    if (segment.header.segment == null) {
+      throw new Error(`Segment ${index} has no 'segment' metadata in its header`);
+    }
+    return writeMoqtrace(segment);
+  });
+  const total = chunks.reduce((sum, chunk) => sum + chunk.length, 0);
+  const result = new Uint8Array(total);
+  let offset = 0;
+  for (const chunk of chunks) {
+    result.set(chunk, offset);
+    offset += chunk.length;
   }
-  return { header, events };
+  return result;
+}
+function readMoqtrace(bytes, options) {
+  const trace = flatten(readSegments(bytes, options));
+  if (trace == null) {
+    throw new Error("Invalid magic bytes: not a .moqtrace file");
+  }
+  return trace;
+}
+function readMoqtraceSegments(bytes, options) {
+  return readSegments(bytes, options);
 }
 function readMoqtraceHeader(bytes) {
   const { headerLength } = validatePreamble(bytes);
-  const headerBytes = bytes.slice(PREAMBLE_SIZE, PREAMBLE_SIZE + headerLength);
+  const headerBytes = bytes.subarray(PREAMBLE_SIZE, PREAMBLE_SIZE + headerLength);
   return cborToHeader(decode(headerBytes));
 }
 function createMoqtraceWriter(header) {
@@ -283,6 +926,12 @@ function createMoqtraceWriter(header) {
     },
     writeEvent(event) {
       return encode(eventToCbor(event));
+    },
+    startSegment(next) {
+      if (next.segment == null) {
+        throw new Error("A segment header must carry 'segment' metadata");
+      }
+      return writePreamble(encode(headerToCbor(next)));
     }
   };
 }
@@ -304,7 +953,122 @@ function traceToJSON(trace) {
   );
 }
 
+// src/reader.ts
+var TruncatedStreamError = class extends Error {
+  /**
+   * Offset into the whole stream at which the incomplete item begins — not
+   * where the bytes ran out. It matches the Rust reader's
+   * `MoqTraceError::Truncated { offset }`, so the same cut is named the same
+   * number in both languages.
+   */
+  offset;
+  /**
+   * How many events reached the caller before the cut.
+   *
+   * The events themselves are gone — that is what makes this error different
+   * from {@link TruncatedTraceError} — but their count is not, and it costs one
+   * integer to keep. It is the difference between "the stream was cut" and "the
+   * stream was cut after 4,812 events at byte 190,224", and only the second
+   * tells whoever is holding a damaged capture how much of it they still have.
+   */
+  events;
+  constructor(offset, events) {
+    super(
+      `Trace stream truncated: the item starting at byte ${offset} is incomplete, after ${events} event${events === 1 ? "" : "s"}`
+    );
+    this.name = "TruncatedStreamError";
+    this.offset = offset;
+    this.events = events;
+  }
+};
+function createMoqtraceReader() {
+  let buffer = new Uint8Array(0);
+  let consumed = 0;
+  let delivered = 0;
+  let current;
+  let ended = false;
+  function take2(count) {
+    const slice = buffer.subarray(0, count);
+    buffer = buffer.subarray(count);
+    consumed += count;
+    return slice;
+  }
+  function tryReadSegment() {
+    if (buffer.length < PREAMBLE_SIZE) return void 0;
+    const view = new DataView(buffer.buffer, buffer.byteOffset, buffer.byteLength);
+    const version = view.getUint32(8, true);
+    if (!SUPPORTED_VERSIONS.includes(version)) {
+      throw new Error(
+        `Unsupported format version: ${version} (supported: ${SUPPORTED_VERSIONS.join(", ")})`
+      );
+    }
+    const headerLength = view.getUint32(12, true);
+    if (buffer.length < PREAMBLE_SIZE + headerLength) return void 0;
+    take2(PREAMBLE_SIZE);
+    const headerBytes = take2(headerLength);
+    return cborToHeader(decode(headerBytes));
+  }
+  function drain(atEnd) {
+    const items = [];
+    for (; ; ) {
+      if (current === void 0) {
+        if (buffer.length >= MAGIC.length && !startsWithMagic(buffer, 0)) {
+          throw new Error("Invalid magic bytes: not a .moqtrace file");
+        }
+        const header = tryReadSegment();
+        if (header === void 0) break;
+        current = header;
+        items.push({ kind: "segment", header });
+        continue;
+      }
+      if (buffer.length === 0) break;
+      if (buffer.length < MAGIC.length && !atEnd) break;
+      if (startsWithMagic(buffer, 0)) {
+        const header = tryReadSegment();
+        if (header === void 0) break;
+        current = header;
+        items.push({ kind: "segment", header });
+        continue;
+      }
+      const length = cborItemLength(buffer, 0);
+      if (length === null) break;
+      const item = decode(take2(length));
+      items.push({ kind: "event", event: cborToEvent(item) });
+      delivered += 1;
+    }
+    return items;
+  }
+  return {
+    push(chunk) {
+      if (ended) throw new Error("Cannot push to a reader that has ended");
+      if (chunk.length > 0) {
+        const grown = new Uint8Array(buffer.length + chunk.length);
+        grown.set(buffer, 0);
+        grown.set(chunk, buffer.length);
+        buffer = grown;
+      }
+      return drain(false);
+    },
+    end() {
+      if (ended) return [];
+      ended = true;
+      const items = drain(true);
+      if (buffer.length > 0 || current === void 0) {
+        throw new TruncatedStreamError(consumed, delivered);
+      }
+      return items;
+    },
+    get header() {
+      return current;
+    },
+    get pending() {
+      return buffer.length;
+    }
+  };
+}
+
 // src/recorder.ts
+var MAX_ERROR_RAW_BYTES = 4096;
 var DETAIL_RANK = {
   control: 0,
   headers: 1,
@@ -315,23 +1079,44 @@ var DETAIL_RANK = {
 function createRecorder(options) {
   const detail = options.detail;
   const detailRank = DETAIL_RANK[detail];
+  if (detailRank === void 0) {
+    throw new Error(
+      `Unknown detail level '${detail}': cannot record at a level this build does not implement`
+    );
+  }
   const maxEvents = options.maxEvents ?? 1e5;
   const clock = options.clock ?? (() => Math.round(performance.now() * 1e3));
   const messageTypeId = options.messageTypeId ?? (() => 0);
   const events = [];
+  let head = 0;
+  let dropped = 0;
+  const rawRecorded = /* @__PURE__ */ new Set();
   let _recording = true;
   let _seq = 0;
   const startTime = Date.now();
   function addEvent(event) {
     if (!_recording) return;
-    if (events.length >= maxEvents) {
-      events.shift();
+    if (events.length - head >= maxEvents) {
+      head++;
+      dropped++;
+      if (head >= 4096 || head >= maxEvents) {
+        events.splice(0, head);
+        head = 0;
+      }
     }
     events.push(event);
   }
   function nextSeq() {
     return _seq++;
   }
+  function rawFlow(streamId) {
+    return streamId == null ? "no-stream" : `stream:${streamId}`;
+  }
+  function claimRawSlot(flow) {
+    if (rawRecorded.has(flow)) return false;
+    rawRecorded.add(flow);
+    return true;
+  }
   function wrapSession(session) {
     return {
       get phase() {
@@ -457,14 +1242,27 @@ function createRecorder(options) {
       };
       addEvent(event);
     },
-    recordError(errorCode, reason) {
-      addEvent({
+    recordError(errorCode, reason, details) {
+      const streamId = details?.streamId;
+      const raw = details?.raw;
+      const rawLength = details?.rawLength === null ? void 0 : details?.rawLength ?? raw?.length;
+      const writeRaw = raw != null && detailRank >= DETAIL_RANK.full && claimRawSlot(rawFlow(streamId));
+      const event = {
         type: "error",
         seq: nextSeq(),
         timestamp: clock(),
         errorCode,
-        reason
-      });
+        reason,
+        ...streamId != null ? { streamId } : {},
+        ...details?.errorKind != null ? { errorKind: details.errorKind } : {},
+        // A size, gated with the other sizes and one level below the bytes: an
+        // error may name a data stream, so at 'control' this length would be a
+        // fact about media volume in a trace whose declared level excludes it.
+        // Written whether or not the bytes are, which is most of its value.
+        ...rawLength != null && detailRank >= DETAIL_RANK["headers+sizes"] ? { rawLength } : {},
+        ...writeRaw && raw != null ? { raw: raw.length > MAX_ERROR_RAW_BYTES ? raw.slice(0, MAX_ERROR_RAW_BYTES) : raw } : {}
+      };
+      addEvent(event);
     },
     annotate(label, data) {
       addEvent({
@@ -486,9 +1284,18 @@ function createRecorder(options) {
         ...options.transport != null ? { transport: options.transport } : {},
         ...options.source != null ? { source: options.source } : {},
         ...options.endpoint != null ? { endpoint: options.endpoint } : {},
-        ...options.sessionId != null ? { sessionId: options.sessionId } : {}
+        ...options.sessionId != null ? { sessionId: options.sessionId } : {},
+        // Carried through so a recorder with something to say the format has
+        // no key for can say it, and so a header this package builds has the
+        // same shape as one it reads. `writeMoqtrace` writes the store after
+        // the keys above and drops any entry naming one of them.
+        ...options.extra != null ? { extra: options.extra } : {},
+        // Only when something was actually dropped: the key's presence is
+        // what tells a reader this trace is incomplete, so writing it with a
+        // zero would make every complete trace look sampled.
+        ...dropped > 0 ? { sampling: { dropPolicy: "head", droppedTotal: dropped } } : {}
       };
-      return { header, events: [...events] };
+      return { header, events: events.slice(head) };
     },
     get recording() {
       return _recording;
@@ -496,10 +1303,21 @@ function createRecorder(options) {
   };
 }
 export {
+  FORMAT_VERSION,
+  MAX_ERROR_RAW_BYTES,
+  MalformedHeaderError,
+  SUPPORTED_VERSIONS,
+  TRACE_ID_LENGTH,
+  TruncatedStreamError,
+  TruncatedTraceError,
+  controlMessageFields,
+  createMoqtraceReader,
   createMoqtraceWriter,
   createRecorder,
   readMoqtrace,
   readMoqtraceHeader,
+  readMoqtraceSegments,
   traceToJSON,
-  writeMoqtrace
+  writeMoqtrace,
+  writeMoqtraceSegments
 };