@observertc/observer-js 1.1.0 → 1.2.0-rc.1

package/README.md

@@ -62,7 +62,7 @@ and emits a single, unified stream of typed events the application can react to.
 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)
+14. [Sinks](#sinks)
 15. [Injecting data into a client](#injecting-data-into-a-client)
 16. [Logging](#logging)
 17. [Design notes](#design-notes)
@@ -83,14 +83,14 @@ yarn add @observertc/observer-js
 works the same whether your project is ESM or CommonJS — your import line is unchanged either way:
 
 ```ts
-import { Observer, ClientSample, createJsonlFileSinkFactory } from '@observertc/observer-js';
+import { Observer, ClientSample, JsonlFileSink } from '@observertc/observer-js';
 ```
 
 In an ESM project this resolves to the `.mjs` build; in a CommonJS project (where TypeScript
 compiles your `import` down to `require()`) it resolves to the `.js` build. Everything is exported
 from the single `@observertc/observer-js` entry. Written in TypeScript; ships type declarations for
 both formats (`dist/index.d.ts` for `require`, `dist/index.d.mts` for `import`). Runtime
-dependencies: `@bufbuild/protobuf`, `events`, `uuid`. The library does **not** bundle a logger or
+dependencies: `@bufbuild/protobuf`, `uuid`. The library does **not** bundle a logger or
 any transport — see [Logging](#logging).
 
 `ClientSample` and friends are re-exported from this package, and are also published as the
@@ -404,7 +404,7 @@ See [Mediasoup router observation](#mediasoup-router-observation) for the full d
 | Event | Extra | Fires when |
 |-------|-------|-----------|
 | `client-added` | — | a client is created |
-| `client-sink-created` | `{ sink: ClientSampleSink }` | a per-client sink was created (only when `createClientSink` returns one); fires right after `client-added` |
+| `client-sink-created` | `{ sink: JsonlFileSink }` | the client's JSONL sample file was created (only when `createClientJsonlSink` returns a path); fires right after `client-added` |
 | `client-updated` | `{ sample: ClientSample, elapsedTimeInMs: number, context?: AcceptContext }` | the client processed a sample |
 | `client-closed` | — | the client closed |
 | `client-joined` | — | first `CLIENT_JOINED` event seen |
@@ -479,8 +479,8 @@ type ObserverConfig<AppData = Record<string, unknown>> = {
     // (incl. lazily by accept()). appData is application-owned; accept `context` never touches it.
     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;
+    // a JSONL file per client: return its path, or undefined for none (see Sinks).
+    createClientJsonlSink?: (p: { clientId: string; observedCall: ObservedCall }) => string | undefined;
     // remote-track-resolver factory — produces a call's RemoteTrackResolver (see Remote track resolution).
     createRemoteTrackResolver?: (observedCall: ObservedCall) => RemoteTrackResolver | undefined;
   };
@@ -591,7 +591,7 @@ Key members:
 
 - `readonly clientId: string`, `appData: AppData`, `readonly call: ObservedCall`
 - `readonly observedPeerConnections: Map<string, ObservedPeerConnection>`
-- `readonly sink?: ClientSampleSink` — the per-client sink (see [Sinks](#sinks-per-client-sample-persistence)), if `createClientSink` is configured; listen on it for `close`/`error`
+- `get sink(): Sink<ClientSample> | undefined` — the sink under its client id in `call.sinks` (see [Sinks](#sinks)); listen on it for `close`/`error`
 - **Injection API** (queue app data to be merged into the next sample processing):
   `injectEvent(ClientEvent)`, `injectIssue(ClientIssue)`, `injectMetaData(ClientMetaData)`,
   `injectExtensionStat(ExtensionStat)`, `injectAttachment(attachments: Record<string, unknown>)`
@@ -1126,6 +1126,7 @@ counters** — that is the rule the whole design hangs on:
 | `PublisherFaultCorroborationDetector` | 🔗 | call | `CORROBORATED_PUBLISHER_FAULT` |
 | `TrackDeliveryMismatchDetector` | 🔗 | call | `PUBLISHED_TRACK_NOT_DELIVERED`, `RECEIVER_TRACK_NOT_DELIVERED`, `PUBLISHER_TRACK_DRY` |
 | `UnconsumedTrackDetector` | 🔗 | call | `UNCONSUMED_PUBLISHED_TRACK` |
+| `AudioEchoDetector` | 🔗¹ | call | `AUDIO_ECHO_SUSPECTED` |
 | `ClientPopulationIssueDetector` | | **observer** | `CLIENT_POPULATION_ISSUE` |
 | `SfuCongestionDetector` | | **observer** | `sfu-congestion` |
 | `TurnServerHealthDetector` | | **observer** | `TURN_SERVER_DEGRADED` |
@@ -1168,6 +1169,16 @@ What each adds that no endpoint can know:
   from the **same SFU** — the finding's meaning is "these clients share only that server".
 - **`TrackDeliveryMismatchDetector`** — *are the two ends of a track disagreeing?*
 - **`UnconsumedTrackDetector`** — *is anyone actually subscribed?* (reads the resolver's silence)
+- **`AudioEchoDetector`** — *is someone sending the others' voices back into the call?* Compares
+  each outbound audio track's per-tick level (`ObservedOutboundTrack.rmsAudioLevel`) with the
+  loudest other participant's, bucket by bucket. An echo is active whenever the source speaks, and
+  louder when the source is louder; turn-taking fails the first test and cross-talk the second.
+  When both tracks of a pair pass, it reports the one with the client's `loopback-audio-input`
+  issue open, else the one that follows more reliably, else the quieter one (`ambiguousDirection`).
+  Works at the clients' sampling granularity, so it catches sustained echo (a `Monitor of …`
+  loopback device, speakers into an open mic) rather than faint echo.
+  ¹ The resolver is needed only for publishers whose browser reports no media-source audio level
+  (Firefox): their level is then read from what their receivers heard.
 - **`TurnServerHealthDetector`** — *does trouble cluster on one relay?*
 - **`TurnServerOutageDetector`** — covers the case the health detector structurally cannot. The
   health detector groups clients by the server relaying them and asks how many report issues — it
@@ -1894,127 +1905,190 @@ observer.on('mediasoup-router-removed', ({ observedMediasoupRouter }: ObservedMe
 
 ---
 
-## Sinks (per-client sample persistence)
+## Sinks
 
-A **sink** receives the samples a client accepts — for archival, streaming, or later offline
-replay. Each `ObservedClient` gets its **own** sink, produced by the
-`ObserverConfig.createClientSink` factory when the client is created (return `undefined` for no
-sink). The client pushes every accepted sample to its sink, and `end()`s it on close.
+A **sink** is a destination for records — client samples, a mediasoup transport's `getStats()`,
+anything the application wants to keep. Sinks are agnostic about what passes through them; their
+**lifecycle is owned by the object they are registered on**, through that object's `sinks`
+registry. The library never polls: what is written, and when, is the application's.
 
-### The `ClientSampleSink` base class
+| Registry | Ended when | Typical use |
+|----------|-----------|-------------|
+| `observer.sinks` | the observer closes | worker- or process-level stats |
+| `observedCall.sinks` | the call closes | each client's sample sink (under its client id), call-level stats |
+| `observedMediasoupRouter.sinks` | the router closes | e.g. one file per pipe transport |
 
-`ClientSampleSink` is an **abstract base class** (a typed `EventEmitter`). You create a sink by
-**subclassing it** and implementing `write` and `end`. It is **object-mode**: `write` receives
-the `ClientSample` *object*, so each sink decides how (or whether) to serialize it — JSON line,
-protobuf, a remote POST body, an in-memory push, etc.
+`observer.sinks` is the parent of every call's and router's registry. **Sink ids are unique per
+observer**: creating a sink with an id that any registry of the observer already holds is refused
+(`create` returns `undefined`, and nothing is constructed). A registry sees its own sinks and its descendants', so `observer.sinks.write(id, record)`
+reaches any sink, and `observer.close()` ends every sink that is left — including those of routers
+that are still open, since the observer does not close mediasoup routers.
 
-```ts
-import { ClientSampleSink, ClientSample } from '@observertc/observer-js';
+### `SinkRegistry`
+
+| Method | Does |
+|--------|------|
+| `create(SinkClass, settings)` | constructs `new SinkClass(settings)` and registers it under `settings.id` (generated when omitted); `undefined` if the id is taken |
+| `get<T>(id)` | the sink, if any (own or a descendant's) |
+| `write(id, record): boolean` | writes to the sink; `false` if there is none, or on backpressure |
+| `clear()` | ends every sink of the registry and its descendants |
+| `size`, `keys()`, `values()` | own and descendants' sinks |
+
+There is no `remove`: **`sink.end()` closes a sink and removes it from its registry**, which frees
+its id. The registry attaches an `error` listener to each sink, so a failing destination is logged
+and never crashes the process.
 
-abstract class ClientSampleSink /* extends EventEmitter */ {
-  abstract write(sample: ClientSample): boolean;   // accept one sample; `false` = backpressure
-  abstract end(): void;                            // flush; emit `close` when the destination is ready
+### The `Sink<T>` interface
 
-  // typed events (inherited): the listener signature is inferred from the event name
-  on(event: 'close' | 'finish' | 'drain', listener: () => void): this;
-  on(event: 'error', listener: (err: Error) => void): this;
-  // ...and the matching `once` / `off` / `emit`
+```ts
+import type { Sink, SinkSettings } from '@observertc/observer-js';
+
+interface Sink<T = unknown> {          // typically: class X extends EventEmitter implements Sink<T>
+  readonly id: string;
+  write(record: T): boolean;           // `false` once ended (nothing written), or on backpressure
+  end(): void;                         // idempotent; MUST emit `ended` synchronously, then flush and emit `close`
+  on / once / off(event, listener);    // the events below
 }
+
+type SinkSettings = { id: string };    // what `create` passes to the constructor, with your own settings
 ```
 
+An implementation must emit `ended` from `end()` — that is how its registry removes it and frees
+its id — refuse writes after it, and emit `close` / `error` for its destination.
+
 | Event | Meaning |
 |-------|---------|
+| `ended` | `end()` was called: no more writes, removed from its registry |
 | `close` | the destination is fully written and closed (e.g. a file flushed and its fd closed) — "ready" |
 | `error` | the destination failed |
 | `finish` | `end()` was processed and queued data flushed (before `close`) |
 | `drain` | the buffer drained after backpressure; safe to write more |
 
-The library calls `write(sample)` **synchronously** per accepted sample (it is not awaited),
-`end()`s the sink when the client closes, and attaches an `error` listener so a failing sink
-can't crash the process (it also catches throws from `write`/`end`). The application — which
-created the sink — listens for `close` (destination ready) and `error`. Because `write` isn't
-awaited in the `accept()` hot path, **backpressure and batching are the sink's concern**.
-
-### Built-in sinks
-
-```ts
-import { Observer, createJsonlFileSinkFactory } from '@observertc/observer-js';
-
-const observer = new Observer({
-  // one ./stats/<callId>__<clientId>.jsonl per client
-  createClientSink: createJsonlFileSinkFactory({ directory: './stats' }),
-});
-
-// React when a sink is created for a client:
-observer.on('client-sink-created', ({ observedClient, sink }) => {
-  sink.on('close', () => {
-    // the file is fully flushed and its fd closed — ready to upload, move, etc.
-  });
-});
-```
-
-| Export | Signature | Notes |
-|--------|-----------|-------|
-| `createJsonlFileSinkFactory` | `({ directory, flags?, getFileName?, serializeSample? }) => ClientSampleSinkFactory` | per-client JSONL files; path defaults to `${callId}__${clientId}.jsonl` under `directory` (which **must exist**) |
-| `createJsonlFileSink` | `({ path, flags?, serializeSample? }) => ClientSampleSink` | a single JSONL file; wraps `fs.WriteStream` and re-emits its `close`/`finish`/`drain`/`error` |
-| `JsonlFileSink` | `class extends ClientSampleSink` | the underlying class; exposes `readonly path` so a `close` handler knows which file is ready |
-| `createInMemorySink` / `InMemorySink` | `(samples?: ClientSample[]) => InMemorySink` | collects the accepted **sample objects** into `.samples: ClientSample[]`; emits `close` on `end()` |
+`ClientSampleSink` is `Sink<ClientSample>`. Built-in implementations:
 
-`serializeSample?: (sample: ClientSample) => string` overrides the default `JSON.stringify` for
-the JSONL sinks (e.g. to redact or reshape before writing).
+| Export | Notes |
+|--------|-------|
+| `JsonlFileSink<T = ClientSample>` / `createJsonlFileSink<T>({ path, serializeSample? })` | appends one JSON line per record; wraps `fs.WriteStream` and re-emits its events; exposes `readonly path`. The directory **must exist** |
+| `InMemorySink` / `createInMemorySink(samples?)` | collects client samples into `.samples`; emits `close` on `end()` |
 
-### Reading sink-specific info (e.g. the file path)
+### Client samples
 
-The bus hands you the sink as the base `ClientSampleSink`. To read information specific to a sink
-type — for a file sink, where it was written — **narrow with `instanceof`** and read the sink's
-public fields. `JsonlFileSink` exposes `path`:
+A client writes every accepted sample to the sink registered under its **client id** in its call's
+registry (`observedClient.sink` returns it), and removes — ends — that sink when it closes. For the
+common case, a JSONL file per client, return a path from `createClientJsonlSink`:
 
 ```ts
-import { JsonlFileSink } from '@observertc/observer-js';
+const observer = new Observer({
+  // return undefined for no file
+  createClientJsonlSink: ({ observedCall, clientId }) => `./stats/${observedCall.callId}__${clientId}.jsonl`,
+});
 
 observer.on('client-sink-created', ({ observedClient, sink }) => {
-  if (sink instanceof JsonlFileSink) {
-    const { path } = sink;                          // the file this client's samples go to
-    sink.once('close', () => uploadFile(path));     // close = flushed & fd closed → ready
-  }
+  sink.once('close', () => uploadFile(sink.path));   // flushed & fd closed → ready
 });
 ```
 
-The general pattern: each concrete sink exposes whatever it wants as `public readonly` fields, and
-consumers narrow (`instanceof YourSink`) to read them. Your own sinks do the same.
-
-### Writing your own sink
-
-Subclass `ClientSampleSink` and emit the lifecycle events yourself — for any non-file
-destination (a remote endpoint, a message queue, an object store, …):
+For any other destination, create your own sink under the client id when the client is created:
 
 ```ts
-import { ClientSampleSink, ClientSample, ClientSampleSinkFactory } from '@observertc/observer-js';
-
-class HttpSink extends ClientSampleSink {
+class HttpSink extends EventEmitter implements ClientSampleSink {
+  readonly id: string;
+  private readonly url: string;
   private buffer: ClientSample[] = [];
-  constructor(private readonly url: string) { super(); }
+  private ended = false;
 
+  constructor(settings: SinkSettings & { url: string }) {
+    super();
+    this.id = settings.id;
+    this.url = settings.url;
+  }
   write(sample: ClientSample): boolean {
+    if (this.ended) return false;
     this.buffer.push(sample);                  // batch; decide your own backpressure
     return true;
   }
   end(): void {
+    if (this.ended) return;
+    this.ended = true;
+    this.emit('ended');                        // required: removes it from its registry
     fetch(this.url, { method: 'POST', body: JSON.stringify(this.buffer) })
       .then(() => this.emit('close'))          // signal "destination ready"
       .catch((err) => this.emit('error', err));
   }
 }
 
-const createClientSink: ClientSampleSinkFactory = ({ clientId, observedCall }) =>
-  new HttpSink(`https://stats.example.com/${observedCall.callId}/${clientId}`);
+observer.on('client-added', ({ observedCall, observedClient }) => {
+  observedCall.sinks.create(HttpSink, { id: observedClient.clientId, url: `https://stats.example.com/${observedClient.clientId}` });
+});
+```
+
+Client ids double as sink ids, so they must be unique across the observer's open calls (client
+monitors generate uuids). A client whose id is already a sink id gets no sample file, and a
+warning is logged.
+
+The library calls `write(sample)` **synchronously** per accepted sample (it is not awaited), so
+**backpressure and batching are the sink's concern**.
+
+### Extension stats
+
+Stats the library does not collect itself can be kept as **extension stats** on the object they
+belong to — `observer` (e.g. a mediasoup worker's resource usage), `observedCall` (an SFU's view of
+the call) or `observedMediasoupRouter` (a pipe transport's `getStats()`): the last data per id, and
+optionally a sink that receives every data. The API is the same on all three; a call is shown.
+
+```ts
+// Register the id; with `createSink` (what `sinks.create` takes), a sink is created under the same id.
+call.createExtensionStats({ id: `${call.callId}:sfu`, createSink: [ JsonlFileSink<SfuStats>, { path: './stats/sfu.jsonl' } ] });
+
+// Your own polling: keep the last data, and write it to the sink with the same id, if any.
+call.acceptExtensionStats(`${call.callId}:sfu`, await collectSfuStats(call.callId));
+
+call.getExtensionStats<SfuStats>(`${call.callId}:sfu`);   // the last data
+call.extensionStats.values;                               // Map<id, last data>
+```
 
-const observer = new Observer({ createClientSink });
+| Method | Behaviour |
+|--------|-----------|
+| `createExtensionStats({ id, createSink? })` | Registers `id`. With `createSink` — what `sinks.create` takes, `[SinkClass, settings]` — it also creates a sink under `id` (an `id` in the sink settings is ignored), ending and replacing a sink the owner already holds under `id`. Returns the created sink, or `undefined`: without `createSink`, on a closed owner, when `id` is already in `extensionStats.values` (created or accepted before), or when another object of the observer holds a sink with this id |
+| `acceptExtensionStats(id, data)` | Keeps `data` as the last data of `id` and writes it to the owner's sink with the same id, if there is one (a sink that throws is logged). `id` does not have to be created first. Dropped once the owner is closed |
+| `getExtensionStats<T>(id)` | The last data accepted for `id`, or `undefined` |
+| `extensionStats` | The owner's `ExtensionStatsRegistry`: `values` (`Map<id, last data>`), `closed`, `close()`, and `create` / `accept` / `get`, which the three methods above delegate to |
+
+**Extension stats ids share the sink id namespace, so they must be unique per observer**: the sink
+of extension stats `x` is the sink with id `x`. Consequently:
+
+- With `createSink`, a sink the owner already holds under the id is ended and replaced. If another
+  object of the observer holds it, no sink is created and the data is only kept.
+- Without `createSink`, a sink you create later under the id (`sinks.create(SinkClass, { id, ... })`)
+  receives the data accepted from then on.
+- An id accepted before it was created can no longer be created with `createSink`; give it a sink
+  with `sinks.create` instead.
+
+**Lifecycle.** When the owner (the call, the router or the observer) closes, it closes its
+`extensionStats`: data accepted afterwards is dropped, `createExtensionStats` returns `undefined`,
+and the extension stats' sinks are ended. The owner's other sinks end with its `sinks.clear()` as
+usual. `extensionStats.close()` can also be called directly; it ends only the extension stats'
+sinks.
+
+### Other records: e.g. mediasoup pipe transport stats
+
+```ts
+const observedRouter = observer.createObservedMediasoupRouter({ router })!;
+
+observedRouter.on('transport-sample-added', ({ transport }) => {
+  if (transport.type !== 'pipe') return;
+
+  observedRouter.sinks.create(JsonlFileSink<PipeTransportStats[]>, { id: transport.id, path: `./stats/${transport.id}.jsonl` });
+
+  // Your own polling. A write to an ended sink returns false, so a late getStats() is harmless.
+  const timer = setInterval(async () => observedRouter.sinks.write(transport.id, await transport.getStats()), 5_000);
+
+  transport.observer.once('close', () => clearInterval(timer));
+});
 ```
 
-`observedClient.sink?` exposes the created sink; the `client-sink-created` event delivers it on
-the bus with full ancestry. `ClientSampleSinkFactory` is
-`(p: { clientId: string; observedCall: ObservedCall }) => ClientSampleSink | undefined`.
+The files are ended when the router closes, which is usually the lifetime you want for a pipe
+transport's stats. To end one earlier, call `end()` on it: `observedRouter.sinks.get(transport.id)?.end()`.
 
 ---
 
@@ -2025,7 +2099,7 @@ client-reported `ClientSample` — a room id or display name, an application-lev
 (*"recording started"*), a server-detected issue, an extension stat, or a device/meta item.
 `ObservedClient` exposes **injection** methods that merge such data into the client's sample stream,
 so it updates the live model **and** is persisted to the client's
-[sink](#sinks-per-client-sample-persistence) exactly like sampled data.
+[sink](#sinks) exactly like sampled data.
 
 | Method | Adds to the sample's | Surfaces as |
 |--------|----------------------|-------------|
@@ -2150,7 +2224,7 @@ event map + scope types), `detectors/` (`Detector`, `Detectors`, and one file pe
 `ActiveIssueTracker`, `ActiveIssuesRegistry`, `ObservedClientIssueRegistry`), `scores/`,
 `resolvers/` (remote-track resolvers), `utils/` (`stats`, `SlidingWindow`, `TrendTester`,
 `CallHealthAggregator`), `common/` (`logger`, `utils`, `Middleware`), `schema/`
-(sample/event/meta types), and `sinks/` (the `ClientSampleSink` base + `JsonlFileSink` /
+(sample/event/meta types), and `sinks/` (the `Sink` interface, `SinkRegistry` + `JsonlFileSink` /
 `InMemorySink`, re-exported from the package root).
 
 **Conventions to follow when developing further:**