@forwardimpact/libbridge 0.1.13 → 0.1.15

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@forwardimpact/libbridge",
-  "version": "0.1.13",
+  "version": "0.1.15",
   "description": "Threaded-channel bridge primitives — relay messages between human channels (GitHub Discussions, Microsoft Teams) and the Kata agent team.",
   "keywords": [
     "bridge",

package/src/callback-registry.js

@@ -1,6 +1,7 @@
 import { randomUUID } from "node:crypto";
 
 const DEFAULT_TTL_MS = 2 * 60 * 60 * 1000;
+const DEFAULT_SWEEP_INTERVAL_MS = 10 * 60 * 1000;
 
 /**
  * In-memory registry of pending bridge → workflow callbacks. Hosts persist
@@ -17,6 +18,7 @@ export class CallbackRegistry {
   #ttlMs;
   #clock;
   #entries = new Map();
+  #sweepTimer = null;
 
   /**
    * @param {object} [options]
@@ -56,8 +58,20 @@ export class CallbackRegistry {
   }
 
   /**
-   * Atomic lookup + delete. Returns null when the token is unknown or when
-   * the supplied `tenant_id` does not match the stored binding.
+   * Whether an entry's TTL has elapsed; expired entries are dropped at the
+   * lookup that observes them so a stale token stops being a credential
+   * even when no sweep has run yet.
+   * @param {{createdAt: number}} entry
+   * @param {number} now
+   * @returns {boolean}
+   */
+  #expired(entry, now) {
+    return now - entry.createdAt > this.#ttlMs;
+  }
+
+  /**
+   * Atomic lookup + delete. Returns null when the token is unknown, expired,
+   * or when the supplied `tenant_id` does not match the stored binding.
    * @param {string} token
    * @param {{tenant_id: string}} bind
    * @returns {{correlationId: string, meta: object, createdAt: number} | null}
@@ -68,6 +82,10 @@ export class CallbackRegistry {
     }
     const entry = this.#entries.get(token);
     if (!entry) return null;
+    if (this.#expired(entry, this.#clock.now())) {
+      this.#entries.delete(token);
+      return null;
+    }
     if (entry.meta.tenant_id !== bind.tenant_id) return null;
     this.#entries.delete(token);
     return entry;
@@ -87,6 +105,10 @@ export class CallbackRegistry {
     }
     const entry = this.#entries.get(token);
     if (!entry) return null;
+    if (this.#expired(entry, this.#clock.now())) {
+      this.#entries.delete(token);
+      return null;
+    }
     if (entry.meta.tenant_id !== bind.tenant_id) return null;
     return { ...entry };
   }
@@ -97,15 +119,25 @@ export class CallbackRegistry {
    * route uses this to verify a path-supplied tenant against the binding
    * the dispatcher recorded. Single-pass scan of the entries map; the
    * registry is one entry per in-flight dispatch per bridge process.
+   *
+   * Scan-by-design (timing-parity): the bounded-n scan is acceptable only
+   * while the caller preserves response-shape parity — a miss here and a
+   * tenant mismatch must produce the same response (the inbox route
+   * collapses both to 404 `Unknown correlation`), so timing or shape never
+   * distinguishes "correlation unknown" from "correlation bound elsewhere".
    * @param {string} correlationId
    * @returns {string | null}
    */
   tenantOf(correlationId) {
     if (typeof correlationId !== "string" || !correlationId) return null;
-    for (const entry of this.#entries.values()) {
-      if (entry.correlationId === correlationId) {
-        return entry.meta.tenant_id;
+    const now = this.#clock.now();
+    for (const [token, entry] of this.#entries) {
+      if (entry.correlationId !== correlationId) continue;
+      if (this.#expired(entry, now)) {
+        this.#entries.delete(token);
+        continue;
       }
+      return entry.meta.tenant_id;
     }
     return null;
   }
@@ -119,11 +151,32 @@ export class CallbackRegistry {
   sweep(now = this.#clock.now()) {
     let evicted = 0;
     for (const [token, entry] of this.#entries) {
-      if (now - entry.createdAt > this.#ttlMs) {
+      if (this.#expired(entry, now)) {
         this.#entries.delete(token);
         evicted++;
       }
     }
     return evicted;
   }
+
+  /**
+   * Start the periodic sweep so tokens whose dispatch never calls back are
+   * reclaimed instead of accumulating for the life of the process. Idempotent;
+   * the handle is unref'd so it never holds the process open.
+   * @param {number} [intervalMs]
+   */
+  startSweepTimer(intervalMs = DEFAULT_SWEEP_INTERVAL_MS) {
+    if (this.#sweepTimer) return;
+    this.#sweepTimer = this.#clock.setInterval(() => this.sweep(), intervalMs);
+    this.#sweepTimer.unref?.();
+  }
+
+  /**
+   * Stop the periodic sweep. Safe to call when no timer is running.
+   */
+  stopSweepTimer() {
+    if (!this.#sweepTimer) return;
+    this.#clock.clearInterval(this.#sweepTimer);
+    this.#sweepTimer = null;
+  }
 }