@observertc/observer-js 1.0.0-beta.10 → 1.0.0-beta.12

package/llms-full.txt

@@ -1,7 +1,7 @@
 # observer-js (@observertc/observer-js) — full documentation
 
 > Single-file export of the project's documentation for one-shot LLM ingestion.
-> Concatenates: README.md, docs/logging.md, CHANGELOG.md. Generated from source —
+> Concatenates: README.md, docs/logging.md, CHANGELOG.md. Generated by scripts/build-llms-full.mjs —
 > the canonical, always-current copies live in the repository; see llms.txt for the link index.
 
 ---
@@ -75,9 +75,10 @@ and emits a single, unified stream of typed events the application can react to.
 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. [Logging](#logging)
-15. [Error-handling philosophy](#error-handling-philosophy)
-16. [Development & extension guide](#development--extension-guide)
+14. [Injecting data into a client](#injecting-data-into-a-client)
+15. [Logging](#logging)
+16. [Error-handling philosophy](#error-handling-philosophy)
+17. [Development & extension guide](#development--extension-guide)
 
 ---
 
@@ -256,8 +257,7 @@ observer.addAcceptMiddleware(route, filter);
 // observer.removeAcceptMiddleware(route);
 ```
 
-This is a lightweight global injection point, distinct from the larger (not-yet-built)
-`ClientSampleProcessor` pipeline in the roadmap. When no middleware is registered, `accept()`
+This is a lightweight global injection point. When no middleware is registered, `accept()`
 dispatches directly with no overhead.
 
 ### `context` (the `AcceptContext`)
@@ -381,7 +381,7 @@ additional field(s) on top of that scope.
 | Event | Extra | Fires when |
 |-------|-------|-----------|
 | `mediasoup-router-added` | — | `observer.createObservedMediasoupRouter(...)` registered a router |
-| `mediasoup-router-matched-with-peer-connection` | `{ observedCall, observedClient, observedPeerConnection }` | a newly added peer connection's id matched one of the router's WebRTC transport ids. |
+| `mediasoup-router-matched-with-peer-connection` | `{ observedCall, observedClient, observedPeerConnection }` | a newly added peer connection's id matched one of the router's WebRTC transport ids. **Opt-in** via `matchPeerConnectionByWebRtcTransportId: true`. |
 | `mediasoup-router-removed` | — | the underlying mediasoup router closed (its `router.observer` `close` fired) |
 
 See [Mediasoup router observation](#mediasoup-router-observation) for the full design and examples.
@@ -420,7 +420,6 @@ See [Mediasoup router observation](#mediasoup-router-observation) for the full d
 | `peer-connection-added` / `peer-connection-closed` | — | lifecycle of the PC |
 | `peer-connection-updated` | `{ context?: AcceptContext }` | the PC processed a sample |
 | `ice-connection-state-changed` / `ice-gathering-state-changed` / `connection-state-changed` | `{ state: string }` | driven by client events |
-| `selected-candidate-pair-changed` | — | *declared; not currently emitted* |
 | `inbound-track-added` / `-updated` / `-removed` / `-muted` / `-unmuted` | `{ observedInboundTrack }` | |
 | `outbound-track-added` / `-updated` / `-removed` / `-muted` / `-unmuted` | `{ observedOutboundTrack }` | |
 | `inbound-rtp-added` / `-updated` / `-removed` | `{ observedInboundRtp }` | `-updated` fires every tick |
@@ -473,8 +472,8 @@ type ObserverConfig<AppData = Record<string, unknown>> = {
     createClientAppData?: (p: { clientId: string; observedCall: ObservedCall }) => 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;
-    // track-resolver factory — produces a call's RemoteTrackResolver (see Remote track resolution).
-    createTrackResolver?: (observedCall: ObservedCall) => RemoteTrackResolver | undefined;
+    // remote-track-resolver factory — produces a call's RemoteTrackResolver (see Remote track resolution).
+    createRemoteTrackResolver?: (observedCall: ObservedCall) => RemoteTrackResolver | undefined;
   };
 ```
 
@@ -528,7 +527,7 @@ Key members:
 - `addIssue(issue: ClientIssue): void` — raise a **call-level** issue → emits `call-issue`
 - `readonly detectors: Detectors` — server-side detector registry (empty by default; see [Detectors](#detectors-server-side-extension-point))
 - `scoreCalculator: ScoreCalculator`, `get score()`, `readonly calculatedScore`
-- `remoteTrackResolver?: RemoteTrackResolver` — set from `ObserverConfig.createTrackResolver` at call creation (see [Remote track resolution](#remote-track-resolution-mediasoup--sfu))
+- `remoteTrackResolver?: RemoteTrackResolver` — set from `ObserverConfig.createRemoteTrackResolver` at call creation (see [Remote track resolution](#remote-track-resolution-mediasoup--sfu))
 - aggregates: `numberOfIssues`, `numberOfPeerConnections`, `numberOfInboundRtpStreams`,
   `numberOfOutboundRtpStreams`, `numberOfDataChannels`, `maxNumberOfClients`,
   `clientsUsedTurn: Set<string>`, `startedAt?`, `endedAt?`, `closedAt?`, `closed`
@@ -551,7 +550,7 @@ Key members:
 - `readonly sink?: ClientSampleSink` — the per-client sink (see [Sinks](#sinks-per-client-sample-persistence)), if `createClientSink` is configured; 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(key, value)`
+  `injectExtensionStat(ExtensionStat)`, `injectAttachment(attachments: Record<string, unknown>)`
 - **Direct add API** (process immediately): `addIssue(ClientIssue)`, `addMetadata(ClientMetaData)`,
   `addExtensionStats(ExtensionStat)`
 - Metrics (current/derived): `currentAvgRttInMs?`, `currentMinRttInMs?`, `currentMaxRttInMs?`,
@@ -763,7 +762,7 @@ class Detectors {
 
 In an SFU, one participant's **outbound** track is delivered to other participants as **inbound**
 tracks (one **publisher** → many **subscribers**). Correlation is **opt-in** per observer: set
-`ObserverConfig.createTrackResolver`, a factory invoked when each call is created that returns the
+`ObserverConfig.createRemoteTrackResolver`, a factory invoked when each call is created that returns the
 call's `RemoteTrackResolver` (or `undefined` for none).
 
 `RemoteTrackResolver` is a generic, strategy-driven class. It subscribes to the bus (filtered to
@@ -774,7 +773,7 @@ the tracks: `inboundTrack.remoteOutboundTrack` and `outboundTrack.remoteInboundT
 import { Observer, createDefaultMediasoupRemoteTrackResolverFactory } from '@observertc/observer-js';
 
 const observer = new Observer({
-  createTrackResolver: createDefaultMediasoupRemoteTrackResolverFactory(),
+  createRemoteTrackResolver: createDefaultMediasoupRemoteTrackResolverFactory(),
 });
 
 // later, given tracks (links are kept up to date as tracks come and go):
@@ -793,7 +792,7 @@ id is just whatever links a subscribed track to the published one:
 import { Observer, RemoteTrackResolver } from '@observertc/observer-js';
 
 const observer = new Observer({
-  createTrackResolver: (observedCall) => new RemoteTrackResolver(observedCall, {
+  createRemoteTrackResolver: (observedCall) => new RemoteTrackResolver(observedCall, {
     resolveOutboundTrackPublisherId: (out) => out.attachments?.mediaId as string | undefined,
     resolveInboundTrackPublisherId:  (inb) => inb.attachments?.mediaId as string | undefined,
     resolveInboundTrackSubscriberId: (inb) => inb.attachments?.subId  as string | undefined, // optional
@@ -817,19 +816,37 @@ transitions. `ObservedMediasoupRouter` captures that server-side view into a
 ### The concept
 
 You hand the observer a live mediasoup `Router`; it attaches to mediasoup's own `observer` API and,
-from then on, **passively records** the router's topology and lifecycle — with no polling and no
+from then on, **passively tracks** the router's topology and lifecycle — with no polling and no
 changes to your media code:
 
-- new transports (`webrtc` / `plain` / `pipe` / `direct`), their selected `tuple`, and ICE state
-  transitions;
+- new transports (`webrtc` / `plain` / `pipe` / `direct`), their selected `tuple`, ICE/DTLS/SCTP
+  state transitions and `connectedAt`;
 - producers (codec, SSRCs/RIDs, `pause`/`resume`) and consumers (`pause`/`resume`,
   `producerPaused`/`producerResumed`);
 - data producers and data consumers;
 - `createdAt` / `closedAt` for every entity above.
 
-All of it accumulates on `observedMediasoupRouter.sample` (a `MediasoupRouterSample` — see
-[`src/schema/MediasoupRouter.ts`](./src/schema/MediasoupRouter.ts)). This is a *Sample*, not a
-*Report*: it mirrors the naming of `ClientSample` and is yours to snapshot, persist, or correlate.
+It keeps all of this **in memory**, in a single `MediasoupRouterSample` exposed as
+`observedRouter.sample` — see [`src/schema/MediasoupRouter.ts`](./src/schema/MediasoupRouter.ts). The
+sample **accumulates for the life of the router**: closed transports/producers/consumers are kept
+(with their `closedAt` set), not removed. Read it whenever you like — it's a plain object you own.
+
+### Memory & large meetings
+
+This is intentionally the **simplest** approach — everything lives in memory and nothing is sampled
+or evicted for you. That's fine for typical rooms, but be aware of the cost at scale:
+
+- **Consumers grow as O(N²)** on a single flat router: with `N` participants each producing audio +
+  video and consuming everyone else, the sample holds roughly `2·N·(N−1)` consumer records (≈ 19,800
+  for `N` = 100).
+- The sample is **cumulative** — closed entities and their `history` are retained — so it also grows
+  with call duration and churn (renegotiation, simulcast layer changes, rejoins).
+
+A 100-participant flat router can therefore reach tens of MB and keep growing. There is **no built-in
+sink, snapshotting, or eviction** — by design. **If you run large meetings, do your own sampling:**
+on your own cadence read `observedRouter.sample` (snapshot/serialize/persist what you need), drop what
+you don't, and close routers you no longer track. (mediasoup also typically shards routers across
+workers/cores, which keeps any one router small.)
 
 ### Matching peer connections — by **event**, not by storage
 
@@ -844,37 +861,62 @@ ancestry, so you get the router **and** the matched `observedPeerConnection`, `o
 `observedCall` in one place. Stamp the `routerId` into the peer connection's / client's `appData`,
 build your own index, attach the server sample to the call in your database — whatever fits.
 
-How it works: as peer connections are observed (`peer-connection-added`), the observer checks whether
-the peer connection's id is one of the router's WebRTC transport ids. On a hit it emits — **once per
-matching peer connection** (de-duplicated by peer-connection id) — and keeps watching, so a router
-that serves many participants emits one match per participant's transport. The internal listener is
-removed automatically when the router closes or the observer closes.
+This matching is **opt-in**: pass `matchPeerConnectionByWebRtcTransportId: true` to
+`createObservedMediasoupRouter`. When enabled, as peer connections are observed
+(`peer-connection-added`) the observer checks whether the peer connection's id is one of the router's
+WebRTC transport ids; on a hit it emits — once per matching peer connection — and keeps watching, so a
+router serving many participants emits one match per participant's transport. When the flag is omitted
+or `false`, no matching is performed and the event never fires. The internal listener is removed
+automatically when the router closes or the observer closes.
+
+### Ordering contract — observe the router first
+
+Matching is **forward-only by design**, and that is sufficient because the lifecycle ordering is
+**guaranteed, not racy**:
+
+- `ObservedMediasoupRouter` works purely by **subscribing to mediasoup's `observer` API**, so it can
+  only see events that happen *after* it is created. You therefore create it the moment the router
+  exists — **before** any transport is added to it — and it captures the rest going forward.
+- A mediasoup transport is always created **on the server first**; only then can the client connect
+  to it, produce/consume, and begin shipping `ClientSample`s. So a peer connection — and the
+  `peer-connection-added` event it triggers — can never appear before its server-side WebRTC
+  transport already exists (and has been observed by the router).
+
+Put together: by the time a `peer-connection-added` fires, the router has already recorded that
+transport's id in `webrtcTransportIds`, so a single forward-looking listener catches every match. No
+back-scan of existing peer connections and no re-check on transport creation are needed — the
+observer deliberately does **not** look backwards.
+
+**Your responsibility:** call `createObservedMediasoupRouter(...)` as early as the router exists
+(before transports are added or samples are accepted). If you register the router *after* its
+transports are created or after the client's first sample, those events are already in the past and
+the corresponding matches are missed.
 
 When the underlying mediasoup router closes, its `close` propagates to `ObservedMediasoupRouter`,
-which emits **`mediasoup-router-removed`**. That is your cue to do whatever cleanup or persistence
-you want with the now-final `sample` — again, the observer itself keeps nothing.
+which sets the sample's `closedAt` and emits **`mediasoup-router-removed`** — your cue to read /
+persist the final `observedRouter.sample` and drop your reference to it.
 
 ### Options — `observer.createObservedMediasoupRouter(settings)`
 
 | Field | Type | Required | Meaning |
 |-------|------|----------|---------|
-| `router` | `mediasoup.types.Router` | yes | the live router to observe; the observer attaches to `router.observer` |
-| `routerId` | `string` | yes | your id for the router (the sample also carries `router.id`) |
+| `router` | `mediasoup.types.Router` | yes | the live router to observe; the observer attaches to `router.observer`. `.id` and the sample's `routerId` come from `router.id` |
 | `appData` | `Record<string, unknown>` | no | application-owned bag on the `ObservedMediasoupRouter` |
-| `attachments` | `Record<string, unknown>` | no | free-form data copied onto `sample.attachments` |
+| `attachments` | `Record<string, unknown>` | no | free-form data; carried on `sample.attachments` |
+| `matchPeerConnectionByWebRtcTransportId` | `boolean` | no | opt in to peer-connection matching: emit `mediasoup-router-matched-with-peer-connection` for each peer connection whose id matches one of the router's WebRTC transport ids. Omitted / `false` → no matching, the event never fires |
 
-Peer-connection matching is automatic — there is nothing to opt into. Returns the
-`ObservedMediasoupRouter`, or `undefined` if the observer is closed (a router with the same id
-returns the existing instance — both warn).
+Peer-connection matching is **off by default**; enable it with
+`matchPeerConnectionByWebRtcTransportId: true`. Returns the `ObservedMediasoupRouter`, or `undefined`
+if the observer is closed (a router with the same id returns the existing instance — both warn).
 
-Useful members on the returned object: `.sample` (the `MediasoupRouterSample`), `.appData`,
-`.attachments` (getter over `sample.attachments`), `.webrtcTransportIds: Set<string>`, `.id`,
-`.close()`.
+Useful members on the returned object: `.sample` (the in-memory `MediasoupRouterSample`, with
+`createdAt` / `closedAt?` on it), `.appData`, `.attachments`, `.webrtcTransportIds: Set<string>`,
+`.id`, `.close()`.
 
 ### Example
 
 ```ts
-import { Observer } from '@observertc/observer-js';
+import { Observer, InMemorySink } from '@observertc/observer-js';
 import type { ObservedMediasoupRouterScope, ObservedPeerConnectionScope } from '@observertc/observer-js';
 
 const observer = new Observer();
@@ -882,42 +924,42 @@ const observer = new Observer();
 // 1) Feed client samples as usual so the observer knows about calls, clients & peer connections.
 //    (e.g. transport-layer: observer.accept(clientSample, context))
 
-// 2) Observe the SFU side. The observer auto-matches peer connections to this router's transports.
+// 2) Observe the SFU side; opt in to peer-connection matching. State accumulates in `.sample`.
 const router = /* your mediasoup router */ undefined as any;
-const observedRouter = observer.createObservedMediasoupRouter({ router, routerId: router.id });
+const observedRouter = observer.createObservedMediasoupRouter({
+  router,
+  matchPeerConnectionByWebRtcTransportId: true,
+});
+
+// For large meetings, sample it yourself on your own cadence (see "Memory & large meetings"):
+// setInterval(() => persist(observedRouter.sample), 10_000);
 
 // 3) Every peer connection whose id matches one of the router's WebRTC transport ids fires this —
 //    WE decide what to do with each pairing. The payload carries the full ancestry.
 observer.on('mediasoup-router-matched-with-peer-connection',
-  ({ observedMediasoupRouter, observedCall, observedClient, observedPeerConnection }:
+  ({ observedMediasoupRouter, observedCall, observedPeerConnection }:
      ObservedMediasoupRouterScope & ObservedPeerConnectionScope) => {
-    // e.g. remember which router serves this peer connection / client…
     (observedPeerConnection.appData ??= {}).routerId = observedMediasoupRouter.id;
-    // …or index the server sample by call in your own store:
-    myStore.linkRouterToCall(observedCall.callId, observedMediasoupRouter.sample);
+    myStore.linkRouterToCall(observedCall.callId, observedMediasoupRouter.id);
   },
 );
 
-// 4) The router closed — WE decide what to persist/forward with the final sample.
+// 4) The router closed — read/persist the final state, then drop your reference.
 observer.on('mediasoup-router-removed', ({ observedMediasoupRouter }: ObservedMediasoupRouterScope) => {
-  myStore.saveRouterSample(observedMediasoupRouter.sample);
-});
-
-// (optional) react to the router being registered at all:
-observer.on('mediasoup-router-added', ({ observedMediasoupRouter }) => {
-  console.log('observing router', observedMediasoupRouter.id);
+  persist(observedMediasoupRouter.sample);   // its `closedAt` is set
 });
 ```
 
-### Why event-driven instead of storing on the call
+### Why event-driven matching instead of storing on the call
 
 - **Loose coupling.** The call model stays about client telemetry; the SFU view lives on its own
-  object and is associated only if and how *you* choose.
+  `ObservedMediasoupRouter` and is associated only if and how *you* choose.
 - **You own the association.** One router serves many peer connections (across clients and calls),
   and the right place to keep that mapping is application-specific — so the observer hands you each
-  peer-connection match and the final sample, and gets out of the way.
-- **No silent accumulation.** Nothing is appended to `ObservedCall`, so there is no hidden growth or
-  lifetime you have to reason about; the router sample lives exactly as long as you keep a reference.
+  peer-connection match and gets out of the way.
+- **You own the sampling.** The router sample is plain in-memory state you read on your own terms;
+  for large meetings, sample/persist it yourself (see [Memory & large meetings](#memory--large-meetings))
+  rather than relying on the library to evict — it deliberately doesn't.
 
 ---
 
@@ -1043,6 +1085,60 @@ const observer = new Observer({ createClientSink });
 the bus with full ancestry. `ClientSampleSinkFactory` is
 `(p: { clientId: string; observedCall: ObservedCall }) => ClientSampleSink | undefined`.
 
+---
+
+## Injecting data into a client
+
+Sometimes the application holds data that belongs on a client's record but isn't part of the
+client-reported `ClientSample` — a room id or display name, an application-level event
+(*"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.
+
+| Method | Adds to the sample's | Surfaces as |
+|--------|----------------------|-------------|
+| `injectAttachment(attachments)` | `attachments` (merged via `Object.assign`) | `observedClient.attachments` |
+| `injectEvent(event: ClientEvent)` | `clientEvents` | `client-event` (plus any state the event drives) |
+| `injectIssue(issue: ClientIssue)` | `clientIssues` | `client-issue` |
+| `injectMetaData(meta: ClientMetaData)` | `clientMetaItems` | `client-metadata` |
+| `injectExtensionStat(stat: ExtensionStat)` | `extensionStats` | `client-extension-stats` |
+
+### When the injected data lands
+
+Injection is timing-aware so nothing is dropped, regardless of *when* you call it:
+
+- **During a sample's processing** — e.g. from inside a `client-updated` / `client-event` handler,
+  which run within `accept()` — the data is applied to the **current** sample immediately: reflected
+  in entity state and written to the sink as part of that sample.
+- **Between samples** — the data is buffered and merged into the **next** `accept()`'s sample.
+- **On `close()` with pending injections and no further sample** — the buffer is flushed as a final
+  synthetic sample (applied to state and written to the sink) before the sink is ended, so a
+  last-moment injection is never lost.
+
+In every case the injected data both updates the live `ObservedClient` and reaches the per-client
+sink — the sink always receives the final, **injection-merged** sample (the sink write happens at the
+end of `accept()`, after the merge).
+
+### Example
+
+```ts
+// Enrich at creation from your app's knowledge of the participant. Injecting in `client-added`
+// (which runs just before the first accept) lands on the first sample.
+observer.on('client-added', ({ observedClient }) => {
+  observedClient.injectAttachment({ roomId: lookupRoomId(observedClient.clientId) });
+});
+
+// Application-level signals at any time:
+const client = observer.getObservedCall(callId)?.getObservedClient(clientId);
+client?.injectEvent({ type: 'RECORDING_STARTED', timestamp: Date.now() });
+client?.injectIssue({ type: 'app-kicked-participant', timestamp: Date.now() });
+```
+
+`attachments` are latest-wins (like sampled `attachments`): injecting a key overwrites its previous
+value. `appData` is unaffected — injections flow into the sample/telemetry, not the app-owned
+`appData` bag (see [Ingestion](#ingestion-accept-context--lifecycle)).
+
 ## Logging
 
 `observer-js` logs through a single, swappable sink. Out of the box it writes `debug` and
@@ -1491,7 +1587,7 @@ the 1.0.0 API provides.
   track to the subscribed (inbound) tracks carrying it (**one publisher → many subscribers**) by a
   **publisher id** (the link key). Links are maintained directly on the tracks
   (`inboundTrack.remoteOutboundTrack`, `outboundTrack.remoteInboundTracks`).
-- **Opt-in via `ObserverConfig.createTrackResolver`**, invoked per call. Built-in factories:
+- **Opt-in via `ObserverConfig.createRemoteTrackResolver`**, invoked per call. Built-in factories:
   `createDefaultMediasoupRemoteTrackResolverFactory()` (producerId/consumerId attachments) and
   `createP2pRemoteTrackResolverFactory()` (RTP SSRC). Custom topologies supply their own
   publisher/subscriber id resolvers.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@observertc/observer-js",
-  "version": "1.0.0-beta.10",
+  "version": "1.0.0-beta.12",
   "description": "Server-side Node.js library for processing ObserveRTC Samples",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",
@@ -32,7 +32,8 @@
     "build": "tsup",
     "typecheck": "tsc --noEmit",
     "test": "jest --config jest.config.js",
-    "test:coverage": "jest --config jest.config.js --coverage"
+    "test:coverage": "jest --config jest.config.js --coverage",
+    "docs:llms-full": "node scripts/build-llms-full.mjs"
   },
   "keywords": [
     "webrtc",