@moqtap/trace 0.3.0 → 0.4.1

package/src/types.ts

@@ -41,6 +41,14 @@ export interface SegmentInfo {
   readonly streamId?: string
   /** True if this segment continues a previous one with the same `streamId`. */
   readonly continues?: boolean
+  /**
+   * Keys in the `"segment"` map this version does not recognise, kept verbatim
+   * and written back inside that map rather than at the top level.
+   *
+   * See {@link TraceHeader.extra}, which this mirrors — including the part
+   * about a key this version *does* know whose value it cannot use.
+   */
+  readonly extra?: Record<string, unknown>
 }
 
 /**
@@ -63,8 +71,24 @@ export interface SamplingInfo {
   readonly rule?: string
   /** Language the rule is written in ('prefix', 'glob', 'cel'). */
   readonly ruleLang?: string
-  /** Event type IDs the drop policy was applied to. */
+  /**
+   * Event type IDs the drop policy was applied to.
+   *
+   * All or nothing: an array with one element that is not an event type ID is
+   * unusable *entire* and stays in {@link extra}. Keeping the elements that
+   * read cleanly would not be a partial answer but a wrong one — this key
+   * names the types the policy touched, and every type absent from it may be
+   * treated as complete, so a shortened array reports a sampled type as fully
+   * recorded.
+   */
   readonly appliesTo?: number[]
+  /**
+   * Keys in the `"sampling"` map this version does not recognise, kept
+   * verbatim and written back inside that map rather than at the top level.
+   *
+   * See {@link TraceHeader.extra}, which this mirrors.
+   */
+  readonly extra?: Record<string, unknown>
 }
 
 export interface TraceHeader {
@@ -85,7 +109,43 @@ export interface TraceHeader {
   readonly segment?: SegmentInfo
   /** Present only when events were dropped or filtered at the source. */
   readonly sampling?: SamplingInfo
+  /**
+   * User-defined metadata, handed back key for key and value for value.
+   *
+   * A passthrough, and the one map in the header with no store of its own:
+   * every key in it belongs to whoever wrote the trace, so there is no such
+   * thing as an unrecognised key there. A `"custom"` this reader cannot hold
+   * exactly — one that is not a map at all — is therefore unusable as a whole
+   * and goes to {@link extra}, leaving this field absent rather than typed as
+   * a record it is not.
+   */
   readonly custom?: Record<string, unknown>
+  /**
+   * Keys in the header map that this version of the package does not
+   * recognise, kept verbatim.
+   *
+   * The same guarantee a `TraceEvent`'s `extra` gives one level down, and for
+   * the same reason: "unknown keys MUST be ignored" is a rule about reading
+   * *past* them, not a licence to drop them. A tool that reads a trace and
+   * writes it back — a redaction pass, a filter, a re-segmentation, a download
+   * with annotations applied — would otherwise emit a valid file that looks as
+   * though it never carried them, and one tool's ignorance would become
+   * permanent for every reader downstream of it.
+   *
+   * A key this version *does* know counts as unrecognised when its value is of
+   * a type the field cannot hold. `"transport": 42` is not a transport; it is
+   * also not nothing. Such a value is kept here rather than coerced into the
+   * field or dropped, {@link transport} reads as absent, and the key is
+   * written back unchanged. Knowing more about a key must not mean preserving
+   * it less.
+   *
+   * Three maps in the header carry a store — this one, {@link SegmentInfo} and
+   * {@link SamplingInfo} — and each is written back into the map it came from.
+   * One store for the whole header would not do: a private key on `"segment"`
+   * and a key of the same name at the top level are different keys, and
+   * re-emitting either in the other's map changes what the file says.
+   */
+  readonly extra?: Record<string, unknown>
 }
 
 interface BaseEvent {
@@ -105,13 +165,54 @@ interface BaseEvent {
    * not name the same peer.
    */
   readonly peer?: string
+  /**
+   * Keys on this event that this version of the package does not recognise,
+   * kept verbatim.
+   *
+   * Optional keys may be added to an existing event type without a format
+   * version bump, so "unknown keys MUST be ignored" is a rule about *reading
+   * past* them. It is not a licence to drop them: a tool that reads a trace
+   * and writes it back — a redaction pass, a filter, an annotated download —
+   * would otherwise emit a valid file that looks like it never carried them,
+   * and one tool's ignorance would become permanent for every reader
+   * downstream of it.
+   *
+   * A key this version *does* know counts as unrecognised when its value is of
+   * a type the field cannot hold — a `"ta"` carrying text, say. It is kept
+   * here rather than coerced into the field or dropped, and written back
+   * unchanged, exactly as a key nobody had heard of would be. Knowing more
+   * about a key must not mean preserving it less.
+   *
+   * {@link UnknownEvent} already does this for an event type the package
+   * cannot name. This is the same guarantee one level down, for a key on a
+   * type it can. It is always absent on an `UnknownEvent`, whose `fields`
+   * hold every non-common key already.
+   */
+  readonly extra?: Record<string, unknown>
 }
 
 export interface ControlMessageEvent extends BaseEvent {
   readonly type: 'control'
   readonly direction: 0 | 1
   readonly messageType: number
-  readonly message: Record<string, unknown>
+  /**
+   * The message's decoded fields — the `"msg"` field of Event 0.
+   *
+   * A writer MUST produce a map here, keyed in snake_case (`request_id`,
+   * `track_alias`), and an empty one when it decoded nothing. A *reader* has
+   * to accept less, because files written before the format said so exist:
+   * every `capture-*` case in the conformance corpus carries a Rust `Debug`
+   * rendering of the message instead — `'Draft16(ClientSetup(ClientSetup {
+   * parameters: [] }))'` — and the format requires such a value to be handed
+   * back unchanged rather than rejected or replaced.
+   *
+   * So the type is `unknown`, not `Record<string, unknown>`. The `Record` was
+   * a lie the compiler could not catch: `event.message.request_id` typechecks
+   * against a string and reads `undefined` at runtime, on exactly the files
+   * this rule exists for. Narrow before reading keys — {@link
+   * controlMessageFields} does it correctly.
+   */
+  readonly message: unknown
   readonly raw?: Uint8Array
   /**
    * QUIC stream the message travelled on.
@@ -124,11 +225,85 @@ export interface ControlMessageEvent extends BaseEvent {
   readonly streamId?: bigint
 }
 
+/**
+ * The decoded fields of a control message, or `undefined` when its `"msg"` is
+ * not a map and there are no fields to address.
+ *
+ * Provided because the narrowing is easy to get wrong once per call site and
+ * silently: `typeof message === 'object'` also admits `null`, a CBOR array,
+ * and a byte string, each of which would then be typed as a field map and
+ * read back `undefined` for every key. A caller that skips the check entirely
+ * gets the bug this function exists to prevent — see
+ * {@link ControlMessageEvent.message}.
+ */
+export function controlMessageFields(message: unknown): Record<string, unknown> | undefined {
+  if (message === null || typeof message !== 'object') return undefined
+  if (Array.isArray(message) || ArrayBuffer.isView(message)) return undefined
+  return message as Record<string, unknown>
+}
+
 export interface StreamOpenedEvent extends BaseEvent {
   readonly type: 'stream-opened'
   readonly streamId: bigint
   readonly direction: 0 | 1
   readonly streamType: 0 | 1 | 2
+  /**
+   * Track alias the stream carries. Written whenever the recorder knows it.
+   *
+   * The stream header carries the alias and no detail level records that
+   * header's bytes, so before this field a `'headers'` recording could not say
+   * which track a stream belonged to — which is most of what the level exists
+   * to answer, and there was nothing left to re-parse it from.
+   *
+   * `bigint`, and so are the three fields below, unlike this event's
+   * `direction` and `streamType`. Those two are small enumerations that a
+   * narrow type suits; these four are wire identifiers with the same range as
+   * {@link ObjectHeaderEvent}'s `groupId`, `objectId` and `streamId`, and
+   * readers compare the two events. Typed as `number` here, a match would read
+   * as a mismatch: `streamOpened.groupId === objectHeader.groupId` evaluates
+   * `42 === 42n`, which is `false`, with no error, for every pair of values
+   * that are in fact the same.
+   *
+   * Absent when the file's `"ta"` was not an unsigned integer — and the same
+   * for the three fields below. Such a value belongs to no field here, so it
+   * stays verbatim in {@link BaseEvent.extra} and is written back as it came.
+   * It is never coerced on the way in: `true` and the text `"4"` are not track
+   * alias 1 and track alias 4, however willingly `BigInt` converts them.
+   */
+  readonly trackAlias?: bigint
+  /**
+   * Subgroup ID, on a subgroup stream (`streamType === 0`).
+   *
+   * A writer must not set it on another stream type, where nothing supplies
+   * it. A reader that meets one there keeps it rather than rejecting the
+   * event: an out-of-scope key makes one field meaningless, not the file
+   * unreadable, and discarding the event throws away every other field on it —
+   * all of which were fine. That is about the key being in the wrong place; a
+   * `"sg"` of the wrong *shape* is not held here at all, but in
+   * {@link BaseEvent.extra}.
+   */
+  readonly subgroupId?: bigint
+  /**
+   * Fetch request ID, on a fetch stream (`streamType === 2`).
+   *
+   * A writer MUST set it there. It is the only correlation between the stream
+   * and the FETCH that asked for it, and without it a fetch stream cannot be
+   * attributed to a request at all. A reader must nevertheless accept a fetch
+   * stream that lacks one — every recording made before the key existed lacks
+   * it — for the same reason as the `'msg'` asymmetry on
+   * {@link ControlMessageEvent.message}: writers conform, readers tolerate.
+   */
+  readonly fetchRequestId?: bigint
+  /**
+   * Group ID, on a datagram stream (`streamType === 1`).
+   *
+   * Scoped to datagrams because on a subgroup stream every object carries the
+   * same group by construction, so a copy here would be a second field with no
+   * independent source. Where an {@link ObjectHeaderEvent} for the same stream
+   * disagrees, that event wins and this is not corruption: this copy is a
+   * convenience for a reader that has not yet seen an object.
+   */
+  readonly groupId?: bigint
 }
 
 export interface StreamClosedEvent extends BaseEvent {
@@ -161,10 +336,86 @@ export interface StateChangeEvent extends BaseEvent {
   readonly to: string
 }
 
+/**
+ * What sort of failure an error event records.
+ *
+ * An open vocabulary: this revision names the three below, others may be added
+ * without a format version bump, and a reader must preserve a value it does not
+ * recognise rather than reject the event — the same contract as {@link
+ * Perspective} and {@link DetailLevel}, which is why all three widen with
+ * `OtherString` instead of being closed unions.
+ */
+export type ErrorKind =
+  /** The peer violated the protocol. */
+  | 'protocol'
+  /** The QUIC or WebTransport layer failed. */
+  | 'transport'
+  /** Bytes that would not parse as any message this recorder knows. */
+  | 'decode'
+  | OtherString
+
 export interface TraceErrorEvent extends BaseEvent {
   readonly type: 'error'
   readonly errorCode: number
   readonly reason: string
+  /**
+   * QUIC stream the error was observed on.
+   *
+   * Optional on the same terms as {@link ControlMessageEvent.streamId}: absent
+   * means there was no stream, or that the recorder knew of none, which a
+   * reader MUST distinguish from stream `0`. `bigint` for the reason given
+   * there — it is the same wire identifier, and `number` stops being exact at
+   * 2^53, which would make this reader disagree with the Rust one silently and
+   * only for large values.
+   *
+   * It may name a *data* stream, which is why {@link rawLength} is gated a
+   * level above this event rather than travelling with it: the length behind an
+   * error on a subgroup stream is the size of a run of media framing.
+   */
+  readonly streamId?: bigint
+  /**
+   * What sort of failure this was.
+   *
+   * Spelt out rather than `kind` because {@link SubscriptionDerivationEvent}
+   * already owns that name with the unrelated vocabulary `'created'` /
+   * `'shared'`. Two vocabularies under one name survive in a typed reader and
+   * break in every flat projection of a trace — a JSONL export, a warehouse
+   * load, this package's own {@link traceToJSON} — where they become one column
+   * holding both. The wire key is `"ek"` for the same reason.
+   */
+  readonly errorKind?: ErrorKind
+  /**
+   * How many bytes the recorder held for this error, before any truncation.
+   *
+   * Not the length of {@link raw}: where the two differ the capture is partial,
+   * and this is how a reader learns how much is missing. A `raw` of exactly
+   * `MAX_ERROR_RAW_BYTES` with no `rawLength` beside it must be treated as
+   * possibly truncated, that being the one length the cap makes ambiguous.
+   *
+   * Recorded from `'headers+sizes'` up — one level below {@link raw} and
+   * deliberately not with it. It is a size and carries no content, so it is
+   * available in every trace where the bytes themselves must not appear, and
+   * how large a malformed message was often separates a truncated message from
+   * a mistyped one on its own.
+   */
+  readonly rawLength?: number
+  /**
+   * The bytes behind the error.
+   *
+   * Payload-bearing, and recorded only at `'full'`: an error naming a data
+   * stream has subgroup framing and object payload behind it, so inheriting
+   * this event's own `control`+ level would have put media into traces whose
+   * declared level excludes payloads entirely.
+   *
+   * The 4096-byte cap on this field binds a *recorder* — see
+   * `MAX_ERROR_RAW_BYTES` in `recorder.ts`, which is where it is applied and
+   * the only place it appears. It does not bind this type, the reader or the
+   * writer: a longer value read out of a file is handed over whole and written
+   * back whole. Re-truncating it would destroy evidence to make someone else's
+   * file conform to a rule that was never addressed to the tool doing the
+   * truncating.
+   */
+  readonly raw?: Uint8Array
 }
 
 export interface AnnotationEvent extends BaseEvent {
@@ -304,6 +555,16 @@ export interface RecorderOptions {
   readonly source?: string
   readonly endpoint?: string
   readonly sessionId?: string
+  /**
+   * Extra header keys to write, for a recorder that has something to say the
+   * format has no key for.
+   *
+   * Goes to {@link TraceHeader.extra} on the finalized trace and is written
+   * into the header map after the keys above. Use the `"x-"` prefix the format
+   * reserves for private use; a key the format defines is dropped here rather
+   * than written twice, since the field always wins.
+   */
+  readonly extra?: Record<string, unknown>
   readonly maxEvents?: number
   readonly clock?: () => number
   /** Map message type name (e.g. 'subscribe') to wire ID (e.g. 0x03). Required for session-layer recording. */