@goodandready/dsh-key-rotation 0.8.57 → 0.8.58

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## 0.8.58 - 2026-10-13
+
+### Fixed
+- **Early-Warning Notification Dispatch (#477)**:
+  - Connected `notifyEarlyWarning` during key penalization in `lib/rotate.js` when healthy pool capacity drops to or below `earlyWarningKeyThreshold`.
+  - Added export `notifyEarlyWarning` in `lib/index.js` and wired dependency through `createRotate`.
+- **Proactive Health Probing Logging (#478)**:
+  - Replaced empty catch block in `lib/lifecycle.js` `setupProactiveHealthProbeEffect` with structured debug logging (`logger?.debug`), eliminating silent swallowed exceptions.
+- **Key Drain Lifecycle Teardown (#479)**:
+  - Registered `setupKeyDrainEffect` in `lib/lifecycle.js` to ensure module-level `drainingKeys` map is wiped cleanly on plugin teardown/dispose via `clearAllDraining()`.
+- **Quota Reset Window Schema Validation (#480)**:
+  - Connected `QUOTA_WINDOW_TYPES` into `SettingsSchema` via `Schema.union(QUOTA_WINDOW_TYPES).default('midnight_utc')`.
+  - Connected `isBlockedUntilReset` in `lib/ops-status.js` to accurately expose calendar-based reset lock status.
+
 ## 0.8.57 - 2026-10-12
 
 ### Added

package/lib/index.js

@@ -31,7 +31,8 @@ import { NotifyQueue } from './notify-queue.js';
 import { classifyFailure } from './error-taxonomy.js';
 import { registerOpsRoutes } from './routes-ops.js';
 import { registerPluginUpdater } from './plugin-updater.js';
-import { notifySwitch, notifyExhaustion, pushEvent } from './notify-events.js';
+import { notifySwitch, notifyExhaustion, notifyEarlyWarning, pushEvent } from './notify-events.js';
+import { QUOTA_WINDOW_TYPES } from './quota-window.js';
 import { getLogger } from './logger.js';
 import { createSandboxService } from './sandbox-service.js';
 import { checkBudgetAndHealthAlerts } from './budget-monitor.js';
@@ -44,12 +45,12 @@ import {
   formatModelQuotaExhaustion,
 } from './model-quota.js';
 import { LOCAL_QUOTA_CODE } from './rotate.js';
-import { setupIdleHealEffect, setupAutoUnbreakEffect, setupPersistence, setupProactiveHealthProbeEffect } from './lifecycle.js';
+import { setupIdleHealEffect, setupAutoUnbreakEffect, setupPersistence, setupProactiveHealthProbeEffect, setupKeyDrainEffect } from './lifecycle.js';
 
 export const name = '@goodandready/dsh-key-rotation';
 export const inject = ['llm', 'webServer', 'settings', 'credentials'];
 export { keyTail, KEY_TAIL_CHARS, KEY_TAIL_PLACEHOLDER, isLoopbackAddress, isTrustedBridgeRequest, DEFAULT_SWITCH_CODES, isSwitchableError, formatExhaustionMessage, getRuntime };
-export { notifySwitch, notifyExhaustion };
+export { notifySwitch, notifyExhaustion, notifyEarlyWarning };
 
 const NS = 'dsh-key-rotation';
 
@@ -88,7 +89,7 @@ const SettingsSchema = Schema.object({
     model: Schema.string(),
   })).default([]),
   quotaResetWindow: Schema.object({
-    type: Schema.string().default('midnight_utc'),
+    type: Schema.union(QUOTA_WINDOW_TYPES).default('midnight_utc'),
     hour: Schema.number().default(0),
   }),
   rateLimitThreshold: Schema.number().default(0.1),
@@ -206,6 +207,7 @@ export function apply(ctx, config = {}) {
 
   setupIdleHealEffect(ctx, getConfig, buildRuntime);
   setupProactiveHealthProbeEffect(ctx, getConfig, buildRuntime, ensureSandboxRunner, logger);
+  setupKeyDrainEffect(ctx);
 
   const poolState = new Map();
   const { schedulePersist, persistenceSnapshot } = setupPersistence(ctx, {
@@ -421,6 +423,7 @@ export function apply(ctx, config = {}) {
     pushEvent,
     notifySwitch: (runtime, pool, info) => notifySwitch(runtime, pool, info, { webhookSender, notifyQueue: moduleNotifyQueue, now: () => Date.now() }),
     notifyExhaustion: (runtime, pool, options) => notifyExhaustion(runtime, pool, options, { webhookSender, notifyQueue: moduleNotifyQueue, now: () => Date.now() }),
+    notifyEarlyWarning: (runtime, pool, info) => notifyEarlyWarning(runtime, pool, info, { webhookSender, notifyQueue: moduleNotifyQueue, now: () => Date.now() }),
     recordLatency,
     latencyHistogram,
     concurrencyTracker,

package/lib/lifecycle.js

@@ -4,6 +4,7 @@ import { decryptSecret } from './crypto-storage.js';
 import { StatePersistence, resolveStatePath } from './persistence.js';
 import path from 'node:path';
 import { envValue } from './pool.js';
+import { clearAllDraining } from './key-drain.js';
 
 export function setupIdleHealEffect(ctx, getConfig, buildRuntime, timers = globalThis) {
   return ctx.effect(() => {
@@ -209,7 +210,9 @@ export function setupProactiveHealthProbeEffect(ctx, getConfig, buildRuntime, en
                 }
                 logger?.warn?.(`[dsh-key-rotation] proactive-probe: restored key ${ref} in pool ${pool.base}`);
               }
-            } catch (_) {}
+            } catch (err) {
+              logger?.debug?.(`[dsh-key-rotation] proactive-probe failed for ${ref}: ${err?.message || err}`);
+            }
           }
         }
       } catch (e) {
@@ -244,3 +247,11 @@ export function setupProactiveHealthProbeEffect(ctx, getConfig, buildRuntime, en
     };
   }, 'dsh-key-rotation: proactive health probing');
 }
+
+export function setupKeyDrainEffect(ctx) {
+  return ctx.effect(() => {
+    return () => {
+      clearAllDraining();
+    };
+  }, 'dsh-key-rotation: clear draining keys on teardown');
+}

package/lib/ops-status.js

@@ -15,6 +15,7 @@ import {
   isLoopbackAddress,
 } from './pool.js';
 import { bucketInfo, tpmInfo } from './bucket.js';
+import { isBlockedUntilReset } from './quota-window.js';
 import { sanitizeSnapshot } from './sanitize-snapshot.js';
 import {
   STATUS_PATH,
@@ -92,6 +93,7 @@ ctx.effect(() => ctx.webServer.register({
           /* describe is optional — the card falls back to editable */
         }
         const until = pool.state.failedUntil?.get(ref);
+        const quotaWin = pool.state.quotaWindows?.get(ref);
         const modelQuota = getModelQuotaStatus(pool, ref, now);
         const activeModelPools = runtime?.index ? modelPoolsForRef(runtime.index, ref) : [];
         keys.push({
@@ -102,6 +104,7 @@ ctx.effect(() => ctx.webServer.register({
           writable,
           active: pool.state.lastUsed === ref,
           cooldownMsLeft: until !== undefined && until > now ? until - now : 0,
+          blockedUntilReset: isBlockedUntilReset(until, quotaWin, now),
           // #210: RPM capacity snapshot (null when rpmLimit is off)
           rpm: bucketInfo(pool.state.rpmWindows, ref, pool.rpmLimit, now),
           // TPM capacity snapshot (null when tpmLimit is off)

package/lib/rotate.js

@@ -19,6 +19,7 @@ import { pickCascadeFallback, CASCADE_MAX_DEPTH } from './cascade.js';
 import { createRequestBudget, BUDGET_EXHAUSTED_TIMEOUT, BUDGET_EXHAUSTED_ATTEMPTS } from './request-budget.js';
 import { createSelectionTrace } from './selection-trace.js';
 import { isKeyDraining } from './key-drain.js';
+import { notifyEarlyWarning as defaultNotifyEarlyWarning } from './notify-events.js';
 import { nextQuotaReset, poolResetAt } from './quota-window.js';
 import { tpmRecord } from './bucket.js';
 import {
@@ -64,6 +65,7 @@ export function createRotate(deps) {
     pushEvent,
     notifySwitch,
     notifyExhaustion,
+    notifyEarlyWarning,
     recordLatency,
     latencyHistogram,
     concurrencyTracker,
@@ -77,6 +79,7 @@ export function createRotate(deps) {
     now = nowMono,
   } = deps;
 
+  const effectiveNotifyEarlyWarning = notifyEarlyWarning ?? defaultNotifyEarlyWarning;
   const logWarn = (msg) => (logger?.warn ? logger.warn(msg) : null);
 
   function rotate(options, pool) {
@@ -204,6 +207,24 @@ export function createRotate(deps) {
         if (typeof schedulePersist === 'function') {
           try { schedulePersist(); } catch (_) { /* best-effort persistence */ }
         }
+        if (runtime0.earlyWarningNotify && effectiveNotifyEarlyWarning) {
+          const total = pool.refs?.length || 1;
+          let available = 0;
+          const at = now();
+          for (const r of (pool.refs || [])) {
+            if (!isKeyRevoked(pool, r) && !isKeyPaused(pool, r) && !isKeyBroken(pool, r, at) && ((pool.state?.failedUntil?.get(r) ?? 0) <= at)) {
+              available++;
+            }
+          }
+          const threshold = Number.isFinite(runtime0.earlyWarningKeyThreshold) ? runtime0.earlyWarningKeyThreshold : 0.25;
+          if (total > 0 && (available / total) <= threshold) {
+            effectiveNotifyEarlyWarning(runtime0, pool, {
+              provider: options.provider,
+              availableCount: available,
+              totalCount: total,
+            });
+          }
+        }
         if (!pool.state.authFailCounts) pool.state.authFailCounts = new Map();
         if (!pool.state.brokenUntil) pool.state.brokenUntil = new Map();
         const _cStr = String(errCode ?? '');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@goodandready/dsh-key-rotation",
-  "version": "0.8.57",
+  "version": "0.8.58",
   "packageManager": "pnpm@10.33.2",
   "description": "Per-provider API key rotation for DeepSeek Harness: a key pool per provider, auto-created clone routes, and switching to the next key on quota/rate-limit errors. Includes a Settings section (Key Rotation) to edit the key pools, cooldown and switch codes.",
   "keywords": [