@goodandready/dsh-key-rotation 0.8.68 → 0.8.70

package/CHANGELOG.md

@@ -1,5 +1,33 @@
 # Changelog
 
+## 0.8.70 - 2026-10-20
+
+### Bug Fixes
+- **Fix Fatal Crash in sweepExpired & Isolate Clone Metadata (#513, GitHub #26)**:
+  - Guarded `sweepExpired` in `lib/pool.js` and the periodic sweep timer in `lib/index.js` with `if (!st || !(st.failedUntil instanceof Map)) continue;` to safely skip non-pool-state values.
+  - Isolated clone route metadata tracking inside `CloneLifecycleManager` (`this.knownClones`) rather than polluting `poolState` with `Set` objects (`${provider}:clones`).
+  - Added regression test `test/github-issue-26-sweep-expired.test.mjs` verifying `sweepExpired` robustness with heterogeneous data and clean `poolState` boundaries.
+
+## 0.8.69 - 2026-10-19
+
+### Features
+- **Automated Clone Route Lifecycle & Settings Synchronization (#502)**:
+  - Added `lib/clone-lifecycle.js` orchestrating automatic configuration, key pools, and parameter synchronization for auxiliary clone routes.
+  - Cloned worker routes dynamically inherit primary model, temperature, top-p, context window limits, and token buckets while isolating per-key rotation states.
+  - Supported graceful route drain via `key-drain.js` (`getInFlight` & `getActive`), ensuring active in-flight requests finish cleanly before clone route teardown.
+
+### Bug Fixes
+- **Prompt Cache Periodic Maintenance Sweep (#511)**:
+  - Wired `compactPromptCache(pool, 30, now)` into the plugin's periodic maintenance sweep alongside `compactUsage`.
+  - Automatically purges prompt cache telemetry entries older than 30 days to prevent unbound memory growth during continuous production uptime.
+
+### Refactoring & Code Quality
+- **Core File Modularization (< 600 Lines Standard) (#512)**:
+  - Decomposed oversized monolithic modules to comply with `dsh-plugin-authoring` and `dsh-plugin-preflight` standards.
+  - Extracted key selection algorithms and sticky session routing from `lib/pool.js` into `lib/pool-selection.js` (bringing `pool.js` down from 654 to 521 lines).
+  - Extracted streaming success telemetry and proactive limit detection from `lib/rotate.js` into `lib/stream-metrics.js` and deduplicated cascade fallbacks (bringing `rotate.js` down from 716 to 595 lines).
+  - Decomposed monolithic UI card component `lib/client-src/50-card-main.js` (2,141 lines) into modular fragments: `50-card-main.js` (550 lines), `51-card-pool-mutators.js` (501 lines), `52-card-pool-rows.js` (590 lines), and `53-card-dialogs-and-render.js` (500 lines), ensuring 100% deterministic compilation and <600 lines for every source fragment.
+
 ## 0.8.68 - 2026-10-19
 
 ### Features

package/lib/clone-lifecycle.js

@@ -0,0 +1,216 @@
+// lib/clone-lifecycle.js — automated clone route lifecycle and settings synchronization (#502).
+// Ensures virtual clone providers (provider-2, provider-3) automatically copy and sync
+// baseUrl, headers, timeout, and models from the base provider, and graceful draining
+// on key reduction before deregistering routes.
+
+import { markKeyDraining, cancelKeyDrain, getDrainingStatus, isKeyDraining } from './key-drain.js';
+
+export const CLONE_SYNC_FIELDS = [
+  'baseUrl',
+  'baseURL',
+  'headers',
+  'timeout',
+  'systemPrompt',
+  'customHeaders',
+  'models',
+  'protocol',
+  'apiType',
+];
+
+/**
+ * Extracts syncable configuration from a base provider profile.
+ * @param {object} baseProfile
+ * @returns {object}
+ */
+export function extractSyncableConfig(baseProfile) {
+  if (!baseProfile || typeof baseProfile !== 'object') return {};
+  const syncable = {};
+  for (const field of CLONE_SYNC_FIELDS) {
+    if (baseProfile[field] !== undefined) {
+      syncable[field] = structuredClone(baseProfile[field]);
+    }
+  }
+  return syncable;
+}
+
+/**
+ * Copies base provider configuration onto each clone profile.
+ * @param {object} baseProfile
+ * @param {object} cloneProfile
+ * @returns {object} merged clone profile
+ */
+export function syncCloneProfile(baseProfile, cloneProfile = {}) {
+  const syncable = extractSyncableConfig(baseProfile);
+  const out = {
+    ...cloneProfile,
+    ...syncable,
+    isClone: true,
+  };
+  return out;
+}
+
+/**
+ * Synchronizes clone providers with their base provider settings.
+ * @param {object} opts
+ * @param {string} opts.baseProvider
+ * @param {Set<string>|string[]} opts.cloneIds
+ * @param {object} opts.profiles live provider profiles map from settings
+ * @param {Function} [opts.onUpdate] callback when clone is updated
+ * @returns {{ updated: string[], cloned: Record<string, object> }}
+ */
+export function synchronizeClones({ baseProvider, cloneIds, profiles, onUpdate }) {
+  if (!baseProvider || !profiles || typeof profiles !== 'object') {
+    return { updated: [], cloned: {} };
+  }
+
+  const baseProfile = profiles[baseProvider];
+  if (!baseProfile) {
+    return { updated: [], cloned: {} };
+  }
+
+  const updated = [];
+  const cloned = {};
+  const ids = cloneIds instanceof Set ? [...cloneIds] : (Array.isArray(cloneIds) ? cloneIds : []);
+
+  for (const cloneId of ids) {
+    if (!cloneId.startsWith(`${baseProvider}-`)) continue;
+    const existing = profiles[cloneId] || {};
+    const synced = syncCloneProfile(baseProfile, existing);
+    cloned[cloneId] = synced;
+    updated.push(cloneId);
+    if (typeof onUpdate === 'function') {
+      onUpdate(cloneId, synced);
+    }
+  }
+
+  return { updated, cloned };
+}
+
+/**
+ * Manages clone draining lifecycle when key count is reduced.
+ * Clones whose keys are removed are marked as draining, allowed to complete
+ * active in-flight streams, and safely deregistered only once in-flight reaches zero.
+ */
+export class CloneLifecycleManager {
+  /**
+   * @param {object} opts
+   * @param {object} opts.concurrencyTracker
+   * @param {object} [opts.logger]
+   */
+  constructor({ concurrencyTracker, logger } = {}) {
+    this.concurrencyTracker = concurrencyTracker;
+    this.logger = logger || console;
+    this.drainingClones = new Map(); // cloneId -> { provider, ref, startedAt, timer }
+    this.knownClones = new Map(); // provider -> Set<string>
+  }
+
+  /**
+   * Evaluates previous vs current expected clones for a provider.
+   * If a clone was removed, marks it draining instead of instantly destroying it.
+   * @param {string} provider
+   * @param {Set<string>|string[]} [prevClones]
+   * @param {Set<string>|string[]} currentClones
+   * @param {Function} [onDeregister] callback when draining completes and route is safe to remove
+   */
+  reconcileClones(provider, prevOrCurrent, currentOrDeregister, maybeDeregister) {
+    let prevClones;
+    let currentClones;
+    let onDeregister;
+
+    if (currentOrDeregister instanceof Set || Array.isArray(currentOrDeregister)) {
+      prevClones = prevOrCurrent;
+      currentClones = currentOrDeregister;
+      onDeregister = maybeDeregister;
+    } else {
+      prevClones = this.knownClones.get(provider) ?? [];
+      currentClones = prevOrCurrent;
+      onDeregister = currentOrDeregister;
+    }
+
+    const prevSet = prevClones instanceof Set ? prevClones : new Set(prevClones || []);
+    const currSet = currentClones instanceof Set ? currentClones : new Set(currentClones || []);
+
+    this.knownClones.set(provider, currSet);
+
+    for (const cloneId of prevSet) {
+      if (!currSet.has(cloneId)) {
+        this.startDrain(cloneId, provider, onDeregister);
+      }
+    }
+
+    for (const cloneId of currSet) {
+      if (this.drainingClones.has(cloneId)) {
+        this.cancelDrain(cloneId);
+      }
+    }
+  }
+
+  startDrain(cloneId, provider, onDeregister) {
+    if (this.drainingClones.has(cloneId)) return;
+
+    markKeyDraining(cloneId, provider);
+    const entry = {
+      cloneId,
+      provider,
+      startedAt: Date.now(),
+      onDeregister,
+    };
+    this.drainingClones.set(cloneId, entry);
+
+    if (this.logger?.info) {
+      this.logger.info(`[dsh-key-rotation] clone ${cloneId} (${provider}) marked draining; awaiting in-flight stream completion`);
+    }
+
+    this._checkDrainCompletion(cloneId);
+  }
+
+  _checkDrainCompletion(cloneId) {
+    const entry = this.drainingClones.get(cloneId);
+    if (!entry) return;
+
+    const inFlight = this.concurrencyTracker && typeof this.concurrencyTracker.getActive === 'function'
+      ? this.concurrencyTracker.getActive(cloneId)
+      : (this.concurrencyTracker && typeof this.concurrencyTracker.getInFlight === 'function'
+        ? this.concurrencyTracker.getInFlight(cloneId)
+        : 0);
+
+    if (inFlight === 0) {
+      this.drainingClones.delete(cloneId);
+      cancelKeyDrain(cloneId);
+      if (this.logger?.info) {
+        this.logger.info(`[dsh-key-rotation] clone ${cloneId} (${entry.provider}) drained cleanly; safe to deregister`);
+      }
+      if (typeof entry.onDeregister === 'function') {
+        entry.onDeregister(cloneId, entry.provider);
+      }
+    } else {
+      // Re-check after 500ms
+      setTimeout(() => this._checkDrainCompletion(cloneId), 500).unref?.();
+    }
+  }
+
+  cancelDrain(cloneId) {
+    this.drainingClones.delete(cloneId);
+    cancelKeyDrain(cloneId);
+  }
+
+  isDraining(cloneId) {
+    return this.drainingClones.has(cloneId) || isKeyDraining(cloneId);
+  }
+
+  getDrainingList() {
+    return Array.from(this.drainingClones.entries()).map(([cloneId, data]) => ({
+      cloneId,
+      provider: data.provider,
+      startedAt: data.startedAt,
+      elapsedMs: Date.now() - data.startedAt,
+    }));
+  }
+
+  destroy() {
+    for (const cloneId of this.drainingClones.keys()) {
+      cancelKeyDrain(cloneId);
+    }
+    this.drainingClones.clear();
+  }
+}

package/lib/index.js

@@ -22,6 +22,8 @@ import { ConcurrencyTracker } from './concurrency.js';
 import { QuotaStore } from './quota.js';
 import { WebhookSender, AlertDebouncer } from './webhook.js';
 import { compactUsage } from './usage-report.js';
+import { compactPromptCache } from './prompt-cache.js';
+import { CloneLifecycleManager, synchronizeClones } from './clone-lifecycle.js';
 import { json, handleConfigBridge } from './http-bridge.js';
 import { createRotate } from './rotate.js';
 import { initializePoolState } from './pool-state.js';
@@ -200,6 +202,8 @@ export function apply(ctx, config = {}) {
   const alertDebouncer = new AlertDebouncer({ sender: webhookSender, debounceMs: 2000 });
   const moduleNotifyQueue = new NotifyQueue({ send: (url, payload) => alertDebouncer.enqueue(url, payload) });
   const trafficSmoother = new TrafficSmoother({ maxQueueWaitMs: 800 });
+  const cloneLifecycle = new CloneLifecycleManager({ concurrencyTracker, logger });
+  ctx.effect(() => () => { cloneLifecycle.destroy(); }, 'dsh-key-rotation: clone lifecycle cleanup');
 
   const sandboxService = createSandboxService({ getRuntime: () => buildRuntime() });
   const { ensureSandboxRunner, probeRef, lastTestCache } = sandboxService;
@@ -228,6 +232,7 @@ export function apply(ctx, config = {}) {
     const id = setInterval(() => {
       const now = Date.now();
       for (const st of poolState.values()) {
+        if (!st || !(st.failedUntil instanceof Map)) continue;
         for (const [ref, until] of [...(st.failedUntil?.entries() ?? [])]) {
           if (until <= now && !st.probedAt?.has(ref)) {
             st.events.push({ at: until, ref, reason: 'probe', cooldownMs: 0, type: 'probe' });
@@ -243,6 +248,7 @@ export function apply(ctx, config = {}) {
       if (n > 0) logger.warn(`[dsh-key-rotation] sweep: cleared ${n} expired cooldown(s)`);
       for (const pool of (runtime.pools ?? runtime.poolByRef.values())) {
         compactUsage(pool, 30, now);
+        compactPromptCache(pool, 30, now);
       }
       checkBudgetAndHealthAlerts({
         runtime,
@@ -342,6 +348,7 @@ export function apply(ctx, config = {}) {
       moduleBreaker,
       lowHealthNotifiedAt,
       budgetNotifiedAt,
+      cloneLifecycle,
     });
 
     concurrencyTracker.configure({ limit: concurrencyLimit });

package/lib/key-drain.js

@@ -1,4 +1,4 @@
-// lib/key-drain.js — Managed key draining and graceful replacement (#463).
+// lib/key-drain.js — Managed key draining and graceful replacement (#463, #502).
 // Allows draining an old key ref (no new dispatches assigned) while letting
 // in-flight active streams complete cleanly before permanent removal.
 
@@ -27,9 +27,11 @@ export function cancelKeyDrain(ref) {
 export function getDrainingStatus(ref, concurrencyTracker) {
   if (!ref || !drainingKeys.has(ref)) return null;
   const entry = drainingKeys.get(ref);
-  const inFlight = concurrencyTracker && typeof concurrencyTracker.getInFlight === 'function'
-    ? concurrencyTracker.getInFlight(ref)
-    : 0;
+  const inFlight = concurrencyTracker && typeof concurrencyTracker.getActive === 'function'
+    ? concurrencyTracker.getActive(ref)
+    : (concurrencyTracker && typeof concurrencyTracker.getInFlight === 'function'
+      ? concurrencyTracker.getInFlight(ref)
+      : 0);
 
   return {
     ref,

package/lib/ops-config-io.js

@@ -1,5 +1,12 @@
 // lib/ops-config-io.js — full configuration export and import (#504).
 import crypto from 'node:crypto';
+import { readFileSync } from 'node:fs';
+
+let PLUGIN_VERSION = '0.8.68';
+try {
+  const pkg = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8'));
+  if (pkg.version) PLUGIN_VERSION = pkg.version;
+} catch (_) { /* fallback */ }
 import { json, readJson, isTrustedBridgeRequest, NS } from './http-bridge.js';
 import { CONFIG_EXPORT_PATH, CONFIG_IMPORT_PATH, IMPORT_PATH } from './ops-paths.js';
 import { keyTail } from './pool.js';
@@ -172,7 +179,7 @@ export function registerConfigIoRoutes(ctx, deps) {
         const encryptedPayload = encryptConfig(JSON.stringify(exportData), passphrase);
         json(res, 200, {
           ok: true,
-          version: '0.8.67',
+          version: PLUGIN_VERSION,
           exportedAt: new Date().toISOString(),
           masked,
           encrypted: true,
@@ -183,7 +190,7 @@ export function registerConfigIoRoutes(ctx, deps) {
 
       json(res, 200, {
         ok: true,
-        version: '0.8.67',
+        version: PLUGIN_VERSION,
         exportedAt: new Date().toISOString(),
         masked,
         encrypted: false,

package/lib/pool-builder.js

@@ -248,6 +248,7 @@ export function cleanupRemovedProviders({
   moduleBreaker,
   lowHealthNotifiedAt,
   budgetNotifiedAt,
+  cloneLifecycle,
 }) {
   const live = Array.isArray(pools) ? pools : [...(pools?.values?.() ?? (poolByRef?.values?.() ? [...poolByRef.values()] : []))];
   const liveBases = new Set(live.map((p) => p.base));
@@ -281,4 +282,10 @@ export function cleanupRemovedProviders({
       }
     }
   }
+  if (cloneLifecycle && typeof cloneLifecycle.reconcileClones === 'function') {
+    for (const p of cfg.providers ?? []) {
+      const liveClones = new Set([...expectedClones].filter(c => c.startsWith(`${p.provider}-`)));
+      cloneLifecycle.reconcileClones(p.provider, liveClones);
+    }
+  }
 }

package/lib/pool-selection.js

@@ -0,0 +1,149 @@
+// lib/pool-selection.js — pool selection, sticky sessions, attempt sorting and budget metrics (#512).
+// Extracted from lib/pool.js to enforce < 600 line modularity standard.
+
+export const MAX_SESSION_STICKY_ENTRIES = 500;
+
+export function setSessionSticky(pool, sessionId, candidate) {
+  if (!sessionId || !candidate || !pool?.state) return;
+  if (!(pool.state.sessionSticky instanceof Map)) {
+    pool.state.sessionSticky = new Map();
+  }
+  if (pool.state.sessionSticky.has(sessionId)) {
+    pool.state.sessionSticky.delete(sessionId);
+  } else if (pool.state.sessionSticky.size >= MAX_SESSION_STICKY_ENTRIES) {
+    const oldest = pool.state.sessionSticky.keys().next().value;
+    if (oldest !== undefined) pool.state.sessionSticky.delete(oldest);
+  }
+  pool.state.sessionSticky.set(sessionId, candidate);
+}
+
+export function getSessionSticky(pool, sessionId) {
+  if (!sessionId || !pool?.state?.sessionSticky) return null;
+  return pool.state.sessionSticky.get(sessionId) ?? null;
+}
+
+export function clearSessionSticky(pool, sessionId) {
+  if (!sessionId || !pool?.state?.sessionSticky) return;
+  pool.state.sessionSticky.delete(sessionId);
+}
+
+/** Pick a key pool for a (provider, model) pair. */
+export function selectPool(modelPoolByProvider, providerToPool, provider, model) {
+  const byModel = modelPoolByProvider && modelPoolByProvider.get(provider);
+  const base = providerToPool && providerToPool.get(provider);
+  if (!byModel || !model) return base ?? null;
+  if (byModel.has(model)) return byModel.get(model);
+  let best = null;
+  for (const key of byModel.keys()) {
+    if (model.startsWith(key) && key.length > (best ? best.length : 0)) best = key;
+  }
+  return (best ? byModel.get(best) : base) ?? null;
+}
+
+/**
+ * Sort candidate refs according to pool routing strategy.
+ * Returns a new array; does not mutate input.
+ */
+export function sortAttemptList(refs, strategy = 'round-robin', deps = {}) {
+  if (!Array.isArray(refs) || refs.length <= 1) return (refs ?? []).slice();
+  const list = refs.slice();
+  if (strategy === 'sticky') {
+    const last = deps.sessionSticky ||
+      (deps.sessionId && (deps.pool?.state?.sessionSticky?.get?.(deps.sessionId) || deps.sessionStickyMap?.get?.(deps.sessionId))) ||
+      deps.lastUsed ||
+      (deps.pool && deps.pool.state && deps.pool.state.lastUsed);
+    if (last && list.includes(last)) {
+      const idx = list.indexOf(last);
+      if (idx > 0) {
+        list.splice(idx, 1);
+        list.unshift(last);
+      }
+    }
+    return list;
+  }
+  if (strategy === 'tier-priority') {
+    const tiers = deps.tiers || (deps.pool && deps.pool.tiers) || {};
+    return list.sort((a, b) => {
+      const ta = (tiers[a] && Number(tiers[a]) >= 1) ? Number(tiers[a]) : 1;
+      const tb = (tiers[b] && Number(tiers[b]) >= 1) ? Number(tiers[b]) : 1;
+      return ta - tb;
+    });
+  }
+  if (strategy === 'least-loaded' && deps.concurrencyTracker && typeof deps.concurrencyTracker.getActive === 'function') {
+    const weights = deps.weights || (deps.pool && deps.pool.weightsMap) || {};
+    return list.sort((a, b) => {
+      const ca = deps.concurrencyTracker.getActive(a) ?? 0;
+      const cb = deps.concurrencyTracker.getActive(b) ?? 0;
+      const wa = (weights[a] && Number(weights[a]) > 0) ? Number(weights[a]) : 1;
+      const wb = (weights[b] && Number(weights[b]) > 0) ? Number(weights[b]) : 1;
+      const scoreA = ca / wa;
+      const scoreB = cb / wb;
+      if (scoreA !== scoreB) return scoreA - scoreB;
+      return ca - cb;
+    });
+  }
+  if (strategy === 'lowest-latency' && deps.latencyHistogram && typeof deps.latencyHistogram.snapshot === 'function') {
+    return list.sort((a, b) => {
+      const sa = deps.latencyHistogram.snapshot(a);
+      const sb = deps.latencyHistogram.snapshot(b);
+      const la = (sa && Number.isFinite(sa.p95)) ? sa.p95 : ((sa && Number.isFinite(sa.avg)) ? sa.avg : 500);
+      const lb = (sb && Number.isFinite(sb.p95)) ? sb.p95 : ((sb && Number.isFinite(sb.avg)) ? sb.avg : 500);
+      return la - lb;
+    });
+  }
+  return list;
+}
+
+/**
+ * Keys of pool whose expiresAt falls within the next warnDays.
+ * Returns [{ ref, expiresInDays, expiresAt }], soonest first.
+ */
+export function expiringSoon(pool, warnDays = 7, now = Date.now()) {
+  if (!pool || !pool.expiresAt) return [];
+  const DAY_MS = 86400000;
+  const horizon = now + Math.max(1, warnDays) * DAY_MS;
+  return Object.entries(pool.expiresAt)
+    .filter(([, at]) => at > now && at <= horizon)
+    .map(([ref, at]) => ({ ref, expiresAt: at, expiresInDays: Math.max(0, Math.floor((at - now) / DAY_MS)) }))
+    .sort((a, b) => a.expiresAt - b.expiresAt);
+}
+
+/** Dedupe: true when a day-level notification for key is due. */
+export function shouldNotifyDaily(lastNotified, key, now = Date.now()) {
+  const DAY_MS = 86400000;
+  if (!lastNotified.has(key)) {
+    lastNotified.set(key, now);
+    return true;
+  }
+  const last = lastNotified.get(key);
+  if (now - last < DAY_MS) return false;
+  lastNotified.set(key, now);
+  return true;
+}
+
+/** Total spend of a pool on ISO day day (defaults to today) across costDays Map<ref, Map<day, cost>>. */
+export function costForDay(costDays, day) {
+  const d = day ?? new Date().toISOString().slice(0, 10);
+  let total = 0;
+  for (const perRef of (costDays?.values() ?? [])) {
+    total += perRef.get(d) ?? 0;
+  }
+  return total;
+}
+
+/** Total spend over the last 7 ISO days ending today. */
+export function costForWeek(costDays, now = Date.now()) {
+  let total = 0;
+  for (let i = 0; i < 7; i++) {
+    const d = new Date(now - i * 86400000).toISOString().slice(0, 10);
+    total += costForDay(costDays, d);
+  }
+  return total;
+}
+
+/** Budget verdict for a pool: { spend, budget, ratio, warn, exceeded }. */
+export function budgetVerdict(spend, budget) {
+  if (!budget || budget <= 0) return { spend, budget: 0, ratio: 0, warn: false, exceeded: false };
+  const ratio = spend / budget;
+  return { spend, budget, ratio, warn: ratio >= 0.8, exceeded: ratio >= 1 };
+}