@trieb.work/nextjs-turbo-redis-cache 1.10.0 → 1.11.0-beta.1

package/src/CacheComponentsHandler.ts

@@ -0,0 +1,471 @@
+import { commandOptions, createClient } from 'redis';
+import type { RedisClientOptions } from 'redis';
+import {
+  Client,
+  CreateRedisStringsHandlerOptions,
+  redisErrorHandler,
+} from './RedisStringsHandler';
+import { SyncedMap } from './SyncedMap';
+import { debug } from './utils/debug';
+
+export interface CacheComponentsEntry {
+  value: ReadableStream<Uint8Array>;
+  tags: string[];
+  stale: number;
+  timestamp: number;
+  expire: number;
+  revalidate: number;
+}
+
+export interface CacheComponentsHandler {
+  get(
+    cacheKey: string,
+    softTags: string[],
+  ): Promise<CacheComponentsEntry | undefined>;
+  set(
+    cacheKey: string,
+    pendingEntry: Promise<CacheComponentsEntry>,
+  ): Promise<void>;
+  refreshTags(): Promise<void>;
+  getExpiration(tags: string[]): Promise<number>;
+  updateTags(tags: string[], durations?: { expire?: number }): Promise<void>;
+}
+
+type StoredCacheEntry = Omit<CacheComponentsEntry, 'value'> & {
+  value: Uint8Array | string;
+};
+
+const REVALIDATED_TAGS_KEY = '__cacheComponents_revalidated_tags__';
+const SHARED_TAGS_KEY = '__cacheComponents_sharedTags__';
+
+let killContainerOnErrorCount = 0;
+
+export type CreateCacheComponentsHandlerOptions =
+  CreateRedisStringsHandlerOptions;
+
+async function streamToBuffer(
+  stream: ReadableStream<Uint8Array>,
+): Promise<Uint8Array> {
+  const reader = stream.getReader();
+  const chunks: Uint8Array[] = [];
+
+  while (true) {
+    const { value, done } = await reader.read();
+    if (done) break;
+    if (value) {
+      chunks.push(value);
+    }
+  }
+
+  if (chunks.length === 1) {
+    return chunks[0];
+  }
+
+  const totalLength = chunks.reduce((sum, chunk) => sum + chunk.byteLength, 0);
+  const result = new Uint8Array(totalLength);
+  let offset = 0;
+  for (const chunk of chunks) {
+    result.set(chunk, offset);
+    offset += chunk.byteLength;
+  }
+  return result;
+}
+
+function bufferToReadableStream(
+  buffer: Uint8Array,
+): ReadableStream<Uint8Array> {
+  return new ReadableStream<Uint8Array>({
+    start(controller) {
+      controller.enqueue(buffer);
+      controller.close();
+    },
+  });
+}
+
+class RedisCacheComponentsHandler implements CacheComponentsHandler {
+  private client: Client;
+  private revalidatedTagsMap: SyncedMap<number>;
+  private sharedTagsMap: SyncedMap<string[]>;
+  private keyPrefix: string;
+  private getTimeoutMs: number;
+
+  constructor({
+    redisUrl = process.env.REDIS_URL
+      ? process.env.REDIS_URL
+      : process.env.REDISHOST
+        ? `redis://${process.env.REDISHOST}:${process.env.REDISPORT}`
+        : 'redis://localhost:6379',
+    database = process.env.VERCEL_ENV === 'production' ? 0 : 1,
+    keyPrefix = process.env.VERCEL_URL || 'UNDEFINED_URL_',
+    getTimeoutMs = process.env.REDIS_COMMAND_TIMEOUT_MS
+      ? (Number.parseInt(process.env.REDIS_COMMAND_TIMEOUT_MS) ?? 500)
+      : 500,
+    revalidateTagQuerySize = 250,
+    avgResyncIntervalMs = 60 * 60 * 1_000,
+    socketOptions,
+    clientOptions,
+    killContainerOnErrorThreshold = process.env
+      .KILL_CONTAINER_ON_ERROR_THRESHOLD
+      ? (Number.parseInt(process.env.KILL_CONTAINER_ON_ERROR_THRESHOLD) ?? 0)
+      : 0,
+  }: CreateCacheComponentsHandlerOptions) {
+    try {
+      this.keyPrefix = keyPrefix;
+      this.getTimeoutMs = getTimeoutMs;
+
+      this.client = createClient({
+        url: redisUrl,
+        pingInterval: 10_000,
+        ...(database !== 0 ? { database } : {}),
+        ...(socketOptions
+          ? { socket: { ...socketOptions } as RedisClientOptions['socket'] }
+          : {}),
+        ...(clientOptions || {}),
+      });
+
+      this.client.on('error', (error) => {
+        console.error(
+          'RedisCacheComponentsHandler client error',
+          error,
+          killContainerOnErrorCount++,
+        );
+        setTimeout(
+          () =>
+            this.client.connect().catch((err) => {
+              console.error(
+                'Failed to reconnect RedisCacheComponentsHandler client after connection loss:',
+                err,
+              );
+            }),
+          1000,
+        );
+        if (
+          killContainerOnErrorThreshold > 0 &&
+          killContainerOnErrorCount >= killContainerOnErrorThreshold
+        ) {
+          console.error(
+            'RedisCacheComponentsHandler client error threshold reached, disconnecting and exiting (please implement a restart process/container watchdog to handle this error)',
+            error,
+            killContainerOnErrorCount++,
+          );
+          this.client.disconnect();
+          this.client.quit();
+          setTimeout(() => {
+            process.exit(1);
+          }, 500);
+        }
+      });
+
+      this.client
+        .connect()
+        .then(() => {
+          debug('green', 'RedisCacheComponentsHandler client connected.');
+        })
+        .catch(() => {
+          this.client.connect().catch((error) => {
+            console.error(
+              'Failed to connect RedisCacheComponentsHandler client:',
+              error,
+            );
+            this.client.disconnect();
+            throw error;
+          });
+        });
+
+      const filterKeys = (key: string): boolean =>
+        key !== REVALIDATED_TAGS_KEY && key !== SHARED_TAGS_KEY;
+
+      this.revalidatedTagsMap = new SyncedMap<number>({
+        client: this.client,
+        keyPrefix,
+        redisKey: REVALIDATED_TAGS_KEY,
+        database,
+        querySize: revalidateTagQuerySize,
+        filterKeys,
+        resyncIntervalMs:
+          avgResyncIntervalMs +
+          avgResyncIntervalMs / 10 +
+          Math.random() * (avgResyncIntervalMs / 10),
+      });
+
+      this.sharedTagsMap = new SyncedMap<string[]>({
+        client: this.client,
+        keyPrefix,
+        redisKey: SHARED_TAGS_KEY,
+        database,
+        querySize: revalidateTagQuerySize,
+        filterKeys,
+        resyncIntervalMs:
+          avgResyncIntervalMs -
+          avgResyncIntervalMs / 10 +
+          Math.random() * (avgResyncIntervalMs / 10),
+      });
+    } catch (error) {
+      console.error('RedisCacheComponentsHandler constructor error', error);
+      throw error;
+    }
+  }
+
+  private async assertClientIsReady(): Promise<void> {
+    if (!this.client.isReady && !this.client.isOpen) {
+      await this.client.connect().catch((error) => {
+        console.error(
+          'RedisCacheComponentsHandler assertClientIsReady reconnect error:',
+          error,
+        );
+        throw error;
+      });
+    }
+    await Promise.all([
+      this.revalidatedTagsMap.waitUntilReady(),
+      this.sharedTagsMap.waitUntilReady(),
+    ]);
+  }
+
+  private async computeMaxRevalidation(tags: string[]): Promise<number> {
+    let max = 0;
+    for (const tag of tags) {
+      const ts = this.revalidatedTagsMap.get(tag);
+      if (ts && ts > max) {
+        max = ts;
+      }
+    }
+    return max;
+  }
+
+  async get(
+    cacheKey: string,
+    softTags: string[],
+  ): Promise<CacheComponentsEntry | undefined> {
+    // Construct the full Redis key
+    // For cache components, Next.js provides the full key including environment prefix
+    // We prepend our keyPrefix for multi-tenant isolation
+    const redisKey = `${this.keyPrefix}${cacheKey}`;
+
+    try {
+      await this.assertClientIsReady();
+
+      const serialized = await redisErrorHandler(
+        'RedisCacheComponentsHandler.get(), operation: get ' +
+          this.getTimeoutMs +
+          'ms ' +
+          redisKey,
+        this.client.get(
+          commandOptions({ signal: AbortSignal.timeout(this.getTimeoutMs) }),
+          redisKey,
+        ),
+      );
+
+      if (!serialized) {
+        return undefined;
+      }
+
+      const stored: StoredCacheEntry = JSON.parse(serialized);
+      const now = Date.now();
+
+      // expire is a duration in seconds, calculate absolute expiry time
+      const expiryTime = stored.timestamp + stored.expire * 1000;
+      if (
+        Number.isFinite(stored.expire) &&
+        stored.expire > 0 &&
+        now > expiryTime
+      ) {
+        await this.client.unlink(redisKey).catch(() => {});
+        await this.sharedTagsMap.delete(cacheKey).catch(() => {});
+        return undefined;
+      }
+
+      const maxRevalidation = await this.computeMaxRevalidation([
+        ...(stored.tags || []),
+        ...(softTags || []),
+      ]);
+
+      if (maxRevalidation > 0 && maxRevalidation > stored.timestamp) {
+        await this.client.unlink(redisKey).catch(() => {});
+        await this.sharedTagsMap.delete(cacheKey).catch(() => {});
+        return undefined;
+      }
+
+      const valueBuffer =
+        typeof stored.value === 'string'
+          ? new Uint8Array(Buffer.from(stored.value, 'base64'))
+          : stored.value;
+
+      return {
+        ...stored,
+        value: bufferToReadableStream(valueBuffer),
+      };
+    } catch (error) {
+      console.error(
+        'RedisCacheComponentsHandler.get() Error occurred while getting cache entry. Returning undefined so site can continue to serve content while cache is disabled. The original error was:',
+        error,
+        killContainerOnErrorCount++,
+      );
+      return undefined;
+    }
+  }
+
+  async set(
+    cacheKey: string,
+    pendingEntry: Promise<CacheComponentsEntry>,
+  ): Promise<void> {
+    try {
+      await this.assertClientIsReady();
+
+      const entry = await pendingEntry;
+
+      const [storeStream] = entry.value.tee();
+
+      // Don't mutate entry.value as Next.js may still be using it internally
+      // entry.value = forwardStream;
+
+      const buffer = await streamToBuffer(storeStream);
+
+      const stored: StoredCacheEntry = {
+        value: Buffer.from(buffer).toString('base64'),
+        tags: entry.tags || [],
+        stale: entry.stale,
+        timestamp: entry.timestamp,
+        expire: entry.expire,
+        revalidate: entry.revalidate,
+      };
+
+      let serialized: string;
+      try {
+        const cleanStored = {
+          value: stored.value,
+          tags: Array.isArray(stored.tags) ? [...stored.tags] : [],
+          stale: Number(stored.stale),
+          timestamp: Number(stored.timestamp),
+          expire: Number(stored.expire),
+          revalidate: Number(stored.revalidate),
+        };
+        serialized = JSON.stringify(cleanStored);
+      } catch (jsonError) {
+        console.error('JSON.stringify error:', jsonError);
+        console.error('Stored object:', stored);
+        throw jsonError;
+      }
+
+      // expire is already a duration in seconds, use it directly
+      const ttlSeconds =
+        Number.isFinite(stored.expire) && stored.expire > 0
+          ? Math.floor(stored.expire)
+          : undefined;
+
+      const redisKey = `${this.keyPrefix}${cacheKey}`;
+
+      const setOperation = redisErrorHandler(
+        'RedisCacheComponentsHandler.set(), operation: set ' + redisKey,
+        this.client.set(redisKey, serialized, {
+          ...(ttlSeconds ? { EX: ttlSeconds } : {}),
+        }),
+      );
+
+      let tagsOperation: Promise<void> | undefined;
+      const tags = stored.tags || [];
+      if (tags.length > 0) {
+        const currentTags = this.sharedTagsMap.get(cacheKey);
+        const currentIsSameAsNew =
+          currentTags?.length === tags.length &&
+          currentTags.every((v) => tags.includes(v)) &&
+          tags.every((v) => currentTags!.includes(v));
+
+        if (!currentIsSameAsNew) {
+          tagsOperation = this.sharedTagsMap.set(cacheKey, [...tags]);
+        }
+      }
+
+      await Promise.all([setOperation, tagsOperation]);
+    } catch (error) {
+      console.error(
+        'RedisCacheComponentsHandler.set() Error occurred while setting cache entry. The original error was:',
+        error,
+        killContainerOnErrorCount++,
+      );
+      throw error;
+    }
+  }
+
+  async refreshTags(): Promise<void> {
+    await this.assertClientIsReady();
+  }
+
+  async getExpiration(tags: string[]): Promise<number> {
+    try {
+      await this.assertClientIsReady();
+      return this.computeMaxRevalidation(tags || []);
+    } catch (error) {
+      console.error(
+        'RedisCacheComponentsHandler.getExpiration() Error occurred while getting expiration for tags. The original error was:',
+        error,
+      );
+      return 0;
+    }
+  }
+
+  async updateTags(
+    tags: string[],
+    _durations?: { expire?: number },
+  ): Promise<void> {
+    try {
+      // Mark optional argument as used to satisfy lint rules while keeping the signature
+      void _durations;
+      await this.assertClientIsReady();
+      const now = Date.now();
+
+      const tagsSet = new Set(tags || []);
+
+      for (const tag of tagsSet) {
+        await this.revalidatedTagsMap.set(tag, now);
+      }
+
+      const keysToDelete: Set<string> = new Set();
+
+      for (const [key, storedTags] of this.sharedTagsMap.entries()) {
+        if (storedTags.some((tag) => tagsSet.has(tag))) {
+          keysToDelete.add(key);
+        }
+      }
+
+      if (keysToDelete.size === 0) {
+        return;
+      }
+
+      const cacheKeys = Array.from(keysToDelete);
+
+      // Construct full Redis keys (same format as in get/set)
+      const fullRedisKeys = cacheKeys.map((key) => `${this.keyPrefix}${key}`);
+
+      await redisErrorHandler(
+        'RedisCacheComponentsHandler.updateTags(), operation: unlink',
+        this.client.unlink(fullRedisKeys),
+      );
+
+      // Delete from sharedTagsMap
+      const deleteTagsOperation = this.sharedTagsMap.delete(cacheKeys);
+      await deleteTagsOperation;
+    } catch (error) {
+      console.error(
+        'RedisCacheComponentsHandler.updateTags() Error occurred while updating tags. The original error was:',
+        error,
+        killContainerOnErrorCount++,
+      );
+      throw error;
+    }
+  }
+}
+
+let singletonHandler: CacheComponentsHandler | undefined;
+
+export function getRedisCacheComponentsHandler(
+  options: CreateCacheComponentsHandlerOptions = {},
+): CacheComponentsHandler {
+  if (!singletonHandler) {
+    singletonHandler = new RedisCacheComponentsHandler(options);
+  }
+  return singletonHandler;
+}
+
+export const redisCacheHandler: CacheComponentsHandler =
+  getRedisCacheComponentsHandler();

package/src/index.test.ts

@@ -2,6 +2,6 @@ import { describe, it } from 'vitest';
 
 describe('Example Test', () => {
   it('should work correctly', () => {
-    console.log("TODO tests")
+    console.log('TODO tests');
   });
 });

package/src/index.ts

@@ -2,3 +2,8 @@ import CachedHandler from './CachedHandler';
 export default CachedHandler;
 import RedisStringsHandler from './RedisStringsHandler';
 export { RedisStringsHandler };
+import {
+  redisCacheHandler,
+  getRedisCacheComponentsHandler,
+} from './CacheComponentsHandler';
+export { redisCacheHandler, getRedisCacheComponentsHandler };

package/test/cache-components/cache-components.integration.spec.ts

@@ -0,0 +1,188 @@
+import { describe, it, expect, beforeAll, afterAll } from 'vitest';
+import { spawn, ChildProcess } from 'child_process';
+import { createClient, RedisClientType } from 'redis';
+import path from 'path';
+
+const PORT = Number(process.env.CACHE_COMPONENTS_PORT || '3065');
+const BASE_URL = `http://localhost:${PORT}`;
+
+describe('Next.js 16 Cache Components Integration', () => {
+  let nextProcess: ChildProcess;
+  let redisClient: RedisClientType;
+  let keyPrefix: string;
+
+  beforeAll(async () => {
+    // Connect to Redis
+    redisClient = createClient({
+      url: process.env.REDIS_URL || 'redis://localhost:6379',
+      database: 1,
+    });
+    await redisClient.connect();
+
+    // Generate unique key prefix for this test run
+    keyPrefix = `cache-components-test-${Math.random().toString(36).substring(7)}`;
+    process.env.VERCEL_URL = keyPrefix;
+
+    // Build and start Next.js app
+    const appDir = path.join(
+      __dirname,
+      '..',
+      'integration',
+      'next-app-16-1-1-cache-components',
+    );
+
+    console.log('Installing Next.js app dependencies...');
+    await new Promise<void>((resolve, reject) => {
+      const installProcess = spawn('pnpm', ['install'], {
+        cwd: appDir,
+        stdio: 'inherit',
+      });
+
+      installProcess.on('close', (code) => {
+        if (code === 0) resolve();
+        else reject(new Error(`Install failed with code ${code}`));
+      });
+    });
+
+    console.log('Building Next.js app...');
+    await new Promise<void>((resolve, reject) => {
+      const buildProcess = spawn('pnpm', ['build'], {
+        cwd: appDir,
+        stdio: 'inherit',
+      });
+
+      buildProcess.on('close', (code) => {
+        if (code === 0) resolve();
+        else reject(new Error(`Build failed with code ${code}`));
+      });
+    });
+
+    console.log('Starting Next.js app...');
+    nextProcess = spawn('pnpm', ['start', '-p', PORT.toString()], {
+      cwd: appDir,
+      env: { ...process.env, VERCEL_URL: keyPrefix },
+    });
+
+    // Wait for server to be ready
+    await new Promise((resolve) => setTimeout(resolve, 3000));
+  }, 120000);
+
+  afterAll(async () => {
+    // Clean up Redis keys
+    const keys = await redisClient.keys(`${keyPrefix}*`);
+    if (keys.length > 0) {
+      await redisClient.del(keys);
+    }
+    await redisClient.quit();
+
+    // Kill Next.js process
+    if (nextProcess) {
+      nextProcess.kill();
+    }
+  });
+
+  describe('Basic use cache functionality', () => {
+    it('should cache data and return same counter value on subsequent requests', async () => {
+      // First request
+      const res1 = await fetch(`${BASE_URL}/api/cached-static-fetch`);
+      const data1 = await res1.json();
+
+      expect(data1.counter).toBe(1);
+
+      // Second request should return cached data
+      const res2 = await fetch(`${BASE_URL}/api/cached-static-fetch`);
+      const data2 = await res2.json();
+
+      expect(data2.counter).toBe(1); // Same counter value
+      expect(data2.timestamp).toBe(data1.timestamp); // Same timestamp
+    });
+
+    it('should store cache entry in Redis', async () => {
+      await fetch(`${BASE_URL}/api/cached-static-fetch`);
+
+      // Check Redis for cache keys
+      const keys = await redisClient.keys(`${keyPrefix}*`);
+      expect(keys.length).toBeGreaterThan(0);
+    });
+  });
+
+  describe('cacheTag functionality', () => {
+    it('should cache data with tags', async () => {
+      const res1 = await fetch(`${BASE_URL}/api/cached-with-tag`);
+      const data1 = await res1.json();
+
+      expect(data1.counter).toBeDefined();
+
+      // Second request should return cached data
+      const res2 = await fetch(`${BASE_URL}/api/cached-with-tag`);
+      const data2 = await res2.json();
+
+      expect(data2.counter).toBe(data1.counter);
+    });
+
+    it('should invalidate cache when tag is revalidated (Stale while revalidate)', async () => {
+      // Get initial cached data
+      const res1 = await fetch(`${BASE_URL}/api/cached-with-tag`);
+      const data1 = await res1.json();
+
+      // Revalidate the tag
+      await fetch(`${BASE_URL}/api/revalidate-tag`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ tag: 'test-tag' }),
+      });
+
+      // The cache should be invalidated - verify by making multiple requests
+      // until we get fresh data (with retries for async revalidation)
+      let freshDataReceived = false;
+      // Next.js tag revalidation can be async and may take longer under some runtimes.
+      // Use a more tolerant window to avoid flaky failures.
+      for (let i = 0; i < 60; i++) {
+        await new Promise((resolve) => setTimeout(resolve, 500));
+        const res = await fetch(`${BASE_URL}/api/cached-with-tag`);
+        const data = await res.json();
+
+        if (
+          data.counter !== data1.counter ||
+          data.timestamp !== data1.timestamp
+        ) {
+          freshDataReceived = true;
+          break;
+        }
+      }
+
+      expect(freshDataReceived).toBe(true);
+    }, 20_000);
+  });
+
+  describe('Redis cache handler integration', () => {
+    it('should call cache handler get and set methods', async () => {
+      // Make request to trigger cache (don't clear first)
+      await fetch(`${BASE_URL}/api/cached-static-fetch`);
+
+      // Verify Redis has the cached data
+      const redisKeys = await redisClient.keys(`${keyPrefix}*`);
+      expect(redisKeys.length).toBeGreaterThan(0);
+
+      // Filter out hash keys (sharedTagsMap) and only check string keys (cache entries)
+      // Try to get each key and verify at least one is a string value
+      let foundStringKey = false;
+      for (const key of redisKeys) {
+        try {
+          const type = await redisClient.type(key);
+          if (type === 'string') {
+            const cachedValue = await redisClient.get(key);
+            if (cachedValue) {
+              foundStringKey = true;
+              expect(cachedValue).toBeTruthy();
+              break;
+            }
+          }
+        } catch (e) {
+          // Skip non-string keys
+        }
+      }
+      expect(foundStringKey).toBe(true);
+    });
+  });
+});

package/test/integration/next-app-15-4-7/next.config.js

@@ -1,6 +1,9 @@
 /** @type {import('next').NextConfig} */
 const nextConfig = {
   cacheHandler: require.resolve('@trieb.work/nextjs-turbo-redis-cache'),
+  turbopack: {
+    root: __dirname,
+  },
 };
 
 module.exports = nextConfig;

package/test/integration/next-app-15-4-7/pnpm-lock.yaml

@@ -471,7 +471,7 @@ packages:
   '@trieb.work/nextjs-turbo-redis-cache@file:../../..':
     resolution: {directory: ../../.., type: directory}
     peerDependencies:
-      next: '>=15.0.3 <= 15.4.7'
+      next: '>=15.0.3 <16.2.0'
       redis: 4.7.0
 
   '@tybys/wasm-util@0.9.0':

package/test/integration/next-app-16-0-3/next.config.ts

@@ -2,6 +2,9 @@ import type { NextConfig } from 'next';
 
 const nextConfig: NextConfig = {
   cacheHandler: require.resolve('@trieb.work/nextjs-turbo-redis-cache'),
+  turbopack: {
+    root: __dirname,
+  },
 };
 
 export default nextConfig;