@juspay/neurolink 10.1.1 → 10.2.0

package/dist/lib/types/proxy.d.ts

@@ -700,6 +700,40 @@ export type ProxyStats = {
     totalQuotaRateLimits: number;
     accounts: Record<string, AccountStats>;
 };
+/** Durability and reconciliation state for the proxy usage counters. */
+export type ProxyStatsPersistenceStatus = {
+    enabled: boolean;
+    filePath: string | null;
+    revision: number;
+    pendingMutations: number;
+    inFlightMutations: number;
+    unpersistedMutations: number;
+    lastFlushedAt: number | null;
+    lastReconciledAt: number | null;
+    lastRecoveryAt: number | null;
+    lastError: string | null;
+};
+/** Versioned on-disk snapshot shared by overlapping proxy workers. */
+export type PersistedProxyStatsSnapshot = {
+    schemaVersion: 1;
+    revision: number;
+    updatedAt: number;
+    stats: ProxyStats;
+};
+/** Ownership metadata for the proxy statistics cross-process lock. */
+export type ProxyStatsLockOwner = {
+    token: string;
+    pid: number;
+    acquiredAt: number;
+};
+/** Construction options for an isolated proxy statistics store. */
+export type ProxyUsageStatsStoreOptions = {
+    filePath?: string;
+    flushIntervalMs?: number;
+    lockTimeoutMs?: number;
+    staleLockMs?: number;
+    now?: () => number;
+};
 export type RefreshableAccount = {
     token: string;
     refreshToken?: string;
@@ -874,6 +908,8 @@ export type ProxyPaths = {
     quotaFile: string;
     /** account-cooldowns.json — restart-safe account cooldown state */
     cooldownFile: string;
+    /** proxy-usage-stats.json — restart- and handoff-safe usage counters */
+    statsFile?: string;
     /** Whether this is a dev-mode isolated instance */
     isDev: boolean;
 };
@@ -1876,6 +1912,7 @@ export type ProxyStartApp = {
 };
 /** Stats shape consumed by the proxy status printer. */
 export type StatusStats = {
+    startedAt?: number;
     totalAttempts?: number;
     totalAttemptErrors?: number;
     totalRequests: number;
@@ -1896,7 +1933,9 @@ export type StatusStats = {
         transientRateLimits?: number;
         quotaRateLimits?: number;
         cooling: boolean;
+        status?: "active" | "cooling" | "disabled" | "excluded" | "removed";
     }[];
+    persistence?: ProxyStatsPersistenceStatus;
 };
 /** Sub-action of the `proxy telemetry` CLI command. */
 export type ProxyTelemetryAction = "setup" | "start" | "stop" | "status" | "logs" | "import-dashboard";

package/dist/lib/utils/imageCache.js

@@ -23,7 +23,11 @@ import { normalizeUrlForCache, redactUrlForError } from "./logSanitize.js";
  */
 export class ImageCache {
     cache = new Map();
-    contentHashIndex = new Map(); // contentHash -> url
+    // contentHash -> set of normalized urls whose cache entry holds that
+    // content. A Set (not a single url) so that evicting/deleting one url
+    // doesn't drop the dedup mapping for other urls still caching the same
+    // content (#1213).
+    contentHashIndex = new Map();
     maxSize;
     ttlMs;
     maxImageSize;
@@ -164,11 +168,37 @@ export class ImageCache {
      * Useful for deduplication when the same image is accessed via different URLs
      */
     getByContentHash(contentHash) {
-        const url = this.contentHashIndex.get(contentHash);
-        if (!url) {
+        const urlSet = this.contentHashIndex.get(contentHash);
+        if (!urlSet) {
             return null;
         }
-        return this.get(url);
+        // Find the first url whose cache entry is still live, pruning any url
+        // whose entry no longer exists in `this.cache` along the way. Entries
+        // that exist but are expired are left in the set (not "gone") - the
+        // normal TTL/get() path is responsible for reaping those.
+        let liveUrl = null;
+        // Iterate a copy so reaping below can mutate the set safely.
+        for (const url of [...urlSet]) {
+            const entry = this.cache.get(url);
+            if (!entry) {
+                urlSet.delete(url);
+                continue;
+            }
+            if (this.isExpired(entry)) {
+                // Reap expired entries here too (matching get() semantics) so stale
+                // urls don't accumulate when callers primarily use getByContentHash.
+                this.cache.delete(url);
+                urlSet.delete(url);
+                continue;
+            }
+            if (liveUrl === null) {
+                liveUrl = url;
+            }
+        }
+        if (urlSet.size === 0) {
+            this.contentHashIndex.delete(contentHash);
+        }
+        return liveUrl ? this.get(liveUrl) : null;
     }
     /**
      * Store an image in the cache
@@ -192,21 +222,42 @@ export class ImageCache {
         }
         // Generate content hash
         const contentHash = this.generateContentHash(imageData);
-        // Check if same content already exists under different URL
-        const existingUrl = this.contentHashIndex.get(contentHash);
-        if (existingUrl && existingUrl !== normalizedUrl) {
-            // Content already cached under different URL - create a shallow copy
-            const existingEntry = this.cache.get(existingUrl);
-            if (existingEntry && !this.isExpired(existingEntry)) {
-                // Create a shallow copy for the new URL to avoid shared reference issues
-                this.cache.set(normalizedUrl, { ...existingEntry });
-                // Update content hash index to point to the new URL as well
-                this.contentHashIndex.set(contentHash, normalizedUrl);
-                logger.debug("Image cache dedup hit", {
-                    newUrl: redactUrlForError(normalizedUrl),
-                    existingUrl: redactUrlForError(existingUrl),
-                });
-                return;
+        // Check if same content already exists under a different URL
+        const existingUrls = this.contentHashIndex.get(contentHash);
+        if (existingUrls) {
+            for (const existingUrl of existingUrls) {
+                if (existingUrl === normalizedUrl) {
+                    continue;
+                }
+                // Content already cached under a different URL - create a shallow copy
+                const existingEntry = this.cache.get(existingUrl);
+                if (existingEntry && !this.isExpired(existingEntry)) {
+                    // A dedup hit still adds a cache entry for the new URL, so enforce
+                    // capacity first — otherwise many URLs sharing one content hash could
+                    // grow the cache past maxSize.
+                    while (this.cache.size >= this.maxSize && this.cache.size > 0) {
+                        this.evictOldest();
+                    }
+                    // Create a shallow copy for the new URL to avoid shared reference issues
+                    this.cache.set(normalizedUrl, { ...existingEntry });
+                    // Re-fetch (or re-create) the hash's URL set: the eviction above may
+                    // have removed this hash's last url, emptying the set and deleting it
+                    // from contentHashIndex — reusing the stale `existingUrls` reference
+                    // would add the new url to an orphaned set that the index no longer
+                    // points to, leaving a live entry unreachable by content hash
+                    // (the exact #1213 failure mode). Never replace an existing mapping.
+                    let hashUrls = this.contentHashIndex.get(contentHash);
+                    if (!hashUrls) {
+                        hashUrls = new Set();
+                        this.contentHashIndex.set(contentHash, hashUrls);
+                    }
+                    hashUrls.add(normalizedUrl);
+                    logger.debug("Image cache dedup hit", {
+                        newUrl: redactUrlForError(normalizedUrl),
+                        existingUrl: redactUrlForError(existingUrl),
+                    });
+                    return;
+                }
             }
         }
         // Evict if at capacity
@@ -224,7 +275,12 @@ export class ImageCache {
             accessCount: 1,
         };
         this.cache.set(normalizedUrl, entry);
-        this.contentHashIndex.set(contentHash, normalizedUrl);
+        let urlSet = this.contentHashIndex.get(contentHash);
+        if (!urlSet) {
+            urlSet = new Set();
+            this.contentHashIndex.set(contentHash, urlSet);
+        }
+        urlSet.add(normalizedUrl);
         logger.debug("Image cached", {
             url: redactUrlForError(normalizedUrl),
             size,
@@ -239,9 +295,14 @@ export class ImageCache {
         const normalizedUrl = this.normalizeUrl(url);
         const entry = this.cache.get(normalizedUrl);
         if (entry) {
-            // Remove from content hash index
-            if (this.contentHashIndex.get(entry.contentHash) === normalizedUrl) {
-                this.contentHashIndex.delete(entry.contentHash);
+            // Remove this URL from its content hash's URL set; only drop the
+            // hash entry once no URL maps to that content anymore (#1213).
+            const urlSet = this.contentHashIndex.get(entry.contentHash);
+            if (urlSet) {
+                urlSet.delete(normalizedUrl);
+                if (urlSet.size === 0) {
+                    this.contentHashIndex.delete(entry.contentHash);
+                }
             }
             this.cache.delete(normalizedUrl);
             return true;
@@ -257,8 +318,15 @@ export class ImageCache {
         if (oldestKey !== undefined) {
             const entry = this.cache.get(oldestKey);
             if (entry) {
-                if (this.contentHashIndex.get(entry.contentHash) === oldestKey) {
-                    this.contentHashIndex.delete(entry.contentHash);
+                // Remove only the evicted URL from its content hash's URL set; the
+                // hash entry is dropped only once no URL maps to it anymore
+                // (#1213).
+                const urlSet = this.contentHashIndex.get(entry.contentHash);
+                if (urlSet) {
+                    urlSet.delete(oldestKey);
+                    if (urlSet.size === 0) {
+                        this.contentHashIndex.delete(entry.contentHash);
+                    }
                 }
             }
             this.cache.delete(oldestKey);

package/dist/proxy/proxyPaths.d.ts

@@ -14,3 +14,4 @@
  */
 import type { ProxyPaths } from "../types/index.js";
 export declare function resolveProxyPaths(dev: boolean): ProxyPaths;
+export declare function resolveProxyUsageStatsPath(paths: ProxyPaths): string;

package/dist/proxy/proxyPaths.js

@@ -22,6 +22,7 @@ export function resolveProxyPaths(dev) {
             logsDir: join(base, "logs"),
             quotaFile: join(base, "account-quotas.json"),
             cooldownFile: join(base, "account-cooldowns.json"),
+            statsFile: join(base, "proxy-usage-stats.json"),
             isDev: true,
         };
     }
@@ -31,6 +32,10 @@ export function resolveProxyPaths(dev) {
         logsDir: join(base, "logs"),
         quotaFile: join(base, "account-quotas.json"),
         cooldownFile: join(base, "account-cooldowns.json"),
+        statsFile: join(base, "proxy-usage-stats.json"),
         isDev: false,
     };
 }
+export function resolveProxyUsageStatsPath(paths) {
+    return paths.statsFile ?? join(paths.stateDir, "proxy-usage-stats.json");
+}

package/dist/proxy/usageStats.d.ts

@@ -1,13 +1,67 @@
 /**
- * Proxy Usage Statistics
- * Tracks per-account request counts, token usage, and error rates.
- * In-memory only — resets on proxy restart.
+ * Proxy usage statistics with restart- and handoff-safe persistence.
+ *
+ * Request handlers update memory synchronously. Small deltas are merged into a
+ * shared snapshot asynchronously, under a cross-process lock, so overlapping
+ * rolling workers cannot overwrite each other's counters.
  */
-import type { AccountStats, ProxyStats } from "../types/index.js";
+import type { AccountStats, ProxyStats, ProxyStatsPersistenceStatus, ProxyUsageStatsStoreOptions } from "../types/index.js";
+export declare class ProxyUsageStatsStore {
+    private readonly now;
+    private readonly flushIntervalMs;
+    private readonly lockTimeoutMs;
+    private readonly staleLockMs;
+    private filePath?;
+    private stats;
+    private pending;
+    private pendingMutations;
+    private inFlightMutations;
+    private revision;
+    private flushTimer;
+    private readonly flushMutex;
+    private lastFlushedAt?;
+    private lastReconciledAt?;
+    private lastRecoveryAt?;
+    private lastError?;
+    constructor(options?: ProxyUsageStatsStoreOptions);
+    initialize(filePath?: string): Promise<void>;
+    recordAttempt(accountLabel: string, accountType: string): void;
+    recordFinalSuccess(accountLabel?: string, accountType?: string): void;
+    recordAttemptError(accountLabel: string, accountType: string, status: number, rateLimitKind?: "transient" | "quota"): void;
+    recordFinalError(_status: number, accountLabel?: string, accountType?: string): void;
+    getStats(): ProxyStats;
+    getAccountStats(label: string): AccountStats | undefined;
+    getPersistenceStatus(): ProxyStatsPersistenceStatus;
+    flush(): Promise<void>;
+    reconcile(): Promise<ProxyStats>;
+    resetMemory(): void;
+    resetForTests(): Promise<void>;
+    private markMutation;
+    private applyAttempt;
+    private applyFinalSuccess;
+    private applyAttemptError;
+    private applyFinalError;
+    private ensureAccount;
+    private scheduleFlush;
+    private cancelFlushTimer;
+    private readSnapshot;
+    private applySnapshot;
+    private recoverCorruptSnapshot;
+    private quarantineCorruptSnapshot;
+    private pruneCorruptSnapshots;
+    private describeError;
+}
+export declare function initUsageStats(filePath: string): Promise<void>;
 export declare function recordAttempt(accountLabel: string, accountType: string): void;
 export declare function recordFinalSuccess(accountLabel?: string, accountType?: string): void;
 export declare function recordAttemptError(accountLabel: string, accountType: string, status: number, rateLimitKind?: "transient" | "quota"): void;
 export declare function recordFinalError(_status: number, accountLabel?: string, accountType?: string): void;
 export declare function getStats(): ProxyStats;
+export declare function getReconciledStats(): Promise<ProxyStats>;
 export declare function getAccountStats(label: string): AccountStats | undefined;
+export declare function getUsageStatsPersistenceStatus(): ProxyStatsPersistenceStatus;
+export declare function flushUsageStats(): Promise<void>;
+/** Reset process-local counters while intentionally preserving durable state. */
 export declare function resetStats(): void;
+/** Disconnect persistence and clear singleton state between isolated tests. */
+export declare function resetUsageStatsForTests(): Promise<void>;