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

package/dist/index.mjs

@@ -2632,6 +2632,10 @@ var ObservedClient = class extends EventEmitter2 {
   }
   close() {
     if (this.closed) return;
+    if (this.closeTimer) {
+      clearTimeout(this.closeTimer);
+      this.closeTimer = void 0;
+    }
     this._flushPendingInjections();
     const activeIssues = [...this.activeIssues.values()];
     for (const issue of activeIssues) {
@@ -2794,6 +2798,7 @@ var ObservedClient = class extends EventEmitter2 {
       this.closeTimer = setTimeout(() => {
         this.close();
       }, this.settings.closeClientIfIdleForMs);
+      this.closeTimer.unref?.();
     }
     this._activeSample = void 0;
     try {
@@ -3265,6 +3270,24 @@ var Detectors = class {
   constructor(...detectors) {
     this._detectors = detectors;
   }
+  /**
+   * Every registered detector, in registration order.
+   *
+   * This is **the** way to get hold of an instance: `addDetector` / `addObserverDetector` are
+   * chainable and return the owning entity, so the registry is where instances live. Read it to
+   * inspect a detector's state, or to pick one out and {@link remove} it.
+   *
+   * A copy, not the live array — a caller iterating this while removing would otherwise skip
+   * entries, and that is exactly what "remove the ones that look like X" does.
+   */
+  get instances() {
+    return [...this._detectors];
+  }
+  /** Iterate the registry directly: `for (const detector of call.detectors)`. */
+  [Symbol.iterator]() {
+    return this.instances[Symbol.iterator]();
+  }
+  /** The names in registration order. Duplicates are meaningful — see {@link getAll}. */
   get listOfNames() {
     return this._detectors.map((d) => d.name);
   }
@@ -3274,12 +3297,48 @@ var Detectors = class {
   add(detector) {
     this._detectors.push(detector);
   }
+  /** The first detector registered under `name`. See {@link getAll} when several can share one. */
   get(name) {
     return this._detectors.find((detector) => detector.name === name);
   }
+  /**
+   * Every detector registered under `name`.
+   *
+   * More than one is legitimate: `ClientPopulationIssueDetector` is meant to be added once per
+   * `groupBy` axis, and two instances of it share a name.
+   */
+  getAll(name) {
+    return this._detectors.filter((detector) => detector.name === name);
+  }
+  has(name) {
+    return this._detectors.some((detector) => detector.name === name);
+  }
+  /** Remove one specific instance. Returns `false` if it was not registered here. */
   remove(detector) {
-    this._detectors = this._detectors.filter((d) => d !== detector);
+    const remaining = this._detectors.filter((candidate) => candidate !== detector);
+    if (remaining.length === this._detectors.length) return false;
+    this._detectors = remaining;
     this._close(detector);
+    return true;
+  }
+  /**
+   * Remove **every** detector registered under `name`, returning how many were removed.
+   *
+   * All of them rather than the first, because a name can legitimately be registered more than once
+   * (see {@link getAll}) and "remove the `client-population-issue-detector`" cannot sensibly mean
+   * "remove whichever axis happens to be first in the array". Removing all of them is the only
+   * behaviour that leaves the registry in a state the caller can predict from the name alone.
+   *
+   * Each removed detector gets `close()`, so trackers unsubscribe from the issue registry, bus
+   * listeners drop, and timers clear — a detector removed without closing keeps being fed issues
+   * forever.
+   */
+  removeByName(name) {
+    const removed = this._detectors.filter((detector) => detector.name === name);
+    if (removed.length === 0) return 0;
+    this._detectors = this._detectors.filter((detector) => detector.name !== name);
+    for (const detector of removed) this._close(detector);
+    return removed.length;
   }
   update() {
     for (const detector of this._detectors) {
@@ -4181,6 +4240,12 @@ var ObservedCall = class extends EventEmitter3 {
   get score() {
     return this.calculatedScore.value;
   }
+  /**
+   * Build a call-scoped detector onto this call. Chainable.
+   *
+   * To get a handle on what was built — to inspect it, or to remove that exact instance later — read
+   * it back off the registry: `call.detectors.getAll(name)`, or `call.detectors.instances`.
+   */
   addDetector(name, config = {}) {
     if (this.closed) return this;
     let detector;
@@ -4213,6 +4278,27 @@ var ObservedCall = class extends EventEmitter3 {
     this.detectors.add(detector);
     return this;
   }
+  /**
+   * Remove a detector from **this call** by name, returning how many were removed.
+   *
+   * **Every** instance under the name goes — a name can legitimately be registered more than once.
+   * When you want one of them specifically, go through the registry, which deals in instances:
+   *
+   * ```ts
+   * const [ first ] = call.detectors.getAll('issue-fan-out-detector');
+   *
+   * call.detectors.remove(first);
+   * ```
+   *
+   * Either route `close()`s the detector, so it unsubscribes from `activeIssuesRegistry` — without
+   * that the registry keeps feeding a detector nobody is running any more, and its tracked set grows
+   * for the life of the call.
+   *
+   * To stop building it on *future* calls too, use `observer.removeCallDetector(name)`.
+   */
+  removeDetector(name) {
+    return this.detectors.removeByName(name);
+  }
   /**
    * Raise a call-level (server-side) finding; surfaced on the Observer bus as `call-issue`.
    *
@@ -4227,6 +4313,10 @@ var ObservedCall = class extends EventEmitter3 {
     if (this.closed) return;
     this.update();
     this.closed = true;
+    if (this.closeTimer) {
+      clearTimeout(this.closeTimer);
+      this.closeTimer = void 0;
+    }
     let minSampleTimestamps;
     let maxSampleTimestamps;
     const clients = [...this.observedClients.values()];
@@ -4285,6 +4375,7 @@ var ObservedCall = class extends EventEmitter3 {
           this.closeTimer = setTimeout(() => {
             this.close();
           }, this.settings.closeCallIfEmptyForMs);
+          this.closeTimer.unref?.();
         }
       }
       ++this.totalRemovedClients;
@@ -6247,6 +6338,12 @@ var Observer = class extends EventEmitter6 {
   get appData() {
     return this.config.appData;
   }
+  /**
+   * Build a cross-call detector onto `observer.detectors`. Chainable.
+   *
+   * To get a handle on what was built — to inspect it, or to remove that exact instance later — read
+   * it back off the registry: `observer.detectors.getAll(name)`, or `observer.detectors.instances`.
+   */
   addObserverDetector(name, config = {}) {
     if (this.closed) return this;
     let detector;
@@ -6290,10 +6387,41 @@ var Observer = class extends EventEmitter6 {
     this.callDetectorConfigs.set(name, config);
     return this;
   }
-  /** Stop building `name` on calls created from now on. Calls already open are untouched. */
-  removeCallDetector(name) {
+  /**
+   * Remove an observer-scoped detector by name, returning how many were removed.
+   *
+   * **Every** instance registered under the name goes, since a name can legitimately be registered
+   * more than once (`ClientPopulationIssueDetector` is meant to be added once per `groupBy` axis).
+   * When you want one of them specifically, go through the registry, which deals in instances:
+   *
+   * ```ts
+   * const [ byBrowser, byOs ] = observer.detectors.getAll('client-population-issue-detector');
+   *
+   * observer.detectors.remove(byOs);   // keeps the browser axis running
+   * ```
+   *
+   * Either route `close()`s the detector, so it unsubscribes from the issue registry and drops any
+   * timers or bus listeners it held.
+   */
+  removeObserverDetector(name) {
+    return this.detectors.removeByName(name);
+  }
+  /**
+   * Stop building `name` on calls created from now on.
+   *
+   * By default this also removes it from the calls **already open**, so that "remove this detector"
+   * means the same thing whether you say it before or after a call started — the alternative leaves
+   * a fleet where the detector is live on some calls and not others, decided by join time. Pass
+   * `{ includeOpenCalls: false }` to change only what future calls are built with.
+   *
+   * Returns the number of live detector instances removed (`0` when only the config changed).
+   */
+  removeCallDetector(name, { includeOpenCalls = true } = {}) {
     this.callDetectorConfigs.delete(name);
-    return this;
+    if (!includeOpenCalls) return 0;
+    let removed = 0;
+    for (const call of this.observedCalls.values()) removed += call.removeDetector(name);
+    return removed;
   }
   /**
    * Start a structural check. It runs on each `observer.update()` until it can decide, reports once
@@ -6332,6 +6460,36 @@ var Observer = class extends EventEmitter6 {
     this.validators.add(validator);
     return this;
   }
+  /**
+   * Stop a running validation, by name or by instance. Returns how many were cancelled.
+   *
+   * Cancelling is **not** silent discarding. The validator finishes with `inconclusive` and the given
+   * `reason`, emits `validation-ready` like any other completion, and removes itself. That matters
+   * because anything waiting on the verdict — a deploy gate, a dashboard, a promise — would otherwise
+   * wait forever, and because "we stopped asking" is a materially different outcome from "we asked
+   * and learned nothing", which is exactly what `inconclusive` with a reason records.
+   *
+   * ```ts
+   * observer.cancelValidator('simulcast-receivers', 'sfu redeployed');
+   *
+   * // or one specific instance — `observer.validators` holds what is running
+   * for (const validator of observer.validators) observer.cancelValidator(validator, 'shutting down');
+   * ```
+   *
+   * Pass a real reason. The default tells the reader nothing they could not already infer.
+   */
+  cancelValidator(target, reason = "cancelled") {
+    const running = [...this.validators];
+    const matching = typeof target === "string" ? running.filter((validator) => validator.name === target) : running.filter((validator) => validator === target);
+    for (const validator of matching) {
+      try {
+        validator.cancel(reason);
+      } catch (err) {
+        logger8.warn("Error cancelling validator %s: %o", validator.name, err);
+      }
+    }
+    return matching.length;
+  }
   getObservedCall(callId) {
     if (this.closed || !this.observedCalls.has(callId)) return;
     return this.observedCalls.get(callId);
@@ -6419,7 +6577,7 @@ var Observer = class extends EventEmitter6 {
     this.closed = true;
     for (const call of [...this.observedCalls.values()]) call.close();
     this.detectors.clear();
-    for (const validator of [...this.validators]) validator.cancel();
+    for (const validator of [...this.validators]) validator.cancel("observer closed");
     this.validators.clear();
     this.activeIssuesRegistry.clear();
     this._notify("observer-closed", { ...this.eventScope });