@goodandready/dsh-key-rotation 0.8.17 → 0.8.18

package/CHANGELOG.md

@@ -3,6 +3,16 @@
 All notable changes to `@goodandready/dsh-key-rotation` are documented here.
 User-facing feature notes also appear in README (en is source of truth).
 
+## 0.8.18 - 2026-09-21
+
+### Fixed
+- **Stream success failCount reset (#336)**: `rotate()` now invokes `recordSuccess(pool, activeRef, now())` upon successful stream completion and clean EOF, clearing accumulated `failCounts`, removing stale `failedUntil`, and updating `lastSuccessAt`.
+- **Calendar-based quota reset connection (#337)**: connected `quota-window.js` (`nextQuotaReset`) to `penalizeRef` in `lib/rotate.js` when `QUOTA` / `RESOURCE_EXHAUSTED` / quota errors occur and `quotaResetWindow` is configured. Ensures exhausted keys remain penalized until calendar reset window instead of rapidly failing over back into penalty. Enhanced `nextQuotaReset` to safely handle both object and string window configurations.
+- **Penalty decay during maintenance sweeps (#338)**: `sweepExpired` in `lib/pool.js` now invokes `decayPenalties({ state: st }, now)`, allowing keys with historic transient failures that have run stably to gradually recover their base backoff levels. Also cleans up expired `quotaWindows`. Removed redundant duplicate check in `isSwitchableError`.
+- **State persistence during failover (#339)**: `schedulePersist()` is now passed into `createRotate()` and invoked whenever a key failover occurs, ensuring key penalty and switch state is promptly written to disk across restarts.
+- **Dead imports cleanup (#340)**: removed 16 unused named imports from `lib/index.js` (`pickCascadeFallback`, `nextQuotaReset`, `usageRows`, `usageCsv`, `findSecrets`, `readJson`, `writeSection`, etc.) ensuring lean bundle evaluation.
+- **Remote configuration import timeout (#341)**: added 10-second timeout via `AbortSignal.timeout(10000)` to remote `fetch(url)` in `/dsh-key-rotation/import` route (`lib/ops-keys.js`), returning HTTP 504 Gateway Timeout with structured error code `'timeout'` on network stalls.
+
 ## 0.8.17 - 2026-09-21
 
 ### Fixed

package/lib/index.js

@@ -15,22 +15,17 @@ import {
   budgetVerdict, sortAttemptList,
 } from './pool.js';
 import { LatencyHistogram } from './histogram.js';
-import { pickCascadeFallback } from './cascade.js';
 import { ConcurrencyTracker } from './concurrency.js';
-import { nextQuotaReset } from './quota-window.js';
 import { QuotaStore } from './quota.js';
 import { WebhookSender } from './webhook.js';
-import { bucketAllow, bucketRetryMs, bucketSweep, bucketInfo } from './bucket.js';
-import { usageRows, usageCsv, compactUsage } from './usage-report.js';
-import { findSecrets, looksLikeApiSecret } from './keycheck.js';
-import { json, readJson, descriptorOf, viewOf, writeSection, providerCatalog, handleConfigBridge, NS as BRIDGE_NS } from './http-bridge.js';
+import { bucketAllow, bucketRetryMs } from './bucket.js';
+import { compactUsage } from './usage-report.js';
+import { json, handleConfigBridge } from './http-bridge.js';
 import { createRotate } from './rotate.js';
 import { nowMono } from './clock.js';
 import { CircuitBreaker } from './circuit-breaker.js';
 import { NotifyQueue } from './notify-queue.js';
-import { BoundedMap } from './bounded-map.js';
 import { classifyFailure } from './error-taxonomy.js';
-import { safeParseJson } from './atomic-io.js';
 import { registerOpsRoutes } from './routes-ops.js';
 import { registerPluginUpdater } from './plugin-updater.js';
 import { notifySwitch, notifyExhaustion, pushEvent } from './notify-events.js';
@@ -472,6 +467,7 @@ export function apply(ctx, config = {}) {
     ctx,
     dispatchStorage,
     buildRuntime,
+    schedulePersist,
     pushEvent,
     notifySwitch: (runtime, pool, info) => notifySwitch(runtime, pool, info, { webhookSender, notifyQueue: moduleNotifyQueue, now: () => Date.now() }),
     notifyExhaustion,

package/lib/ops-keys.js

@@ -167,7 +167,7 @@ ctx.effect(() => ctx.webServer.register({
     const url = typeof body?.url === 'string' ? body.url.trim() : '';
     if (!url || !url.startsWith('https://')) { json(res, 400, { error: { code: 'bad-url', message: 'dsh-key-rotation: only HTTPS URLs are allowed' } }); return; }
     try {
-      const resp = await fetch(url);
+      const resp = await fetch(url, { signal: AbortSignal.timeout(10000) });
       if (!resp.ok) { json(res, 400, { error: { code: 'fetch-failed', message: 'dsh-key-rotation: fetch returned ' + resp.status } }); return; }
       const data = await resp.json();
       if (!Array.isArray(data)) { json(res, 400, { error: { code: 'bad-format', message: 'dsh-key-rotation: expected JSON array of providers' } }); return; }
@@ -181,7 +181,10 @@ ctx.effect(() => ctx.webServer.register({
       const mergedArr = [...merged.values()];
       await settings.replace(NS, { ...(desc?.value ?? {}), providers: mergedArr }, desc?.revision);
       json(res, 200, { ok: true, providersImported: data.length, total: mergedArr.length });
-    } catch (e) { json(res, 400, { error: { code: 'import-failed', message: String(e?.message ?? e) } }); }
+    } catch (e) {
+      const isTimeout = e?.name === 'TimeoutError' || e?.name === 'AbortError';
+      json(res, isTimeout ? 504 : 400, { error: { code: isTimeout ? 'timeout' : 'import-failed', message: String(e?.message ?? e) } });
+    }
   },
 }), 'dsh-key-rotation: import route');
 

package/lib/pool.js

@@ -185,10 +185,13 @@ export function sweepExpired(poolState, now = Date.now(), activeRefs = null) {
   let cleared = 0;
   const activeSet = activeRefs ? new Set(activeRefs) : null;
   for (const st of poolState.values()) {
+    // #338: decay penalty failCounts for stable keys in maintenance sweep
+    decayPenalties({ state: st }, now);
     for (const [ref, until] of [...st.failedUntil.entries()]) {
       if (until <= now) {
         st.failedUntil.delete(ref);
         st.failCounts?.delete(ref);
+        st.quotaWindows?.delete(ref);
         cleared++;
       }
     }
@@ -372,7 +375,6 @@ export function isSwitchableError(failureOrPayload, switchCodes = new Set(DEFAUL
 
   // 1. Direct HTTP status codes (#267: also 408/425 transient)
   if ((status === 429 || status === 408 || status === 425) && (switchCodes.has('RATE_LIMIT') || switchCodes.has('QUOTA') || switchCodes.has('429') || switchCodes.has('TIMEOUT') || switchCodes.has(String(status)))) return true;
-  if (status === 429 && (switchCodes.has('RATE_LIMIT') || switchCodes.has('QUOTA') || switchCodes.has('429'))) return true;
   if ((status === 401 || status === 403) && (switchCodes.has('AUTH') || switchCodes.has('401'))) return true;
   if ((status >= 500 && status <= 504) && (switchCodes.has('SERVER') || switchCodes.has(String(status)))) return true;
 

package/lib/quota-window.js

@@ -4,9 +4,10 @@ export const QUOTA_WINDOW_TYPES = ['midnight_utc', 'midnight_pst', 'rolling_24h'
 
 export function nextQuotaReset(quotaResetWindow, now) {
   now = now || Date.now();
-  if (!quotaResetWindow || typeof quotaResetWindow !== 'object') return null;
-  const type = quotaResetWindow.type;
-  const hour = Number.isFinite(quotaResetWindow.hour) ? quotaResetWindow.hour : 0;
+  const win = typeof quotaResetWindow === 'string' ? { type: quotaResetWindow === 'daily' ? 'midnight_utc' : quotaResetWindow } : quotaResetWindow;
+  if (!win || typeof win !== 'object') return null;
+  const type = win.type === 'daily' ? 'midnight_utc' : win.type;
+  const hour = Number.isFinite(win.hour) ? win.hour : 0;
 
   if (type === 'rolling_24h') {
     const d = new Date(now);

package/lib/rotate.js

@@ -5,6 +5,7 @@ import { classifyFailure } from './error-taxonomy.js';
 import {
   isSwitchableError,
   recordFailure,
+  recordSuccess,
   parseRetryAfter,
   extractRateLimit,
   isRateLimited,
@@ -12,6 +13,7 @@ import {
   sortAttemptList,
 } from './pool.js';
 import { pickCascadeFallback } from './cascade.js';
+import { nextQuotaReset } from './quota-window.js';
 
 /**
  * Create the rotate(options, pool) async generator used by llm/stream.
@@ -34,6 +36,7 @@ export function createRotate(deps) {
     quotaStore,
     circuitBreaker,
     logger,
+    schedulePersist,
     now = nowMono,
   } = deps;
 
@@ -77,8 +80,24 @@ export function createRotate(deps) {
         const _effBase = _retry !== undefined ? Math.max(_base, Math.min(_retry, _max ?? _base * 8)) : _base;
         const cls = classifyFailure({ code: errCode, message: errMsg });
         const _b = recordFailure(pool, targetRef, now(), _effBase, _max, cls.soft, true);
+
+        // #337: connect quota-window calendar reset for quota exhaustion
+        const isQuota = errCode === 'QUOTA' || cls.code === 'QUOTA' || /quota|exceeded/i.test(errMsg);
+        const qWindow = pool.quotaResetWindow ?? runtime0.quotaResetWindow;
+        if (isQuota && qWindow) {
+          const quotaResetAt = nextQuotaReset(qWindow, now());
+          if (quotaResetAt && quotaResetAt > now()) {
+            if (!pool.state.quotaWindows) pool.state.quotaWindows = new Map();
+            pool.state.quotaWindows.set(targetRef, quotaResetAt);
+            pool.state.failedUntil.set(targetRef, quotaResetAt);
+          }
+        }
+
         if (circuitBreaker) circuitBreaker.onFailure(pool.base ?? options?.provider);
         pushEvent(pool, targetRef, errCode ?? 'UNKNOWN', _b);
+        if (typeof schedulePersist === 'function') {
+          try { schedulePersist(); } catch (_) { /* best-effort persistence */ }
+        }
         if (!pool.state.authFailCounts) pool.state.authFailCounts = new Map();
         if (!pool.state.brokenUntil) pool.state.brokenUntil = new Map();
         const _cStr = String(errCode ?? '');
@@ -190,6 +209,11 @@ export function createRotate(deps) {
                   if (!byRef) { byRef = new Map(); pool.state.byModel.set(activeRef, byRef); }
                   byRef.set(options.model, (byRef.get(options.model) ?? 0) + 1);
                 }
+                // #336: record success for the active key upon successful stream finish
+                if (activeRef) {
+                  recordSuccess(pool, activeRef, now());
+                }
+
                 // Proactive rate-limit (#115, #303): if response headers say this key is near
                 // its quota or has retry-after, cool it down so the NEXT request starts on a different key.
                 // We do NOT re-run this (already successful) request — that would double-send.
@@ -248,6 +272,9 @@ export function createRotate(deps) {
           }
 
           if (switching) continue; // try the next key
+          if (_pickedRef && yielded) {
+            recordSuccess(pool, _pickedRef, now());
+          }
           return; // clean end — served
         } finally {
           if (acquired && _pickedRef) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@goodandready/dsh-key-rotation",
-  "version": "0.8.17",
+  "version": "0.8.18",
   "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": [