@moqtap/trace 0.2.0 → 0.3.0

package/dist/index.js

@@ -1,13 +1,150 @@
 // 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;
+
+// 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 +154,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,20 +167,85 @@ 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"]);
+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);
+  }
+};
+function segmentToCbor(segment) {
+  const map = { sequence: int(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 map;
+}
+function cborToSegment(obj) {
+  return {
+    sequence: Number(obj.sequence ?? 0),
+    ...obj.durationMs != null ? { durationMs: Number(obj.durationMs) } : {},
+    ...obj.streamId != null ? { streamId: obj.streamId } : {},
+    ...obj.continues != null ? { continues: obj.continues } : {}
+  };
+}
+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 map;
+}
+function cborToSampling(obj) {
+  return {
+    ...obj.effectiveRate != null ? { effectiveRate: Number(obj.effectiveRate) } : {},
+    ...obj.maxEventsPerSec != null ? { maxEventsPerSec: Number(obj.maxEventsPerSec) } : {},
+    ...obj.dropPolicy != null ? { dropPolicy: obj.dropPolicy } : {},
+    ...obj.droppedTotal != null ? { droppedTotal: Number(obj.droppedTotal) } : {},
+    ...obj.droppedSegment != null ? { droppedSegment: Number(obj.droppedSegment) } : {},
+    ...obj.rule != null ? { rule: obj.rule } : {},
+    ...obj.ruleLang != null ? { ruleLang: obj.ruleLang } : {},
+    ...obj.appliesTo != null ? { appliesTo: obj.appliesTo.map(Number) } : {}
+  };
+}
 function headerToCbor(header) {
   const map = {
     protocol: header.protocol,
     perspective: header.perspective,
     detail: header.detail,
-    startTime: header.startTime
+    startTime: int(header.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;
 }
@@ -49,25 +254,51 @@ function cborToHeader(obj) {
     protocol: obj.protocol,
     perspective: obj.perspective,
     detail: obj.detail,
-    startTime: obj.startTime,
-    ...obj.endTime != null ? { endTime: obj.endTime } : {},
+    startTime: Number(obj.startTime),
+    ...obj.endTime != null ? { endTime: Number(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.segment != null ? { segment: cborToSegment(obj.segment) } : {},
+    ...obj.sampling != null ? { sampling: cborToSampling(obj.sampling) } : {},
     ...obj.custom != null ? { custom: obj.custom } : {}
   };
 }
+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]");
+  }
+  return { peer: value[0], requestId: BigInt(value[1]) };
+}
+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.mt = int(event.messageType);
       base.msg = event.message;
       if (event.streamId != null) base.sid = event.streamId;
       if (event.raw != null) base.raw = event.raw;
@@ -81,22 +312,22 @@ function eventToCbor(event) {
     }
     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,7 +337,7 @@ function eventToCbor(event) {
       break;
     }
     case "error": {
-      base.ec = event.errorCode;
+      base.ec = int(event.errorCode);
       base.reason = event.reason;
       break;
     }
@@ -115,39 +346,79 @@ 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)) {
+        base[key] = value;
+      }
+      break;
+    }
   }
   return base;
 }
 function cborToEvent(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)) 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,
+        ...peerFields,
         direction: obj.d,
         messageType: Number(obj.mt ?? 0),
         message: obj.msg ?? {},
         ...obj.sid != null ? { streamId: BigInt(obj.sid) } : {},
-        ...obj.raw != null ? { raw: obj.raw } : {}
+        ...obj.raw != null ? { raw: toBytes(obj.raw) } : {}
       };
     case "stream-opened":
       return {
         type: "stream-opened",
         seq,
         timestamp,
+        ...peerFields,
         streamId: BigInt(obj.sid),
         direction: obj.d,
         streamType: obj.st
@@ -157,6 +428,7 @@ function cborToEvent(obj) {
         type: "stream-closed",
         seq,
         timestamp,
+        ...peerFields,
         streamId: BigInt(obj.sid),
         errorCode: Number(obj.ec ?? 0)
       };
@@ -165,6 +437,7 @@ function cborToEvent(obj) {
         type: "object-header",
         seq,
         timestamp,
+        ...peerFields,
         streamId: BigInt(obj.sid),
         groupId: BigInt(obj.g),
         objectId: BigInt(obj.o),
@@ -176,17 +449,19 @@ function cborToEvent(obj) {
         type: "object-payload",
         seq,
         timestamp,
+        ...peerFields,
         streamId: BigInt(obj.sid),
         groupId: BigInt(obj.g),
         objectId: BigInt(obj.o),
         size: Number(obj.sz ?? 0),
-        ...obj.pl != null ? { payload: obj.pl } : {}
+        ...obj.pl != null ? { payload: toBytes(obj.pl) } : {}
       };
     case "state-change":
       return {
         type: "state-change",
         seq,
         timestamp,
+        ...peerFields,
         from: obj.from,
         to: obj.to
       };
@@ -195,6 +470,7 @@ function cborToEvent(obj) {
         type: "error",
         seq,
         timestamp,
+        ...peerFields,
         errorCode: Number(obj.ec ?? 0),
         reason: obj.reason ?? ""
       };
@@ -203,9 +479,47 @@ function cborToEvent(obj) {
         type: "annotation",
         seq,
         timestamp,
+        ...peerFields,
         label: obj.label ?? "",
         data: obj.data
       };
+    case "peer-connected":
+      return {
+        type: "peer-connected",
+        seq,
+        timestamp,
+        ...peerFields,
+        ...obj.endpoint != null ? { endpoint: obj.endpoint } : {},
+        ...obj.transport != null ? { transport: obj.transport } : {},
+        ...obj.role != null ? { role: obj.role } : {},
+        ...obj.side != null ? { side: obj.side } : {}
+      };
+    case "peer-disconnected":
+      return {
+        type: "peer-disconnected",
+        seq,
+        timestamp,
+        ...peerFields,
+        errorCode: Number(obj.ec ?? 0),
+        ...obj.reason != null ? { reason: obj.reason } : {}
+      };
+    case "subscription-derivation":
+      return {
+        type: "subscription-derivation",
+        seq,
+        timestamp,
+        ...peerFields,
+        upstream: cborToSubscriptionRef(obj.u),
+        downstream: (obj.d ?? []).map(cborToSubscriptionRef),
+        kind: obj.kind ?? "",
+        ...obj.traceId != null ? { traceId: checkTraceId(obj.traceId) } : {},
+        ...obj.ns != null ? { namespace: obj.ns.map(toBytes) } : {},
+        ...obj.tn != null ? { trackName: toBytes(obj.tn) } : {},
+        ...obj.tdr != null ? { tDownstreamReceived: Number(obj.tdr) } : {},
+        ...obj.tus != null ? { tUpstreamSent: Number(obj.tus) } : {},
+        ...obj.tuo != null ? { tUpstreamOkReceived: Number(obj.tuo) } : {},
+        ...obj.tdo != null ? { tDownstreamOkSent: Number(obj.tdo) } : {}
+      };
   }
 }
 function writePreamble(headerCbor) {
@@ -217,26 +531,89 @@ 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;
+  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);
+      events = [];
+      segments.push({
+        header: cborToHeader(decode(headerBytes)),
+        events
+      });
+      offset = start + headerLength;
+      continue;
+    }
+    let length;
+    try {
+      length = cborItemLength(bytes, offset);
+    } catch (error) {
+      if (!recover || !(error instanceof MalformedCborError)) throw error;
+      length = null;
+    }
+    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;
+      }
+    } else if (!recover) {
+      throw new TruncatedTraceError(offset, segments);
+    }
+    const next = findNextSegment(bytes, offset + 1);
+    if (next < 0) return segments;
+    offset = next;
+  }
+  return segments;
+}
 function writeMoqtrace(trace) {
   const headerCbor = encode(headerToCbor(trace.header));
   const preamble = writePreamble(headerCbor);
@@ -256,22 +633,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 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 { header, events };
+  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 +673,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)));
     }
   };
 }
@@ -315,6 +711,11 @@ 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);
@@ -496,10 +897,16 @@ function createRecorder(options) {
   };
 }
 export {
+  FORMAT_VERSION,
+  SUPPORTED_VERSIONS,
+  TRACE_ID_LENGTH,
+  TruncatedTraceError,
   createMoqtraceWriter,
   createRecorder,
   readMoqtrace,
   readMoqtraceHeader,
+  readMoqtraceSegments,
   traceToJSON,
-  writeMoqtrace
+  writeMoqtrace,
+  writeMoqtraceSegments
 };