@juspay/neurolink 9.30.0 → 9.31.0

package/dist/client/utils/imageCache.js

@@ -0,0 +1,376 @@
+/**
+ * Image Cache Utility for NeuroLink
+ *
+ * Implements an LRU cache for downloaded images to avoid redundant URL downloads.
+ * Addresses IMG-026: No Caching issue - same URL downloaded multiple times wasting bandwidth.
+ *
+ * Features:
+ * - LRU (Least Recently Used) eviction strategy
+ * - Configurable cache size and TTL
+ * - Cache hit/miss metrics
+ * - Content hash tracking for deduplication
+ *
+ * @module utils/imageCache
+ */
+import { createHash } from "crypto";
+import { logger } from "./logger.js";
+/**
+ * LRU Cache for downloaded images
+ *
+ * Uses URL as primary key and tracks content hashes for deduplication.
+ * Implements LRU eviction and configurable TTL for memory management.
+ */
+export class ImageCache {
+    cache = new Map();
+    contentHashIndex = new Map(); // contentHash -> url
+    maxSize;
+    ttlMs;
+    maxImageSize;
+    enabled;
+    stats = {
+        hits: 0,
+        misses: 0,
+        evictions: 0,
+        expirations: 0,
+        totalRequests: 0,
+    };
+    constructor(config = {}) {
+        // Parse configuration with environment variable overrides
+        const envEnabled = process.env.NEUROLINK_IMAGE_CACHE_ENABLED;
+        const envMaxSize = process.env.NEUROLINK_IMAGE_CACHE_SIZE;
+        const envTtlMs = process.env.NEUROLINK_IMAGE_CACHE_TTL_MS;
+        const envMaxImageSize = process.env.NEUROLINK_IMAGE_MAX_SIZE;
+        // Check if cache is enabled (default: false)
+        this.enabled =
+            envEnabled !== undefined ? envEnabled.toLowerCase() === "true" : false;
+        this.maxSize = this.parseConfigValue(envMaxSize, config.maxSize, 100, 1, 1000);
+        this.ttlMs = this.parseConfigValue(envTtlMs, config.ttlMs, 30 * 60 * 1000, // 30 minutes
+        1000, // 1 second min
+        24 * 60 * 60 * 1000);
+        this.maxImageSize = this.parseConfigValue(envMaxImageSize, config.maxImageSize, 10 * 1024 * 1024, // 10MB
+        1024, // 1KB min
+        100 * 1024 * 1024);
+        logger.debug("ImageCache initialized", {
+            enabled: this.enabled,
+            maxSize: this.maxSize,
+            ttlMs: this.ttlMs,
+            maxImageSize: this.maxImageSize,
+        });
+    }
+    /**
+     * Parse a config value with bounds checking
+     */
+    parseConfigValue(envValue, configValue, defaultValue, min, max) {
+        let value;
+        if (envValue !== undefined) {
+            const parsed = parseInt(envValue, 10);
+            value = isNaN(parsed) ? defaultValue : parsed;
+        }
+        else if (configValue !== undefined) {
+            value = configValue;
+        }
+        else {
+            value = defaultValue;
+        }
+        // Apply bounds
+        if (value < min) {
+            logger.warn(`Cache config value ${value} below minimum ${min}, using min`);
+            return min;
+        }
+        if (value > max) {
+            logger.warn(`Cache config value ${value} above maximum ${max}, using max`);
+            return max;
+        }
+        return value;
+    }
+    /**
+     * Normalize URL for consistent cache key generation
+     * Removes tracking parameters and normalizes the URL
+     */
+    normalizeUrl(url) {
+        try {
+            const parsed = new URL(url);
+            // Remove common tracking parameters that don't affect content
+            const trackingParams = [
+                "utm_source",
+                "utm_medium",
+                "utm_campaign",
+                "utm_term",
+                "utm_content",
+                "fbclid",
+                "gclid",
+                "_ga",
+            ];
+            trackingParams.forEach((param) => parsed.searchParams.delete(param));
+            return parsed.toString();
+        }
+        catch {
+            // If URL parsing fails, use the original URL
+            return url;
+        }
+    }
+    /**
+     * Generate content hash from image data
+     */
+    generateContentHash(data) {
+        const buffer = typeof data === "string" ? Buffer.from(data, "base64") : data;
+        return createHash("sha256").update(buffer).digest("hex").substring(0, 16);
+    }
+    /**
+     * Check if an entry is expired based on TTL
+     */
+    isExpired(entry) {
+        return Date.now() - entry.createdAt > this.ttlMs;
+    }
+    /**
+     * Check if cache is enabled
+     */
+    isEnabled() {
+        return this.enabled;
+    }
+    /**
+     * Get a cached image by URL
+     * Returns null if not found or expired
+     */
+    get(url) {
+        // Return null immediately if cache is disabled
+        if (!this.enabled) {
+            return null;
+        }
+        this.stats.totalRequests++;
+        const normalizedUrl = this.normalizeUrl(url);
+        const entry = this.cache.get(normalizedUrl);
+        if (!entry) {
+            this.stats.misses++;
+            logger.debug("Image cache miss", { url: normalizedUrl.substring(0, 50) });
+            return null;
+        }
+        // Check TTL expiration
+        if (this.isExpired(entry)) {
+            this.stats.expirations++;
+            this.delete(normalizedUrl);
+            logger.debug("Image cache entry expired", {
+                url: normalizedUrl.substring(0, 50),
+            });
+            return null;
+        }
+        // Update LRU info
+        entry.lastAccessedAt = Date.now();
+        entry.accessCount++;
+        // Move to end (most recently used) - delete and re-add
+        this.cache.delete(normalizedUrl);
+        this.cache.set(normalizedUrl, entry);
+        this.stats.hits++;
+        logger.debug("Image cache hit", {
+            url: normalizedUrl.substring(0, 50),
+            accessCount: entry.accessCount,
+        });
+        return entry;
+    }
+    /**
+     * Get a cached image by content hash
+     * Useful for deduplication when the same image is accessed via different URLs
+     */
+    getByContentHash(contentHash) {
+        const url = this.contentHashIndex.get(contentHash);
+        if (!url) {
+            return null;
+        }
+        return this.get(url);
+    }
+    /**
+     * Store an image in the cache
+     */
+    set(url, dataUri, contentType, imageData) {
+        // Skip caching if disabled
+        if (!this.enabled) {
+            logger.debug("Image caching disabled, skipping cache storage");
+            return;
+        }
+        const normalizedUrl = this.normalizeUrl(url);
+        const size = imageData.length;
+        // Skip caching if image exceeds max size
+        if (size > this.maxImageSize) {
+            logger.debug("Image too large to cache", {
+                url: normalizedUrl.substring(0, 50),
+                size,
+                maxSize: this.maxImageSize,
+            });
+            return;
+        }
+        // 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: normalizedUrl.substring(0, 50),
+                    existingUrl: existingUrl.substring(0, 50),
+                });
+                return;
+            }
+        }
+        // Evict if at capacity
+        while (this.cache.size >= this.maxSize) {
+            this.evictOldest();
+        }
+        const now = Date.now();
+        const entry = {
+            dataUri,
+            contentType,
+            size,
+            contentHash,
+            createdAt: now,
+            lastAccessedAt: now,
+            accessCount: 1,
+        };
+        this.cache.set(normalizedUrl, entry);
+        this.contentHashIndex.set(contentHash, normalizedUrl);
+        logger.debug("Image cached", {
+            url: normalizedUrl.substring(0, 50),
+            size,
+            contentHash: contentHash.substring(0, 8),
+            cacheSize: this.cache.size,
+        });
+    }
+    /**
+     * Delete an entry from the cache
+     */
+    delete(url) {
+        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);
+            }
+            this.cache.delete(normalizedUrl);
+            return true;
+        }
+        return false;
+    }
+    /**
+     * Evict the oldest (least recently used) entry
+     */
+    evictOldest() {
+        // Map maintains insertion order, first entry is oldest
+        const oldestKey = this.cache.keys().next().value;
+        if (oldestKey !== undefined) {
+            const entry = this.cache.get(oldestKey);
+            if (entry) {
+                if (this.contentHashIndex.get(entry.contentHash) === oldestKey) {
+                    this.contentHashIndex.delete(entry.contentHash);
+                }
+            }
+            this.cache.delete(oldestKey);
+            this.stats.evictions++;
+            logger.debug("Image cache eviction", {
+                url: String(oldestKey).substring(0, 50),
+            });
+        }
+    }
+    /**
+     * Clear all expired entries
+     */
+    evictExpired() {
+        let evicted = 0;
+        const now = Date.now();
+        for (const [url, entry] of this.cache.entries()) {
+            if (now - entry.createdAt > this.ttlMs) {
+                this.delete(url);
+                evicted++;
+                this.stats.expirations++;
+            }
+        }
+        if (evicted > 0) {
+            logger.debug(`Evicted ${evicted} expired image cache entries`);
+        }
+        return evicted;
+    }
+    /**
+     * Clear all entries from the cache
+     */
+    clear() {
+        const size = this.cache.size;
+        this.cache.clear();
+        this.contentHashIndex.clear();
+        logger.debug(`Image cache cleared (${size} entries removed)`);
+    }
+    /**
+     * Get cache statistics
+     */
+    getStats() {
+        let totalBytes = 0;
+        for (const entry of this.cache.values()) {
+            totalBytes += entry.size;
+        }
+        const hitRate = this.stats.totalRequests > 0
+            ? Number(((this.stats.hits / this.stats.totalRequests) * 100).toFixed(2))
+            : 0;
+        return {
+            ...this.stats,
+            size: this.cache.size,
+            totalBytes,
+            hitRate,
+        };
+    }
+    /**
+     * Check if a URL is cached and not expired
+     */
+    has(url) {
+        const normalizedUrl = this.normalizeUrl(url);
+        const entry = this.cache.get(normalizedUrl);
+        return entry !== null && entry !== undefined && !this.isExpired(entry);
+    }
+    /**
+     * Get the current cache size
+     */
+    getSize() {
+        return this.cache.size;
+    }
+    /**
+     * Get cache configuration
+     */
+    getConfig() {
+        return {
+            enabled: this.enabled,
+            maxSize: this.maxSize,
+            ttlMs: this.ttlMs,
+            maxImageSize: this.maxImageSize,
+        };
+    }
+}
+// Global image cache instance
+let globalImageCache = null;
+/**
+ * Get the global image cache instance
+ * Creates a new instance if none exists
+ */
+export function getImageCache(config) {
+    if (!globalImageCache) {
+        globalImageCache = new ImageCache(config);
+    }
+    return globalImageCache;
+}
+/**
+ * Reset the global image cache (useful for testing)
+ */
+export function resetImageCache() {
+    if (globalImageCache) {
+        globalImageCache.clear();
+        globalImageCache = null;
+    }
+}
+/**
+ * Get image cache statistics from the global instance
+ */
+export function getImageCacheStats() {
+    return globalImageCache ? globalImageCache.getStats() : null;
+}