@goodandready/dsh-subscriptions 0.6.61 → 0.6.63

package/lib/session-pin.js

@@ -1,52 +1,258 @@
+// Cache-aware session affinity and pinning with lifecycle management (#170, #517, #520).
+// Enforces 0 Cyrillic characters.
+
+export const CACHE_AWARE_PROVIDERS = new Set(['claude', 'codex', 'antigravity', 'grok'])
+
+/**
+ * Check if a provider supports prompt/prefix caching where pinning benefits cache hit rates.
+ * @param {string|undefined} provider
+ * @returns {boolean}
+ */
+export function isCacheAwareProvider(provider) {
+  if (!provider || typeof provider !== 'string') return false
+  return CACHE_AWARE_PROVIDERS.has(provider.toLowerCase().trim())
+}
+
+const DEFAULT_TTL_MS = 30 * 60 * 1000 // 30 minutes
+const MAX_PINS = 200
+
+/**
+ * @typedef {Object} SessionPinEntry
+ * @property {string} accountRef
+ * @property {string} [provider]
+ * @property {string} [model]
+ * @property {number} pinnedAt
+ * @property {number} lastHitAt
+ * @property {number} expiresAt
+ * @property {number} hits
+ * @property {boolean} cacheAware
+ * @property {number} cacheHits
+ * @property {number} cacheTokensSaved
+ */
+
+/** @type {Map<string, SessionPinEntry>} */
 const sessionPins = new Map()
-const DEFAULT_TTL_MS = 30 * 60 * 1000 // 30 mins
+
+const stats = {
+  totalPins: 0,
+  retainedHits: 0,
+  cacheAwareHits: 0,
+  releasedCount: 0,
+  cacheTokensSaved: 0,
+  releasesByReason: {},
+}
+
+/**
+ * Record a release reason in statistics.
+ * @param {string} reason
+ */
+function recordReleaseReason(reason) {
+  const r = String(reason || 'manual')
+  stats.releasedCount++
+  stats.releasesByReason[r] = (stats.releasesByReason[r] || 0) + 1
+}
 
 /**
  * Prune expired session pin entries.
  * @param {number} [now]
- * @returns {void}
+ * @returns {number} count of pruned pins
  */
 export function pruneSessionPins(now = Date.now()) {
+  let pruned = 0
   for (const [id, entry] of sessionPins.entries()) {
     if (now > entry.expiresAt) {
       sessionPins.delete(id)
+      recordReleaseReason('pin_released_expired')
+      pruned++
     }
   }
+  return pruned
 }
 
 /**
- * Bind a session id to an account ref for ttlMs (default 30 minutes).
+ * Bind a session id to an account ref with cache awareness and metadata.
  * @param {string|undefined} sessionId
  * @param {string|undefined} accountRef
- * @param {number} [ttlMs]
+ * @param {Object} [options]
+ * @param {string} [options.provider]
+ * @param {string} [options.model]
+ * @param {number} [options.ttlMs]
+ * @param {boolean} [options.cacheAware]
  * @returns {void}
  */
-export function pinSession(sessionId, accountRef, ttlMs = DEFAULT_TTL_MS) {
+export function pinSession(sessionId, accountRef, options = {}) {
   if (!sessionId || !accountRef) return
-  if (sessionPins.size >= 50) {
+  if (sessionPins.size >= MAX_PINS) {
     pruneSessionPins()
   }
+
+  const now = Date.now()
+  const ttl = typeof options === 'number'
+    ? options
+    : (options && typeof options.ttlMs === 'number' ? options.ttlMs : DEFAULT_TTL_MS)
+  const provider = options.provider || undefined
+  const cacheAware = options.cacheAware !== undefined ? Boolean(options.cacheAware) : isCacheAwareProvider(provider)
+
+  const existing = sessionPins.get(sessionId)
+  if (existing && existing.accountRef === accountRef) {
+    // Sliding TTL on re-pinning same account
+    existing.lastHitAt = now
+    existing.expiresAt = now + ttl
+    if (options.model) existing.model = options.model
+    return
+  }
+
   sessionPins.set(sessionId, {
     accountRef,
-    expiresAt: Date.now() + ttlMs
+    provider,
+    model: options.model || undefined,
+    pinnedAt: now,
+    lastHitAt: now,
+    expiresAt: now + ttl,
+    hits: 0,
+    cacheAware,
+    cacheHits: 0,
+    cacheTokensSaved: 0,
   })
+  stats.totalPins++
 }
 
 /**
+ * Retrieve bound account ref or null if missing/expired.
  * @param {string|undefined} sessionId
- * @returns {string|null} the bound account ref, or null when absent/expired
+ * @param {number} [now]
+ * @returns {string|null}
  */
-export function getPinnedAccountRef(sessionId) {
+export function getPinnedAccountRef(sessionId, now = Date.now()) {
   if (!sessionId) return null
   const entry = sessionPins.get(sessionId)
   if (!entry) return null
-  if (Date.now() > entry.expiresAt) {
+  if (now > entry.expiresAt) {
     sessionPins.delete(sessionId)
+    recordReleaseReason('pin_released_expired')
     return null
   }
   return entry.accountRef
 }
 
+/**
+ * Retrieve full session pin details.
+ * @param {string|undefined} sessionId
+ * @param {number} [now]
+ * @returns {SessionPinEntry|null}
+ */
+export function getPinnedSessionDetails(sessionId, now = Date.now()) {
+  if (!sessionId) return null
+  const entry = sessionPins.get(sessionId)
+  if (!entry) return null
+  if (now > entry.expiresAt) {
+    sessionPins.delete(sessionId)
+    recordReleaseReason('pin_released_expired')
+    return null
+  }
+  return { ...entry }
+}
+
+/**
+ * Touch an active session pin (record hit, sliding TTL extension).
+ * @param {string|undefined} sessionId
+ * @param {Object} [options]
+ * @param {number} [options.ttlMs]
+ * @param {string} [options.model]
+ * @param {string} [options.provider]
+ * @returns {boolean} true if pin existed and was updated
+ */
+export function touchSessionPin(sessionId, options = {}) {
+  if (!sessionId) return false
+  const entry = sessionPins.get(sessionId)
+  if (!entry) return false
+
+  const now = Date.now()
+  if (now > entry.expiresAt) {
+    sessionPins.delete(sessionId)
+    recordReleaseReason('pin_released_expired')
+    return false
+  }
+
+  const ttl = typeof options === 'number'
+    ? options
+    : (options && typeof options.ttlMs === 'number' ? options.ttlMs : DEFAULT_TTL_MS)
+  entry.lastHitAt = now
+  entry.expiresAt = now + ttl
+  entry.hits++
+  if (options.provider) entry.provider = options.provider
+  if (options.model) entry.model = options.model
+
+  stats.retainedHits++
+  if (entry.cacheAware) {
+    stats.cacheAwareHits++
+  }
+  return true
+}
+
+/**
+ * Explicitly release a session pin with a documented reason code.
+ * @param {string|undefined} sessionId
+ * @param {string} [reason] e.g. 'pinned_cooldown', 'pinned_quarantine', 'pinned_quota', 'manual'
+ * @returns {boolean} true if a pin was removed
+ */
+export function unpinSession(sessionId, reason = 'manual') {
+  if (!sessionId) return false
+  const exists = sessionPins.has(sessionId)
+  if (exists) {
+    sessionPins.delete(sessionId)
+    recordReleaseReason(reason)
+    return true
+  }
+  return false
+}
+
+/**
+ * Record actual token caching metrics for a pinned session.
+ * @param {string|undefined} sessionId
+ * @param {number} cacheReadTokens
+ */
+export function recordSessionCacheUsage(sessionId, cacheReadTokens = 0) {
+  if (!sessionId || typeof cacheReadTokens !== 'number' || cacheReadTokens <= 0) return
+  const entry = sessionPins.get(sessionId)
+  if (!entry) return
+
+  entry.cacheHits++
+  entry.cacheTokensSaved += cacheReadTokens
+  stats.cacheTokensSaved += cacheReadTokens
+}
+
+/**
+ * Get cumulative statistics and current state of session pinning.
+ * @returns {Object}
+ */
+export function getSessionPinStats() {
+  let cacheAwareActive = 0
+  for (const entry of sessionPins.values()) {
+    if (entry.cacheAware) cacheAwareActive++
+  }
+
+  return {
+    totalPins: stats.totalPins,
+    activePins: sessionPins.size,
+    cacheAwareActivePins: cacheAwareActive,
+    retainedHits: stats.retainedHits,
+    cacheAwareHits: stats.cacheAwareHits,
+    releasedCount: stats.releasedCount,
+    cacheTokensSaved: stats.cacheTokensSaved,
+    releasesByReason: { ...stats.releasesByReason },
+  }
+}
+
+/**
+ * Reset all session pins and statistics (useful for tests and full resets).
+ */
 export function clearSessionPins() {
   sessionPins.clear()
+  stats.totalPins = 0
+  stats.retainedHits = 0
+  stats.cacheAwareHits = 0
+  stats.releasedCount = 0
+  stats.cacheTokensSaved = 0
+  stats.releasesByReason = {}
 }

package/lib/stream-rotate.js

@@ -1,3 +1,5 @@
+import { defaultConcurrencyQueue } from './concurrency-queue.js'
+import { recordSessionCacheUsage } from './session-pin.js'
 import { pickAccountWithTrace, markCooldown, isSwitchableError, isRegionError, modelFamily } from './rotate.js'
 import { putInQuarantine, REASON_RATE_LIMIT, REASON_HARD_LIMIT, REASON_REVOKED } from './quarantine.js'
 import { notifySessionExpired, notifyQuarantineEntered } from './alerts.js'
@@ -16,6 +18,7 @@ export async function* streamWithRotation({
   offlineFallback, // #174: optional fallback generator if all accounts exhausted
   webhookUrl,
   fetchImpl = fetch,
+  concurrencyQueue = defaultConcurrencyQueue,
 }) {
   const pool = (accounts || []).map((account) => ({ ...account }))
   let lastError = null
@@ -100,10 +103,36 @@ export async function* streamWithRotation({
 
     tried.add(account.ref || account.id)
 
+    const queueKey = account.ref || account.id || 'default'
+    const queueConfig = {
+      signal: options && options.signal,
+      timeoutMs: options && (options.queueTimeoutMs !== undefined ? options.queueTimeoutMs : (options.config && options.config.queueTimeoutMs)),
+      maxConcurrency: options && (options.accountMaxConcurrency !== undefined ? options.accountMaxConcurrency : (options.config && options.config.accountMaxConcurrency)),
+      maxQueueSize: options && (options.maxQueueSize !== undefined ? options.maxQueueSize : (options.config && options.config.maxQueueSize)),
+      enabled: options && (options.enableQueue !== undefined ? options.enableQueue : (options.config && options.config.enableQueue !== undefined ? options.config.enableQueue : true)),
+    }
+
+    let releaseSlot = null
+    try {
+      releaseSlot = await concurrencyQueue.acquire(queueKey, queueConfig)
+    } catch (queueErr) {
+      if (queueErr && (queueErr.code === 'ABORT_ERR' || queueErr.name === 'AbortError')) {
+        currentAttempt.status = 'aborted'
+        currentAttempt.error = queueErr.message
+        syncTrace('aborted')
+        throw queueErr
+      }
+      currentAttempt.status = queueErr && queueErr.code === 'QUEUE_OVERFLOW' ? 'queue_overflow' : 'queue_timeout'
+      currentAttempt.error = queueErr ? queueErr.message : String(queueErr)
+      lastError = queueErr
+      continue
+    }
+
     let firstChunkDelivered = false
     let regionRetries = 0
 
-    while (true) {
+    try {
+      while (true) {
       try {
         const runawayState = options && options._runawayState ? options._runawayState : { tripped: false, reason: null }
         const runawayOpts = {
@@ -119,6 +148,14 @@ export async function* streamWithRotation({
         )
         for await (const chunk of guardedStream) {
           firstChunkDelivered = true
+          const cachedTokens = Number(
+            (chunk && chunk.usage && (chunk.usage.cacheReadTokens || chunk.usage.cachedTokens)) ||
+            (chunk && chunk.tokens && (chunk.tokens.cacheRead || chunk.tokens.cached)) ||
+            0
+          )
+          if (cachedTokens > 0 && options && options.sessionId) {
+            recordSessionCacheUsage(options.sessionId, cachedTokens)
+          }
           yield chunk
         }
         currentAttempt.status = 'success'
@@ -207,5 +244,10 @@ export async function* streamWithRotation({
         break
       }
     }
+    } finally {
+      if (typeof releaseSlot === 'function') {
+        releaseSlot()
+      }
+    }
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@goodandready/dsh-subscriptions",
-  "version": "0.6.61",
+  "version": "0.6.63",
   "description": "Use ChatGPT Codex, Claude, Grok, Antigravity, Kimi, GLM, Cursor, Kiro, Copilot, Qwen, ERNIE, Spark, JetBrains, Perplexity, Replit, and Cody subscriptions as DeepSeek Harness LLM providers via OAuth.",
   "license": "MIT",
   "type": "module",