@trieb.work/nextjs-turbo-redis-cache 1.0.0

package/src/RedisStringsHandler.ts

@@ -0,0 +1,344 @@
+import { commandOptions, createClient } from 'redis';
+import { SyncedMap } from './SyncedMap';
+import { DeduplicatedRequestHandler } from './DeduplicatedRequestHandler';
+import {
+  CacheHandler,
+  CacheHandlerValue,
+  IncrementalCache,
+} from 'next/dist/server/lib/incremental-cache';
+
+export type CommandOptions = ReturnType<typeof commandOptions>;
+type GetParams = Parameters<IncrementalCache['get']>;
+type SetParams = Parameters<IncrementalCache['set']>;
+type RevalidateParams = Parameters<IncrementalCache['revalidateTag']>;
+export type Client = ReturnType<typeof createClient>;
+
+export type CreateRedisStringsHandlerOptions = {
+  database?: number;
+  keyPrefix?: string;
+  timeoutMs?: number;
+  revalidateTagQuerySize?: number;
+  sharedTagsKey?: string;
+  avgResyncIntervalMs?: number;
+  redisGetDeduplication?: boolean;
+  inMemoryCachingTime?: number;
+  defaultStaleAge?: number;
+  estimateExpireAge?: (staleAge: number) => number;
+  maxMemoryCacheSize?: number;
+};
+
+const NEXT_CACHE_IMPLICIT_TAG_ID = '_N_T_';
+const REVALIDATED_TAGS_KEY = '__revalidated_tags__';
+
+function isImplicitTag(tag: string): boolean {
+  return tag.startsWith(NEXT_CACHE_IMPLICIT_TAG_ID);
+}
+
+export function getTimeoutRedisCommandOptions(
+  timeoutMs: number,
+): CommandOptions {
+  return commandOptions({ signal: AbortSignal.timeout(timeoutMs) });
+}
+
+export default class RedisStringsHandler implements CacheHandler {
+  private maxMemoryCacheSize: undefined | number;
+  private client: Client;
+  private sharedTagsMap: SyncedMap<string[]>;
+  private revalidatedTagsMap: SyncedMap<number>;
+  private inMemoryDeduplicationCache: SyncedMap<
+    Promise<ReturnType<Client['get']>>
+  >;
+  private redisGet: Client['get'];
+  private redisDeduplicationHandler: DeduplicatedRequestHandler<
+    Client['get'],
+    string | Buffer | null
+  >;
+  private deduplicatedRedisGet: (key: string) => Client['get'];
+  private timeoutMs: number;
+  private keyPrefix: string;
+  private redisGetDeduplication: boolean;
+  private inMemoryCachingTime: number;
+  private defaultStaleAge: number;
+  private estimateExpireAge: (staleAge: number) => number;
+
+  constructor({
+    maxMemoryCacheSize,
+    database = process.env.VERCEL_ENV === 'production' ? 0 : 1,
+    keyPrefix = process.env.VERCEL_URL || 'UNDEFINED_URL_',
+    sharedTagsKey = '__sharedTags__',
+    timeoutMs = 5000,
+    revalidateTagQuerySize = 250,
+    avgResyncIntervalMs = 60 * 60 * 1000,
+    redisGetDeduplication = true,
+    inMemoryCachingTime = 10_000,
+    defaultStaleAge = 60 * 60 * 24 * 14,
+    estimateExpireAge = (staleAge) =>
+      process.env.VERCEL_ENV === 'preview' ? staleAge * 1.2 : staleAge * 2,
+  }: CreateRedisStringsHandlerOptions) {
+    this.maxMemoryCacheSize = maxMemoryCacheSize;
+    this.keyPrefix = keyPrefix;
+    this.timeoutMs = timeoutMs;
+    this.redisGetDeduplication = redisGetDeduplication;
+    this.inMemoryCachingTime = inMemoryCachingTime;
+    this.defaultStaleAge = defaultStaleAge;
+    this.estimateExpireAge = estimateExpireAge;
+
+    try {
+      this.client = createClient({
+        ...(database !== 0 ? { database } : {}),
+        url: process.env.REDISHOST
+          ? `redis://${process.env.REDISHOST}:${process.env.REDISPORT}`
+          : 'redis://localhost:6379',
+      });
+
+      this.client.on('error', (error) => {
+        console.error('Redis client error', error);
+      });
+
+      this.client
+        .connect()
+        .then(() => {
+          console.info('Redis client connected.');
+        })
+        .catch((error) => {
+          console.error('Failed to connect Redis client:', error);
+          this.client.disconnect();
+        });
+    } catch (error: unknown) {
+      console.error('Failed to initialize Redis client');
+      throw error;
+    }
+
+    const filterKeys = (key: string): boolean =>
+      key !== REVALIDATED_TAGS_KEY && key !== sharedTagsKey;
+
+    this.sharedTagsMap = new SyncedMap<string[]>({
+      client: this.client,
+      keyPrefix,
+      redisKey: sharedTagsKey,
+      database,
+      timeoutMs,
+      querySize: revalidateTagQuerySize,
+      filterKeys,
+      resyncIntervalMs:
+        avgResyncIntervalMs -
+        avgResyncIntervalMs / 10 +
+        Math.random() * (avgResyncIntervalMs / 10),
+    });
+
+    this.revalidatedTagsMap = new SyncedMap<number>({
+      client: this.client,
+      keyPrefix,
+      redisKey: REVALIDATED_TAGS_KEY,
+      database,
+      timeoutMs,
+      querySize: revalidateTagQuerySize,
+      filterKeys,
+      resyncIntervalMs:
+        avgResyncIntervalMs +
+        avgResyncIntervalMs / 10 +
+        Math.random() * (avgResyncIntervalMs / 10),
+    });
+
+    this.inMemoryDeduplicationCache = new SyncedMap({
+      client: this.client,
+      keyPrefix,
+      redisKey: 'inMemoryDeduplicationCache',
+      database,
+      timeoutMs,
+      querySize: revalidateTagQuerySize,
+      filterKeys,
+      customizedSync: {
+        withoutRedisHashmap: true,
+        withoutSetSync: true,
+      },
+    });
+
+    const redisGet: Client['get'] = this.client.get.bind(this.client);
+    this.redisDeduplicationHandler = new DeduplicatedRequestHandler(
+      redisGet,
+      inMemoryCachingTime,
+      this.inMemoryDeduplicationCache,
+    );
+    this.redisGet = redisGet;
+    this.deduplicatedRedisGet =
+      this.redisDeduplicationHandler.deduplicatedFunction;
+  }
+  resetRequestCache(...args: never[]): void {
+    console.warn('WARNING resetRequestCache() was called', args);
+  }
+
+  private async assertClientIsReady(): Promise<void> {
+    await Promise.all([
+      this.sharedTagsMap.waitUntilReady(),
+      this.revalidatedTagsMap.waitUntilReady(),
+    ]);
+    if (!this.client.isReady) {
+      throw new Error('Redis client is not ready yet or connection is lost.');
+    }
+  }
+
+  public async get(key: GetParams[0], ctx: GetParams[1]) {
+    await this.assertClientIsReady();
+
+    const clientGet = this.redisGetDeduplication
+      ? this.deduplicatedRedisGet(key)
+      : this.redisGet;
+    const result = await clientGet(
+      getTimeoutRedisCommandOptions(this.timeoutMs),
+      this.keyPrefix + key,
+    );
+
+    if (!result) {
+      return null;
+    }
+
+    const cacheValue = JSON.parse(result) as
+      | (CacheHandlerValue & { lastModified: number })
+      | null;
+
+    if (!cacheValue) {
+      return null;
+    }
+
+    if (cacheValue.value?.kind === 'FETCH') {
+      cacheValue.value.data.body = Buffer.from(
+        cacheValue.value.data.body,
+      ).toString('base64');
+    }
+
+    const combinedTags = new Set([
+      ...(ctx?.softTags || []),
+      ...(ctx?.tags || []),
+    ]);
+
+    if (combinedTags.size === 0) {
+      return cacheValue;
+    }
+
+    for (const tag of combinedTags) {
+      // TODO: check how this revalidatedTagsMap is used or if it can be deleted
+      const revalidationTime = this.revalidatedTagsMap.get(tag);
+      if (revalidationTime && revalidationTime > cacheValue.lastModified) {
+        const redisKey = this.keyPrefix + key;
+        // Do not await here as this can happen in the background while we can already serve the cacheValue
+        this.client
+          .unlink(getTimeoutRedisCommandOptions(this.timeoutMs), redisKey)
+          .catch((err) => {
+            console.error(
+              'Error occurred while unlinking stale data. Retrying now. Error was:',
+              err,
+            );
+            this.client.unlink(
+              getTimeoutRedisCommandOptions(this.timeoutMs),
+              redisKey,
+            );
+          })
+          .finally(async () => {
+            await this.sharedTagsMap.delete(key);
+            await this.revalidatedTagsMap.delete(tag);
+          });
+        return null;
+      }
+    }
+
+    return cacheValue;
+  }
+  public async set(
+    key: SetParams[0],
+    data: SetParams[1] & { lastModified: number },
+    ctx: SetParams[2],
+  ) {
+    if (data.kind === 'FETCH') {
+      console.time('encoding' + key);
+      data.data.body = Buffer.from(data.data.body, 'base64').toString();
+      console.timeEnd('encoding' + key);
+    }
+    await this.assertClientIsReady();
+
+    data.lastModified = Date.now();
+
+    const value = JSON.stringify(data);
+
+    // pre seed data into deduplicated get client. This will reduce redis load by not requesting
+    // the same value from redis which was just set.
+    if (this.redisGetDeduplication) {
+      this.redisDeduplicationHandler.seedRequestReturn(key, value);
+    }
+
+    const expireAt =
+      ctx.revalidate &&
+      Number.isSafeInteger(ctx.revalidate) &&
+      ctx.revalidate > 0
+        ? this.estimateExpireAge(ctx.revalidate)
+        : this.estimateExpireAge(this.defaultStaleAge);
+    const options = getTimeoutRedisCommandOptions(this.timeoutMs);
+    const setOperation: Promise<string | null> = this.client.set(
+      options,
+      this.keyPrefix + key,
+      value,
+      {
+        EX: expireAt,
+      },
+    );
+
+    let setTagsOperation: Promise<void> | undefined;
+    if (ctx.tags && ctx.tags.length > 0) {
+      const currentTags = this.sharedTagsMap.get(key);
+      const currentIsSameAsNew =
+        currentTags?.length === ctx.tags.length &&
+        currentTags.every((v) => ctx.tags!.includes(v)) &&
+        ctx.tags.every((v) => currentTags.includes(v));
+
+      if (!currentIsSameAsNew) {
+        setTagsOperation = this.sharedTagsMap.set(
+          key,
+          structuredClone(ctx.tags) as string[],
+        );
+      }
+    }
+
+    await Promise.all([setOperation, setTagsOperation]);
+  }
+  public async revalidateTag(tagOrTags: RevalidateParams[0]) {
+    const tags = new Set([tagOrTags || []].flat());
+    await this.assertClientIsReady();
+
+    // TODO: check how this revalidatedTagsMap is used or if it can be deleted
+    for (const tag of tags) {
+      if (isImplicitTag(tag)) {
+        const now = Date.now();
+        await this.revalidatedTagsMap.set(tag, now);
+      }
+    }
+
+    const keysToDelete: string[] = [];
+
+    for (const [key, sharedTags] of this.sharedTagsMap.entries()) {
+      if (sharedTags.some((tag) => tags.has(tag))) {
+        keysToDelete.push(key);
+      }
+    }
+
+    if (keysToDelete.length === 0) {
+      return;
+    }
+
+    const fullRedisKeys = keysToDelete.map((key) => this.keyPrefix + key);
+
+    const options = getTimeoutRedisCommandOptions(this.timeoutMs);
+
+    const deleteKeysOperation = this.client.unlink(options, fullRedisKeys);
+
+    // delete entries from in-memory deduplication cache
+    if (this.redisGetDeduplication && this.inMemoryCachingTime > 0) {
+      for (const key of keysToDelete) {
+        this.inMemoryDeduplicationCache.delete(key);
+      }
+    }
+
+    const deleteTagsOperation = this.sharedTagsMap.delete(keysToDelete);
+
+    await Promise.all([deleteKeysOperation, deleteTagsOperation]);
+  }
+}

package/src/SyncedMap.ts

@@ -0,0 +1,298 @@
+// SyncedMap.ts
+import { Client, getTimeoutRedisCommandOptions } from './RedisStringsHandler';
+
+type CustomizedSync = {
+  withoutRedisHashmap?: boolean;
+  withoutSetSync?: boolean;
+};
+
+type SyncedMapOptions = {
+  client: Client;
+  keyPrefix: string;
+  redisKey: string; // Redis Hash key
+  database: number;
+  timeoutMs: number;
+  querySize: number;
+  filterKeys: (key: string) => boolean;
+  resyncIntervalMs?: number;
+  customizedSync?: CustomizedSync;
+};
+
+export type SyncMessage<V> = {
+  type: 'insert' | 'delete';
+  key?: string;
+  value?: V;
+  keys?: string[];
+};
+
+const SYNC_CHANNEL_SUFFIX = ':sync-channel:';
+export class SyncedMap<V> {
+  private client: Client;
+  private subscriberClient: Client;
+  private map: Map<string, V>;
+  private keyPrefix: string;
+  private syncChannel: string;
+  private redisKey: string;
+  private database: number;
+  private timeoutMs: number;
+  private querySize: number;
+  private filterKeys: (key: string) => boolean;
+  private resyncIntervalMs?: number;
+  private customizedSync?: CustomizedSync;
+
+  private setupLock: Promise<void>;
+  private setupLockResolve!: () => void;
+
+  constructor(options: SyncedMapOptions) {
+    this.client = options.client;
+    this.keyPrefix = options.keyPrefix;
+    this.redisKey = options.redisKey;
+    this.syncChannel = `${options.keyPrefix}${SYNC_CHANNEL_SUFFIX}${options.redisKey}`;
+    this.database = options.database;
+    this.timeoutMs = options.timeoutMs;
+    this.querySize = options.querySize;
+    this.filterKeys = options.filterKeys;
+    this.resyncIntervalMs = options.resyncIntervalMs;
+    this.customizedSync = options.customizedSync;
+
+    this.map = new Map<string, V>();
+    this.subscriberClient = this.client.duplicate();
+    this.setupLock = new Promise<void>((resolve) => {
+      this.setupLockResolve = resolve;
+    });
+
+    this.setup().catch((error) => {
+      console.error('Failed to setup SyncedMap:', error);
+      throw error;
+    });
+  }
+
+  private async setup() {
+    let setupPromises: Promise<void>[] = [];
+    if (!this.customizedSync?.withoutRedisHashmap) {
+      setupPromises.push(this.initialSync());
+      this.setupPeriodicResync();
+    }
+    setupPromises.push(this.setupPubSub());
+    await Promise.all(setupPromises);
+    this.setupLockResolve();
+  }
+
+  private async initialSync() {
+    let cursor = 0;
+    const hScanOptions = { COUNT: this.querySize };
+
+    try {
+      do {
+        const remoteItems = await this.client.hScan(
+          getTimeoutRedisCommandOptions(this.timeoutMs),
+          this.keyPrefix + this.redisKey,
+          cursor,
+          hScanOptions,
+        );
+        for (const { field, value } of remoteItems.tuples) {
+          if (this.filterKeys(field)) {
+            const parsedValue = JSON.parse(value);
+            this.map.set(field, parsedValue);
+          }
+        }
+        cursor = remoteItems.cursor;
+      } while (cursor !== 0);
+
+      // Clean up keys not in Redis
+      await this.cleanupKeysNotInRedis();
+    } catch (error) {
+      console.error('Error during initial sync:', error);
+      throw error;
+    }
+  }
+
+  private async cleanupKeysNotInRedis() {
+    let cursor = 0;
+    const scanOptions = { COUNT: this.querySize, MATCH: `${this.keyPrefix}*` };
+    let remoteKeys: string[] = [];
+    try {
+      do {
+        const remoteKeysPortion = await this.client.scan(
+          getTimeoutRedisCommandOptions(this.timeoutMs),
+          cursor,
+          scanOptions,
+        );
+        remoteKeys = remoteKeys.concat(remoteKeysPortion.keys);
+        cursor = remoteKeysPortion.cursor;
+      } while (cursor !== 0);
+
+      const remoteKeysSet = new Set(
+        remoteKeys.map((key) => key.substring(this.keyPrefix.length)),
+      );
+
+      const keysToDelete: string[] = [];
+      for (const key of this.map.keys()) {
+        const keyStr = key as unknown as string;
+        if (!remoteKeysSet.has(keyStr) && this.filterKeys(keyStr)) {
+          keysToDelete.push(keyStr);
+        }
+      }
+
+      if (keysToDelete.length > 0) {
+        await this.delete(keysToDelete);
+      }
+    } catch (error) {
+      console.error('Error during cleanup of keys not in Redis:', error);
+      throw error;
+    }
+  }
+
+  private setupPeriodicResync() {
+    if (this.resyncIntervalMs && this.resyncIntervalMs > 0) {
+      setInterval(() => {
+        this.initialSync().catch((error) => {
+          console.error('Error during periodic resync:', error);
+        });
+      }, this.resyncIntervalMs);
+    }
+  }
+
+  private async setupPubSub() {
+    const syncHandler = async (message: string) => {
+      const syncMessage: SyncMessage<V> = JSON.parse(message);
+      if (syncMessage.type === 'insert') {
+        if (syncMessage.key !== undefined && syncMessage.value !== undefined) {
+          this.map.set(syncMessage.key, syncMessage.value);
+        }
+      } else if (syncMessage.type === 'delete') {
+        if (syncMessage.keys) {
+          for (const key of syncMessage.keys) {
+            this.map.delete(key);
+          }
+        }
+      }
+    };
+
+    const keyEventHandler = async (_channel: string, message: string) => {
+      const key = message;
+      if (key.startsWith(this.keyPrefix)) {
+        const keyInMap = key.substring(this.keyPrefix.length);
+        if (this.filterKeys(keyInMap)) {
+          await this.delete(keyInMap, true);
+        }
+      }
+    };
+
+    try {
+      await this.subscriberClient.connect();
+
+      await Promise.all([
+        // We use a custom channel for insert/delete For the following reason:
+        // With custom channel we can delete multiple entries in one message. If we would listen to unlink / del we
+        // could get thousands of messages for one revalidateTag (For example revalidateTag("algolia") would send an enormous amount of network packages)
+        // Also we can send the value in the message for insert
+        this.subscriberClient.subscribe(this.syncChannel, syncHandler),
+        // Subscribe to Redis keyspace notifications for evicted and expired keys
+        this.subscriberClient.subscribe(
+          `__keyevent@${this.database}__:evicted`,
+          keyEventHandler,
+        ),
+        this.subscriberClient.subscribe(
+          `__keyevent@${this.database}__:expired`,
+          keyEventHandler,
+        ),
+      ]);
+
+      // Error handling for reconnection
+      this.subscriberClient.on('error', async (err) => {
+        console.error('Subscriber client error:', err);
+        try {
+          await this.subscriberClient.quit();
+          this.subscriberClient = this.client.duplicate();
+          await this.setupPubSub();
+        } catch (reconnectError) {
+          console.error(
+            'Failed to reconnect subscriber client:',
+            reconnectError,
+          );
+        }
+      });
+    } catch (error) {
+      console.error('Error setting up pub/sub client:', error);
+      throw error;
+    }
+  }
+
+  public async waitUntilReady() {
+    await this.setupLock;
+  }
+
+  public get(key: string): V | undefined {
+    return this.map.get(key);
+  }
+
+  public async set(key: string, value: V): Promise<void> {
+    this.map.set(key, value);
+    const operations = [];
+
+    // This is needed if we only want to sync delete commands. This is especially useful for non serializable data like a promise map
+    if (this.customizedSync?.withoutSetSync) {
+      return;
+    }
+    if (!this.customizedSync?.withoutRedisHashmap) {
+      const options = getTimeoutRedisCommandOptions(this.timeoutMs);
+      operations.push(
+        this.client.hSet(
+          options,
+          this.keyPrefix + this.redisKey,
+          key as unknown as string,
+          JSON.stringify(value),
+        ),
+      );
+    }
+
+    const insertMessage: SyncMessage<V> = {
+      type: 'insert',
+      key: key as unknown as string,
+      value,
+    };
+    operations.push(
+      this.client.publish(this.syncChannel, JSON.stringify(insertMessage)),
+    );
+    await Promise.all(operations);
+  }
+
+  public async delete(
+    keys: string[] | string,
+    withoutSyncMessage = false,
+  ): Promise<void> {
+    const keysArray = Array.isArray(keys) ? keys : [keys];
+    const operations = [];
+
+    for (const key of keysArray) {
+      this.map.delete(key);
+    }
+
+    if (!this.customizedSync?.withoutRedisHashmap) {
+      const options = getTimeoutRedisCommandOptions(this.timeoutMs);
+      operations.push(
+        this.client.hDel(options, this.keyPrefix + this.redisKey, keysArray),
+      );
+    }
+
+    if (!withoutSyncMessage) {
+      const deletionMessage: SyncMessage<V> = {
+        type: 'delete',
+        keys: keysArray,
+      };
+      operations.push(
+        this.client.publish(this.syncChannel, JSON.stringify(deletionMessage)),
+      );
+    }
+    await Promise.all(operations);
+  }
+
+  public has(key: string): boolean {
+    return this.map.has(key);
+  }
+
+  public entries(): IterableIterator<[string, V]> {
+    return this.map.entries();
+  }
+}

package/src/index.test.ts

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

package/src/index.ts

@@ -0,0 +1,2 @@
+import CachedHandler from "./CachedHandler";
+export default CachedHandler;

package/tsconfig.json

@@ -0,0 +1,14 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "module": "CommonJS",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "declaration": true,
+    "outDir": "dist"
+  },
+  "include": ["src", "vitest.config.ts"],
+  "exclude": ["node_modules", "dist"],
+  "types": ["vitest"]
+}

package/vite.config.ts

@@ -0,0 +1,18 @@
+import { defineConfig } from 'vitest/config';
+
+export default defineConfig({
+  test: {
+    globals: true, // Enable global test APIs like `describe`, `it`, and `expect`
+    environment: 'node', // Use 'node' as the test environment
+    include: ['src/**/*.test.ts', 'src/**/*.test.tsx'], // Only include TypeScript test files
+    exclude: ['node_modules', 'dist', '.git'], // Exclude unnecessary directories
+    coverage: {
+      provider: 'v8', // Use v8 for coverage reporting
+      reporter: ['text', 'lcov'], // Generate text and lcov coverage reports
+      include: process.env.VITEST_COVERAGE_INCLUDE?.split(',') || [
+        'src/**/*.ts',
+      ], // Use the specified files (by scripts/vitest-run-staged.cjs) or default to all files
+      exclude: ['node_modules', 'dist'], // Exclude specific directories from coverage
+    },
+  },
+});