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

package/README.md

@@ -63,9 +63,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)
 
 ---
 
@@ -369,7 +370,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.
@@ -539,7 +540,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?`,
@@ -832,11 +833,13 @@ 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.
 
 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
@@ -850,10 +853,11 @@ you want with the now-final `sample` — again, the observer itself keeps nothin
 | `routerId` | `string` | yes | your id for the router (the sample also carries `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` |
+| `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`,
@@ -870,9 +874,13 @@ 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, opting in to peer-connection matching for this router's transports.
 const router = /* your mediasoup router */ undefined as any;
-const observedRouter = observer.createObservedMediasoupRouter({ router, routerId: router.id });
+const observedRouter = observer.createObservedMediasoupRouter({
+  router,
+  routerId: router.id,
+  matchPeerConnectionByWebRtcTransportId: true,
+});
 
 // 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.
@@ -1031,6 +1039,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

package/dist/index.d.mts

@@ -2570,7 +2570,8 @@ declare class ObservedClient<AppData extends Record<string, unknown> = Record<st
     numberOfScoreMeasurements: number;
     readonly mediaDevices: MediaDeviceInfo[];
     issues: ClientIssue[];
-    private _injections;
+    private _pendingInjections;
+    private _activeSample?;
     private closeTimer?;
     constructor(settings: ObservedClientSettings<AppData>, call: ObservedCall);
     get numberOfPeerConnections(): number;
@@ -2581,13 +2582,14 @@ declare class ObservedClient<AppData extends Record<string, unknown> = Record<st
     injectEvent(event: ClientEvent): void;
     injectIssue(issue: ClientIssue): void;
     injectExtensionStat(stat: ExtensionStat): void;
-    injectAttachment(key: string, value: unknown): void;
+    injectAttachment(attachments: Record<string, unknown>): void;
     addMetadata(metadata: ClientMetaData): void;
     addIssue(issue: ClientIssue): void;
     addExtensionStats(stats: ExtensionStat): void;
     private _processClientEvent;
     private _updatePeerConnection;
-    private _mergeInjections;
+    private _mergePendingInjections;
+    private _flushPendingInjections;
     /** Emit an Observer-bus event scoped to this client (or a peer connection under it). */
     private _notify;
 }
@@ -2836,7 +2838,9 @@ declare class Observer<AppData extends Record<string, unknown> = Record<string,
     getObservedCall<T extends Record<string, unknown> = Record<string, unknown>>(callId: string): ObservedCall<T> | undefined;
     createObservedCall<T extends Record<string, unknown> = Record<string, unknown>>(settings: ObservedCallSettings<T>): ObservedCall<T> | undefined;
     getOrCreateObservedCall<T extends Record<string, unknown> = Record<string, unknown>>(settings: ObservedCallSettings<T>): ObservedCall<T> | undefined;
-    createObservedMediasoupRouter<T extends Record<string, unknown> = Record<string, unknown>>(settings: ObservedMediasoupRouterSettings<T>): ObservedMediasoupRouter<Record<string, unknown>> | undefined;
+    createObservedMediasoupRouter<T extends Record<string, unknown> = Record<string, unknown>>(settings: ObservedMediasoupRouterSettings<T> & {
+        matchPeerConnectionByWebRtcTransportId?: boolean;
+    }): ObservedMediasoupRouter<Record<string, unknown>> | undefined;
     close(): void;
     accept(sample: ClientSample, context?: AcceptContext): void;
     update(): void;

package/dist/index.d.ts

@@ -2570,7 +2570,8 @@ declare class ObservedClient<AppData extends Record<string, unknown> = Record<st
     numberOfScoreMeasurements: number;
     readonly mediaDevices: MediaDeviceInfo[];
     issues: ClientIssue[];
-    private _injections;
+    private _pendingInjections;
+    private _activeSample?;
     private closeTimer?;
     constructor(settings: ObservedClientSettings<AppData>, call: ObservedCall);
     get numberOfPeerConnections(): number;
@@ -2581,13 +2582,14 @@ declare class ObservedClient<AppData extends Record<string, unknown> = Record<st
     injectEvent(event: ClientEvent): void;
     injectIssue(issue: ClientIssue): void;
     injectExtensionStat(stat: ExtensionStat): void;
-    injectAttachment(key: string, value: unknown): void;
+    injectAttachment(attachments: Record<string, unknown>): void;
     addMetadata(metadata: ClientMetaData): void;
     addIssue(issue: ClientIssue): void;
     addExtensionStats(stats: ExtensionStat): void;
     private _processClientEvent;
     private _updatePeerConnection;
-    private _mergeInjections;
+    private _mergePendingInjections;
+    private _flushPendingInjections;
     /** Emit an Observer-bus event scoped to this client (or a peer connection under it). */
     private _notify;
 }
@@ -2836,7 +2838,9 @@ declare class Observer<AppData extends Record<string, unknown> = Record<string,
     getObservedCall<T extends Record<string, unknown> = Record<string, unknown>>(callId: string): ObservedCall<T> | undefined;
     createObservedCall<T extends Record<string, unknown> = Record<string, unknown>>(settings: ObservedCallSettings<T>): ObservedCall<T> | undefined;
     getOrCreateObservedCall<T extends Record<string, unknown> = Record<string, unknown>>(settings: ObservedCallSettings<T>): ObservedCall<T> | undefined;
-    createObservedMediasoupRouter<T extends Record<string, unknown> = Record<string, unknown>>(settings: ObservedMediasoupRouterSettings<T>): ObservedMediasoupRouter<Record<string, unknown>> | undefined;
+    createObservedMediasoupRouter<T extends Record<string, unknown> = Record<string, unknown>>(settings: ObservedMediasoupRouterSettings<T> & {
+        matchPeerConnectionByWebRtcTransportId?: boolean;
+    }): ObservedMediasoupRouter<Record<string, unknown>> | undefined;
     close(): void;
     accept(sample: ClientSample, context?: AcceptContext): void;
     update(): void;

package/dist/index.js

@@ -2250,7 +2250,8 @@ var ObservedClient = class extends import_events2.EventEmitter {
   // public totalNumberOfIssues = 0;
   mediaDevices = [];
   issues = [];
-  _injections = {};
+  _pendingInjections = {};
+  _activeSample;
   closeTimer;
   get numberOfPeerConnections() {
     return this.observedPeerConnections.size;
@@ -2260,11 +2261,8 @@ var ObservedClient = class extends import_events2.EventEmitter {
   }
   close() {
     if (this.closed) return;
+    this._flushPendingInjections();
     this.closed = true;
-    this._injections.clientEvents?.forEach((clientEvent) => this._processClientEvent(clientEvent));
-    this._injections.clientIssues?.forEach((clientIssue) => this.addIssue(clientIssue));
-    this._injections.extensionStats?.forEach((extensionStat) => this.addExtensionStats(extensionStat));
-    this._injections.clientMetaItems?.forEach((clientMetaItem) => this.addMetadata(clientMetaItem));
     Array.from(this.observedPeerConnections.values()).forEach((peerConnection) => peerConnection.close());
     if (!this.leftAt) {
       this.leftAt = this.lastSampleTimestamp;
@@ -2287,7 +2285,6 @@ var ObservedClient = class extends import_events2.EventEmitter {
       logger2.warn("Attempted to accept a sample on a closed client %s", this.clientId);
       return;
     }
-    this.sink?.write(sample);
     if (this.closeTimer) {
       clearTimeout(this.closeTimer);
       this.closeTimer = void 0;
@@ -2327,7 +2324,8 @@ var ObservedClient = class extends import_events2.EventEmitter {
     this.usingTCP = false;
     this.currentMinRttInMs = void 0;
     this.currentMaxRttInMs = void 0;
-    this._mergeInjections(sample);
+    this._mergePendingInjections(sample);
+    this._activeSample = sample;
     const clientEventsPostBuffer = [];
     for (const clientEvent of sample.clientEvents ?? []) {
       this._processClientEvent(clientEvent, clientEventsPostBuffer);
@@ -2415,31 +2413,68 @@ var ObservedClient = class extends import_events2.EventEmitter {
         this.close();
       }, this.settings.closeClientIfIdleForMs);
     }
+    this._activeSample = void 0;
+    try {
+      this.sink?.write(sample);
+    } catch (err) {
+      logger2.warn("ClientSampleSink.write failed for client %s: %o", this.clientId, err);
+    }
   }
   injectMetaData(metaData) {
     if (this.closed) return;
-    if (!this._injections.clientMetaItems) this._injections.clientMetaItems = [];
-    this._injections.clientMetaItems.push(metaData);
+    if (this._activeSample) {
+      if (!this._activeSample.clientMetaItems) this._activeSample.clientMetaItems = [];
+      this._activeSample.clientMetaItems.push(metaData);
+      this.addMetadata(metaData);
+      return;
+    }
+    if (!this._pendingInjections.clientMetaItems) this._pendingInjections.clientMetaItems = [];
+    this._pendingInjections.clientMetaItems.push(metaData);
   }
   injectEvent(event) {
     if (this.closed) return;
-    if (!this._injections.clientEvents) this._injections.clientEvents = [];
-    this._injections.clientEvents.push(event);
+    if (this._activeSample) {
+      if (!this._activeSample.clientEvents) this._activeSample.clientEvents = [];
+      this._activeSample.clientEvents.push(event);
+      this._processClientEvent(event);
+      return;
+    }
+    if (!this._pendingInjections.clientEvents) this._pendingInjections.clientEvents = [];
+    this._pendingInjections.clientEvents.push(event);
   }
   injectIssue(issue) {
     if (this.closed) return;
-    if (!this._injections.clientIssues) this._injections.clientIssues = [];
-    this._injections.clientIssues.push(issue);
+    if (this._activeSample) {
+      if (!this._activeSample.clientIssues) this._activeSample.clientIssues = [];
+      this._activeSample.clientIssues.push(issue);
+      this.addIssue(issue);
+      ++this.deltaNumberOfIssues;
+      return;
+    }
+    if (!this._pendingInjections.clientIssues) this._pendingInjections.clientIssues = [];
+    this._pendingInjections.clientIssues.push(issue);
   }
   injectExtensionStat(stat) {
     if (this.closed) return;
-    if (!this._injections.extensionStats) this._injections.extensionStats = [];
-    this._injections.extensionStats.push(stat);
+    if (this._activeSample) {
+      if (!this._activeSample.extensionStats) this._activeSample.extensionStats = [];
+      this._activeSample.extensionStats.push(stat);
+      this.addExtensionStats(stat);
+      return;
+    }
+    if (!this._pendingInjections.extensionStats) this._pendingInjections.extensionStats = [];
+    this._pendingInjections.extensionStats.push(stat);
   }
-  injectAttachment(key, value) {
+  injectAttachment(attachments) {
     if (this.closed) return;
-    if (!this._injections.attachments) this._injections.attachments = {};
-    this._injections.attachments[key] = value;
+    if (this._activeSample) {
+      if (!this._activeSample.attachments) this._activeSample.attachments = {};
+      Object.assign(this._activeSample.attachments, attachments);
+      this.attachments = this._activeSample.attachments;
+      return;
+    }
+    if (!this._pendingInjections.attachments) this._pendingInjections.attachments = {};
+    Object.assign(this._pendingInjections.attachments, attachments);
   }
   addMetadata(metadata) {
     if (this.closed) return;
@@ -2701,35 +2736,53 @@ var ObservedClient = class extends import_events2.EventEmitter {
     observedPeerConnection.accept(sample, context);
     return observedPeerConnection;
   }
-  _mergeInjections(sample) {
+  _mergePendingInjections(sample) {
     if (this.closed) return sample;
-    if (this._injections.clientEvents) {
+    if (this._pendingInjections.clientEvents) {
       if (!sample.clientEvents) sample.clientEvents = [];
-      sample.clientEvents.push(...this._injections.clientEvents);
-      this._injections.clientEvents = void 0;
+      sample.clientEvents.push(...this._pendingInjections.clientEvents);
+      this._pendingInjections.clientEvents = void 0;
     }
-    if (this._injections.clientIssues) {
+    if (this._pendingInjections.clientIssues) {
       if (!sample.clientIssues) sample.clientIssues = [];
-      sample.clientIssues.push(...this._injections.clientIssues);
-      this._injections.clientIssues = void 0;
+      sample.clientIssues.push(...this._pendingInjections.clientIssues);
+      this._pendingInjections.clientIssues = void 0;
     }
-    if (this._injections.extensionStats) {
+    if (this._pendingInjections.extensionStats) {
       if (!sample.extensionStats) sample.extensionStats = [];
-      sample.extensionStats.push(...this._injections.extensionStats);
-      this._injections.extensionStats = void 0;
+      sample.extensionStats.push(...this._pendingInjections.extensionStats);
+      this._pendingInjections.extensionStats = void 0;
     }
-    if (this._injections.attachments) {
+    if (this._pendingInjections.attachments) {
       if (!sample.attachments) sample.attachments = {};
-      Object.assign(sample.attachments, this._injections.attachments);
-      this._injections.attachments = void 0;
+      Object.assign(sample.attachments, this._pendingInjections.attachments);
+      this._pendingInjections.attachments = void 0;
     }
-    if (this._injections.clientMetaItems) {
+    if (this._pendingInjections.clientMetaItems) {
       if (!sample.clientMetaItems) sample.clientMetaItems = [];
-      sample.clientMetaItems.push(...this._injections.clientMetaItems);
-      this._injections.clientMetaItems = void 0;
+      sample.clientMetaItems.push(...this._pendingInjections.clientMetaItems);
+      this._pendingInjections.clientMetaItems = void 0;
     }
     return sample;
   }
+  _flushPendingInjections() {
+    const hasPending = Boolean(
+      this._pendingInjections.clientEvents || this._pendingInjections.clientIssues || this._pendingInjections.extensionStats || this._pendingInjections.clientMetaItems || this._pendingInjections.attachments
+    );
+    if (!hasPending) return;
+    const finalSample = { timestamp: Date.now() };
+    this._mergePendingInjections(finalSample);
+    for (const clientEvent of finalSample.clientEvents ?? []) this._processClientEvent(clientEvent);
+    for (const metaData of finalSample.clientMetaItems ?? []) this.addMetadata(metaData);
+    for (const issue of finalSample.clientIssues ?? []) this.addIssue(issue);
+    for (const extensionStat of finalSample.extensionStats ?? []) this.addExtensionStats(extensionStat);
+    if (finalSample.attachments) this.attachments = { ...this.attachments, ...finalSample.attachments };
+    try {
+      this.sink?.write(finalSample);
+    } catch (err) {
+      logger2.warn("ClientSampleSink.write failed during injection flush for client %s: %o", this.clientId, err);
+    }
+  }
   /** Emit an Observer-bus event scoped to this client (or a peer connection under it). */
   _notify(type, ...args) {
     this.call.observer.emit(type, ...args);
@@ -3729,17 +3782,19 @@ var Observer = class extends import_events6.EventEmitter {
       observedMediasoupRouter,
       observer: this
     };
-    const onPeerConnectionAdded = (observedPeerConnectionScope) => {
-      if (!observedMediasoupRouter.webrtcTransportIds.has(observedPeerConnectionScope.observedPeerConnection.peerConnectionId)) return;
-      this.emit("mediasoup-router-matched-with-peer-connection", {
-        ...observedMediasoupRouterScope,
-        ...observedPeerConnectionScope
-      });
-    };
-    const stopMatching = () => this.off("peer-connection-added", onPeerConnectionAdded);
-    this.on("peer-connection-added", onPeerConnectionAdded);
-    this.once("observer-closed", stopMatching);
-    observedMediasoupRouter.once("close", stopMatching);
+    if (settings.matchPeerConnectionByWebRtcTransportId) {
+      const onPeerConnectionAdded = (observedPeerConnectionScope) => {
+        if (!observedMediasoupRouter.webrtcTransportIds.has(observedPeerConnectionScope.observedPeerConnection.peerConnectionId)) return;
+        this.emit("mediasoup-router-matched-with-peer-connection", {
+          ...observedMediasoupRouterScope,
+          ...observedPeerConnectionScope
+        });
+      };
+      const stopMatching = () => this.off("peer-connection-added", onPeerConnectionAdded);
+      this.on("peer-connection-added", onPeerConnectionAdded);
+      this.once("observer-closed", stopMatching);
+      observedMediasoupRouter.once("close", stopMatching);
+    }
     observedMediasoupRouter.once("close", () => {
       this.observedMediasoupRouters.delete(observedMediasoupRouter.id);
       this.emit("mediasoup-router-removed", observedMediasoupRouterScope);