Code refactoring

vicb · vicb · commit 797b3d4733bb · 2025-04-02T13:34:42.000+02:00
diff --git a/.changeset/khaki-spies-notice.md b/.changeset/khaki-spies-notice.md
@@ -0,0 +1,14 @@
+---
+"@opennextjs/cloudflare": minor
+---
+
+Code refactoring
+
+BREAKING CHANGES
+
+- `DurableObjectQueueHandler` renamed to `DOQueueHandler`
+- `NEXT_CACHE_DO_QUEUE_MAX_NUM_REVALIDATIONS` renamed to `NEXT_CACHE_DO_QUEUE_MAX_RETRIES`
+- `D1TagCache` has been removed, use `D1NextModeTagCache` instead.
+- The `enableShardReplication` and `shardReplicationOptions` options passed to `ShardedDOTagCache`
+  have been folded into `shardReplication`. A value for `shardReplication` must be specified to enable
+  replications. The value must be an object with the number of soft and hard replicas.
diff --git a/examples/bugs/gh-223/package.json b/examples/bugs/gh-223/package.json
@@ -32,6 +32,6 @@
     "postcss": "^8.4.49",
     "tailwindcss": "^3.4.17",
     "typescript": "^5.7.2",
-    "wrangler": "^3.107.0"
+    "wrangler": "catalog:"
   }
 }
diff --git a/examples/e2e/app-router/open-next.config.ts b/examples/e2e/app-router/open-next.config.ts
@@ -8,8 +8,7 @@ export default defineCloudflareConfig({
   // With such a configuration, we could have up to 12 * (8 + 2) = 120 Durable Objects instances
   tagCache: shardedTagCache({
     baseShardSize: 12,
-    enableShardReplication: true,
-    shardReplicationOptions: {
+    shardReplication: {
       numberOfSoftReplicas: 8,
       numberOfHardReplicas: 2,
     },
diff --git a/examples/e2e/app-router/wrangler.jsonc b/examples/e2e/app-router/wrangler.jsonc
@@ -12,7 +12,7 @@
     "bindings": [
       {
         "name": "NEXT_CACHE_DO_QUEUE",
-        "class_name": "DurableObjectQueueHandler"
+        "class_name": "DOQueueHandler"
       },
       {
         "name": "NEXT_TAG_CACHE_DO_SHARDED",
@@ -23,7 +23,7 @@
   "migrations": [
     {
       "tag": "v1",
-      "new_sqlite_classes": ["DurableObjectQueueHandler", "DOShardedTagCache"]
+      "new_sqlite_classes": ["DOQueueHandler", "DOShardedTagCache"]
     }
   ],
   "kv_namespaces": [
diff --git a/examples/overrides/r2-incremental-cache/open-next.config.ts b/examples/overrides/r2-incremental-cache/open-next.config.ts
@@ -1,5 +1,5 @@
 import { defineCloudflareConfig } from "@opennextjs/cloudflare";
-import d1TagCache from "@opennextjs/cloudflare/overrides/tag-cache/d1-tag-cache";
+import d1NextTagCache from "@opennextjs/cloudflare/overrides/tag-cache/d1-next-tag-cache";
 import memoryQueue from "@opennextjs/cloudflare/overrides/queue/memory-queue";
 import r2IncrementalCache from "@opennextjs/cloudflare/overrides/incremental-cache/r2-incremental-cache";
 import { withRegionalCache } from "@opennextjs/cloudflare/overrides/incremental-cache/regional-cache";
@@ -9,6 +9,6 @@ export default defineCloudflareConfig({
     mode: "long-lived",
     shouldLazilyUpdateOnCacheHit: true,
   }),
-  tagCache: d1TagCache,
+  tagCache: d1NextTagCache,
   queue: memoryQueue,
 });
diff --git a/packages/cloudflare/src/api/cloudflare-context.ts b/packages/cloudflare/src/api/cloudflare-context.ts
@@ -2,7 +2,7 @@ import type { Context, RunningCodeOptions } from "node:vm";
 
 import type { GetPlatformProxyOptions } from "wrangler";
 
-import type { DurableObjectQueueHandler } from "./durable-objects/queue";
+import type { DOQueueHandler } from "./durable-objects/queue";
 import { DOShardedTagCache } from "./durable-objects/sharded-tag-cache";
 
 declare global {
@@ -35,7 +35,7 @@ declare global {
     NEXT_TAG_CACHE_DO_SHARDED_DLQ?: Queue;
 
     // Durable Object namespace to use for the durable object queue
-    NEXT_CACHE_DO_QUEUE?: DurableObjectNamespace<DurableObjectQueueHandler>;
+    NEXT_CACHE_DO_QUEUE?: DurableObjectNamespace<DOQueueHandler>;
 
     // Below are the optional environment variables to configure the durable object queue
     // The max number of revalidations that can be processed by the durable worker at the same time
@@ -46,7 +46,7 @@ declare global {
     // If it fails again it will exponentially back off until it reaches the max retry interval
     NEXT_CACHE_DO_QUEUE_RETRY_INTERVAL_MS?: string;
     // The maximum number of attempts that can be made to revalidate a path
-    NEXT_CACHE_DO_QUEUE_MAX_NUM_REVALIDATIONS?: string;
+    NEXT_CACHE_DO_QUEUE_MAX_RETRIES?: string;
     // Disable SQLite for the durable object queue handler
     // This can be safely used if you don't use an eventually consistent incremental cache (i.e. R2 without the regional cache for example)
     NEXT_CACHE_DO_QUEUE_DISABLE_SQLITE?: string;
diff --git a/packages/cloudflare/src/api/durable-objects/queue.spec.ts b/packages/cloudflare/src/api/durable-objects/queue.spec.ts
@@ -1,6 +1,6 @@
 import { describe, expect, it, vi } from "vitest";
 
-import { DurableObjectQueueHandler } from "./queue";
+import { DOQueueHandler } from "./queue";
 
 vi.mock("cloudflare:workers", () => ({
   DurableObject: class {
@@ -36,7 +36,7 @@ const createDurableObjectQueue = ({
     },
   };
   // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  return new DurableObjectQueueHandler(mockState as any, {
+  return new DOQueueHandler(mockState as any, {
     WORKER_SELF_REFERENCE: {
       fetch: vi.fn().mockReturnValue(
         new Promise<Response>((res) =>
@@ -198,7 +198,7 @@ describe("DurableObjectQueue", () => {
   });
 
   describe("addAlarm", () => {
-    const getStorage = (queue: DurableObjectQueueHandler): DurableObjectStorage => {
+    const getStorage = (queue: DOQueueHandler): DurableObjectStorage => {
       // @ts-expect-error - ctx is a protected field
       return queue.ctx.storage;
     };
diff --git a/packages/cloudflare/src/api/durable-objects/queue.ts b/packages/cloudflare/src/api/durable-objects/queue.ts
@@ -11,15 +11,15 @@ import { DurableObject } from "cloudflare:workers";
 const DEFAULT_MAX_REVALIDATION = 5;
 const DEFAULT_REVALIDATION_TIMEOUT_MS = 10_000;
 const DEFAULT_RETRY_INTERVAL_MS = 2_000;
-const DEFAULT_MAX_NUM_REVALIDATIONS = 6;
+const DEFAULT_MAX_RETRIES = 6;
 
 interface FailedState {
   msg: QueueMessage;
   retryCount: number;
   nextAlarmMs: number;
 }
 
-export class DurableObjectQueueHandler extends DurableObject<CloudflareEnv> {
+export class DOQueueHandler extends DurableObject<CloudflareEnv> {
   // Ongoing revalidations are deduped by the deduplication id
   // Since this is running in waitUntil, we expect the durable object state to persist this during the duration of the revalidation
   // TODO: handle incremental cache with only eventual consistency (i.e. KV or R2/D1 with the optional cache layer on top)
@@ -35,7 +35,7 @@ export class DurableObjectQueueHandler extends DurableObject<CloudflareEnv> {
   readonly maxRevalidations: number;
   readonly revalidationTimeout: number;
   readonly revalidationRetryInterval: number;
-  readonly maxRevalidationAttempts: number;
+  readonly maxRetries: number;
   readonly disableSQLite: boolean;
 
   constructor(ctx: DurableObjectState, env: CloudflareEnv) {
@@ -57,9 +57,9 @@ export class DurableObjectQueueHandler extends DurableObject<CloudflareEnv> {
       ? parseInt(env.NEXT_CACHE_DO_QUEUE_RETRY_INTERVAL_MS)
       : DEFAULT_RETRY_INTERVAL_MS;
 
-    this.maxRevalidationAttempts = env.NEXT_CACHE_DO_QUEUE_MAX_NUM_REVALIDATIONS
-      ? parseInt(env.NEXT_CACHE_DO_QUEUE_MAX_NUM_REVALIDATIONS)
-      : DEFAULT_MAX_NUM_REVALIDATIONS;
+    this.maxRetries = env.NEXT_CACHE_DO_QUEUE_MAX_RETRIES
+      ? parseInt(env.NEXT_CACHE_DO_QUEUE_MAX_RETRIES)
+      : DEFAULT_MAX_RETRIES;
 
     this.disableSQLite = env.NEXT_CACHE_DO_QUEUE_DISABLE_SQLITE === "true";
 
@@ -199,10 +199,9 @@ export class DurableObjectQueueHandler extends DurableObject<CloudflareEnv> {
     let updatedFailedState: FailedState;
 
     if (existingFailedState) {
-      if (existingFailedState.retryCount >= this.maxRevalidationAttempts) {
-        // We give up after 6 retries and log the error
+      if (existingFailedState.retryCount >= this.maxRetries) {
         error(
-          `The revalidation for ${msg.MessageBody.host}${msg.MessageBody.url} has failed after 6 retries. It will not be tried again, but subsequent ISR requests will retry.`
+          `The revalidation for ${msg.MessageBody.host}${msg.MessageBody.url} has failed after ${this.maxRetries} retries. It will not be tried again, but subsequent ISR requests will retry.`
         );
         this.routeInFailedState.delete(msg.MessageDeduplicationId);
         return;
diff --git a/packages/cloudflare/src/api/overrides/incremental-cache/kv-incremental-cache.ts b/packages/cloudflare/src/api/overrides/incremental-cache/kv-incremental-cache.ts
@@ -7,15 +7,17 @@ export const CACHE_ASSET_DIR = "cdn-cgi/_next_cache";
 
 export const STATUS_DELETED = 1;
 
+export const CACHE_NAME = "cf-kv-incremental-cache";
+
 /**
  * Open Next cache based on cloudflare KV and Assets.
  *
  * Note: The class is instantiated outside of the request context.
  * The cloudflare context and process.env are not initialized yet
  * when the constructor is called.
  */
-class Cache implements IncrementalCache {
-  readonly name = "cloudflare-kv";
+class KVIncrementalCache implements IncrementalCache {
+  readonly name = CACHE_NAME;
 
   async get<IsFetch extends boolean = false>(
     key: string,
@@ -158,4 +160,4 @@ class Cache implements IncrementalCache {
   }
 }
 
-export default new Cache();
+export default new KVIncrementalCache();
diff --git a/packages/cloudflare/src/api/overrides/incremental-cache/r2-incremental-cache.ts b/packages/cloudflare/src/api/overrides/incremental-cache/r2-incremental-cache.ts
@@ -12,7 +12,7 @@ import { getCloudflareContext } from "../../cloudflare-context.js";
  * environment variable, and defaults to `incremental-cache`.
  */
 class R2IncrementalCache implements IncrementalCache {
-  readonly name = "r2-incremental-cache";
+  readonly name = "cf-r2-incremental-cache";
 
   async get<IsFetch extends boolean = false>(
     key: string,
diff --git a/packages/cloudflare/src/api/overrides/incremental-cache/regional-cache.ts b/packages/cloudflare/src/api/overrides/incremental-cache/regional-cache.ts
@@ -3,6 +3,7 @@ import { CacheValue, IncrementalCache, WithLastModified } from "@opennextjs/aws/
 
 import { getCloudflareContext } from "../../cloudflare-context.js";
 import { IncrementalCacheEntry } from "./internal.js";
+import { CACHE_NAME as KV_CACHE_NAME } from "./kv-incremental-cache.js";
 
 const ONE_MINUTE_IN_SECONDS = 60;
 const THIRTY_MINUTES_IN_SECONDS = ONE_MINUTE_IN_SECONDS * 30;
@@ -12,18 +13,23 @@ type Options = {
    * The mode to use for the regional cache.
    *
    * - `short-lived`: Re-use a cache entry for up to a minute after it has been retrieved.
-   * - `long-lived`: Re-use a fetch cache entry until it is revalidated (per-region), or an ISR/SSG entry for up to 30 minutes.
+   * - `long-lived`: Re-use a fetch cache entry until it is revalidated (per-region),
+   *                 or an ISR/SSG entry for up to 30 minutes.
    */
   mode: "short-lived" | "long-lived";
+
   /**
    * Whether the regional cache entry should be updated in the background or not when it experiences
    * a cache hit.
    *
-   * Defaults to `false` for the `short-lived` mode, and `true` for the `long-lived` mode.
+   * @default `false` for the `short-lived` mode, and `true` for the `long-lived` mode.
    */
   shouldLazilyUpdateOnCacheHit?: boolean;
 };
 
+/**
+ * Wrapper adding a regional cache on an `IncrementalCache` implementation
+ */
 class RegionalCache implements IncrementalCache {
   public name: string;
 
@@ -33,8 +39,10 @@ class RegionalCache implements IncrementalCache {
     private store: IncrementalCache,
     private opts: Options
   ) {
+    if (this.store.name === KV_CACHE_NAME) {
+      throw new Error("The KV incremental cache does not need a regional cache.");
+    }
     this.name = this.store.name;
-
     this.opts.shouldLazilyUpdateOnCacheHit ??= this.opts.mode === "long-lived";
   }
 
@@ -150,17 +158,19 @@ class RegionalCache implements IncrementalCache {
  *
  * The regional cache uses the Cache API.
  *
- * **WARNING:** If an entry is revalidated in one region, it will trigger an additional revalidation if
+ * **WARNING:**
+ * If an entry is revalidated in one region, it will trigger an additional revalidation if
  * a request is made to another region that has an entry stored in its regional cache.
  *
- * @param cache - Incremental cache instance.
- * @param opts.mode - The mode to use for the regional cache.
- * - `short-lived`: Re-use a cache entry for up to a minute after it has been retrieved.
- * - `long-lived`: Re-use a fetch cache entry until it is revalidated (per-region), or an ISR/SSG entry for up to 30 minutes.
- * @param opts.shouldLazilyUpdateOnCacheHit - Whether the regional cache entry should be updated in
- * the background or not when it experiences a cache hit.
+ * @param cache Incremental cache instance.
+ * @param opts.mode The mode to use for the regional cache.
+ *                  - `short-lived`: Re-use a cache entry for up to a minute after it has been retrieved.
+ *                  - `long-lived`: Re-use a fetch cache entry until it is revalidated (per-region),
+ *                                  or an ISR/SSG entry for up to 30 minutes.
+ * @param opts.shouldLazilyUpdateOnCacheHit Whether the regional cache entry should be updated in
+ *                                          the background or not when it experiences a cache hit.
  *
- * Defaults to `false` for the `short-lived` mode, and `true` for the `long-lived` mode.
+ * @default `false` for the `short-lived` mode, and `true` for the `long-lived` mode.
  */
 export function withRegionalCache(cache: IncrementalCache, opts: Options) {
   return new RegionalCache(cache, opts);
diff --git a/packages/cloudflare/src/api/overrides/tag-cache/d1-tag-cache.ts b/packages/cloudflare/src/api/overrides/tag-cache/d1-tag-cache.ts
diff --git a/packages/cloudflare/src/api/overrides/tag-cache/do-sharded-tag-cache.spec.ts b/packages/cloudflare/src/api/overrides/tag-cache/do-sharded-tag-cache.spec.ts
diff --git a/packages/cloudflare/src/api/overrides/tag-cache/do-sharded-tag-cache.ts b/packages/cloudflare/src/api/overrides/tag-cache/do-sharded-tag-cache.ts
diff --git a/packages/cloudflare/src/cli/templates/worker.ts b/packages/cloudflare/src/cli/templates/worker.ts
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml

Original file line number	Diff line number	Diff line change
`@@ -32,6 +32,6 @@`
`32`	`32`	`"postcss": "^8.4.49",`
`33`	`33`	`"tailwindcss": "^3.4.17",`
`34`	`34`	`"typescript": "^5.7.2",`
`35`		`- "wrangler": "^3.107.0"`
	`35`	`+ "wrangler": "catalog:"`
`36`	`36`	`}`
`37`	`37`	`}`
Original file line number	Diff line number	Diff line change
`@@ -12,7 +12,7 @@`
`12`	`12`	`"bindings": [`
`13`	`13`	`{`
`14`	`14`	`"name": "NEXT_CACHE_DO_QUEUE",`
`15`		`- "class_name": "DurableObjectQueueHandler"`
	`15`	`+ "class_name": "DOQueueHandler"`
`16`	`16`	`},`
`17`	`17`	`{`
`18`	`18`	`"name": "NEXT_TAG_CACHE_DO_SHARDED",`
`@@ -23,7 +23,7 @@`
`23`	`23`	`"migrations": [`
`24`	`24`	`{`
`25`	`25`	`"tag": "v1",`
`26`		`- "new_sqlite_classes": ["DurableObjectQueueHandler", "DOShardedTagCache"]`
	`26`	`+ "new_sqlite_classes": ["DOQueueHandler", "DOShardedTagCache"]`
`27`	`27`	`}`
`28`	`28`	`],`
`29`	`29`	`"kv_namespaces": [`