Fix regional caching of tag cache (#3504)

conico974 · web-flow · commit c7993756ddd0 · 2025-07-29T13:27:56.000+02:00
Co-authored-by: Nicolas Dorseuil &lt;nicolas@gitbook.io&gt;
diff --git a/bun.lock b/bun.lock
diff --git a/packages/gitbook/openNext/customWorkers/default.js b/packages/gitbook/openNext/customWorkers/default.js
@@ -2,6 +2,9 @@ import { runWithCloudflareRequestContext } from '../../.open-next/cloudflare/ini
 
 import { DurableObject } from 'cloudflare:workers';
 
+//Only needed to run locally, in prod we'll use the one from do.js
+export { DOShardedTagCache } from '../../.open-next/.build/durable-objects/sharded-tag-cache.js';
+
 // Only needed to run locally, in prod we'll use the one from do.js
 export class R2WriteBuffer extends DurableObject {
     writePromise;
diff --git a/packages/gitbook/openNext/customWorkers/defaultWrangler.jsonc b/packages/gitbook/openNext/customWorkers/defaultWrangler.jsonc
@@ -36,13 +36,17 @@
                     {
                         "name": "WRITE_BUFFER",
                         "class_name": "R2WriteBuffer"
+                    },
+                    {
+                        "name": "NEXT_TAG_CACHE_DO_SHARDED",
+                        "class_name": "DOShardedTagCache"
                     }
                 ]
             },
             "migrations": [
                 {
                     "tag": "v1",
-                    "new_sqlite_classes": ["R2WriteBuffer"]
+                    "new_sqlite_classes": ["R2WriteBuffer", "DOShardedTagCache"]
                 }
             ]
         },
diff --git a/packages/gitbook/openNext/customWorkers/middlewareWrangler.jsonc b/packages/gitbook/openNext/customWorkers/middlewareWrangler.jsonc
@@ -22,6 +22,9 @@
             "vars": {
                 "STAGE": "dev",
                 "NEXT_PRIVATE_DEBUG_CACHE": "true",
+                // When deployed locally, we don't have access to the tag cache here,
+                // we should just bypass the cache to go to the server directly
+                "SHOULD_BYPASS_CACHE": "true",
                 "OPEN_NEXT_REQUEST_ID_HEADER": "true"
             },
             "r2_buckets": [
diff --git a/packages/gitbook/openNext/incrementalCache.ts b/packages/gitbook/openNext/incrementalCache.ts
@@ -36,6 +36,11 @@ class GitbookIncrementalCache implements IncrementalCache {
         const r2 = getCloudflareContext().env[BINDING_NAME];
         const localCache = await this.getCacheInstance();
         if (!r2) throw new Error('No R2 bucket');
+        if (process.env.SHOULD_BYPASS_CACHE === 'true') {
+            // We are in a local middleware environment, we should bypass the cache
+            // and go directly to the server.
+            return null;
+        }
         try {
             // Check local cache first if available
             const localCacheEntry = await localCache.match(this.getCacheUrlKey(cacheKey));
@@ -134,19 +139,27 @@ class GitbookIncrementalCache implements IncrementalCache {
     }
 
     async writeToR2(key: string, value: string): Promise<void> {
-        const env = getCloudflareContext().env as {
-            WRITE_BUFFER: DurableObjectNamespace<
-                Rpc.DurableObjectBranded & {
-                    write: (key: string, value: string) => Promise<void>;
-                }
-            >;
-        };
-        const id = env.WRITE_BUFFER.idFromName(key);
-
-        // A stub is a client used to invoke methods on the Durable Object
-        const stub = env.WRITE_BUFFER.get(id);
-
-        await stub.write(key, value);
+        try {
+            const env = getCloudflareContext().env as {
+                WRITE_BUFFER: DurableObjectNamespace<
+                    Rpc.DurableObjectBranded & {
+                        write: (key: string, value: string) => Promise<void>;
+                    }
+                >;
+            };
+            const id = env.WRITE_BUFFER.idFromName(key);
+
+            // A stub is a client used to invoke methods on the Durable Object
+            const stub = env.WRITE_BUFFER.get(id);
+
+            await stub.write(key, value);
+        } catch {
+            // We fallback to writing directly to R2
+            // it can fail locally because the limit is 1Mb per args
+            // It is 32Mb in production, so we should be fine
+            const r2 = getCloudflareContext().env[BINDING_NAME];
+            r2?.put(key, value);
+        }
     }
 
     async getCacheInstance(): Promise<Cache> {
diff --git a/packages/gitbook/openNext/tagCache/middleware.ts b/packages/gitbook/openNext/tagCache/middleware.ts
@@ -1,13 +1,14 @@
-import { getLogger } from '@/lib/logger';
+import { createLogger, getLogger } from '@/lib/logger';
 import type { NextModeTagCache } from '@opennextjs/aws/types/overrides.js';
 import doShardedTagCache from '@opennextjs/cloudflare/overrides/tag-cache/do-sharded-tag-cache';
 import { softTagFilter } from '@opennextjs/cloudflare/overrides/tag-cache/tag-cache-filter';
 
 const originalTagCache = doShardedTagCache({
     baseShardSize: 12,
     regionalCache: true,
-    // We can probably increase this value even further
-    regionalCacheTtlSec: 60,
+    regionalCacheTtlSec: 60 * 5 /* 5 minutes */,
+    // Because we invalidate the Cache API on update, we can safely set this to true
+    regionalCacheDangerouslyPersistMissingTags: true,
     shardReplication: {
         numberOfSoftReplicas: 2,
         numberOfHardReplicas: 1,
@@ -20,6 +21,7 @@ const originalTagCache = doShardedTagCache({
 export default {
     name: 'GitbookTagCache',
     mode: 'nextMode',
+    // We don't really use this one, as of now it is only used for soft tags
     getLastRevalidated: async (tags: string[]) => {
         const tagsToCheck = tags.filter(softTagFilter);
         if (tagsToCheck.length === 0) {
@@ -29,12 +31,20 @@ export default {
         return await originalTagCache.getLastRevalidated(tagsToCheck);
     },
     hasBeenRevalidated: async (tags: string[], lastModified?: number) => {
-        const tagsToCheck = tags.filter(softTagFilter);
-        if (tagsToCheck.length === 0) {
-            return false; // If no tags to check, return false
-        }
+        try {
+            const tagsToCheck = tags.filter(softTagFilter);
+            if (tagsToCheck.length === 0) {
+                return false; // If no tags to check, return false
+            }
 
-        return await originalTagCache.hasBeenRevalidated(tagsToCheck, lastModified);
+            return await originalTagCache.hasBeenRevalidated(tagsToCheck, lastModified);
+        } catch (e) {
+            createLogger('gitbookTagCache', {}).error(
+                `hasBeenRevalidated - Error checking tags ${tags.join(', ')}`,
+                e
+            );
+            return false; // In case of error, return false
+        }
     },
     writeTags: async (tags: string[]) => {
         const tagsToWrite = tags.filter(softTagFilter);
@@ -43,7 +53,7 @@ export default {
             logger.warn('writeTags - No valid tags to write');
             return; // If no tags to write, exit early
         }
-        // Write only the filtered tags
+
         await originalTagCache.writeTags(tagsToWrite);
     },
 } satisfies NextModeTagCache;
diff --git a/packages/gitbook/package.json b/packages/gitbook/package.json
@@ -13,7 +13,7 @@
         "@gitbook/react-contentkit": "workspace:*",
         "@gitbook/react-math": "workspace:*",
         "@gitbook/react-openapi": "workspace:*",
-        "@opennextjs/cloudflare": "^1.4.0",
+        "@opennextjs/cloudflare": "^1.6.2",
         "@radix-ui/react-checkbox": "^1.0.4",
         "@radix-ui/react-dropdown-menu": "^2.1.12",
         "@radix-ui/react-navigation-menu": "^1.2.3",
@@ -22,6 +22,7 @@
         "@sindresorhus/fnv1a": "^3.1.0",
         "@tailwindcss/container-queries": "^0.1.1",
         "@tailwindcss/typography": "^0.5.16",
+        "@tusbar/cache-control": "^1.0.2",
         "ai": "^4.2.2",
         "assert-never": "^1.2.1",
         "bun-types": "^1.1.20",
@@ -49,7 +50,7 @@
         "object-identity": "^0.1.2",
         "openapi-types": "^12.1.3",
         "p-map": "^7.0.3",
-        "@tusbar/cache-control": "^1.0.2",
+        "quick-lru": "^7.0.1",
         "react-hotkeys-hook": "^4.4.1",
         "rehype-sanitize": "^6.0.0",
         "rehype-stringify": "^10.0.1",
@@ -67,8 +68,7 @@
         "url-join": "^5.0.0",
         "usehooks-ts": "^3.1.0",
         "warn-once": "^0.1.1",
-        "zustand": "^5.0.3",
-        "quick-lru": "^7.0.1"
+        "zustand": "^5.0.3"
     },
     "devDependencies": {
         "@argos-ci/playwright": "^5.0.5",

Original file line number	Diff line number	Diff line change
`@@ -36,13 +36,17 @@`
`36`	`36`	`{`
`37`	`37`	`"name": "WRITE_BUFFER",`
`38`	`38`	`"class_name": "R2WriteBuffer"`
	`39`	`+ },`
	`40`	`+ {`
	`41`	`+ "name": "NEXT_TAG_CACHE_DO_SHARDED",`
	`42`	`+ "class_name": "DOShardedTagCache"`
`39`	`43`	`}`
`40`	`44`	`]`
`41`	`45`	`},`
`42`	`46`	`"migrations": [`
`43`	`47`	`{`
`44`	`48`	`"tag": "v1",`
`45`		`- "new_sqlite_classes": ["R2WriteBuffer"]`
	`49`	`+ "new_sqlite_classes": ["R2WriteBuffer", "DOShardedTagCache"]`
`46`	`50`	`}`
`47`	`51`	`]`
`48`	`52`	`},`