@goodandready/dsh-key-rotation 0.8.37 → 0.8.38

package/CHANGELOG.md

@@ -1,12 +1,24 @@
 # Changelog
 
+## 0.8.38 - 2026-09-30
+
+### Added
+- **Sliding-Window TPM (Tokens Per Minute) Rate Limiting (#402, GH #20)**:
+  - Added 60-second sliding-window TPM rate-limiting alongside existing RPM (`tpmAllow`, `tpmRecord`, `tpmRetryMs`, `tpmSweep`, `tpmInfo` in `lib/bucket.js`).
+  - Added `tpmLimit` configuration at global, provider, and per-model scopes in `lib/index.js` and `lib/pool-builder.js`.
+  - Automatically records consumed tokens on streaming and non-streaming responses in `lib/rotate.js`.
+  - Enforced fail-over and cooldown in `lib/resolver.js` when candidate key exceeds its configured TPM budget.
+  - Exposed live TPM telemetry (`used`, `remaining`, `limit`, `resetMs`) in `GET /dsh-key-rotation/status` with sanitization in `lib/sanitize-snapshot.js`.
+  - Added visual UI badge and editable TPM limit input in `lib/client-src/50-card-main.js` with localization (`en`, `zh`).
+  - Added automated test suite `test/tpm-rate-limit.test.mjs` verifying bucket math, sweep cleanup, resolver fail-over, and snapshot sanitization.
+
 ## 0.8.37
 
 ### Fixed
 - **Peer gate on DSH 0.2.0-rc.1** (#58): the bundle was skipped at profile startup because its `peerDependencies` excluded the running version.
 - **Settings card served no form**: `NS` was the package name rather than the profile entry id, `Config` declared no `.volatile()` field, and `getConfig` handed out `Volatile` boxes. Both 0.1.7-rc.2 and 0.2.0 now serve and read the form.
 - **A saved setting never took effect**: the host applied changes through `settings.register` and `scope.watch`, neither of which exists in either release. Changes are applied on `loader/volatile-update` now.
-- **`settings.plugin.item` registration removed**: retired before DSH 0.1.7-rc.2, so it only registered the card a second time on a seat that no longer exists.
+- **`settings.plugin.item` registration removed**: retired before DSH 0.1.7-rc.2, it only registered the card a second time on a seat that no longer exists.
 
 ## 0.8.36
 

package/lib/bucket.js

@@ -41,3 +41,64 @@ export function bucketInfo(windows, ref, limit, now = Date.now()) {
   };
 }
 
+
+/** Sliding-window check: true if `ref` is under `limit` tokens/min. */
+export function tpmAllow(windows, ref, limit, now = Date.now()) {
+  if (!limit || limit <= 0) return true;
+  const cut = now - WINDOW_MS;
+  const entries = (windows?.get(ref) ?? []).filter((e) => e.time > cut);
+  let total = 0;
+  for (const e of entries) total += e.tokens;
+  return total < limit;
+}
+
+/** Record actual consumed tokens for `ref` in sliding 60s window. */
+export function tpmRecord(windows, ref, tokens, now = Date.now()) {
+  if (!tokens || tokens <= 0 || !windows) return;
+  const cut = now - WINDOW_MS;
+  const validTokens = Math.max(1, Math.floor(tokens));
+  const entries = (windows.get(ref) ?? []).filter((e) => e.time > cut);
+  entries.push({ time: now, tokens: validTokens });
+  windows.set(ref, entries);
+}
+
+/** ms until `ref` may retry again under TPM limit (0 = now). */
+export function tpmRetryMs(windows, ref, limit, now = Date.now()) {
+  if (!limit || limit <= 0) return 0;
+  const cut = now - WINDOW_MS;
+  const entries = (windows?.get(ref) ?? []).filter((e) => e.time > cut);
+  let total = 0;
+  for (const e of entries) total += e.tokens;
+  if (total < limit) return 0;
+  let rem = total;
+  for (const e of entries) {
+    rem -= e.tokens;
+    if (rem < limit) {
+      return Math.max(0, e.time + WINDOW_MS - now);
+    }
+  }
+  return WINDOW_MS;
+}
+
+/** Drop TPM state for refs that no longer exist. */
+export function tpmSweep(windows, liveRefs) {
+  if (!windows) return;
+  for (const ref of [...windows.keys()]) {
+    if (!liveRefs.has(ref)) windows.delete(ref);
+  }
+}
+
+/** Snapshot for /status - used/remaining/limit/resetMs for one ref. */
+export function tpmInfo(windows, ref, limit, now = Date.now()) {
+  if (!limit || limit <= 0) return null;
+  const cut = now - WINDOW_MS;
+  const entries = (windows?.get(ref) ?? []).filter((e) => e.time > cut);
+  let used = 0;
+  for (const e of entries) used += e.tokens;
+  return {
+    used,
+    remaining: Math.max(0, limit - used),
+    limit,
+    resetMs: used >= limit ? tpmRetryMs(windows, ref, limit, now) : 0,
+  };
+}

package/lib/client.js

@@ -117,6 +117,9 @@ window.__ModuleLoader__.load({
       keyWriteFailed: 'could not store the key: {msg}',
       notSecretShape: 'saved, but the value does not look like an API key - check for a typo',
       rpmTitle: 'requests/min: {u} used, {r} remaining',
+      tpmTitle: 'tokens/min: {u} used, {r} remaining',
+      rpmLimitLabel: 'Rate Limit (RPM)',
+      tpmLimitLabel: 'Rate Limit (TPM)',
       budgetLabel: 'budget:',
       exportCsv: 'Export CSV',
       weightHint: 'round-robin weight: how many times this key joins the cycle (1 = equal share)',
@@ -299,6 +302,9 @@ window.__ModuleLoader__.load({
       keyWriteFailed: '无法存储密钥: {msg}',
       notSecretShape: '已保存，但该值看起来不像 API 密钥 - 请检查是否有拼写错误',
       rpmTitle: '请求/分钟: 已用 {u}, 剩余 {r}',
+      tpmTitle: 'Token/分钟: 已用 {u}, 剩余 {r}',
+      rpmLimitLabel: '速率限制 (RPM)',
+      tpmLimitLabel: '速率限制 (TPM)',
       budgetLabel: '预算:',
       exportCsv: '导出 CSV',
       weightHint: '轮换权重：该密钥参与循环的次数 (1 = 等分)',
@@ -1918,6 +1924,11 @@ window.__ModuleLoader__.load({
             title: t('rpmTitle').replace('{u}', String(info.rpm.used)).replace('{r}', String(info.rpm.remaining)),
             style: info.rpm.remaining === 0 ? { color: 'var(--dsw-alias-state-error-primary)', fontWeight: 700 } : undefined },
             '⏱' + info.rpm.remaining));
+          // TPM capacity indicator (only when tpmLimit is active)
+          if (info && info.tpm) meta.push(h('span', { key: 'tpm', className: 'krot-tail',
+            title: t('tpmTitle').replace('{u}', String(info.tpm.used)).replace('{r}', String(info.tpm.remaining)),
+            style: info.tpm.remaining === 0 ? { color: 'var(--dsw-alias-state-error-primary)', fontWeight: 700 } : undefined },
+            '⚡' + info.tpm.remaining));
           if (info && typeof info.cost === 'number' && info.cost > 0) meta.push(h('span', { key: 'c', className: 'krot-tail', title: 'cost' }, '$' + info.cost.toFixed(2)));
           const tr = testResult[key];
           if (tr) meta.push(h('span', { key: 'tr', className: 'krot-tail',
@@ -2393,6 +2404,10 @@ window.__ModuleLoader__.load({
           field(t('cooldown'), textInput(String(val.cooldownMs ?? 60000), (v) => setField((cur) => ({ ...cur, cooldownMs: Number(v) || 0 })))),
           field(t('scheduleDays'), textInput(String(val.rotationScheduleDays ?? 0), (v) => setField((cur) => ({ ...cur, rotationScheduleDays: Number(v) || 0 }))))
         ),
+        h('div', { className: 'krot-grid-2', style: { marginTop: '10px' } },
+          field(t('rpmLimitLabel'), textInput(String(val.rpmLimit ?? 0), (v) => setField((cur) => ({ ...cur, rpmLimit: Number(v) || 0 })))),
+          field(t('tpmLimitLabel'), textInput(String(val.tpmLimit ?? 0), (v) => setField((cur) => ({ ...cur, tpmLimit: Number(v) || 0 }))))
+        ),
         h('div', { className: 'krot-grid-3', style: { marginTop: '10px' } },
           field(t('routingStrategyLabel'), h('select', {
             className: 'krot-in',

package/lib/index.js

@@ -52,6 +52,17 @@ export { keyTail, KEY_TAIL_CHARS, KEY_TAIL_PLACEHOLDER, isLoopbackAddress, isTru
 export { notifySwitch, notifyExhaustion };
 
 const NS = 'dsh-key-rotation';
+
+// DSH serves a namespace's settings form from the volatile fields of its profile
+// entry schema, and a volatile field holds a Volatile box rather than its value.
+// Unwrap before any caller reads one, and read lazily: the Loader mutates the
+// boxes in place and re-announces them with loader/volatile-update.
+export function plainConfig(value) {
+  if (value === null || typeof value !== 'object') return value
+  if (Array.isArray(value)) return value.map(plainConfig)
+  if (typeof value.get === 'function') return plainConfig(value.get())
+  return Object.fromEntries(Object.entries(value).map(([k, v]) => [k, plainConfig(v)]))
+}
 const CONFIG_PATH = '/dsh-key-rotation/config';
 const PIAI_NS = 'llm-pi-ai';
 const MARKER = '__dshKeyRotation';
@@ -107,6 +118,7 @@ const SettingsSchema = Schema.object({
   selfHealingIntervalMinutes: Schema.number().default(30),
   routingStrategy: Schema.union(['round-robin', 'least-loaded', 'lowest-latency']).default('round-robin'),
   rpmLimit: Schema.number().default(0),
+  tpmLimit: Schema.number().default(0),
   webhookActionToken: Schema.string().role('secret').default(''),
   expiryWarnDays: Schema.number().default(7),
   switchNotify: Schema.boolean().default(false),
@@ -137,11 +149,15 @@ const SettingsSchema = Schema.object({
       quotas: Schema.dict(Schema.object({
         tokenLimit: Schema.number(),
       })).default({}),
+      rpmLimit: Schema.number(),
+      tpmLimit: Schema.number(),
     })).default({}),
     cooldownMs: Schema.number(),
     maxCooldownMs: Schema.number(),
     routingStrategy: Schema.union(['round-robin', 'least-loaded', 'lowest-latency']),
     proactiveRateLimitGuard: Schema.boolean(),
+    rpmLimit: Schema.number(),
+    tpmLimit: Schema.number(),
   })).default([...DEFAULT_PROVIDERS]),
 });
 
@@ -233,17 +249,20 @@ export function apply(ctx, config = {}) {
   let lastProfilesRef = null;
 
   function buildRuntime() {
-    const cfg = getConfig() ?? {};
+    const rawConfig = getConfig();
+    // Identity check below stays on the raw object: plainConfig allocates a new
+    // object each call, which would defeat the runtime memo cache.
+    const cfg = plainConfig(rawConfig ?? {});
     let profilesSnapshot = null;
     try {
       profilesSnapshot = readProfiles();
     } catch {
       profilesSnapshot = null;
     }
-    if (cachedRuntime && cfg === lastConfigRef && profilesSnapshot === lastProfilesRef) {
+    if (cachedRuntime && rawConfig === lastConfigRef && profilesSnapshot === lastProfilesRef) {
       return cachedRuntime;
     }
-    lastConfigRef = cfg;
+    lastConfigRef = rawConfig;
     lastProfilesRef = profilesSnapshot;
 
     moduleBreaker.configure({
@@ -261,6 +280,7 @@ export function apply(ctx, config = {}) {
     const quotaResetWindow = cfg.quotaResetWindow ?? { type: 'midnight_utc', hour: 0 };
     const rateLimitThreshold = cfg.rateLimitThreshold ?? 0.1;
     const rpmLimit = cfg.rpmLimit ?? 0;
+    const tpmLimit = cfg.tpmLimit ?? 0;
     const webhookActionToken = cfg.webhookActionToken ?? '';
 
     const built = buildPools({ cfg, poolState, defaultState: initializePoolState });
@@ -306,7 +326,7 @@ export function apply(ctx, config = {}) {
 
     cachedRuntime = {
       switchCodes, cooldownMs, maxCooldownMs, notifyWebhook, notifyThreshold,
-      concurrencyLimit, cascade, quotaResetWindow, rateLimitThreshold, rpmLimit,
+      concurrencyLimit, cascade, quotaResetWindow, rateLimitThreshold, rpmLimit, tpmLimit,
       webhookActionToken, expiryWarnDays: cfg.expiryWarnDays ?? 7,
       switchNotify: cfg.switchNotify ?? false, verboseLogging: cfg.verboseLogging ?? false,
       proactiveRateLimitGuard: cfg.proactiveRateLimitGuard ?? true,
@@ -362,7 +382,7 @@ export function apply(ctx, config = {}) {
   let _rotateStartMs = Date.now();
   function recordLatency(pool, reqStore) {
     try {
-      const cfg = getConfig();
+      const cfg = plainConfig(getConfig());
       if (!cfg || cfg.latencyEnabled === false) return;
       const ref = reqStore?.pickedRef ?? pool?.state?.lastUsed;
       if (!ref) return;

package/lib/ops-status.js

@@ -13,7 +13,7 @@ import {
   costForWeek,
   isLoopbackAddress,
 } from './pool.js';
-import { bucketInfo } from './bucket.js';
+import { bucketInfo, tpmInfo } from './bucket.js';
 import { sanitizeSnapshot } from './sanitize-snapshot.js';
 import {
   STATUS_PATH,
@@ -101,6 +101,8 @@ ctx.effect(() => ctx.webServer.register({
           cooldownMsLeft: until !== undefined && until > now ? until - now : 0,
           // #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)
+          tpm: tpmInfo(pool.state.tpmWindows, ref, pool.tpmLimit, now),
           // #215: effective round-robin weight of this key
           weight: pool.weights?.[pool.refs.indexOf(ref)] ?? 1,
           usage: pool.state.usageCounts?.get(ref) ?? 0,

package/lib/pool-builder.js

@@ -1,5 +1,5 @@
 // lib/pool-builder.js — provider & per-model pool assembly and cleanup
-import { bucketSweep } from './bucket.js';
+import { bucketSweep, tpmSweep } from './bucket.js';
 import { isValidRef } from './pool.js';
 import { normalizeModelQuotas } from './model-quota.js';
 import { createPoolIndex, addProviderPools } from './pool-index.js';
@@ -26,6 +26,7 @@ export function buildPoolItem({
   poolStrategy,
   poolGuard,
   rpmLimit,
+  tpmLimit = 0,
   makeState,
   provider = null,
   model = null,
@@ -88,6 +89,7 @@ export function buildPoolItem({
     maxCooldownMs: poolMax,
     expiresAt: parsedExpiry,
     rpmLimit,
+    tpmLimit: typeof tpmLimit === 'number' && Number.isFinite(tpmLimit) && tpmLimit > 0 ? Math.floor(tpmLimit) : 0,
     routingStrategy: poolStrategy,
     proactiveRateLimitGuard: poolGuard,
   };
@@ -95,6 +97,7 @@ export function buildPoolItem({
 
 export function buildPools({ cfg = {}, poolState = new Map(), defaultState = initializePoolState } = {}) {
   const rpmLimit = cfg.rpmLimit ?? 0;
+  const tpmLimit = cfg.tpmLimit ?? 0;
   const quotaResetWindow = cfg.quotaResetWindow ?? null;
   const poolByRef = new Map();
   const providerToPool = new Map();
@@ -111,19 +114,21 @@ export function buildPools({ cfg = {}, poolState = new Map(), defaultState = ini
     return initializePoolState(st);
   };
 
-  const buildPool = (base, keys, weights, paused, revoked, poolCooldown, poolMax, expiresAt, poolStrategy, poolGuard, meta) =>
+  const buildPool = (base, keys, weights, paused, revoked, poolCooldown, poolMax, expiresAt, poolStrategy, poolGuard, meta, pRpm = rpmLimit, pTpm = tpmLimit) =>
     buildPoolItem({
       base, keys, weights, paused, revoked, poolCooldown, poolMax, expiresAt, poolStrategy, poolGuard,
-      rpmLimit, makeState, quotaResetWindow, ...meta,
+      rpmLimit: pRpm, tpmLimit: pTpm, makeState, quotaResetWindow, ...meta,
     });
 
   for (const p of cfg.providers ?? []) {
     const poolCooldown = typeof p.cooldownMs === 'number' ? p.cooldownMs : (cfg.cooldownMs ?? 60000);
     const poolMax = typeof p.maxCooldownMs === 'number' ? p.maxCooldownMs : (cfg.maxCooldownMs ?? undefined);
+    const provRpm = typeof p.rpmLimit === 'number' ? p.rpmLimit : rpmLimit;
+    const provTpm = typeof p.tpmLimit === 'number' ? p.tpmLimit : tpmLimit;
     const pool = buildPool(p.provider, p.keys, p.weights, p.paused, p.revoked, poolCooldown, poolMax, p.expiresAt, p.routingStrategy, p.proactiveRateLimitGuard, {
       provider: p.provider,
       model: null,
-    });
+    }, provRpm, provTpm);
     if (pool) {
       for (const ref of pool.refs) {
         if (!poolByRef.has(ref)) poolByRef.set(ref, pool);
@@ -133,11 +138,13 @@ export function buildPools({ cfg = {}, poolState = new Map(), defaultState = ini
     }
     const byModel = new Map();
     for (const [model, mp] of Object.entries(p.models ?? {})) {
+      const modelRpm = typeof mp.rpmLimit === 'number' ? mp.rpmLimit : provRpm;
+      const modelTpm = typeof mp.tpmLimit === 'number' ? mp.tpmLimit : provTpm;
       const mpool = buildPool(`${p.provider}::${model}`, mp.keys, mp.weights, mp.paused, mp.revoked, poolCooldown, poolMax, undefined, p.routingStrategy, p.proactiveRateLimitGuard, {
         provider: p.provider,
         model,
         quotas: mp.quotas,
-      });
+      }, modelRpm, modelTpm);
       if (!mpool) continue;
       byModel.set(model, mpool);
       for (const ref of mpool.refs) {
@@ -187,6 +194,7 @@ export function cleanupRemovedProviders({
   }
   for (const st of poolState.values()) {
     if (st.rpmWindows) bucketSweep(st.rpmWindows, liveRefs);
+    if (st.tpmWindows) tpmSweep(st.tpmWindows, liveRefs);
     if (st.tokenUsage instanceof Map) {
       for (const ref of [...st.tokenUsage.keys()]) {
         if (!liveRefs.has(ref)) st.tokenUsage.delete(ref);

package/lib/pool-state.js

@@ -3,7 +3,7 @@
 const MAP_FIELDS = [
   'failedUntil', 'failCounts', 'authFailCounts', 'brokenUntil', 'costPerKey',
   'lastUsedAt', 'usageCounts', 'byModel', 'usageDays', 'quotaWindows', 'costDays',
-  'tokenUsage',
+  'tokenUsage', 'rpmWindows', 'tpmWindows',
 ];
 
 export function initializePoolState(state = {}) {

package/lib/resolver.js

@@ -9,7 +9,7 @@
 // credentials service. It never sees or returns a secret value itself; it
 // delegates to `original(ref)`.
 
-import { bucketAllow, bucketRetryMs } from './bucket.js';
+import { bucketAllow, bucketRetryMs, tpmAllow, tpmRetryMs } from './bucket.js';
 import { envValue, sortAttemptList, isKeyPaused, isKeyRevoked } from './pool.js';
 import { decryptSecret } from './crypto-storage.js';
 import { resolveRefPool, isQuotaManagedRequest } from './pool-index.js';
@@ -95,6 +95,17 @@ export function createResolver({
           continue;
         }
       }
+      const tpmLimit = pool.tpmLimit ?? 0;
+      if (tpmLimit > 0) {
+        if (!pool.state.tpmWindows) pool.state.tpmWindows = new Map();
+        if (!tpmAllow(pool.state.tpmWindows, candidate, tpmLimit, at)) {
+          const waitMs = tpmRetryMs(pool.state.tpmWindows, candidate, tpmLimit, at);
+          if ((pool.state.failedUntil.get(candidate) ?? 0) < at + waitMs) {
+            pool.state.failedUntil.set(candidate, at + waitMs);
+          }
+          continue;
+        }
+      }
       if (pool.perHour) {
         if (!pool.state.quotaWindows) pool.state.quotaWindows = new Map();
         let win = pool.state.quotaWindows.get(candidate);

package/lib/rotate.js

@@ -16,6 +16,7 @@ import {
 } from './pool.js';
 import { pickCascadeFallback, CASCADE_MAX_DEPTH } from './cascade.js';
 import { nextQuotaReset } from './quota-window.js';
+import { tpmRecord } from './bucket.js';
 import {
   isModelQuotaAvailable,
   hasModelQuotaConfig,
@@ -302,9 +303,16 @@ export function createRotate(deps) {
                   if (activeRef) {
                     recordSuccess(pool, activeRef, now());
                   }
+                  if (activeRef) {
+                    const usedTokens = extractUsageTokens(chunk?.usage ?? chunk?.metadata?.usage);
+                    if (usedTokens && usedTokens > 0) {
+                      if (!pool.state.tpmWindows) pool.state.tpmWindows = new Map();
+                      tpmRecord(pool.state.tpmWindows, activeRef, usedTokens, Date.now());
+                    }
+                  }
                   if (activeRef && quotaManaged) {
                     const charged = consumeModelTokens(
-                      pool, activeRef, extractUsageTokens(chunk.usage),
+                      pool, activeRef, extractUsageTokens(chunk?.usage ?? chunk?.metadata?.usage),
                       runtime0.quotaResetWindow, Date.now(),
                     );
                     if (charged) {

package/lib/sanitize-snapshot.js

@@ -45,6 +45,14 @@ export function sanitizeKeyStatus(key, now = Date.now()) {
           limit: clampNonNegative(key.rpm.limit),
         }
       : key.rpm,
+    tpm: key.tpm && typeof key.tpm === 'object'
+      ? {
+          ...key.tpm,
+          used: clampNonNegative(key.tpm.used),
+          remaining: clampNonNegative(key.tpm.remaining),
+          limit: clampNonNegative(key.tpm.limit),
+        }
+      : key.tpm,
   };
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@goodandready/dsh-key-rotation",
-  "version": "0.8.37",
+  "version": "0.8.38",
   "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": [
@@ -57,7 +57,7 @@
   },
   "peerDependencies": {
     "@deepseek-ai/cordis": "^4.0.1",
-    "@deepseek-ai/schemastery": "^3.18.1",
+    "@deepseek-ai/schemastery": "^3.18.4",
     "@deepseek-ai/dsh-llm": "^0.1.7-rc.2 || ^0.2.0-rc.1"
   },
   "scripts": {