@opennextjs/cloudflare 0.5.12 → 0.6.0

package/README.md

@@ -19,13 +19,13 @@ Run the following commands to preview the production build of your application l
 - build the app and adapt it for Cloudflare
 
   ```bash
-  npx opennextjs-cloudflare
+  npx opennextjs-cloudflare build
   # or
-  pnpm opennextjs-cloudflare
+  pnpm opennextjs-cloudflare build
   # or
-  yarn opennextjs-cloudflare
+  yarn opennextjs-cloudflare build
   # or
-  bun opennextjs-cloudflare
+  bun opennextjs-cloudflare build
   ```
 
 - Preview the app in Wrangler
@@ -47,11 +47,11 @@ Deploy your application to production with the following:
 - build the app and adapt it for Cloudflare
 
   ```bash
-  npx opennextjs-cloudflare && npx wrangler deploy
+  npx opennextjs-cloudflare build && npx opennextjs-cloudflare deploy
   # or
-  pnpm opennextjs-cloudflare && pnpm wrangler deploy
+  pnpm opennextjs-cloudflare build && pnpm opennextjs-cloudflare deploy
   # or
-  yarn opennextjs-cloudflare && yarn wrangler deploy
+  yarn opennextjs-cloudflare build && yarn opennextjs-cloudflare deploy
   # or
-  bun opennextjs-cloudflare && bun wrangler deploy
+  bun opennextjs-cloudflare build && bun opennextjs-cloudflare deploy
   ```

package/dist/api/cloudflare-context.d.ts

@@ -1,11 +1,22 @@
+import type { DurableObjectQueueHandler } from "./durable-objects/queue";
+import { DOShardedTagCache } from "./durable-objects/sharded-tag-cache";
 declare global {
     interface CloudflareEnv {
-        NEXT_CACHE_WORKERS_KV?: KVNamespace;
-        NEXT_CACHE_D1?: D1Database;
-        NEXT_CACHE_D1_TAGS_TABLE?: string;
-        NEXT_CACHE_D1_REVALIDATIONS_TABLE?: string;
-        NEXT_CACHE_REVALIDATION_WORKER?: Service;
         ASSETS?: Fetcher;
+        NEXTJS_ENV?: string;
+        WORKER_SELF_REFERENCE?: Service;
+        NEXT_INC_CACHE_KV?: KVNamespace;
+        NEXT_INC_CACHE_R2_BUCKET?: R2Bucket;
+        NEXT_INC_CACHE_R2_PREFIX?: string;
+        NEXT_TAG_CACHE_D1?: D1Database;
+        NEXT_TAG_CACHE_DO_SHARDED?: DurableObjectNamespace<DOShardedTagCache>;
+        NEXT_TAG_CACHE_DO_SHARDED_DLQ?: Queue;
+        NEXT_CACHE_DO_QUEUE?: DurableObjectNamespace<DurableObjectQueueHandler>;
+        NEXT_CACHE_DO_QUEUE_MAX_REVALIDATION?: string;
+        NEXT_CACHE_DO_QUEUE_REVALIDATION_TIMEOUT_MS?: string;
+        NEXT_CACHE_DO_QUEUE_RETRY_INTERVAL_MS?: string;
+        NEXT_CACHE_DO_QUEUE_MAX_NUM_REVALIDATIONS?: string;
+        NEXT_CACHE_DO_QUEUE_DISABLE_SQLITE?: string;
     }
 }
 export type CloudflareContext<CfProperties extends Record<string, unknown> = IncomingRequestCfProperties, Context = ExecutionContext> = {

package/dist/api/config.d.ts

@@ -1,56 +1,29 @@
-import { OpenNextConfig } from "@opennextjs/aws/types/open-next";
+import { BaseOverride, LazyLoadedOverride, OpenNextConfig } from "@opennextjs/aws/types/open-next";
 import type { IncrementalCache, Queue, TagCache } from "@opennextjs/aws/types/overrides";
-export type CloudflareConfigOptions = {
+export type Override<T extends BaseOverride> = "dummy" | T | LazyLoadedOverride<T>;
+/**
+ * Cloudflare specific overrides.
+ *
+ * See the [Caching documentation](https://opennext.js.org/cloudflare/caching))
+ */
+export type CloudflareOverrides = {
     /**
-     * The incremental cache implementation to use, for more details see the [Caching documentation](https://opennext.js.org/cloudflare/caching))
-     *
-     * `@opennextjs/cloudflare` offers a kv incremental cache implementation ready
-     * to use which can be imported from `"@opennextjs/cloudflare/kv-cache"`
-     *
-     * @example
-     *   import { defineCloudflareConfig } from "@opennextjs/cloudflare";
-     *   import kvIncrementalCache from "@opennextjs/cloudflare/kv-cache";
-     *
-     *   export default defineCloudflareConfig({
-     *     incrementalCache: kvIncrementalCache,
-     *   });
+     * Sets the incremental cache implementation.
      */
-    incrementalCache?: "dummy" | IncrementalCache | (() => IncrementalCache | Promise<IncrementalCache>);
+    incrementalCache?: Override<IncrementalCache>;
     /**
-     * The tag cache implementation to use, for more details see the [Caching documentation](https://opennext.js.org/cloudflare/caching))
-     *
-     * `@opennextjs/cloudflare` offers a d1 tag cache implementation ready
-     * to use which can be imported from `"@opennextjs/cloudflare/d1-tag-cache"`
-     *
-     * @example
-     *   import { defineCloudflareConfig } from "@opennextjs/cloudflare";
-     *   import d1TagCache from "@opennextjs/cloudflare/d1-tag-cache";
-     *
-     *   export default defineCloudflareConfig({
-     *     tagCache: d1TagCache,
-     *   });
+     * Sets the tag cache implementation.
      */
-    tagCache?: "dummy" | TagCache | (() => TagCache | Promise<TagCache>);
+    tagCache?: Override<TagCache>;
     /**
-     * The revalidation queue implementation to use, for more details see the [Caching documentation](https://opennext.js.org/cloudflare/caching))
-     *
-     * `@opennextjs/cloudflare` offers an in memory queue implementation ready
-     * to use which can be imported from `"@opennextjs/cloudflare/memory-queue"`
-     *
-     * @example
-     *   import { defineCloudflareConfig } from "@opennextjs/cloudflare";
-     *   import memoryQueue from "@opennextjs/cloudflare/memory-queue";
-     *
-     *   export default defineCloudflareConfig({
-     *     queue: memoryQueue,
-     *   });
+     * Sets the revalidation queue implementation
      */
-    queue?: "dummy" | "direct" | Queue | (() => Queue | Promise<Queue>);
+    queue?: "direct" | Override<Queue>;
 };
 /**
  * Defines the OpenNext configuration that targets the Cloudflare adapter
  *
- * @param options options that enabled you to configure the application's behavior
+ * @param config options that enabled you to configure the application's behavior
  * @returns the OpenNext configuration object
  */
-export declare function defineCloudflareConfig(options?: CloudflareConfigOptions): OpenNextConfig;
+export declare function defineCloudflareConfig(config?: CloudflareOverrides): OpenNextConfig;

package/dist/api/config.js

@@ -1,37 +1,39 @@
 /**
  * Defines the OpenNext configuration that targets the Cloudflare adapter
  *
- * @param options options that enabled you to configure the application's behavior
+ * @param config options that enabled you to configure the application's behavior
  * @returns the OpenNext configuration object
  */
-export function defineCloudflareConfig(options = {}) {
-    const { incrementalCache, tagCache, queue } = options;
+export function defineCloudflareConfig(config = {}) {
+    const { incrementalCache, tagCache, queue } = config;
     return {
         default: {
             override: {
                 wrapper: "cloudflare-node",
                 converter: "edge",
-                incrementalCache: resolveOverride(incrementalCache),
-                tagCache: resolveOverride(tagCache),
-                queue: resolveOverride(queue),
-            },
-        },
-        middleware: {
-            external: true,
-            override: {
-                wrapper: "cloudflare-edge",
-                converter: "edge",
                 proxyExternalRequest: "fetch",
+                incrementalCache: resolveIncrementalCache(incrementalCache),
+                tagCache: resolveTagCache(tagCache),
+                queue: resolveQueue(queue),
             },
         },
     };
 }
-function resolveOverride(value) {
-    if (!value || value === "dummy") {
-        return "dummy";
+function resolveIncrementalCache(value = "dummy") {
+    if (typeof value === "string") {
+        return value;
     }
-    if (value === "direct") {
-        return "direct";
+    return typeof value === "function" ? value : () => value;
+}
+function resolveTagCache(value = "dummy") {
+    if (typeof value === "string") {
+        return value;
+    }
+    return typeof value === "function" ? value : () => value;
+}
+function resolveQueue(value = "dummy") {
+    if (typeof value === "string") {
+        return value;
     }
-    return (typeof value === "function" ? value : () => value);
+    return typeof value === "function" ? value : () => value;
 }

package/dist/api/durable-objects/queue.d.ts

@@ -0,0 +1,32 @@
+import type { QueueMessage } from "@opennextjs/aws/types/overrides";
+import { DurableObject } from "cloudflare:workers";
+interface FailedState {
+    msg: QueueMessage;
+    retryCount: number;
+    nextAlarmMs: number;
+}
+export declare class DurableObjectQueueHandler extends DurableObject<CloudflareEnv> {
+    ongoingRevalidations: Map<string, Promise<void>>;
+    sql: SqlStorage;
+    routeInFailedState: Map<string, FailedState>;
+    service: NonNullable<CloudflareEnv["WORKER_SELF_REFERENCE"]>;
+    readonly maxRevalidations: number;
+    readonly revalidationTimeout: number;
+    readonly revalidationRetryInterval: number;
+    readonly maxRevalidationAttempts: number;
+    readonly disableSQLite: boolean;
+    constructor(ctx: DurableObjectState, env: CloudflareEnv);
+    revalidate(msg: QueueMessage): Promise<void>;
+    executeRevalidation(msg: QueueMessage): Promise<void>;
+    alarm(): Promise<void>;
+    addToFailedState(msg: QueueMessage): Promise<void>;
+    addAlarm(): Promise<void>;
+    initState(): Promise<void>;
+    /**
+     *
+     * @param msg
+     * @returns `true` if the route has been revalidated since the lastModified from the message, `false` otherwise
+     */
+    checkSyncTable(msg: QueueMessage): boolean;
+}
+export {};

package/dist/api/durable-objects/queue.js

@@ -0,0 +1,234 @@
+import { debug, error } from "@opennextjs/aws/adapters/logger.js";
+import { FatalError, IgnorableError, isOpenNextError, RecoverableError, } from "@opennextjs/aws/utils/error.js";
+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;
+export class DurableObjectQueueHandler extends DurableObject {
+    // 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)
+    ongoingRevalidations = new Map();
+    sql;
+    routeInFailedState = new Map();
+    service;
+    // Configurable params
+    maxRevalidations;
+    revalidationTimeout;
+    revalidationRetryInterval;
+    maxRevalidationAttempts;
+    disableSQLite;
+    constructor(ctx, env) {
+        super(ctx, env);
+        this.service = env.WORKER_SELF_REFERENCE;
+        // If there is no service binding, we throw an error because we can't revalidate without it
+        if (!this.service)
+            throw new IgnorableError("No service binding for cache revalidation worker");
+        this.sql = ctx.storage.sql;
+        this.maxRevalidations = env.NEXT_CACHE_DO_QUEUE_MAX_REVALIDATION
+            ? parseInt(env.NEXT_CACHE_DO_QUEUE_MAX_REVALIDATION)
+            : DEFAULT_MAX_REVALIDATION;
+        this.revalidationTimeout = env.NEXT_CACHE_DO_QUEUE_REVALIDATION_TIMEOUT_MS
+            ? parseInt(env.NEXT_CACHE_DO_QUEUE_REVALIDATION_TIMEOUT_MS)
+            : DEFAULT_REVALIDATION_TIMEOUT_MS;
+        this.revalidationRetryInterval = env.NEXT_CACHE_DO_QUEUE_RETRY_INTERVAL_MS
+            ? 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.disableSQLite = env.NEXT_CACHE_DO_QUEUE_DISABLE_SQLITE === "true";
+        // We restore the state
+        ctx.blockConcurrencyWhile(async () => {
+            debug(`Restoring the state of the durable object`);
+            await this.initState();
+        });
+        debug(`Durable object initialized`);
+    }
+    async revalidate(msg) {
+        // If there is already an ongoing revalidation, we don't need to revalidate again
+        if (this.ongoingRevalidations.has(msg.MessageDeduplicationId))
+            return;
+        // The route is already in a failed state, it will be retried later
+        if (this.routeInFailedState.has(msg.MessageDeduplicationId))
+            return;
+        // If the last success is newer than the last modified, it's likely that the regional cache is out of date
+        // We don't need to revalidate in this case
+        if (this.checkSyncTable(msg))
+            return;
+        if (this.ongoingRevalidations.size >= this.maxRevalidations) {
+            debug(`The maximum number of revalidations (${this.maxRevalidations}) is reached. Blocking until one of the revalidations finishes.`);
+            const ongoingRevalidations = this.ongoingRevalidations.values();
+            // When there is more than the max revalidations, we block concurrency until one of the revalidations finishes
+            // We still await the promise to ensure the revalidation is completed
+            // This is fine because the queue itself run inside a waitUntil
+            await this.ctx.blockConcurrencyWhile(async () => {
+                debug(`Waiting for one of the revalidations to finish`);
+                await Promise.race(ongoingRevalidations);
+            });
+        }
+        const revalidationPromise = this.executeRevalidation(msg);
+        // We store the promise to dedupe the revalidation
+        this.ongoingRevalidations.set(msg.MessageDeduplicationId, revalidationPromise);
+        // TODO: check if the object stays up during waitUntil so that the internal state is maintained
+        this.ctx.waitUntil(revalidationPromise);
+    }
+    async executeRevalidation(msg) {
+        try {
+            debug(`Revalidating ${msg.MessageBody.host}${msg.MessageBody.url}`);
+            const { MessageBody: { host, url }, } = msg;
+            const protocol = host.includes("localhost") ? "http" : "https";
+            const response = await this.service.fetch(`${protocol}://${host}${url}`, {
+                method: "HEAD",
+                headers: {
+                    // This is defined during build
+                    "x-prerender-revalidate": process.env.__NEXT_PREVIEW_MODE_ID,
+                    "x-isr": "1",
+                },
+                signal: AbortSignal.timeout(this.revalidationTimeout),
+            });
+            // Now we need to handle errors from the fetch
+            if (response.status === 200 && response.headers.get("x-nextjs-cache") !== "REVALIDATED") {
+                this.routeInFailedState.delete(msg.MessageDeduplicationId);
+                throw new FatalError(`The revalidation for ${host}${url} cannot be done. This error should never happen.`);
+            }
+            else if (response.status === 404) {
+                // The page is not found, we should not revalidate it
+                // We remove the route from the failed state because it might be expected (i.e. a route that was deleted)
+                this.routeInFailedState.delete(msg.MessageDeduplicationId);
+                throw new IgnorableError(`The revalidation for ${host}${url} cannot be done because the page is not found. It's either expected or an error in user code itself`);
+            }
+            else if (response.status === 500) {
+                // A server error occurred, we should retry
+                await this.addToFailedState(msg);
+                throw new IgnorableError(`Something went wrong while revalidating ${host}${url}`);
+            }
+            else if (response.status !== 200) {
+                // TODO: check if we need to handle cloudflare specific status codes/errors
+                // An unknown error occurred, most likely from something in user code like missing auth in the middleware
+                // We probably want to retry in this case as well
+                await this.addToFailedState(msg);
+                throw new RecoverableError(`An unknown error occurred while revalidating ${host}${url}`);
+            }
+            // Everything went well, we can update the sync table
+            // We use unixepoch here,it also works with Date.now()/1000, but not with Date.now() alone.
+            // TODO: This needs to be investigated
+            if (!this.disableSQLite) {
+                this.sql.exec("INSERT OR REPLACE INTO sync (id, lastSuccess, buildId) VALUES (?, unixepoch(), ?)", 
+                // We cannot use the deduplication id because it's not unique per route - every time a route is revalidated, the deduplication id is different.
+                `${host}${url}`, process.env.__NEXT_BUILD_ID);
+            }
+            // If everything went well, we can remove the route from the failed state
+            this.routeInFailedState.delete(msg.MessageDeduplicationId);
+        }
+        catch (e) {
+            // Do we want to propagate the error to the calling worker?
+            if (!isOpenNextError(e)) {
+                await this.addToFailedState(msg);
+            }
+            error(e);
+        }
+        finally {
+            this.ongoingRevalidations.delete(msg.MessageDeduplicationId);
+        }
+    }
+    async alarm() {
+        const currentDateTime = Date.now();
+        // We fetch the first event that needs to be retried or if the date is expired
+        const nextEventToRetry = Array.from(this.routeInFailedState.values())
+            .filter(({ nextAlarmMs }) => nextAlarmMs > currentDateTime)
+            .sort(({ nextAlarmMs: a }, { nextAlarmMs: b }) => a - b)[0];
+        // We also have to check if there are expired events, if the revalidation takes too long, or if the
+        const expiredEvents = Array.from(this.routeInFailedState.values()).filter(({ nextAlarmMs }) => nextAlarmMs <= currentDateTime);
+        const allEventsToRetry = nextEventToRetry ? [nextEventToRetry, ...expiredEvents] : expiredEvents;
+        for (const event of allEventsToRetry) {
+            debug(`Retrying revalidation for ${event.msg.MessageBody.host}${event.msg.MessageBody.url}`);
+            await this.executeRevalidation(event.msg);
+        }
+    }
+    async addToFailedState(msg) {
+        debug(`Adding ${msg.MessageBody.host}${msg.MessageBody.url} to the failed state`);
+        const existingFailedState = this.routeInFailedState.get(msg.MessageDeduplicationId);
+        let updatedFailedState;
+        if (existingFailedState) {
+            if (existingFailedState.retryCount >= this.maxRevalidationAttempts) {
+                // We give up after 6 retries and log the error
+                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.`);
+                this.routeInFailedState.delete(msg.MessageDeduplicationId);
+                return;
+            }
+            const nextAlarmMs = Date.now() + Math.pow(2, existingFailedState.retryCount + 1) * this.revalidationRetryInterval;
+            updatedFailedState = {
+                ...existingFailedState,
+                retryCount: existingFailedState.retryCount + 1,
+                nextAlarmMs,
+            };
+        }
+        else {
+            updatedFailedState = {
+                msg,
+                retryCount: 1,
+                nextAlarmMs: Date.now() + 2_000,
+            };
+        }
+        this.routeInFailedState.set(msg.MessageDeduplicationId, updatedFailedState);
+        if (!this.disableSQLite) {
+            this.sql.exec("INSERT OR REPLACE INTO failed_state (id, data, buildId) VALUES (?, ?, ?)", msg.MessageDeduplicationId, JSON.stringify(updatedFailedState), process.env.__NEXT_BUILD_ID);
+        }
+        // We probably want to do something if routeInFailedState is becoming too big, at least log it
+        await this.addAlarm();
+    }
+    async addAlarm() {
+        const existingAlarm = await this.ctx.storage.getAlarm({ allowConcurrency: false });
+        if (existingAlarm)
+            return;
+        if (this.routeInFailedState.size === 0)
+            return;
+        let nextAlarmToSetup = Math.min(...Array.from(this.routeInFailedState.values()).map(({ nextAlarmMs }) => nextAlarmMs));
+        if (nextAlarmToSetup < Date.now()) {
+            // We don't want to set an alarm in the past
+            nextAlarmToSetup = Date.now() + this.revalidationRetryInterval;
+        }
+        await this.ctx.storage.setAlarm(nextAlarmToSetup);
+    }
+    // This function is used to restore the state of the durable object
+    // We don't restore the ongoing revalidations because we cannot know in which state they are
+    // We only restore the failed state and the alarm
+    async initState() {
+        if (this.disableSQLite)
+            return;
+        // We store the failed state as a blob, we don't want to do anything with it anyway besides restoring
+        this.sql.exec("CREATE TABLE IF NOT EXISTS failed_state (id TEXT PRIMARY KEY, data TEXT, buildId TEXT)");
+        // We create the sync table to handle eventually consistent incremental cache
+        this.sql.exec("CREATE TABLE IF NOT EXISTS sync (id TEXT PRIMARY KEY, lastSuccess INTEGER, buildId TEXT)");
+        // Before doing anything else, we clear the DB for any potential old data
+        this.sql.exec("DELETE FROM failed_state WHERE buildId != ?", process.env.__NEXT_BUILD_ID);
+        this.sql.exec("DELETE FROM sync WHERE buildId != ?", process.env.__NEXT_BUILD_ID);
+        const failedStateCursor = this.sql.exec("SELECT * FROM failed_state");
+        for (const row of failedStateCursor) {
+            this.routeInFailedState.set(row.id, JSON.parse(row.data));
+        }
+        // Now that we have restored the failed state, we can restore the alarm as well
+        await this.addAlarm();
+    }
+    /**
+     *
+     * @param msg
+     * @returns `true` if the route has been revalidated since the lastModified from the message, `false` otherwise
+     */
+    checkSyncTable(msg) {
+        try {
+            if (this.disableSQLite)
+                return false;
+            const numNewer = this.sql
+                .exec("SELECT COUNT(*) as numNewer FROM sync WHERE id = ? AND lastSuccess > ? LIMIT 1", `${msg.MessageBody.host}${msg.MessageBody.url}`, Math.round(msg.MessageBody.lastModified / 1000))
+                .one().numNewer;
+            return numNewer > 0;
+            // eslint-disable-next-line @typescript-eslint/no-unused-vars
+        }
+        catch (e) {
+            return false;
+        }
+    }
+}