@observertc/observer-js 1.0.0-beta.16 → 1.0.0-beta.18

package/README.md

@@ -58,14 +58,15 @@ and emits a single, unified stream of typed events the application can react to.
 8. [API reference](#api-reference)
 9. [Schema types (`ClientSample`)](#schema-types-clientsample)
 10. [Detectors (server-side extension point)](#detectors-server-side-extension-point)
-11. [Remote track resolution (mediasoup / SFU)](#remote-track-resolution-mediasoup--sfu)
-12. [Mediasoup router observation](#mediasoup-router-observation)
-13. [Sinks (per-client sample persistence)](#sinks-per-client-sample-persistence)
-14. [Injecting data into a client](#injecting-data-into-a-client)
-15. [Logging](#logging)
-16. [Design notes](#design-notes)
-17. [Error-handling philosophy](#error-handling-philosophy)
-18. [Development & extension guide](#development--extension-guide)
+11. [Call summaries](#call-summaries)
+12. [Remote track resolution (mediasoup / SFU)](#remote-track-resolution-mediasoup--sfu)
+13. [Mediasoup router observation](#mediasoup-router-observation)
+14. [Sinks (per-client sample persistence)](#sinks-per-client-sample-persistence)
+15. [Injecting data into a client](#injecting-data-into-a-client)
+16. [Logging](#logging)
+17. [Design notes](#design-notes)
+18. [Error-handling philosophy](#error-handling-philosophy)
+19. [Development & extension guide](#development--extension-guide)
 
 ---
 
@@ -261,7 +262,10 @@ deliberately distinct:
 
 - **`appData`** — application-assigned extra info that identifies/decorates an entity, fixed at
   creation (via `settings.appData` or the `createCallAppData` / `createClientAppData` factories),
-  or assigned by the app on the `*-added` events. The library never changes it.
+  or assigned by the app on the `*-added` events. The library never changes it. The factories
+  **receive the context of the `accept()` that triggered the creation**, so a fact carried on the
+  context can be baked into `appData` at birth — but it is copied by the factory, deliberately, not
+  written across by the library.
 - **`context`** — passed per `accept()`, may differ on every call, and is carried straight
   through to the `*-updated` events that the `accept()` triggers, then discarded.
 
@@ -391,7 +395,8 @@ See [Mediasoup router observation](#mediasoup-router-observation) for the full d
 | `call-closed` | — | the call closed |
 | `call-empty` | — | last client left the call |
 | `call-not-empty` | — | first client joined a previously-empty call |
-| `call-issue` | `{ issue: ObserverIssue }` | `call.addIssue(...)` (server-side detector finding) |
+| `call-issue` | `{ issue: CallIssue }` | `call.addIssue(...)` (server-side detector finding) |
+| `call-summary` | `{ summary: CallSummary }` | the call is closing and a [summary](#call-summaries) was configured. Emitted **inside** `close()`, while the call is still reachable |
 
 #### Client level — scope `{ observer, observedCall, observedClient }`
 
@@ -463,10 +468,13 @@ type ObserverConfig<AppData = Record<string, unknown>> = {
     appData?: AppData;
     closeClientIfIdleForMs?: number;
     closeCallIfEmptyForMs?: number;
+    // accumulate a per-call summary (see Call summaries). Absent or null = off, and nothing
+    // subscribes to anything. `{}` is valid: a summary with no built-in sections.
+    callSummary?: Partial<CallSummaryConfig> | null;
     // appData factories — run when an entity is created without explicit appData
     // (incl. lazily by accept()). appData is application-owned; accept `context` never touches it.
-    createCallAppData?: (p: { callId: string; observer: Observer }) => Record<string, unknown>;
-    createClientAppData?: (p: { clientId: string; observedCall: ObservedCall }) => Record<string, unknown>;
+    createCallAppData?: (p: { callId: string; observer: Observer; acceptCtx?: AcceptContext }) => Record<string, unknown>;
+    createClientAppData?: (p: { clientId: string; observedCall: ObservedCall; acceptCtx?: AcceptContext }) => Record<string, unknown>;
     // sink factory — produces a per-client sink that receives every accepted sample (see Sinks).
     createClientSink?: (p: { clientId: string; observedCall: ObservedCall }) => ClientSampleSink | undefined;
     // remote-track-resolver factory — produces a call's RemoteTrackResolver (see Remote track resolution).
@@ -475,26 +483,37 @@ type ObserverConfig<AppData = Record<string, unknown>> = {
 ```
 
 **appData factories.** Instead of pre-creating a call/client (or assigning on `call-added` /
-`client-added`) just to enrich its `appData`, register a factory once. It runs in the entity's
-constructor whenever it's created without an explicit `settings.appData` — including the lazy
-creation inside `accept()`. The `client` factory receives the already-created parent
-`observedCall`, so it can derive fields from it. `appData` is application-owned and is never
-modified by the `accept()` context.
+`client-added`) just to enrich its `appData`, register a factory once. It runs whenever the entity
+is created without an explicit `settings.appData` — including the lazy creation inside `accept()`.
+The `client` factory receives the already-created parent `observedCall`, so it can derive fields
+from it.
+
+Both also receive **`acceptCtx`**: the [`AcceptContext`](#context-the-acceptcontext) of the
+`accept()` that caused the creation, or `undefined` when you created the entity yourself. This is
+what lets an [accept middleware](#accept-middlewares-global-pre-dispatch-hook) resolve something
+once — a tenant, a trace id — and have it land in `appData` at birth, instead of every factory
+re-deriving it from the sample.
 
 ```ts
 const observer = new Observer({
-  createCallAppData:   ({ callId })                 => ({ callId, startedAt: Date.now(), region: 'eu' }),
-  createClientAppData: ({ clientId, observedCall }) => ({ clientId, region: observedCall.appData.region }),
+  createCallAppData:   ({ callId, acceptCtx })      => ({ callId, startedAt: Date.now(), tenant: acceptCtx?.tenant }),
+  createClientAppData: ({ clientId, observedCall }) => ({ clientId, tenant: observedCall.appData.tenant }),
 });
+
+observer.accept(sample, { tenant: 'acme' });
 ```
 
+`appData` stays application-owned: the context is *offered* to the factory, never written across by
+the library, and it is still not stored on any entity.
+
 Key members:
 
 - `accept(sample: ClientSample, context?: AcceptContext): void`
 - `addAcceptMiddleware(...mw: AcceptMiddleware[]): this` / `removeAcceptMiddleware(...mw): this` — global pre-dispatch sample hooks (see [Accept middlewares](#accept-middlewares-global-pre-dispatch-hook))
 - `getObservedCall<T>(callId): ObservedCall<T> | undefined`
-- `createObservedCall<T>(settings): ObservedCall<T> | undefined`
-- `getOrCreateObservedCall<T>(settings): ObservedCall<T> | undefined`
+- `createObservedCall<T>(settings, acceptCtx?): ObservedCall<T> | undefined`
+- `getOrCreateObservedCall<T>(settings, acceptCtx?): ObservedCall<T> | undefined`
+- `addIssue(issue: Omit<ObserverIssue, 'scope'>): void` — raise an **observer-level** finding → emits `observer-issue`. `scope` is stamped for you
 - `update(): void` — force an aggregation/`observer-updated` tick
 - `addObserverDetector(name, config?): this` — build a cross-call detector onto `observer.detectors`
 - `addCallDetector(name, config?): this` — register a call-scoped detector for every call created
@@ -509,6 +528,9 @@ Key members:
 - `close(): void`
 - `readonly detectors: Detectors` — observer-scoped registry. **Starts empty**; nothing is implicit
 - `readonly callDetectorConfigs: Map<name, config>` — what `addCallDetector` recorded
+- `readonly callSummaryCollector?: CallSummaryCollector` — owns the resolved `config.callSummary`,
+  the summary subscriptions, and the summaries. `undefined` when summaries are off, which is the
+  only place that answer lives
 - `readonly validators: Set<RunningValidator>` — normally empty; each removes itself on finishing
 - `readonly activeIssuesRegistry: ActiveIssuesRegistry` — the fleet's open client issues
 - `readonly observedCalls: Map<string, ObservedCall>`
@@ -535,8 +557,8 @@ Key members:
 
 - `readonly callId: string`, `appData: AppData`
 - `readonly observedClients: Map<string, ObservedClient>`, `get numberOfClients()`
-- `getObservedClient<T>(clientId)`, `createObservedClient<T>(settings)`, `getOrCreateObservedClient<T>(settings)` (all `… | undefined`)
-- `addIssue(issue: ObserverIssue): void` — raise a **call-level** issue → emits `call-issue`
+- `getObservedClient<T>(clientId)`, `createObservedClient<T>(settings, acceptCtx?)`, `getOrCreateObservedClient<T>(settings, acceptCtx?)` (all `… | undefined`)
+- `addIssue(issue: Omit<CallIssue, 'scope'>): void` — raise a **call-level** finding → emits `call-issue`. `scope` is stamped for you
 - `addDetector(name, config?): this` — build a call-scoped detector onto this call only
 - `removeDetector(name): number` — remove it from this call, `close()`ing it. For one specific
   instance use `call.detectors.remove(detector)`
@@ -548,6 +570,7 @@ Key members:
 - aggregates: `numberOfIssues`, `numberOfPeerConnections`, `numberOfInboundRtpStreams`,
   `numberOfOutboundRtpStreams`, `numberOfDataChannels`, `maxNumberOfClients`,
   `clientsUsedTurn: Set<string>`, `startedAt?`, `endedAt?`, `closedAt?`, `closed`
+- `summary?: CallSummary` — the live record of this call, when [summaries](#call-summaries) are on
 - `update()`, `close()`
 
 ### `ObservedClient`
@@ -658,7 +681,7 @@ type PeerConnectionSample = {
 };
 
 type ClientEvent     = { type: string; payload?: string; timestamp?: number; /* +ids */ };
-type ClientIssue     = { type: string; payload?: string; timestamp?: number };   // also used for call-issue
+type ClientIssue     = { type: string; payload?: string; timestamp?: number };
 type ClientMetaData  = { type: string; payload?: string; timestamp?: number; /* +ids */ };
 type ExtensionStat   = { type: string; payload?: string };
 ```
@@ -754,14 +777,14 @@ correlate **across** the clients of a call or the calls of a fleet, because that
 server can do better than a browser: per-client signals — packet loss, jitter, RTT, freezes — are
 already detected on the client and arrive on samples as `clientIssues` (surfaced via `client-issue`).
 
-Findings are raised as **`ObserverIssue`** — `{ type, timestamp, payload? }` — and the payload is the
-**object**, not a JSON string. A server-raised finding is delivered to an in-process handler, so
-there is nothing to serialise for:
+Findings are raised as **`CallIssue`** or **`ObserverIssue`** — both share `IssueBase`: `{ type,
+timestamp, conclusion?, payload? }` — and the payload is the **object**, not a JSON string. A
+server-raised finding is delivered to an in-process handler, so there is nothing to serialise for:
 
 ```ts
 observer.on('call-issue', ({ observedCall, issue }) => {
   issue.payload;                  // the object; no JSON.parse
-  issuePayloadOf(issue);          // if you want to accept a string payload too
+  issue.conclusion?.faultDomain;  // a first-class field, not payload.conclusion
   issuePayloadAsString(issue);    // only at an edge that needs text (log, HTTP, queue)
 });
 ```
@@ -779,7 +802,7 @@ class MyCrossClientDetector implements Detector {
   update() {                                   // called on every call.update()
     // …inspect this.call.observedClients across participants…
     if (/* condition only visible server-side */ false) {
-      this.call.addIssue({ type: this.name, payload: JSON.stringify({ /* … */ }), timestamp: Date.now() });
+      this.call.addIssue({ type: this.name, payload: { /* … */ }, timestamp: Date.now() });
       // → emitted on the bus as 'call-issue'
     }
   }
@@ -1217,22 +1240,62 @@ observer.addValidator('remote-track-resolver');
 observer.addValidator('codec-consistency', { expected: { video: 'video/VP9', audio: 'audio/opus' } });
 ```
 
+#### `CallIssue` vs `ObserverIssue`
+
+Server-raised findings come in two kinds, distinguished by the scope that raised them:
+
+| | raised by | delivered as | `scope` |
+|---|---|---|---|
+| `CallIssue` | `observedCall.addIssue(...)` | `call-issue` | `'call'` |
+| `ObserverIssue` | `observer.addIssue(...)` | `observer-issue` | `'observer'` |
+
+Both share `IssueBase` — `type`, `timestamp`, `conclusion?`, `payload?` — and `Issue` is the union,
+discriminated on `scope`.
+
+```ts
+observer.on('call-issue', ({ observedCall, issue }) => {
+  issue.scope;              // 'call'
+  observedCall.callId;      // the call — NOT repeated in the payload
+  issue.conclusion?.faultDomain;
+  issue.payload;            // evidence only
+});
+
+observer.on('observer-issue', ({ issue }) => {
+  issue.scope;              // 'observer'
+});
+```
+
+`scope` is stamped by `addIssue` rather than asked of the detector: it is a fact about *where the
+finding was raised*, which the entity knows and a detector should not have to restate. Having it on
+the issue — not merely implied by which event fired — keeps a finding self-describing once it leaves
+the bus, into a shared handler, a log line or a queue.
+
+**The payload is evidence and nothing else.** It no longer repeats `type`, `scope`, or the `callId`
+already carried by the event, and `conclusion` was lifted out of it to a first-class field. A payload
+that restates its own envelope invites the two to disagree — and they did, because nothing kept them
+in step. `payload` is always an object (the `string` form is gone, along with `issuePayloadOf`); use
+`issuePayloadAsString(issue)` at a boundary that genuinely needs text.
+
 #### Conclusions
 
-Every issue-driven finding carries a `conclusion` in its payload — the interpretation step, so the
-person reading the alert doesn't have to perform it:
+Every issue-driven finding carries a `conclusion` — the interpretation step, so the person reading
+the alert doesn't have to perform it. It sits **beside** the evidence, not inside it:
 
 ```jsonc
 {
   "type": "CROSS_CALL_ISSUE_ONSET_BURST",
-  "issueType": "congestion",
-  "calls": 40, "affectedCalls": 6,
-  "perCall": [ { "callId": "…", "affectedClients": 4, "totalClients": 9 } ],
+  "scope": "observer",
+  "timestamp": 1739812345678,
   "conclusion": {
     "faultDomain": "infrastructure",
     "summary": "network congestion is open across independent calls at the same time — 6 of 40 calls (11/300 clients)",
     "recommendation": "check SFU egress bandwidth and host network saturation before looking at any single participant",
     "confidence": 0.85
+  },
+  "payload": {
+    "issueType": "congestion",
+    "calls": 40, "affectedCalls": 6,
+    "perCall": [ { "callId": "…", "affectedClients": 4, "totalClients": 9 } ]
   }
 }
 ```
@@ -1317,6 +1380,109 @@ rather than trusting the flag alone: **"no subscribers" and "no resolver configu
 identical observation.** Without a resolver it would report every published track in the call as
 unconsumed.
 
+## Call summaries
+
+Everything else in this library is about *now*. Detectors answer "is something wrong right now",
+validators answer a structural question once, and both read state the call throws away when it ends.
+A **call summary** is the one thing that outlives the call: who was in it, what was raised against
+it, how it scored — the questions asked *after* the meeting, by support, by billing, by whoever is
+writing the incident note.
+
+It is configured on the observer, at construction:
+
+```ts
+const observer = new Observer({
+  callSummary: {
+    include: [ 'clients', 'issues', 'turnServers', 'scores' ],
+  },
+});
+
+observer.on('call-summary', ({ summary }) => archive(summary));
+```
+
+Omit `callSummary`, or set it to `null`, and there are no summaries and **not one extra bus
+subscription**. Pass an object — `{}` is valid — and every call this observer creates carries one.
+
+> **Why construction-time, when detectors are added per call?** A summary is a record of what
+> happened, and a record you can switch on halfway through is a record with a hole in it. Calls that
+> started before the switch would carry different sections from calls that started after, with
+> nothing on either to say which. One shape for every call, or none.
+
+### Sections are opt-in, and absence means "not collected"
+
+`include` picks from four built-ins, and **the default is `[]`** — none of them:
+
+| Section | Contains |
+|---------|----------|
+| `clients` | `clientIds` (join order), `peak`, `joined`, `left`. Identifiers and counts only |
+| `issues` | `CallIssue[]`, in the order raised, capped by `maxIssues` |
+| `turnServers` | `serverUrls` that carried media, and `clientsRelayed` |
+| `scores` | `min` / `max` / `median` of the call score, and `samples` |
+
+**A missing section means it was never collected — never "nothing happened".** Reading
+`summary.issues === undefined` as "this call was clean" is the one misreading this type invites, so
+there is no default-empty section to make it easy. This is the same rule as `inconclusive` on a
+validator: silence is not success.
+
+The `clients` section is deliberately identifiers and counts. Anything *about* a client — browser,
+platform, region — is already on `observedClient` while the call is live, and belongs in
+`attachments` via an enricher if you want it kept; see below.
+
+### Enrichers: fold in anything, from any call-scoped event
+
+```ts
+new Observer({
+  callSummary: {
+    include: [ 'issues' ],
+    enrich: {
+      'client-joined': (summary, { observedClient }) => {
+        // serialisable facts only — the region string, never the live object it came from
+        ((summary.attachments.regions ??= []) as string[]).push(String(observedClient.appData.region));
+      },
+    },
+  },
+});
+```
+
+Each enricher is typed against its own event's payload. Only **call-scoped** events are accepted —
+the ones carrying an `observedCall`. An enricher on `observer-issue` or `validation-ready` will not
+compile, because there is no single call to attribute a fleet-wide fact to, and quietly writing it
+into every open summary would be worse than a type error.
+
+The library never writes to `summary.attachments`, so nothing you put there can collide with a
+section added in a future version.
+
+> **Why `attachments` and not `appData`.** `appData` is live working state hung off an entity for
+> that entity's lifetime, and it may hold things that cannot be serialised — a mediasoup router, a
+> socket. A summary is the opposite: it outlives the call so it can be **shipped**, and it reaches
+> you on `call-summary` while the call it describes is being torn down, so an unserialisable value
+> in it points at something already gone. Same contract as `attachments` on a `ClientSample`: read
+> the live object off `observedCall` / `observedClient` in the enricher, attach what serialises —
+> the router's `id`, not the router. An enricher that throws is logged and skipped — a summary is a
+side-channel, and nothing about a call should break because a field could not be recorded.
+
+### Caps announce what they dropped
+
+`maxIssues` (default `500`) and `maxClientIds` (default `10_000`) bound the two unbounded lists.
+When either bites, `summary.truncated` appears with the shortfall — present **only** when something
+was actually dropped. That is what makes dropping safe: the true count is recoverable as
+`issues.length + (truncated?.issues ?? 0)`. A silently truncated summary is worse than no summary,
+because someone will count `issues.length` and report it as the issue count.
+
+`issues` is the plain array, with no derived tallies alongside it. A count is `issues.length` and a
+per-type count is one `filter` — both cheaper at the call site than kept correct here.
+
+### Reading it
+
+`observedCall.summary` is live: read it at any point during the call. It is also delivered once on
+`call-summary`, emitted **inside** `close()` while the call is still in `observer.observedCalls` —
+after that the call is gone and there is nothing left to ask. `observer.close()` closes its calls
+first and its collector afterwards, so every summary still makes it out.
+
+Cost is **one bus listener per subscribed event type, for the whole observer** — not one per call. A
+per-call design would be quadratic in concurrent calls: at 500 calls and eight events, 4 000
+listeners each doing 500 no-op invocations per event. Percentiles are computed once, at close.
+
 ## Remote track resolution (mediasoup / SFU)
 
 In an SFU, one participant's **outbound** track is delivered to other participants as **inbound**