feat(cache): probe Pages Router cacheability

Author: james-elicx

packages/cloudflare/src/cacheability-probe.ts

@@ -161,7 +161,7 @@ export async function probeStagedWorkerCacheability(options: {
       });
       if (
         result.version !== 1 ||
-        result.kind !== "app-page" ||
+        (result.kind !== "app-page" && result.kind !== "pages-page") ||
         typeof result.pattern !== "string" ||
         !result.pattern.startsWith("/") ||
         !isProbeRouteState(result.state) ||
@@ -177,7 +177,7 @@ export async function probeStagedWorkerCacheability(options: {
       }
 
       const route: CacheabilityManifestRoute = {
-        kind: "app-page",
+        kind: result.kind,
         pattern: result.pattern,
         representation: identity.representation,
         requestKey: identity.requestKey,

packages/cloudflare/src/cdn-warm.ts

@@ -88,6 +88,7 @@ export type PrerenderWarmPlan = {
   buildIdentity?: string;
   deploymentId?: string;
   loadingShellPaths: string[];
+  pagesPaths?: string[];
   paths: string[];
   rscBuildId?: string;
   rscPaths: string[];
@@ -238,6 +239,7 @@ export function readPrerenderWarmPlan(
     loadingShellPaths: supportsCanonicalRsc
       ? (manifest.loadingShellPaths ?? []).map(applyConfig)
       : [],
+    ...(manifest.pagesPaths ? { pagesPaths: manifest.pagesPaths.map(applyConfig) } : {}),
     paths: htmlPaths,
     ...(supportsCanonicalRsc ? { rscBuildId: manifest.rscBuildId } : {}),
     rscPaths: supportsCanonicalRsc ? manifest.rscPaths!.map(applyConfig) : [],

packages/cloudflare/src/deploy.ts

@@ -1096,19 +1096,20 @@ async function deployWithCacheabilityProbe(
       ...discovered,
       appPaths: discovered.appPaths ? [...discovered.appPaths] : undefined,
       loadingShellPaths: [...discovered.loadingShellPaths],
+      pagesPaths: discovered.pagesPaths ? [...discovered.pagesPaths] : undefined,
       paths: [...discovered.paths],
       rscPaths: [...discovered.rscPaths],
     };
-    if (!plan.appPaths) {
+    if (!plan.appPaths && !plan.pagesPaths) {
       throw new Error(
-        "Two-stage CDN warming requires staged discovery to report App Page route ownership.",
+        "Two-stage CDN warming requires staged discovery to report App or Pages route ownership.",
       );
     }
-    const appPathSet = new Set(plan.appPaths);
-    plan.paths = plan.paths.filter((pathname) => appPathSet.has(pathname));
+    const ownedHtmlPaths = new Set([...(plan.appPaths ?? []), ...(plan.pagesPaths ?? [])]);
+    plan.paths = plan.paths.filter((pathname) => ownedHtmlPaths.has(pathname));
     if (!hasCdnWarmRequests(plan)) {
       throw new Error(
-        "Two-stage CDN warming did not discover any App Page request identities to probe.",
+        "Two-stage CDN warming did not discover any page request identities to probe.",
       );
     }
 

packages/vinext/src/index.ts

@@ -288,6 +288,7 @@ import { getPagesPreviewModeId } from "./server/pages-preview.js";
 import commonjs from "vite-plugin-commonjs";
 import { createIgnoreDynamicRequestsPlugin } from "./plugins/ignore-dynamic-requests.js";
 import { createTransformCache } from "./plugins/transform-cache.js";
+import { isServerEnvironment } from "./plugins/environment.js";
 import {
   isPathInside,
   isPathInsideOrEqual,
@@ -3905,7 +3906,10 @@ export default function vinext(options: VinextOptions = {}): PluginOption[] {
           // App Router virtual modules
           if (cleanId === VIRTUAL_RSC_ENTRY) return RESOLVED_RSC_ENTRY;
           if (cleanId === VIRTUAL_CACHEABILITY_MANIFEST) {
-            if (this.environment?.name === "rsc" && this.environment.config?.command === "build") {
+            const isWorkerBuildEnvironment = hasAppDir
+              ? this.environment?.name === "rsc"
+              : this.environment !== undefined && isServerEnvironment(this.environment);
+            if (isWorkerBuildEnvironment && this.environment.config?.command === "build") {
               return { id: `./${CACHEABILITY_MANIFEST_MODULE}`, external: true };
             }
             return RESOLVED_CACHEABILITY_MANIFEST;
@@ -4410,7 +4414,10 @@ export const loadServerActionClient = ${
       apply: "build",
 
       generateBundle() {
-        if (this.environment?.name !== "rsc") return;
+        const isWorkerBuildEnvironment = hasAppDir
+          ? this.environment?.name === "rsc"
+          : this.environment !== undefined && isServerEnvironment(this.environment);
+        if (!isWorkerBuildEnvironment) return;
         this.emitFile({
           type: "asset",
           fileName: CACHEABILITY_MANIFEST_MODULE,
@@ -6753,16 +6760,35 @@ export const loadServerActionClient = ${
         sequential: true,
         order: "post" as const,
         handler(options: { dir?: string }) {
-          const envName = this.environment?.name;
-          // Fire for App Router RSC builds (rsc env) and Pages Router SSR builds
-          // (ssr env). Skip client and other environments.
-          if (envName !== "rsc" && envName !== "ssr") return;
+          const environment = this.environment;
+          // App Router metadata belongs to its RSC build. Pages Router may use
+          // Vite's `ssr` environment or a platform-owned server environment
+          // such as the one created by the Cloudflare Vite plugin.
+          if (
+            !environment ||
+            (hasAppDir ? environment.name !== "rsc" : !isServerEnvironment(environment))
+          ) {
+            return;
+          }
 
           const outDir = options.dir;
           if (!outDir) return;
 
           const manifest = { prerenderSecret };
-          fs.writeFileSync(path.join(outDir, "vinext-server.json"), JSON.stringify(manifest));
+          const source = JSON.stringify(manifest);
+          fs.writeFileSync(path.join(outDir, "vinext-server.json"), source);
+
+          // Staged discovery and cacheability probing deliberately read build
+          // metadata from the platform-independent server directory. A Pages
+          // Worker bundle may live in a platform-named output directory, so
+          // retain the adjacent copy above and also publish the canonical copy.
+          if (!hasAppDir) {
+            const canonicalServerDir = path.join(root, "dist", "server");
+            if (path.resolve(outDir) !== canonicalServerDir) {
+              fs.mkdirSync(canonicalServerDir, { recursive: true });
+              fs.writeFileSync(path.join(canonicalServerDir, "vinext-server.json"), source);
+            }
+          }
         },
       },
     },

packages/vinext/src/server/cacheability-manifest.ts

@@ -16,6 +16,7 @@ import { APP_RSC_RENDER_MODE_PREFETCH_LOADING_SHELL } from "./app-rsc-render-mod
 
 export const CACHEABILITY_MANIFEST_MODULE = "__vinext_cacheability_manifest.js";
 
+export type CacheabilityRouteKind = "app-page" | "pages-page";
 export type CacheabilityRepresentation = "html" | "rsc-full" | "rsc-loading-shell";
 type CacheabilityManifestRouteState =
   | "static-candidate"
@@ -24,7 +25,7 @@ type CacheabilityManifestRouteState =
   | "probe-failed";
 
 export type CacheabilityManifestRoute = {
-  kind: "app-page";
+  kind: CacheabilityRouteKind;
   pattern: string;
   representation: CacheabilityRepresentation;
   requestKey: string;
@@ -64,7 +65,7 @@ function parseRoute(key: string, value: unknown): CacheabilityManifestRoute | nu
   if (!value || typeof value !== "object" || Array.isArray(value)) return null;
   const route = value as Record<string, unknown>;
   if (
-    route.kind !== "app-page" ||
+    (route.kind !== "app-page" && route.kind !== "pages-page") ||
     typeof route.pattern !== "string" ||
     !route.pattern.startsWith("/") ||
     !isRepresentation(route.representation) ||
@@ -78,7 +79,7 @@ function parseRoute(key: string, value: unknown): CacheabilityManifestRoute | nu
     return null;
   }
   const parsed: CacheabilityManifestRoute = {
-    kind: "app-page",
+    kind: route.kind,
     pattern: route.pattern,
     representation: route.representation,
     requestKey: route.requestKey,
@@ -175,17 +176,13 @@ export function cacheabilityRequestIdentity(request: Request): {
 
 export function findCacheabilityManifestRoute(
   manifest: CacheabilityManifest,
+  kind: CacheabilityRouteKind,
   pattern: string,
   identity: { representation: CacheabilityRepresentation; requestKey: string },
 ): CacheabilityManifestRoute | null {
   return (
     manifest.routes[
-      cacheabilityManifestRouteKey(
-        "app-page",
-        pattern,
-        identity.representation,
-        identity.requestKey,
-      )
+      cacheabilityManifestRouteKey(kind, pattern, identity.representation, identity.requestKey)
     ] ?? null
   );
 }

packages/vinext/src/server/cacheability-request.ts

@@ -4,7 +4,12 @@ import {
   type RouteCacheabilityOutcome,
   type RouteCacheabilityState,
 } from "vinext/shims/cacheability-classification";
-import { applyCdnResponseHeaders, NO_STORE_CACHE_CONTROL } from "./cache-control.js";
+import {
+  applyCdnResponseHeaders,
+  hasExplicitNonCacheableResponsePolicy,
+  NO_STORE_CACHE_CONTROL,
+} from "./cache-control.js";
+import { isNonCacheableCacheControl } from "vinext/shims/cdn-cache";
 import { VINEXT_CACHEABILITY_PROBE_HEADER, VINEXT_PRERENDER_SECRET_HEADER } from "./headers.js";
 import { workerCapabilityMatches } from "./worker-prerender-discovery.js";
 import {
@@ -27,7 +32,7 @@ type CacheabilityProbeRouteState =
 
 type CacheabilityProbeResult = {
   cacheControl?: string;
-  kind?: "app-page";
+  kind?: "app-page" | "pages-page";
   pattern?: string;
   reason?: string;
   state: CacheabilityProbeRouteState;
@@ -285,6 +290,38 @@ function responseWithCachePolicy(
   });
 }
 
+function inferPagesPageCacheability(response: Response): RouteCacheabilityOutcome {
+  const cacheControl =
+    response.headers.get("Cloudflare-CDN-Cache-Control") ??
+    response.headers.get("CDN-Cache-Control") ??
+    response.headers.get("Cache-Control");
+  if (!cacheControl || isNonCacheableCacheControl(cacheControl)) {
+    return { cacheable: false };
+  }
+  const cacheTag = response.headers.get("Cache-Tag");
+  return {
+    cacheable: true,
+    cacheControl,
+    ...(cacheTag
+      ? {
+          tags: cacheTag
+            .split(",")
+            .map((tag) => tag.trim())
+            .filter(Boolean),
+        }
+      : {}),
+  };
+}
+
+function completedRouteOutcome(
+  response: Response,
+  state: RouteCacheabilityState,
+): RouteCacheabilityOutcome | null {
+  if (state.route?.kind !== "pages-page") return state.outcome ?? null;
+  if (hasExplicitNonCacheableResponsePolicy(response.headers)) return { cacheable: false };
+  return state.outcome ?? inferPagesPageCacheability(response);
+}
+
 function staticToDynamicResponse(route: CacheabilityManifestRoute): Response {
   const headers = new Headers({ "Content-Type": "text/plain; charset=utf-8" });
   applyCdnResponseHeaders(headers, { cacheControl: NO_STORE_CACHE_CONTROL });
@@ -312,12 +349,17 @@ async function finalizeWorkerCacheabilityAdmission(
     return responseWithCachePolicy(response, response.body, null);
   }
   const manifest = admission.manifest as CacheabilityManifest;
-  const manifestRoute = findCacheabilityManifestRoute(manifest, state.route.pattern, {
-    representation: admission.representation as Parameters<
-      typeof findCacheabilityManifestRoute
-    >[2]["representation"],
-    requestKey: admission.requestKey,
-  });
+  const manifestRoute = findCacheabilityManifestRoute(
+    manifest,
+    state.route.kind,
+    state.route.pattern,
+    {
+      representation: admission.representation as Parameters<
+        typeof findCacheabilityManifestRoute
+      >[3]["representation"],
+      requestKey: admission.requestKey,
+    },
+  );
   if (
     !manifestRoute ||
     manifestRoute.state === "dynamic" ||
@@ -338,7 +380,9 @@ async function finalizeWorkerCacheabilityAdmission(
     return responseWithCachePolicy(response, captured.body, null);
   }
 
-  const outcome = state.completion ? await state.completion : (state.outcome ?? null);
+  const outcome = state.completion
+    ? await state.completion
+    : completedRouteOutcome(response, state);
   if (outcome?.cacheable !== true || !outcome.cacheControl) {
     return manifestRoute.state === "static-candidate" &&
       (outcome === null || outcome.dynamicUsage === true)
@@ -366,7 +410,7 @@ export async function finalizeWorkerCacheabilityResponse(
       state.route ? "runtime-check" : "probe-failed",
       state.route
         ? { cacheable: false }
-        : { cacheable: false, reason: "request did not resolve to a probeable App Page" },
+        : { cacheable: false, reason: "request did not resolve to a probeable page route" },
       response.status,
     );
   }
@@ -376,7 +420,7 @@ export async function finalizeWorkerCacheabilityResponse(
     return probeResponse(
       state,
       "probe-failed",
-      { cacheable: false, reason: "request did not resolve to a probeable App Page" },
+      { cacheable: false, reason: "request did not resolve to a probeable page route" },
       response.status,
     );
   }
@@ -401,7 +445,9 @@ export async function finalizeWorkerCacheabilityResponse(
     );
   }
 
-  const outcome = state.completion ? await state.completion : state.outcome;
+  const outcome = state.completion
+    ? await state.completion
+    : completedRouteOutcome(response, state);
   if (!outcome) {
     return probeResponse(
       state,