feat(cloudflare): share one Workers Cache entry across a static App page's queries

packages/cloudflare/src/cacheability-artifact.ts

@@ -3,6 +3,8 @@ import path from "node:path";
 import { Buffer } from "node:buffer";
 import {
   CACHEABILITY_MANIFEST_MODULE,
+  CACHEABILITY_REQUEST_PROJECTION_MODULE,
+  projectCacheabilityManifestForRequestStage,
   type CacheabilityManifest,
 } from "vinext/internal/server/cacheability-manifest";
 import {
@@ -223,7 +225,7 @@ function resolveBuildOutputArtifact(root: string): GeneratedWorkerArtifact {
   return { configPath, main, serverDirectory: path.join(path.dirname(configPath), "bundle") };
 }
 
-function assertManifestModuleReachable(artifact: GeneratedWorkerArtifact): void {
+function assertModuleReachable(artifact: GeneratedWorkerArtifact, moduleName: string): void {
   const { main, serverDirectory } = artifact;
   const mainPath = path.resolve(serverDirectory, main);
   if (!fs.existsSync(mainPath) || !fs.lstatSync(mainPath).isFile()) {
@@ -253,16 +255,11 @@ function assertManifestModuleReachable(artifact: GeneratedWorkerArtifact): void
     if (!entry || typeof entry.file !== "string") continue;
     const modulePath = path.resolve(serverDirectory, entry.file);
     if (fs.existsSync(modulePath) && fs.lstatSync(modulePath).isFile()) {
-      const relativeManifest = path
-        .relative(
-          path.dirname(modulePath),
-          path.join(serverDirectory, CACHEABILITY_MANIFEST_MODULE),
-        )
+      const relativeModule = path
+        .relative(path.dirname(modulePath), path.join(serverDirectory, moduleName))
         .split(path.sep)
         .join("/");
-      const specifier = relativeManifest.startsWith(".")
-        ? relativeManifest
-        : `./${relativeManifest}`;
+      const specifier = relativeModule.startsWith(".") ? relativeModule : `./${relativeModule}`;
       reachable = hasStaticModuleSpecifier(fs.readFileSync(modulePath, "utf8"), specifier);
     }
     for (const references of [entry.imports, entry.dynamicImports]) {
@@ -273,15 +270,31 @@ function assertManifestModuleReachable(artifact: GeneratedWorkerArtifact): void
   }
   if (!reachable) {
     throw new Error(
-      `Two-stage CDN warming requires the generated Worker graph to statically import ${CACHEABILITY_MANIFEST_MODULE}.`,
+      `Two-stage CDN warming requires the generated Worker graph to statically import ${moduleName}.`,
     );
   }
 }
 
+function writeStringModule(modulePath: string, value: string): void {
+  const source = `export default ${JSON.stringify(value)};\n`;
+  const pendingPath = `${modulePath}.${process.pid}.tmp`;
+  try {
+    fs.writeFileSync(pendingPath, source, "utf8");
+    fs.renameSync(pendingPath, modulePath);
+  } finally {
+    if (fs.existsSync(pendingPath)) fs.unlinkSync(pendingPath);
+  }
+}
+
 /**
  * Write the version-specific manifest into the built Worker artifact.
  * The application build already imports this stable module asset, so the
  * completed dist directory remains the exact input to the final upload.
+ *
+ * App Router builds also emit the request stage's projection module. It
+ * carries the App page routes that can admit a query-free entry, so the
+ * request stage can strip the query from those dispatches without loading the
+ * full manifest.
  */
 export function writeCacheabilityManifestArtifact(
   root: string,
@@ -293,7 +306,7 @@ export function writeCacheabilityManifestArtifact(
     deploymentTool === "cf"
       ? resolveBuildOutputArtifact(root)
       : resolveGeneratedWranglerArtifact(root, configuredPath);
-  assertManifestModuleReachable(artifact);
+  assertModuleReachable(artifact, CACHEABILITY_MANIFEST_MODULE);
   const { configPath, serverDirectory } = artifact;
   const manifestPath = path.join(serverDirectory, CACHEABILITY_MANIFEST_MODULE);
   if (!fs.existsSync(manifestPath) || !fs.lstatSync(manifestPath).isFile()) {
@@ -307,13 +320,26 @@ export function writeCacheabilityManifestArtifact(
     throw cacheabilityManifestByteLimitError(manifestBytes);
   }
 
-  const manifestSource = `export default ${JSON.stringify(serializedManifest)};\n`;
-  const pendingManifestPath = `${manifestPath}.${process.pid}.tmp`;
-  try {
-    fs.writeFileSync(pendingManifestPath, manifestSource, "utf8");
-    fs.renameSync(pendingManifestPath, manifestPath);
-  } finally {
-    if (fs.existsSync(pendingManifestPath)) fs.unlinkSync(pendingManifestPath);
+  const projectionPath = path.join(serverDirectory, CACHEABILITY_REQUEST_PROJECTION_MODULE);
+  const hasProjectionModule =
+    fs.existsSync(projectionPath) && fs.lstatSync(projectionPath).isFile();
+  // Without the projection, the request stage would never drop the query for
+  // the App page paths this manifest certifies.
+  if (Object.values(manifest.routes).some((route) => route.kind === "app-page")) {
+    if (!hasProjectionModule) {
+      throw new Error(
+        `Two-stage CDN warming requires ${CACHEABILITY_REQUEST_PROJECTION_MODULE} in the generated Worker artifact. Rebuild the app before deploying.`,
+      );
+    }
+    assertModuleReachable(artifact, CACHEABILITY_REQUEST_PROJECTION_MODULE);
+  }
+
+  writeStringModule(manifestPath, serializedManifest);
+  if (hasProjectionModule) {
+    writeStringModule(
+      projectionPath,
+      JSON.stringify(projectCacheabilityManifestForRequestStage(manifest)),
+    );
   }
   return path.relative(root, configPath);
 }