@trieb.work/nextjs-turbo-redis-cache 1.15.0 → 1.16.0

package/test/nextjs-test-projects/next-pages-16-2-6/src/pages/api/revalidate.ts

@@ -0,0 +1,24 @@
+import type { NextApiRequest, NextApiResponse } from 'next';
+
+// On-demand revalidation endpoint: res.revalidate(path) re-renders the page
+// and writes the fresh entry through the cache handler, so all instances
+// sharing the same Redis pick it up.
+export default async function handler(
+  req: NextApiRequest,
+  res: NextApiResponse,
+) {
+  const path = req.query.path;
+  if (typeof path !== 'string') {
+    return res
+      .status(400)
+      .json({ revalidated: false, error: 'Missing ?path= query parameter' });
+  }
+  try {
+    await res.revalidate(path);
+    return res.json({ revalidated: true, path });
+  } catch (err) {
+    return res
+      .status(500)
+      .json({ revalidated: false, path, error: String(err) });
+  }
+}

package/test/nextjs-test-projects/next-pages-16-2-6/src/pages/index.tsx

@@ -0,0 +1,11 @@
+export default function Home() {
+  return (
+    <main>
+      <h1>Pages Router test app</h1>
+      <p>
+        Fixture for testing the Redis cache handler with the Next.js Pages
+        Router (PAGES, REDIRECT and notFound cache entries).
+      </p>
+    </main>
+  );
+}

package/test/nextjs-test-projects/next-pages-16-2-6/src/pages/isr/[slug].tsx

@@ -0,0 +1,49 @@
+import type { GetStaticPaths, GetStaticProps } from 'next';
+
+type Props = { slug: string; timestamp: number; counter: number };
+
+// Per-process regeneration counter. Two server instances of the same build
+// have independent counters, while the timestamp proves cross-instance
+// freshness after on-demand revalidation.
+let regenerationCounter = 0;
+
+export default function IsrPage({ slug, timestamp, counter }: Props) {
+  return (
+    <main>
+      <h1>ISR page</h1>
+      <p>Slug: {slug}</p>
+      <p>Timestamp: {timestamp}</p>
+      <p>Counter: {counter}</p>
+    </main>
+  );
+}
+
+export const getStaticPaths: GetStaticPaths = async () => {
+  return {
+    paths: [{ params: { slug: 'prebuilt' } }],
+    fallback: 'blocking',
+  };
+};
+
+// revalidate is set high (300s) so that natural ISR regeneration does not
+// interfere with the on-demand revalidation (res.revalidate) tests.
+export const getStaticProps: GetStaticProps<Props> = async (context) => {
+  const slug = context.params?.slug as string;
+
+  if (slug === 'not-found') {
+    return { notFound: true, revalidate: 300 };
+  }
+
+  if (slug === 'redirect') {
+    return {
+      redirect: { destination: '/static-forever', permanent: false },
+      revalidate: 300,
+    };
+  }
+
+  regenerationCounter += 1;
+  return {
+    props: { slug, timestamp: Date.now(), counter: regenerationCounter },
+    revalidate: 300,
+  };
+};

package/test/nextjs-test-projects/next-pages-16-2-6/src/pages/static-forever.tsx

@@ -0,0 +1,20 @@
+import type { GetStaticProps } from 'next';
+
+type Props = { timestamp: number };
+
+export default function StaticForever({ timestamp }: Props) {
+  return (
+    <main>
+      <h1>Static forever</h1>
+      <p>Timestamp: {timestamp}</p>
+    </main>
+  );
+}
+
+// revalidate is intentionally omitted (revalidate: false): the cache entry
+// must fall through to the defaultStaleAge based TTL in the cache handler.
+export const getStaticProps: GetStaticProps<Props> = async () => {
+  return {
+    props: { timestamp: Date.now() },
+  };
+};

package/test/nextjs-test-projects/next-pages-16-2-6/tsconfig.json

@@ -0,0 +1,34 @@
+{
+  "compilerOptions": {
+    "target": "ES2017",
+    "lib": ["dom", "dom.iterable", "esnext"],
+    "allowJs": true,
+    "skipLibCheck": true,
+    "strict": true,
+    "noEmit": true,
+    "esModuleInterop": true,
+    "module": "esnext",
+    "moduleResolution": "bundler",
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "jsx": "react-jsx",
+    "incremental": true,
+    "plugins": [
+      {
+        "name": "next"
+      }
+    ],
+    "paths": {
+      "@/*": ["./src/*"]
+    }
+  },
+  "include": [
+    "next-env.d.ts",
+    "**/*.ts",
+    "**/*.tsx",
+    ".next/types/**/*.ts",
+    ".next/dev/types/**/*.ts",
+    "**/*.mts"
+  ],
+  "exclude": ["node_modules"]
+}

package/{tests → test/playwright}/update-tag.spec.ts

@@ -1,7 +1,7 @@
 import { test, expect } from '@playwright/test';
 
 // This test assumes the Next 16 app is already running, e.g.:
-//   cd test/integration/next-app-16-0-3 && pnpm dev
+//   cd test/nextjs-test-projects/next-app-16-0-11 && pnpm dev
 // on the same origin as baseURL.
 
 test('button click triggers Server Action using updateTag', async ({

package/test/{integration → vitest/integration}/build-id-prefix.integration.test.ts

@@ -5,7 +5,7 @@ import path from 'path';
 import fs from 'fs';
 import fetch from 'node-fetch';
 
-const NEXT_APP = 'next-app-15-4-7';
+const NEXT_APP = 'next-app-15-4-11';
 const PORT = 3075;
 const BASE_URL = `http://localhost:${PORT}`;
 
@@ -28,7 +28,7 @@ describe('BUILD_ID-based key prefix (Next handlers)', () => {
   let buildId: string;
 
   beforeAll(async () => {
-    appDir = path.join(__dirname, NEXT_APP);
+    appDir = path.join(__dirname, '..', '..', 'nextjs-test-projects', NEXT_APP);
 
     // Ensure clean env so BUILD_ID precedence kicks in
     delete (process.env as Record<string, string | undefined>).KEY_PREFIX;

package/test/{cache-components/cache-components.integration.spec.ts → vitest/integration/cache-components/cache-components.integration.test.ts}

@@ -27,12 +27,16 @@ describe('Next.js 16 Cache Components Integration', () => {
     keyPrefix = `cache-components-test-${Math.random().toString(36).substring(7)}`;
     process.env.VERCEL_URL = keyPrefix;
 
-    // Build and start Next.js app
+    const cacheComponentsApp =
+      process.env.CACHE_COMPONENTS_APP || 'next-app-16-2-6-cache-components';
+
     const appDir = path.join(
       __dirname,
       '..',
-      'integration',
-      'next-app-16-2-3-cache-components',
+      '..',
+      '..',
+      'nextjs-test-projects',
+      cacheComponentsApp,
     );
 
     console.log('Installing Next.js app dependencies...');

package/test/{cache-components/redis-kill-reconnect.spec.ts → vitest/integration/cache-components/redis-kill-reconnect.test.ts}

@@ -1,6 +1,21 @@
 import { describe, it, expect } from 'vitest';
 import { spawn } from 'child_process';
 import path from 'path';
+import { spawnSync } from 'child_process';
+
+function hasContainerRuntime() {
+  const podman = spawnSync('podman', ['--version'], {
+    encoding: 'utf8',
+    timeout: 3_000,
+  });
+  if (!podman.error && (podman.status ?? 1) === 0) return true;
+
+  const docker = spawnSync('docker', ['--version'], {
+    encoding: 'utf8',
+    timeout: 3_000,
+  });
+  return !docker.error && (docker.status ?? 1) === 0;
+}
 
 function runNode(script: string, timeoutMs = 120_000) {
   return new Promise<{ code: number; stdout: string; stderr: string }>(
@@ -26,13 +41,19 @@ function runNode(script: string, timeoutMs = 120_000) {
 }
 
 describe('redis kill/reconnect end-to-end (both handlers)', () => {
-  it('survives redis restart without Socket already opened', async () => {
-    const script = path.join(__dirname, 'scripts', 'redis-kill-reconnect.ts');
+  const runOrSkip = hasContainerRuntime() ? it : it.skip;
 
-    const res = await runNode(script, 180_000);
+  runOrSkip(
+    'survives redis restart without Socket already opened',
+    async () => {
+      const script = path.join(__dirname, 'scripts', 'redis-kill-reconnect.ts');
 
-    expect(res.code).toBe(0);
-    expect(res.stdout).toContain('OK');
-    expect(res.stderr).not.toContain('Socket already opened');
-  }, 180_000);
+      const res = await runNode(script, 180_000);
+
+      expect(res.code).toBe(0);
+      expect(res.stdout).toContain('OK');
+      expect(res.stderr).not.toContain('Socket already opened');
+    },
+    180_000,
+  );
 });

package/test/vitest/integration/cache-components/redis-quit-vs-disconnect.test.ts

@@ -0,0 +1,59 @@
+import { describe, it, expect, beforeAll } from 'vitest';
+import path from 'path';
+import {
+  hasContainerRuntime,
+  runNode,
+  parseResults,
+  type TestResult,
+} from './scripts/redis-test-helpers';
+
+const describeOrSkip = hasContainerRuntime() ? describe : describe.skip;
+
+describeOrSkip('subscriber teardown: quit() vs disconnect()', () => {
+  let results: Map<string, TestResult>;
+  let exitCode: number;
+  let stderr: string;
+
+  beforeAll(async () => {
+    const script = path.join(
+      __dirname,
+      'scripts',
+      'redis-quit-vs-disconnect.ts',
+    );
+    const res = await runNode(script, 60_000);
+    exitCode = res.code;
+    stderr = res.stderr;
+    results = parseResults(res.stdout);
+  }, 60_000);
+
+  it('script exits successfully', () => {
+    if (exitCode !== 0) {
+      process.stderr.write(stderr);
+    }
+    expect(exitCode).toBe(0);
+  });
+
+  it('subscriber clients are ready before outage', () => {
+    const r = results.get('subscribers-ready');
+    expect(r).toBeDefined();
+    expect(r!.pass, r!.detail).toBe(true);
+  });
+
+  it('quit() does not immediately close a subscriber during outage', () => {
+    const r = results.get('quit-does-not-immediately-close');
+    expect(r).toBeDefined();
+    expect(r!.pass, r!.detail).toBe(true);
+  });
+
+  it('disconnect() closes the subscriber immediately during outage', () => {
+    const r = results.get('disconnect-closes-immediately');
+    expect(r).toBeDefined();
+    expect(r!.pass, r!.detail).toBe(true);
+  });
+
+  it('disconnected subscriber stays dead after Redis restarts', () => {
+    const r = results.get('disconnected-client-stays-dead');
+    expect(r).toBeDefined();
+    expect(r!.pass, r!.detail).toBe(true);
+  });
+});

package/test/vitest/integration/cache-components/redis-subscriber-outage.test.ts

@@ -0,0 +1,100 @@
+import { describe, it, expect, beforeAll } from 'vitest';
+import path from 'path';
+import {
+  hasContainerRuntime,
+  runNode,
+  parseResults,
+  type TestResult,
+} from './scripts/redis-test-helpers';
+
+const describeOrSkip = hasContainerRuntime() ? describe : describe.skip;
+
+describeOrSkip('issue #86: subscriber outage recovery', () => {
+  let results: Map<string, TestResult>;
+
+  beforeAll(async () => {
+    const script = path.join(
+      __dirname,
+      'scripts',
+      'redis-subscriber-outage.ts',
+    );
+    const res = await runNode(script, 300_000);
+    // Script always exits 0 (it records pass/fail per sub-test)
+    if (res.code !== 0) {
+      throw new Error(
+        `Script exited with code ${res.code}\nstdout:\n${res.stdout}\nstderr:\n${res.stderr}`,
+      );
+    }
+    results = parseResults(res.stdout);
+  }, 300_000);
+
+  // --- Tests that should PASS (verify correct behavior before outage) ---
+
+  it('PubSub sync works before outage', () => {
+    const r = results.get('pubsub-initial-strings');
+    expect(r).toBeDefined();
+    expect(r!.pass, r!.detail).toBe(true);
+  });
+
+  it('subscriber clients have error listeners before outage', () => {
+    const r = results.get('error-listener-initial');
+    expect(r).toBeDefined();
+    expect(r!.pass, r!.detail).toBe(true);
+  });
+
+  // --- Tests that verify symptoms during outage ---
+
+  it('get() returns null during outage', () => {
+    const r = results.get('get-during-outage');
+    expect(r).toBeDefined();
+    expect(r!.pass, r!.detail).toBe(true);
+  });
+
+  it('heap does not grow excessively during 50 get() calls in outage', () => {
+    const r = results.get('heap-growth-during-outage');
+    expect(r).toBeDefined();
+    expect(r!.pass, r!.detail).toBe(true);
+  });
+
+  it('main client reconnects after Redis restart', () => {
+    const r = results.get('main-client-reconnects');
+    expect(r).toBeDefined();
+    expect(r!.pass, r!.detail).toBe(true);
+  });
+
+  it('get() works after Redis restart (main client path)', () => {
+    const r = results.get('get-after-outage');
+    expect(r).toBeDefined();
+    expect(r!.pass, r!.detail).toBe(true);
+  });
+
+  // --- Tests that reproduce the bug (EXPECTED TO FAIL with current code) ---
+
+  it('PubSub sync works after outage (issue #86 — subscriber never recovers)', () => {
+    const r = results.get('pubsub-after-outage-strings');
+    expect(r).toBeDefined();
+    expect(r!.pass, r!.detail).toBe(true);
+  });
+
+  it('subscriber error listener state after outage (informational)', () => {
+    const r = results.get('error-listener-after-outage');
+    expect(r).toBeDefined();
+    // Informational — always passes. Detail shows whether the listener
+    // survived and whether the subscriber client object was replaced.
+    expect(r!.pass, r!.detail).toBe(true);
+  });
+
+  it('duplicate() call count during outage (informational)', () => {
+    const r = results.get('duplicate-count-during-outage');
+    expect(r).toBeDefined();
+    // Informational — always passes. Detail has the actual count.
+    expect(r!.pass, r!.detail).toBe(true);
+  });
+
+  it('total duplicate() call count (informational)', () => {
+    const r = results.get('duplicate-count-total');
+    expect(r).toBeDefined();
+    // Informational — always passes. Detail has the actual count.
+    expect(r!.pass, r!.detail).toBe(true);
+  });
+});

package/test/{cache-components → vitest/integration/cache-components}/scripts/redis-kill-reconnect.ts

@@ -1,5 +1,7 @@
 import { spawnSync } from 'child_process';
 
+type ContainerRuntime = 'podman' | 'docker';
+
 function sh(cmd: string, args: string[], opts: { timeoutMs?: number } = {}) {
   const res = spawnSync(cmd, args, {
     encoding: 'utf8',
@@ -13,6 +15,26 @@ function sh(cmd: string, args: string[], opts: { timeoutMs?: number } = {}) {
   };
 }
 
+function canRun(cmd: string) {
+  const res = spawnSync(cmd, ['--version'], {
+    encoding: 'utf8',
+    timeout: 3_000,
+  });
+  return !res.error && (res.status ?? 1) === 0;
+}
+
+function detectContainerRuntime(): ContainerRuntime {
+  if (process.env.CONTAINER_RUNTIME === 'podman') return 'podman';
+  if (process.env.CONTAINER_RUNTIME === 'docker') return 'docker';
+
+  if (canRun('podman')) return 'podman';
+  if (canRun('docker')) return 'docker';
+
+  throw new Error(
+    'Neither podman nor docker is available. Install one of them or set CONTAINER_RUNTIME.',
+  );
+}
+
 async function sleep(ms: number) {
   await new Promise((r) => setTimeout(r, ms));
 }
@@ -28,6 +50,7 @@ async function waitUntil(fn: () => Promise<boolean>, timeoutMs = 20_000) {
 }
 
 async function main() {
+  const runtime = detectContainerRuntime();
   const name = `redis-e2e-${Math.random().toString(36).slice(2, 8)}`;
 
   // Pick a free localhost port
@@ -45,12 +68,12 @@ async function main() {
   });
 
   // cleanup
-  sh('podman', ['rm', '-f', name]);
+  sh(runtime, ['rm', '-f', name]);
 
   // Start redis with keyspace notifications enabled (required by SyncedMap)
   {
     const r = sh(
-      'podman',
+      runtime,
       [
         'run',
         '-d',
@@ -75,10 +98,10 @@ async function main() {
   process.env.VERCEL_URL = `e2e-${name}-`;
 
   const { getRedisCacheComponentsHandler } = await import(
-    '../../../src/CacheComponentsHandler'
+    '../../../../../src/CacheComponentsHandler'
   );
   const { default: RedisStringsHandler } = await import(
-    '../../../src/RedisStringsHandler'
+    '../../../../../src/RedisStringsHandler'
   );
 
   // Cache Components handler
@@ -153,14 +176,14 @@ async function main() {
   if (!got) throw new Error('expected cache hit (regular handler)');
 
   // Kill redis
-  sh('podman', ['stop', '-t', '0', name], { timeoutMs: 30_000 });
+  sh(runtime, ['stop', '-t', '0', name], { timeoutMs: 30_000 });
 
   // Wait a bit, then start again
   await sleep(500);
 
   {
     const r = sh(
-      'podman',
+      runtime,
       [
         'run',
         '-d',
@@ -176,7 +199,7 @@ async function main() {
       ],
       { timeoutMs: 60_000 },
     );
-    if (r.code !== 0) throw new Error(`podman run2 failed: ${r.stderr}`);
+    if (r.code !== 0) throw new Error(`${runtime} run2 failed: ${r.stderr}`);
   }
 
   // Should recover (both)
@@ -205,7 +228,7 @@ async function main() {
   } catch {}
 
   // cleanup best effort
-  sh('podman', ['rm', '-f', name]);
+  sh(runtime, ['rm', '-f', name]);
 
   // If we reach here without crashing due to Socket already opened, we're good.
   // (Vitest will check stdout for this line.)

package/test/vitest/integration/cache-components/scripts/redis-quit-vs-disconnect.ts

@@ -0,0 +1,113 @@
+/**
+ * Demonstrates the difference between quit() and disconnect() on a
+ * node-redis subscriber client while Redis is down.
+ *
+ * Scenario:
+ * 1. Start Redis.
+ * 2. Connect two subscriber clients and subscribe them.
+ * 3. Kill Redis and wait for the reconnect loop to start.
+ * 4. Subscriber A: call quit(). It should NOT resolve quickly while Redis is down.
+ * 5. Subscriber B: call disconnect(). It must close the socket immediately.
+ * 6. Restart Redis and verify that the disconnected subscriber stays dead.
+ *
+ * This shows why disconnect() is the correct teardown method during an outage.
+ */
+
+import { createClient } from 'redis';
+import {
+  detectContainerRuntime,
+  getFreePort,
+  record,
+  sh,
+  sleep,
+  startRedis,
+} from './redis-test-helpers';
+
+async function createSubscriber(url: string) {
+  const client = createClient({
+    url,
+    socket: {
+      connectTimeout: 2_000,
+      reconnectStrategy: (retries: number) => Math.min(50 + retries * 50, 500),
+    },
+  });
+  client.on('error', () => {});
+  await client.connect();
+  await client.subscribe('test-channel', () => {});
+  return client;
+}
+
+async function main() {
+  const runtime = detectContainerRuntime();
+  const name = `redis-quit-disc-${Math.random().toString(36).slice(2, 8)}`;
+  const port = await getFreePort();
+
+  sh(runtime, ['rm', '-f', name]);
+  startRedis(runtime, name, port);
+
+  const url = `redis://127.0.0.1:${port}`;
+
+  const quitSubscriber = await createSubscriber(url);
+  const disconnectSubscriber = await createSubscriber(url);
+
+  record(
+    'subscribers-ready',
+    quitSubscriber.isReady && disconnectSubscriber.isReady,
+    `quitSub isReady=${quitSubscriber.isReady}, disconnectSub isReady=${disconnectSubscriber.isReady}`,
+  );
+
+  // Kill Redis and let both clients enter their reconnect loops
+  sh(runtime, ['stop', '-t', '0', name], { timeoutMs: 30_000 });
+  await sleep(1_500);
+
+  // Test quit(): it should not resolve while Redis is unreachable.
+  const quitResult = await Promise.race([
+    quitSubscriber
+      .quit()
+      .then(() => 'resolved')
+      .catch((e) => `error:${e.message ?? e}`),
+    sleep(3_000).then(() => 'timeout'),
+  ]);
+
+  record(
+    'quit-does-not-immediately-close',
+    quitResult !== 'resolved',
+    `quit() result during outage: ${quitResult}`,
+  );
+
+  // Test disconnect(): it must close the client immediately, even during outage.
+  const disconnectStart = Date.now();
+  try {
+    await disconnectSubscriber.disconnect();
+  } catch (e: any) {
+    // If the client is already closed, that's still a successful teardown.
+  }
+  const disconnectDuration = Date.now() - disconnectStart;
+
+  record(
+    'disconnect-closes-immediately',
+    !disconnectSubscriber.isOpen && !disconnectSubscriber.isReady,
+    `disconnect() took ${disconnectDuration}ms, isOpen=${disconnectSubscriber.isOpen}, isReady=${disconnectSubscriber.isReady}`,
+  );
+
+  // Restart Redis and make sure the disconnected client does not come back.
+  startRedis(runtime, name, port);
+  await sleep(1_500);
+
+  record(
+    'disconnected-client-stays-dead',
+    !disconnectSubscriber.isOpen && !disconnectSubscriber.isReady,
+    `after restart: isOpen=${disconnectSubscriber.isOpen}, isReady=${disconnectSubscriber.isReady}`,
+  );
+
+  // Also clean up the quit subscriber so we don't leak the process.
+  try {
+    await quitSubscriber.disconnect();
+  } catch {}
+  sh(runtime, ['rm', '-f', name]);
+}
+
+main().catch((err) => {
+  process.stderr.write(String(err) + '\n');
+  process.exit(1);
+});