@moqtap/trace 0.3.0 → 0.4.2

package/README.md

@@ -1,15 +1,9 @@
 # @moqtap/trace
 
-Record, serialize, and analyze MoQT (Media over QUIC Transport) sessions using the `.moqtrace` binary format.
-
-- Binary `.moqtrace` format with CBOR encoding (compact, streamable, cross-language)
-- Segmented traces for capture rotation, live carriage, and recovery from a damaged region
-- Configurable detail levels from control-only to full wire captures
-- Session recorder that wraps `@moqtap/codec` session state machines
-- Human-readable JSON export for debugging
-- Zero-copy streaming writer for large traces
-
-Writes format version 2 and reads versions 1 and 2.
+Record, serialize and analyze MoQT (Media over QUIC Transport) sessions as
+`.moqtrace` files — a compact, streamable CBOR format that reads the same across
+implementations. Includes a recorder that wraps `@moqtap/codec` session state
+machines, streaming read and write, and a lossy JSON export for debugging.
 
 ## Install
 
@@ -17,186 +11,109 @@ Writes format version 2 and reads versions 1 and 2.
 npm install @moqtap/trace @moqtap/codec
 ```
 
-`@moqtap/codec` is a peer dependency — install it alongside `@moqtap/trace`.
+`@moqtap/codec` is a peer dependency — install it alongside.
 
 ## Quick Start
 
-### Recording a session
+Wrap a codec session state machine, then serialize what it recorded:
 
 ```typescript
 import { createRecorder, writeMoqtrace } from '@moqtap/trace'
-import { createDraft17SessionState } from '@moqtap/codec/draft17/session'
+import { MESSAGE_ID_MAP } from '@moqtap/codec/draft21'
+import { createDraft21SessionState } from '@moqtap/codec/draft21/session'
 
 const recorder = createRecorder({
-  protocol: 'moq-transport-17',
+  protocol: 'moqt-21',
   perspective: 'client',
   detail: 'control',
+  messageTypeId: (name) => Number(MESSAGE_ID_MAP.get(name) ?? 0),
 })
 
-// Wrap a session to auto-capture control messages and state transitions
-const session = createDraft17SessionState('client')
-const traced = recorder.wrapSession(session)
-
-// Use `traced` instead of `session` — all send/receive calls are recorded
+// Every send/receive on the wrapper is recorded.
+const traced = recorder.wrapSession(createDraft21SessionState('client'))
 traced.send(setupMessage)
 traced.receive(setupMessage)
 
-// Manually record events the session layer doesn't see
-recorder.recordStreamOpened(4n, 0, 0) // outgoing subgroup stream
+// Events the session layer never sees.
+recorder.recordStreamOpened(4n, 0, 0)
 recorder.annotate('connected', { relay: 'cdn.example.com' })
 
-// Finalize and serialize
-const trace = recorder.finalize()
-const bytes = writeMoqtrace(trace) // → Uint8Array (.moqtrace binary)
+const bytes = writeMoqtrace(recorder.finalize()) // Uint8Array
 ```
 
-### Reading a trace file
+Read one back:
 
 ```typescript
 import { readMoqtrace, readMoqtraceHeader } from '@moqtap/trace'
 
-// Quick metadata peek (no event parsing)
-const header = readMoqtraceHeader(bytes)
-console.log(header.protocol) // "moq-transport-17"
-console.log(header.perspective) // "client"
-console.log(header.detail) // "control"
+const header = readMoqtraceHeader(bytes) // metadata only, no event parsing
+console.log(header.protocol, header.perspective, header.detail)
 
-// Full parse
 const trace = readMoqtrace(bytes)
 for (const event of trace.events) {
   console.log(event.type, event.timestamp)
 }
 ```
 
-### Streaming writer (for large traces)
-
-```typescript
-import { createMoqtraceWriter } from '@moqtap/trace'
-
-const writer = createMoqtraceWriter(header)
-outputStream.write(writer.preamble())
-
-for (const event of events) {
-  outputStream.write(writer.writeEvent(event))
-}
-```
-
-### Segmented traces
-
-A segment is a complete `.moqtrace` blob — magic, version, header, events —
-appended after the one before it, so a reader can start at any segment without
-the ones preceding it. That buys capture rotation without finalizing a file, a
-natural cut point for live carriage, and recovery from a damaged region.
-
-```typescript
-import { readMoqtraceSegments, writeMoqtraceSegments } from '@moqtap/trace'
-
-// Each segment header must carry `segment` metadata: it is what tells a reader
-// that `seq` and `timestamp` restart at zero in every segment.
-const bytes = writeMoqtraceSegments([
-  { header: { ...header, segment: { sequence: 0 } }, events: firstBatch },
-  { header: { ...header, segment: { sequence: 1, continues: true } }, events: secondBatch },
-])
-
-// Read the boundaries — you need them to order events across segments.
-for (const segment of readMoqtraceSegments(bytes)) {
-  console.log(segment.header.segment?.sequence, segment.events.length)
-}
+## API
+
+| Function                                             | Purpose                                                      |
+| ---------------------------------------------------- | ------------------------------------------------------------ |
+| `createRecorder(options)`                            | Session recorder; wraps a codec session state machine         |
+| `writeMoqtrace(trace)`                               | Serialize a complete trace to bytes                           |
+| `readMoqtrace(bytes)`                                | Parse a complete file, flattening every segment in order      |
+| `readMoqtraceHeader(bytes)`                          | Parse the header only                                         |
+| `createMoqtraceWriter(header)`                       | Streaming writer: `preamble()`, then `writeEvent()` per event  |
+| `createMoqtraceReader()`                             | Incremental reader for a stream arriving in chunks             |
+| `writeMoqtraceSegments()` / `readMoqtraceSegments()` | Segmented traces, for rotation, live carriage and recovery    |
+| `traceToJSON(trace)`                                 | Human-readable export; lossy, as bigints and bytes stringify   |
+
+`createRecorder` requires `protocol`, `perspective` and `detail`. Pass
+`messageTypeId` to map a message name to its wire id, which session-layer
+recording needs; `maxEvents` bounds the event buffer.
+
+Beyond `wrapSession`, the recorder takes events the session layer cannot see:
+`recordStreamOpened`, `recordStreamClosed`, `recordObjectHeader`,
+`recordObjectPayload`, `recordError` and `annotate`. `finalize()` returns the
+trace and stops recording.
+
+## Detail levels
+
+| Level           | What is recorded                       |
+| --------------- | -------------------------------------- |
+| `control`       | Control messages only                  |
+| `headers`       | + data stream and object headers       |
+| `headers+sizes` | + payload byte lengths                 |
+| `headers+data`  | + full payload bytes                   |
+| `full`          | + raw wire bytes, pre-decode           |
+
+Errors and annotations are recorded at every level. `headers+data` and `full`,
+and the `raw` field on any event, carry user content, so capturing them should
+be an explicit choice rather than a default.
+
+When recording an error, hand `recordError` the full bytes: it applies
+`MAX_ERROR_RAW_BYTES` itself and reports the untruncated length separately, so a
+caller that pre-truncates destroys the signal saying the capture is partial.
 
-// Or ignore them: readMoqtrace flattens every segment's events in order.
-```
+## Reading a trace you did not write
 
-### Damaged and truncated files
+Nothing is rejected for carrying something newer than this version knows. An
+unrecognised event type arrives as an `UnknownEvent` with its fields intact, and
+an unrecognised key is preserved verbatim in an `extra` map beside the fields, so
+neither is dropped by a read-modify-write round trip.
 
 A file that stops part-way through an event throws `TruncatedTraceError`, which
-carries everything that decoded before the cut — a truncated trace is still
-evidence. On a segmented trace, `{ recover: true }` skips a damaged region and
+carries everything that decoded before the cut. On a segmented trace,
+`readMoqtraceSegments(bytes, { recover: true })` skips a damaged region and
 resumes at the next segment instead of throwing.
 
-```typescript
-import { readMoqtrace, readMoqtraceSegments, TruncatedTraceError } from '@moqtap/trace'
-
-try {
-  const trace = readMoqtrace(bytes)
-} catch (error) {
-  if (error instanceof TruncatedTraceError) {
-    console.warn(`truncated at byte ${error.offset}`)
-    console.log(error.trace?.events.length, 'events survived')
-  }
-}
-
-const whatSurvived = readMoqtraceSegments(bytes, { recover: true })
-```
-
-## Reading a trace you did not write
-
-Nothing here rejects a file for carrying something newer than this version
-knows. An unrecognised event type arrives as an `UnknownEvent` with its fields
-intact, so it survives a read-modify-write round trip rather than being dropped
-or relabelled; an unrecognised perspective, detail level, role, side, drop
-policy or derivation kind is kept verbatim.
-
-The one place that refuses is `createRecorder`, which cannot honour a detail
-level it does not implement: it would either capture less than you asked for
-while writing a header claiming otherwise, or — for the payload-bearing levels
-— capture more.
+## File format
 
-## Detail Levels
+[SPEC.md](./SPEC.md) is the complete `.moqtrace` binary specification.
 
-| Level           | What's recorded                                           |
-| --------------- | --------------------------------------------------------- |
-| `control`       | Control messages only (setup, subscribe, publish, goaway) |
-| `headers`       | + data stream headers (subgroup/fetch, object metadata)   |
-| `headers+sizes` | + payload byte lengths                                    |
-| `headers+data`  | + full payload bytes                                      |
-| `full`          | + raw wire bytes (pre-decode)                             |
-
-`headers+data` and `full`, and the `raw` field on any event, carry user
-content. Capturing them is optional for a conformant recorder and should be an
-explicit choice, not a default.
-
-## JSON Export
-
-For human-readable debugging (not lossless — bigint/Uint8Array become strings):
-
-```typescript
-import { traceToJSON } from '@moqtap/trace'
-
-const json = traceToJSON(trace)
-console.log(json)
-```
+## Documentation
 
-## Upgrading from 0.2.0
-
-The package now writes format version 2. A 0.2.0 reader rejects those files at
-byte 8, which is the point of the bump: it turns what would have been silent
-desynchronization on a segmented trace into a clear refusal. Reading is
-unaffected in the other direction — 0.3.0 reads everything 0.2.0 wrote.
-
-What changes for code already using it:
-
-- `TraceEvent` gained four members (`peer-connected`, `peer-disconnected`,
-  `subscription-derivation`, `unknown`). A `switch` that handles only the
-  cases it cares about is unaffected; one that asserts exhaustiveness is not.
-- `Perspective`, `DetailLevel` and the new string unions accept values they do
-  not name, so indexing a `Record<DetailLevel, T>` with one now yields
-  `T | undefined`.
-- An unknown event type used to arrive as an annotation labelled
-  `unknown-event-<n>`. It now arrives as an `UnknownEvent` carrying its real
-  type and fields, so code matching that label should match `type === 'unknown'`
-  instead. The old shape was lossy in a way that mattered: writing the trace
-  back rewrote the event's type to 7.
-- `createRecorder` throws on a detail level it does not implement, which the
-  types previously made unexpressible.
-- The bytes changed in two ways that make files readable by the Rust
-  implementation for the first time: an integral value past 32 bits is now
-  written as a CBOR integer rather than a float64, and a byte string as major
-  type 2 rather than wrapped in the typed-array tag 64. Both readers accept
-  either form, so nothing already written becomes unreadable.
-
-## File Format
-
-See [SPEC.md](./SPEC.md) for the complete `.moqtrace` binary format specification.
+<https://moqtap.com/npm-packages/moqtap-trace/>
 
 ## License