@pantheon-systems/nextjs-cache-handler 0.1.0 → 0.2.0

package/dist/use-cache/file-handler.js

@@ -0,0 +1,366 @@
+import * as fs from 'fs';
+import * as path from 'path';
+import { serializeUseCacheEntry, deserializeUseCacheEntry, } from './stream-serialization.js';
+import { createLogger } from '../utils/logger.js';
+import { createEdgeCacheClearer } from '../edge/edge-cache-clear.js';
+const log = createLogger('UseCacheFileHandler');
+/**
+ * Next.js internal prefix for path-based cache tags.
+ */
+const NEXTJS_PATH_TAG_PREFIX = '_N_T_';
+/**
+ * Symbol for path→surrogate-key registry on globalThis.
+ */
+const PATH_TAGS_REGISTRY_SYMBOL = Symbol.for('@nextjs-cache-handler/path-tags-registry');
+/**
+ * Symbol used to access CacheTagContext from globalThis.
+ * This matches the Symbol.for pattern used by Next.js for @next/request-context.
+ */
+const CACHE_TAG_CONTEXT_SYMBOL = Symbol.for('@nextjs-cache-handler/tag-context');
+/**
+ * Access the CacheTagContext via globalThis using Symbol.for.
+ * This allows cross-context access without direct module imports.
+ */
+function getCacheTagContext() {
+    const accessor = globalThis[CACHE_TAG_CONTEXT_SYMBOL];
+    return accessor?.get();
+}
+/**
+ * Add tags to the CacheTagContext if available.
+ * Falls back to global store if CacheTagContext is not active.
+ */
+function captureTags(tags) {
+    if (tags.length === 0) {
+        return { captured: false, source: 'none' };
+    }
+    // Primary: Try CacheTagContext (Symbol.for pattern)
+    const context = getCacheTagContext();
+    if (context) {
+        context.tags.push(...tags);
+        log.debug(`Captured ${tags.length} tags via CacheTagContext: ${tags.join(', ')}`);
+        return { captured: true, source: 'CacheTagContext' };
+    }
+    // Fallback: Use global store (for environments where Symbol.for doesn't propagate)
+    let globalTags = globalThis.__pantheonSurrogateKeyTags;
+    if (!globalTags) {
+        globalTags = [];
+        globalThis.__pantheonSurrogateKeyTags = globalTags;
+    }
+    globalTags.push(...tags);
+    log.debug(`Captured ${tags.length} tags via globalStore fallback: ${tags.join(', ')}`);
+    return { captured: true, source: 'globalStore' };
+}
+/**
+ * File-based cache handler for Next.js 16 'use cache' directive.
+ * Implements the cacheHandlers (plural) interface.
+ *
+ * Suitable for:
+ * - Local development
+ * - Single-instance deployments
+ * - Testing
+ */
+export class UseCacheFileHandler {
+    constructor(config = {}) {
+        this.tagTimestamps = new Map();
+        this.pathToSurrogateKeys = new Map();
+        this.cacheDir = config.cacheDir ?? path.join(process.cwd(), '.next', 'cache', 'use-cache');
+        this.tagsFile = path.join(this.cacheDir, '_tags.json');
+        this.ensureCacheDir();
+        this.loadTagTimestamps();
+        // Initialize edge cache clearer if OUTBOUND_PROXY_ENDPOINT is configured
+        this.edgeCacheClearer = createEdgeCacheClearer();
+        if (this.edgeCacheClearer) {
+            log.debug('Edge cache clearing enabled');
+        }
+        // Expose registerPathTags on globalThis for withSurrogateKey integration
+        globalThis[PATH_TAGS_REGISTRY_SYMBOL] =
+            (p, t) => this.registerPathTags(p, t);
+        log.debug('Initialized with cache dir:', this.cacheDir);
+    }
+    ensureCacheDir() {
+        try {
+            fs.mkdirSync(this.cacheDir, { recursive: true });
+        }
+        catch (error) {
+            if (error.code !== 'EEXIST') {
+                log.error('Error creating cache directory:', error);
+            }
+        }
+    }
+    loadTagTimestamps() {
+        try {
+            if (fs.existsSync(this.tagsFile)) {
+                const data = fs.readFileSync(this.tagsFile, 'utf-8');
+                const parsed = JSON.parse(data);
+                this.tagTimestamps = new Map(Object.entries(parsed));
+            }
+        }
+        catch (error) {
+            log.warn('Error loading tag timestamps:', error);
+            this.tagTimestamps = new Map();
+        }
+    }
+    saveTagTimestamps() {
+        try {
+            const obj = Object.fromEntries(this.tagTimestamps);
+            fs.writeFileSync(this.tagsFile, JSON.stringify(obj, null, 2), 'utf-8');
+        }
+        catch (error) {
+            log.error('Error saving tag timestamps:', error);
+        }
+    }
+    getCacheFilePath(cacheKey) {
+        // Sanitize cache key for filesystem
+        const safeKey = cacheKey.replace(/[^a-zA-Z0-9-]/g, '_');
+        return path.join(this.cacheDir, `${safeKey}.json`);
+    }
+    /**
+     * Check if an entry is expired based on revalidate time.
+     */
+    isExpired(entry) {
+        const now = Date.now();
+        const age = now - entry.timestamp;
+        const revalidateMs = entry.revalidate * 1000;
+        // Entry is expired if it's older than revalidate time
+        if (age > revalidateMs) {
+            return true;
+        }
+        // Also check if any of the entry's tags have been invalidated
+        for (const tag of entry.tags) {
+            const tagTimestamp = this.tagTimestamps.get(tag);
+            if (tagTimestamp && tagTimestamp > entry.timestamp) {
+                return true;
+            }
+        }
+        return false;
+    }
+    /**
+     * Retrieve a cache entry.
+     */
+    async get(cacheKey, softTags) {
+        log.debug(`GET: ${cacheKey}`);
+        try {
+            const filePath = this.getCacheFilePath(cacheKey);
+            if (!fs.existsSync(filePath)) {
+                log.debug(`MISS: ${cacheKey} (not found)`);
+                return undefined;
+            }
+            const data = fs.readFileSync(filePath, 'utf-8');
+            const stored = JSON.parse(data);
+            const entry = deserializeUseCacheEntry(stored);
+            // Check expiration
+            if (this.isExpired(entry)) {
+                log.debug(`MISS: ${cacheKey} (expired)`);
+                // Optionally delete expired entry
+                try {
+                    fs.unlinkSync(filePath);
+                }
+                catch {
+                    // Ignore deletion errors
+                }
+                return undefined;
+            }
+            log.debug(`HIT: ${cacheKey}`);
+            // Capture tags for Surrogate-Key header propagation
+            // Uses Symbol.for pattern to access PantheonContext across async boundaries
+            const storedTags = entry.tags ?? [];
+            const { captured, source } = captureTags(storedTags);
+            if (captured) {
+                log.debug(`HIT ${cacheKey}: Captured ${storedTags.length} tags via ${source}`);
+            }
+            else if (storedTags.length === 0) {
+                // TODO: Remove this diagnostic logging once Next.js fixes the empty tags bug
+                // See: https://github.com/vercel/next.js/issues/78864
+                log.info(`HIT ${cacheKey}: No tags to capture (Next.js empty tags bug)`);
+            }
+            return entry;
+        }
+        catch (error) {
+            log.error(`Error reading cache for key ${cacheKey}:`, error);
+            return undefined;
+        }
+    }
+    /**
+     * Store a cache entry.
+     * CRITICAL: Must await pendingEntry before storing.
+     */
+    async set(cacheKey, pendingEntry) {
+        log.debug(`SET: ${cacheKey}`);
+        try {
+            // CRITICAL: Await the pending entry
+            const entry = await pendingEntry;
+            // TODO: Remove this diagnostic logging once Next.js fixes the empty tags bug
+            // Diagnostic logging for empty tags issue
+            // See: https://github.com/vercel/next.js/issues/78864
+            // See: docs/known-issues-nextjs16.md
+            const tagsLength = entry.tags?.length ?? 0;
+            if (tagsLength === 0) {
+                // Use info level so this is gated behind CACHE_DEBUG
+                log.info(`[EMPTY_TAGS_BUG] SET ${cacheKey}: Next.js passed empty tags array. ` +
+                    `This is a known Next.js bug - cacheTag() values are not propagated to cacheHandlers.set(). ` +
+                    `See: https://github.com/vercel/next.js/issues/78864`);
+            }
+            log.info(`SET entry structure for ${cacheKey}:`, {
+                hasTags: !!entry.tags,
+                tags: entry.tags,
+                tagsLength,
+                stale: entry.stale,
+                revalidate: entry.revalidate,
+                expire: entry.expire,
+                timestamp: entry.timestamp,
+                hasValue: !!entry.value,
+                entryKeys: Object.keys(entry),
+            });
+            const serialized = await serializeUseCacheEntry(entry);
+            const filePath = this.getCacheFilePath(cacheKey);
+            fs.writeFileSync(filePath, JSON.stringify(serialized, null, 2), 'utf-8');
+            log.debug(`Cached ${cacheKey}`);
+        }
+        catch (error) {
+            log.error(`Error setting cache for key ${cacheKey}:`, error);
+        }
+    }
+    /**
+     * Synchronize tag state from external source.
+     * For file-based handler, this reloads from disk.
+     */
+    async refreshTags() {
+        log.debug('REFRESH TAGS');
+        this.loadTagTimestamps();
+    }
+    /**
+     * Return maximum revalidation timestamp for given tags.
+     */
+    async getExpiration(tags) {
+        let maxTimestamp = 0;
+        for (const tag of tags) {
+            const timestamp = this.tagTimestamps.get(tag) ?? 0;
+            if (timestamp > maxTimestamp) {
+                maxTimestamp = timestamp;
+            }
+        }
+        log.debug(`GET EXPIRATION for [${tags.join(', ')}]: ${maxTimestamp}`);
+        return maxTimestamp;
+    }
+    /**
+     * Register the surrogate keys associated with a path.
+     * Called by withSurrogateKey via globalThis Symbol.
+     */
+    registerPathTags(path, surrogateKeys) {
+        this.pathToSurrogateKeys.set(path, surrogateKeys);
+        log.debug(`Registered path tags: ${path} → [${surrogateKeys.join(', ')}]`);
+    }
+    /**
+     * Invalidate cache entries with matching tags.
+     * Also triggers CDN edge cache clearing via Surrogate-Key if configured.
+     */
+    async updateTags(tags, durations) {
+        log.debug(`UPDATE TAGS: [${tags.join(', ')}]`);
+        if (tags.length === 0) {
+            return;
+        }
+        const now = Date.now();
+        for (const tag of tags) {
+            this.tagTimestamps.set(tag, now);
+        }
+        this.saveTagTimestamps();
+        // Clear edge cache if configured
+        if (this.edgeCacheClearer) {
+            const explicitTags = [];
+            const pathTags = [];
+            for (const tag of tags) {
+                if (tag.startsWith(NEXTJS_PATH_TAG_PREFIX)) {
+                    pathTags.push(tag);
+                }
+                else {
+                    explicitTags.push(tag);
+                }
+            }
+            if (explicitTags.length > 0) {
+                this.edgeCacheClearer.clearKeysInBackground(explicitTags, `use-cache tag invalidation: ${explicitTags.join(', ')}`);
+            }
+            if (pathTags.length > 0) {
+                const resolvedKeys = [];
+                const unresolvedPaths = [];
+                for (const pathTag of pathTags) {
+                    const p = pathTag.substring(NEXTJS_PATH_TAG_PREFIX.length);
+                    const surrogateKeys = this.pathToSurrogateKeys.get(p);
+                    if (surrogateKeys && surrogateKeys.length > 0) {
+                        resolvedKeys.push(...surrogateKeys);
+                    }
+                    else {
+                        unresolvedPaths.push(p);
+                    }
+                }
+                if (resolvedKeys.length > 0) {
+                    this.edgeCacheClearer.clearKeysInBackground(resolvedKeys, `path revalidation (resolved): ${resolvedKeys.join(', ')}`);
+                }
+                if (unresolvedPaths.length > 0) {
+                    this.edgeCacheClearer.clearPathsInBackground(unresolvedPaths, `path revalidation (fallback): ${unresolvedPaths.join(', ')}`);
+                }
+            }
+        }
+    }
+    /**
+     * Get cache statistics for the use-cache entries.
+     * Returns information about all valid (non-expired) cache entries.
+     */
+    async getStats() {
+        log.debug('GET STATS');
+        const entries = [];
+        const keys = [];
+        try {
+            if (!fs.existsSync(this.cacheDir)) {
+                return { size: 0, entries: [], keys: [] };
+            }
+            const files = fs.readdirSync(this.cacheDir);
+            for (const file of files) {
+                // Skip tags file and non-JSON files
+                if (file === '_tags.json' || !file.endsWith('.json')) {
+                    continue;
+                }
+                try {
+                    const filePath = path.join(this.cacheDir, file);
+                    const data = fs.readFileSync(filePath, 'utf-8');
+                    const stored = JSON.parse(data);
+                    // Reconstruct the key from the filename (reverse of sanitization)
+                    const key = file.replace('.json', '');
+                    // Deserialize to check expiration
+                    const entry = deserializeUseCacheEntry(stored);
+                    // Skip expired entries
+                    if (this.isExpired(entry)) {
+                        continue;
+                    }
+                    // Get file stats for size
+                    const fileStat = fs.statSync(filePath);
+                    const entryInfo = {
+                        key,
+                        tags: stored.tags || [],
+                        type: 'use-cache',
+                        lastModified: new Date(entry.timestamp).toISOString(),
+                        size: fileStat.size,
+                        revalidate: entry.revalidate,
+                        stale: entry.stale,
+                        expire: entry.expire,
+                    };
+                    entries.push(entryInfo);
+                    keys.push(key);
+                }
+                catch (error) {
+                    log.warn(`Error reading cache file ${file}:`, error);
+                }
+            }
+        }
+        catch (error) {
+            log.error('Error getting cache stats:', error);
+        }
+        log.debug(`Found ${entries.length} valid cache entries`);
+        return {
+            size: entries.length,
+            entries,
+            keys,
+        };
+    }
+}
+export default UseCacheFileHandler;
+//# sourceMappingURL=file-handler.js.map

package/dist/use-cache/file-handler.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"file-handler.js","sourceRoot":"","sources":["../../src/use-cache/file-handler.ts"],"names":[],"mappings":"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"}

package/dist/use-cache/gcs-handler.d.ts

@@ -0,0 +1,64 @@
+import type { UseCacheEntry, UseCacheHandler, UseCacheStats } from './types.js';
+/**
+ * Google Cloud Storage cache handler for Next.js 16 'use cache' directive.
+ * Implements the cacheHandlers (plural) interface.
+ *
+ * Suitable for:
+ * - Production/Pantheon environments
+ * - Multi-instance deployments requiring shared cache
+ */
+export declare class UseCacheGcsHandler implements UseCacheHandler {
+    private readonly bucket;
+    private readonly cachePrefix;
+    private readonly tagsKey;
+    private readonly edgeCacheClearer;
+    private tagTimestamps;
+    private pathToSurrogateKeys;
+    private initialized;
+    private initPromise;
+    constructor();
+    private initialize;
+    private ensureInitialized;
+    private loadTagTimestamps;
+    private saveTagTimestamps;
+    private getCacheKey;
+    /**
+     * Check if an entry is expired based on revalidate time.
+     */
+    private isExpired;
+    /**
+     * Retrieve a cache entry.
+     */
+    get(cacheKey: string, softTags: string[]): Promise<UseCacheEntry | undefined>;
+    /**
+     * Store a cache entry.
+     * CRITICAL: Must await pendingEntry before storing.
+     */
+    set(cacheKey: string, pendingEntry: Promise<UseCacheEntry>): Promise<void>;
+    /**
+     * Synchronize tag state from external source.
+     * Reloads tag timestamps from GCS.
+     */
+    refreshTags(): Promise<void>;
+    /**
+     * Return maximum revalidation timestamp for given tags.
+     */
+    getExpiration(tags: string[]): Promise<number>;
+    /**
+     * Register the surrogate keys (explicit cacheTag values) associated with a path.
+     * Called by withSurrogateKey when tags are captured during a cache HIT,
+     * enabling revalidatePath to resolve the correct CDN surrogate keys.
+     */
+    registerPathTags(path: string, surrogateKeys: string[]): void;
+    /**
+     * Invalidate cache entries with matching tags.
+     */
+    updateTags(tags: string[], durations: number[]): Promise<void>;
+    /**
+     * Get cache statistics for the use-cache entries in GCS.
+     * Returns information about all valid (non-expired) cache entries.
+     */
+    getStats(): Promise<UseCacheStats>;
+}
+export default UseCacheGcsHandler;
+//# sourceMappingURL=gcs-handler.d.ts.map

package/dist/use-cache/gcs-handler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"gcs-handler.d.ts","sourceRoot":"","sources":["../../src/use-cache/gcs-handler.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,aAAa,EAAE,eAAe,EAAE,aAAa,EAAqB,MAAM,YAAY,CAAC;AAiFnG;;;;;;;GAOG;AACH,qBAAa,kBAAmB,YAAW,eAAe;IACxD,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAChC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAS;IACrC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAwB;IACzD,OAAO,CAAC,aAAa,CAAkC;IACvD,OAAO,CAAC,mBAAmB,CAAoC;IAC/D,OAAO,CAAC,WAAW,CAAkB;IACrC,OAAO,CAAC,WAAW,CAA8B;;YA2BnC,UAAU;YAMV,iBAAiB;YAOjB,iBAAiB;YA6BjB,iBAAiB;IAY/B,OAAO,CAAC,WAAW;IAMnB;;OAEG;IACH,OAAO,CAAC,SAAS;IAqBjB;;OAEG;IACG,GAAG,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,aAAa,GAAG,SAAS,CAAC;IAmDnF;;;OAGG;IACG,GAAG,CAAC,QAAQ,EAAE,MAAM,EAAE,YAAY,EAAE,OAAO,CAAC,aAAa,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;IA4ChF;;;OAGG;IACG,WAAW,IAAI,OAAO,CAAC,IAAI,CAAC;IAKlC;;OAEG;IACG,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC;IAcpD;;;;OAIG;IACH,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,EAAE,GAAG,IAAI;IAK7D;;OAEG;IACG,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,SAAS,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAiEpE;;;OAGG;IACG,QAAQ,IAAI,OAAO,CAAC,aAAa,CAAC;CAsEzC;AAED,eAAe,kBAAkB,CAAC"}