@opennextjs/aws 4.1.12 → 4.1.14

package/dist/build/patch/patches/patchNextServer.js

@@ -60,6 +60,47 @@ rule:
 fix:
  return globalThis.__openNextAls.getStore()?.waitUntil;
 `;
+/**
+ * Exposes `NextNodeServer#revalidate` to `res.revalidate()` of the Pages Router API routes.
+ *
+ * Starting with Next 15.4, `res.revalidate()` uses the `revalidate` function of the router server
+ * context (`globalThis[Symbol.for("@next/router-server-methods")]`) to revalidate in-process.
+ * The context is populated by the router server which is not used by OpenNext.
+ * Without it, `res.revalidate()` throws
+ * `Invariant: missing internal router-server-methods this is an internal bug`.
+ *
+ * `NextNodeServer#handleCatchallRenderRequest` creates the context for environments without
+ * router server, this rule adds `revalidate` to it:
+ *
+ * ```js
+ * routerServerGlobal[RouterServerContextSymbol][relativeProjectDir] = {
+ *   render404: this.render404.bind(this),
+ *   // added by the rule
+ *   revalidate: this.revalidate.bind(this),
+ * };
+ * ```
+ *
+ * OpenNext wraps `NextNodeServer#revalidate` at runtime, see `core/revalidate.ts`.
+ *
+ * https://github.com/vercel/next.js/blob/4e6c27b/packages/next/src/server/api-utils/node/api-resolver.ts
+ */
+export const exposeRevalidateRule = `
+rule:
+  pattern:
+    context: "({ render404: this.render404.bind(this) })"
+    selector: pair
+  inside:
+    kind: object
+    not:
+      has:
+        kind: pair
+        has:
+          field: key
+          regex: ^revalidate$
+fix: |-
+  render404: this.render404.bind(this),
+  revalidate: this.revalidate.bind(this)
+`;
 /**
  * Swaps the body for a throwing implementation
  *
@@ -138,6 +179,13 @@ export const patchNextServer = {
             contentFilter: /getInternalWaitUntil/,
             patchCode: createPatchCode(provideInternalWaitUntil),
         },
+        // Expose `NextNodeServer#revalidate` to `res.revalidate()`
+        {
+            versions: ">=15.4.0",
+            pathFilter,
+            contentFilter: /render404: this\.render404\.bind\(this\)/,
+            patchCode: createPatchCode(exposeRevalidateRule),
+        },
         ...babelPatches,
     ],
 };

package/dist/build/patch/testUtils.d.ts

@@ -0,0 +1,49 @@
+import { type CodePatcher } from "./codePatcher.js";
+/**
+ * A Next.js package installed on disk.
+ */
+export interface NextPackage {
+    /** Directory of the package, i.e. the directory of its `package.json`. */
+    dir: string;
+    /** Version of the package. */
+    version: string;
+}
+/**
+ * Compute the diff resulting of applying the `rule` to `src`.
+ *
+ * `diff` is an optional peer dependency of `@opennextjs/aws`: it must be installed to call this function.
+ *
+ * @param filename Filename used in the patch output
+ * @param src Content of the source code
+ * @param rule ASTgrep rule
+ * @returns diff in unified diff format
+ * @throws When the `diff` package is not installed
+ */
+export declare function computePatchDiff(filename: string, src: string, rule: string): string;
+/**
+ * Get the Next.js packages installed for some applications.
+ *
+ * Packages are deduplicated by version: a package manager can install the same version in multiple
+ * directories (i.e. pnpm when the peer dependencies differ).
+ *
+ * @param appDirs Directories of the applications (absolute or relative to the current working directory),
+ *                `next` is resolved from their `package.json`
+ * @returns the path and version of the Next.js packages
+ * @throws When `next` can not be resolved from one of the applications
+ */
+export declare function getInstalledNextPackages(appDirs: string[]): NextPackage[];
+/**
+ * Get the files of a Next.js package that a code patcher applies to.
+ *
+ * It selects the files the same way `applyCodePatches` does at build time,
+ * i.e. using the `versions`, the `pathFilter` and the `contentFilter` of the patches.
+ *
+ * @param next A Next.js package, see `getInstalledNextPackages`
+ * @param codePatcher The code patcher
+ * @returns the files (path relative to the package) with their content and the patches to apply
+ */
+export declare function getNextFilesToPatch(next: NextPackage, codePatcher: CodePatcher): {
+    name: string;
+    code: string;
+    patches: CodePatcher["patches"];
+}[];

package/dist/build/patch/testUtils.js

@@ -0,0 +1,78 @@
+/**
+ * Utilities to test code patches.
+ *
+ * They are used by the OpenNext adapters to test their patches against frozen snippets and against
+ * the files of the Next.js versions they are installed with.
+ * This module is not used at build time or at runtime.
+ */
+import { readFileSync, readdirSync } from "node:fs";
+import { createRequire } from "node:module";
+import path from "node:path";
+import { patchCode } from "./astCodePatcher.js";
+import { isVersionInRange } from "./codePatcher.js";
+const require = createRequire(import.meta.url);
+/**
+ * Compute the diff resulting of applying the `rule` to `src`.
+ *
+ * `diff` is an optional peer dependency of `@opennextjs/aws`: it must be installed to call this function.
+ *
+ * @param filename Filename used in the patch output
+ * @param src Content of the source code
+ * @param rule ASTgrep rule
+ * @returns diff in unified diff format
+ * @throws When the `diff` package is not installed
+ */
+export function computePatchDiff(filename, src, rule) {
+    // Loaded lazily so that the other utilities can be used without `diff`.
+    const { createPatch } = require("diff");
+    const dst = patchCode(src, rule);
+    return createPatch(filename, src, dst);
+}
+/**
+ * Get the Next.js packages installed for some applications.
+ *
+ * Packages are deduplicated by version: a package manager can install the same version in multiple
+ * directories (i.e. pnpm when the peer dependencies differ).
+ *
+ * @param appDirs Directories of the applications (absolute or relative to the current working directory),
+ *                `next` is resolved from their `package.json`
+ * @returns the path and version of the Next.js packages
+ * @throws When `next` can not be resolved from one of the applications
+ */
+export function getInstalledNextPackages(appDirs) {
+    const packages = new Map();
+    for (const appDir of appDirs) {
+        const appRequire = createRequire(path.join(path.resolve(appDir), "package.json"));
+        const dir = path.dirname(appRequire.resolve("next/package.json"));
+        const { version } = JSON.parse(readFileSync(path.join(dir, "package.json"), "utf-8"));
+        if (!packages.has(version)) {
+            packages.set(version, dir);
+        }
+    }
+    return [...packages].map(([version, dir]) => ({ dir, version }));
+}
+/**
+ * Get the files of a Next.js package that a code patcher applies to.
+ *
+ * It selects the files the same way `applyCodePatches` does at build time,
+ * i.e. using the `versions`, the `pathFilter` and the `contentFilter` of the patches.
+ *
+ * @param next A Next.js package, see `getInstalledNextPackages`
+ * @param codePatcher The code patcher
+ * @returns the files (path relative to the package) with their content and the patches to apply
+ */
+export function getNextFilesToPatch(next, codePatcher) {
+    const patches = codePatcher.patches.filter(({ versions }) => isVersionInRange(next.version, versions));
+    return readdirSync(next.dir, { recursive: true }).flatMap((name) => {
+        const filePath = path.join(next.dir, name);
+        const matchingPath = patches.filter(({ pathFilter }) => filePath.match(pathFilter));
+        if (matchingPath.length === 0) {
+            return [];
+        }
+        const code = readFileSync(filePath, "utf-8");
+        const matchingContent = matchingPath.filter(({ contentFilter }) => !contentFilter || code.match(contentFilter));
+        return matchingContent.length === 0
+            ? []
+            : [{ name, code, patches: matchingContent }];
+    });
+}

package/dist/core/requestHandler.js

@@ -33,6 +33,11 @@ export async function openNextHandler(internalEvent, options) {
         if (initialHeaders["x-forwarded-host"]) {
             initialHeaders.host = initialHeaders["x-forwarded-host"];
         }
+        const requestStore = globalThis.__openNextAls.getStore();
+        if (requestStore) {
+            // Used by `res.revalidate()`, see `core/revalidate.ts`
+            requestStore.host = initialHeaders.host;
+        }
         debug("internalEvent", internalEvent);
         // These 3 will get overwritten by the routing handler if not using an external middleware
         const internalHeaders = {

package/dist/core/resolve.d.ts

@@ -51,5 +51,12 @@ export declare function resolveProxyRequest(proxyRequest: OverrideOptions["proxy
 /**
  * @__PURE__
  */
-export declare function resolveCdnInvalidation(cdnInvalidation: OverrideOptions["cdnInvalidation"]): Promise<import("../types/overrides.js").CDNInvalidationHandler>;
+export declare function resolveCdnInvalidation(cdnInvalidation: OverrideOptions["cdnInvalidation"]): Promise<{
+    name: string;
+    invalidatePaths: (_: {
+        initialPath: string;
+        rawPath: string;
+        resolvedRoutes: import("../types/open-next.js").ResolvedRoute[];
+    }[]) => Promise<void>;
+}>;
 export {};

package/dist/core/revalidate.d.ts

@@ -0,0 +1,68 @@
+import type { ResolvedRoute } from "../types/open-next.js";
+/**
+ * Arguments passed by Next to the router server `revalidate` function.
+ *
+ * Next renamed `revalidateHeaders` to `headers` in 16.x.
+ */
+export interface RevalidateArgs {
+    urlPath: string;
+    headers?: Record<string, string | string[] | undefined>;
+    revalidateHeaders?: Record<string, string | string[] | undefined>;
+    opts: {
+        unstable_onlyGenerated?: boolean;
+    };
+}
+export type RevalidateFn = (args: RevalidateArgs) => Promise<void>;
+/**
+ * Resolve the route of a path.
+ *
+ * Static routes take precedence over dynamic routes, as in Next.
+ *
+ * @param urlPath The path passed to `res.revalidate()`, may include the basePath and a locale
+ * @returns The resolved route or `undefined` when no route matches
+ */
+export declare function resolveRoute(urlPath: string): ResolvedRoute | undefined;
+/**
+ * Convert a resolved route to the format used in `functions[name].routes` of the OpenNext config.
+ *
+ * i.e. `pages/index`, `pages/blog/[slug]`, `app/page`, `app/blog/[slug]/page`, ...
+ *
+ * @param route The resolved route
+ * @returns The candidate route templates (app routes may have several because of route groups)
+ */
+export declare function getRouteTemplates(route: ResolvedRoute): string[];
+/**
+ * Returns whether the route is served by the current function.
+ *
+ * Routes that are not listed in any split function are served by the default function.
+ * Paths that do not match any route are considered local so that Next handles them.
+ *
+ * @param route The resolved route
+ * @returns `true` when the route is served by the current function
+ */
+export declare function isServedByCurrentFunction(route: ResolvedRoute | undefined): boolean;
+/**
+ * Revalidate a page served by another function by sending a `HEAD` request to the app.
+ *
+ * Only the revalidate headers provided by Next are forwarded (no cookies).
+ * The function serving the page takes care of the CDN invalidation.
+ *
+ * TODO: the host comes from the request headers, use a trusted origin instead.
+ *
+ * @param args The arguments passed by Next to `revalidate`
+ * @throws When the host is unknown or the page has not been revalidated
+ */
+export declare function revalidateRemote({ urlPath, headers, revalidateHeaders, opts, }: RevalidateArgs): Promise<void>;
+/**
+ * Wrap `NextNodeServer#revalidate` used by `res.revalidate()` in the Pages Router API routes.
+ *
+ * - Pages served by the current function are revalidated in-process, then invalidated in the CDN.
+ * - Pages served by another split function are revalidated with a `HEAD` request.
+ *
+ * `NextNodeServer#revalidate` is exposed to `res.revalidate()` by a build time patch,
+ * see `exposeRevalidateRule` in `build/patch/patches/patchNextServer.ts`.
+ *
+ * @param revalidateInProcess The original `NextNodeServer#revalidate`
+ * @returns The wrapped revalidate function
+ */
+export declare function createRevalidate(revalidateInProcess: RevalidateFn): RevalidateFn;

package/dist/core/revalidate.js

@@ -0,0 +1,143 @@
+import { AppPathRoutesManifest } from "../adapters/config/index.js";
+import { NEXTJS_CACHE_HEADER } from "../utils/cacheHeaders.js";
+import { RequestCache } from "../utils/requestCache.js";
+import { debug, error } from "../adapters/logger";
+import { dynamicRouteMatcher, staticRouteMatcher, } from "./routing/routeMatcher";
+/**
+ * Timeout of the request revalidating a page served by another function.
+ */
+const REMOTE_REVALIDATE_TIMEOUT_MS = 30_000;
+/**
+ * Resolve the route of a path.
+ *
+ * Static routes take precedence over dynamic routes, as in Next.
+ *
+ * @param urlPath The path passed to `res.revalidate()`, may include the basePath and a locale
+ * @returns The resolved route or `undefined` when no route matches
+ */
+export function resolveRoute(urlPath) {
+    const pathname = urlPath.split(/[?#]/)[0];
+    return staticRouteMatcher(pathname)[0] ?? dynamicRouteMatcher(pathname)[0];
+}
+/**
+ * Convert a resolved route to the format used in `functions[name].routes` of the OpenNext config.
+ *
+ * i.e. `pages/index`, `pages/blog/[slug]`, `app/page`, `app/blog/[slug]/page`, ...
+ *
+ * @param route The resolved route
+ * @returns The candidate route templates (app routes may have several because of route groups)
+ */
+export function getRouteTemplates(route) {
+    if (route.type === "page") {
+        return [`pages${route.route === "/" ? "/index" : route.route}`];
+    }
+    return Object.entries(AppPathRoutesManifest)
+        .filter(([, path]) => path === route.route)
+        .map(([appPath]) => `app${appPath}`);
+}
+/**
+ * Returns whether the route is served by the current function.
+ *
+ * Routes that are not listed in any split function are served by the default function.
+ * Paths that do not match any route are considered local so that Next handles them.
+ *
+ * @param route The resolved route
+ * @returns `true` when the route is served by the current function
+ */
+export function isServedByCurrentFunction(route) {
+    const functions = globalThis.openNextConfig?.functions ?? {};
+    if (!route || Object.keys(functions).length === 0) {
+        return true;
+    }
+    const templates = getRouteTemplates(route);
+    const owner = Object.entries(functions).find(([, fn]) => fn.routes?.some((r) => templates.includes(r)))?.[0];
+    // `globalThis.fnName` is `undefined` in the default function
+    return owner === (globalThis.fnName || undefined);
+}
+/**
+ * Revalidate a page served by another function by sending a `HEAD` request to the app.
+ *
+ * Only the revalidate headers provided by Next are forwarded (no cookies).
+ * The function serving the page takes care of the CDN invalidation.
+ *
+ * TODO: the host comes from the request headers, use a trusted origin instead.
+ *
+ * @param args The arguments passed by Next to `revalidate`
+ * @throws When the host is unknown or the page has not been revalidated
+ */
+export async function revalidateRemote({ urlPath, headers, revalidateHeaders, opts, }) {
+    const host = globalThis.__openNextAls.getStore()?.host;
+    if (!host) {
+        throw new Error(`Unable to revalidate ${urlPath}: unknown host`);
+    }
+    const requestHeaders = new Headers();
+    for (const [key, value] of Object.entries(headers ?? revalidateHeaders ?? {})) {
+        if (value === undefined)
+            continue;
+        for (const v of Array.isArray(value) ? value : [value]) {
+            requestHeaders.append(key, v);
+        }
+    }
+    const url = `https://${host}${urlPath}`;
+    debug("Revalidating page served by another function", { url });
+    const res = await globalThis.internalFetch(url, {
+        method: "HEAD",
+        headers: requestHeaders,
+        redirect: "manual",
+        signal: AbortSignal.timeout(REMOTE_REVALIDATE_TIMEOUT_MS),
+    });
+    // Same check as Next, see `NextNodeServer#revalidate`
+    if (res.headers.get(NEXTJS_CACHE_HEADER)?.toUpperCase() !== "REVALIDATED" &&
+        res.status !== 200 &&
+        !(res.status === 404 && opts.unstable_onlyGenerated)) {
+        throw new Error(`Invalid response ${res.status}`);
+    }
+}
+/**
+ * Wrap `NextNodeServer#revalidate` used by `res.revalidate()` in the Pages Router API routes.
+ *
+ * - Pages served by the current function are revalidated in-process, then invalidated in the CDN.
+ * - Pages served by another split function are revalidated with a `HEAD` request.
+ *
+ * `NextNodeServer#revalidate` is exposed to `res.revalidate()` by a build time patch,
+ * see `exposeRevalidateRule` in `build/patch/patches/patchNextServer.ts`.
+ *
+ * @param revalidateInProcess The original `NextNodeServer#revalidate`
+ * @returns The wrapped revalidate function
+ */
+export function createRevalidate(revalidateInProcess) {
+    return async (args) => {
+        const route = resolveRoute(args.urlPath);
+        if (!isServedByCurrentFunction(route)) {
+            return revalidateRemote(args);
+        }
+        // Render the page in a context isolated from the API route request
+        // so that per-request state (i.e. `lastModified`, request cache) does not leak.
+        // The promise runner and `waitUntil` are shared to keep background work alive.
+        const store = globalThis.__openNextAls.getStore();
+        const renderInProcess = () => revalidateInProcess(args);
+        // Throws when the page has not been revalidated
+        await (store
+            ? globalThis.__openNextAls.run({
+                ...store,
+                lastModified: undefined,
+                writtenTags: new Set(),
+                requestCache: new RequestCache(),
+            }, renderInProcess)
+            : renderInProcess());
+        const path = args.urlPath.split(/[?#]/)[0];
+        try {
+            await globalThis.cdnInvalidationHandler?.invalidatePaths([
+                {
+                    initialPath: path,
+                    rawPath: path,
+                    resolvedRoutes: route ? [route] : [{ route: path, type: "page" }],
+                },
+            ]);
+        }
+        catch (e) {
+            // The page has been revalidated, only the CDN may serve stale content
+            error(`Failed to invalidate ${path} in the CDN`, e);
+        }
+    };
+}

package/dist/core/util.js

@@ -3,6 +3,7 @@ import { AppPathsManifestKeys, NextConfig, RoutesManifest, } from "../adapters/c
 import NextServer from "next/dist/server/next-server.js";
 import { debug, error } from "../adapters/logger.js";
 import { applyOverride as applyNextjsRequireHooksOverride, overrideHooks as overrideNextjsRequireHooks, } from "./require-hooks.js";
+import { createRevalidate } from "./revalidate.js";
 // WORKAROUND: Set `__NEXT_PRIVATE_PREBUNDLED_REACT` to use prebundled Reac
 // See https://opennext.js.org/aws/v2/advanced/workaround#workaround-set-__next_private_prebundled_react-to-use-prebundled-react
 // Step 1: Need to override the require hooks for React before Next.js server
@@ -67,6 +68,10 @@ const nextServer = new NextServer.default({
     dev: false,
     dir: __dirname,
 });
+// `res.revalidate()` in Pages Router API routes (Next 15.4+)
+if (typeof nextServer.revalidate === "function") {
+    nextServer.revalidate = createRevalidate(nextServer.revalidate.bind(nextServer));
+}
 let routesLoaded = false;
 globalThis.__next_route_preloader = async (stage) => {
     if (routesLoaded) {

package/dist/overrides/cdnInvalidation/cloudfront.js

@@ -11,7 +11,8 @@ export default {
                 ? [`/${path}`, `/${path}?_rsc=*`]
                 : [
                     `/${path}`,
-                    `/_next/data/${process.env.OPEN_NEXT_BUILD_ID}${path === "/" ? "/index" : `/${path}`}.json*`,
+                    // Data URLs are generated by Next and use the Next build id, not the Open Next build id
+                    `/_next/data/${process.env.NEXT_BUILD_ID}${path === "/" ? "/index" : `/${path}`}.json*`,
                 ];
         });
         await cloudfront.send(new CreateInvalidationCommand({

package/dist/overrides/wrappers/aws-lambda-compressed.js

@@ -1,6 +1,7 @@
 import { Readable, Writable } from "node:stream";
 import zlib from "node:zlib";
 import { error } from "../../adapters/logger";
+import { getBrotliQuality } from "../../utils/compression";
 import { formatWarmerResponse } from "./aws-lambda";
 const handler = async (handler, converter) => async (event) => {
     // Handle warmer event
@@ -70,10 +71,7 @@ function compressBody(body, encoding) {
             case "br":
                 transform = zlib.createBrotliCompress({
                     params: {
-                        // This is a compromise between speed and compression ratio.
-                        // The default one will most likely timeout an AWS Lambda with default configuration on large bodies (>6mb).
-                        // Therefore we set it to 6, which is a good compromise.
-                        [zlib.constants.BROTLI_PARAM_QUALITY]: Number(process.env.BROTLI_QUALITY) ?? 6,
+                        [zlib.constants.BROTLI_PARAM_QUALITY]: getBrotliQuality(),
                     },
                 });
                 break;

package/dist/overrides/wrappers/aws-lambda-streaming.js

@@ -1,6 +1,7 @@
 import { Readable } from "node:stream";
 import zlib from "node:zlib";
 import { debug, error } from "../../adapters/logger";
+import { getBrotliQuality } from "../../utils/compression";
 import { DetachedPromiseRunner } from "../../utils/promise";
 function formatWarmerResponse(event) {
     const result = new Promise((resolve) => {
@@ -34,6 +35,9 @@ const handler = async (handler, converter) => awslambda.streamifyResponse(async
         compressedStream = zlib.createBrotliCompress({
             flush: zlib.constants.BROTLI_OPERATION_FLUSH,
             finishFlush: zlib.constants.BROTLI_OPERATION_FINISH,
+            params: {
+                [zlib.constants.BROTLI_PARAM_QUALITY]: getBrotliQuality(),
+            },
         });
         compressedStream.pipe(responseStream);
     }

package/dist/plugins/edge.js

@@ -1,7 +1,7 @@
 import { readFileSync } from "node:fs";
 import path from "node:path";
 import chalk from "chalk";
-import { loadAppPathRoutesManifest, loadAppPathsManifest, loadAppPathsManifestKeys, loadBuildId, loadConfig, loadConfigHeaders, loadFunctionsConfigManifest, loadHtmlPages, loadMiddlewareManifest, loadPagesManifest, loadPrerenderManifest, loadRoutesManifest, } from "../adapters/config/util.js";
+import { getOpenNextBuildId, loadAppPathRoutesManifest, loadAppPathsManifest, loadAppPathsManifestKeys, loadBuildId, loadConfig, loadConfigHeaders, loadFunctionsConfigManifest, loadHtmlPages, loadMiddlewareManifest, loadPagesManifest, loadPrerenderManifest, loadRoutesManifest, } from "../adapters/config/util.js";
 import logger from "../logger.js";
 import { normalizePath } from "../utils/normalize-path.js";
 import { getCrossPlatformPathRegex } from "../utils/regex.js";
@@ -109,6 +109,7 @@ ${contents}
             build.onLoad({ filter: getCrossPlatformPathRegex("adapters/config/index") }, async () => {
                 const NextConfig = loadConfig(nextDir);
                 const BuildId = loadBuildId(nextDir);
+                const OpenNextBuildId = getOpenNextBuildId(NextConfig, BuildId);
                 const HtmlPages = loadHtmlPages(nextDir);
                 const RoutesManifest = loadRoutesManifest(nextDir);
                 const ConfigHeaders = loadConfigHeaders(nextDir);
@@ -145,7 +146,7 @@ ${contents}
   export const PagesManifest = ${JSON.stringify(PagesManifest)};
 
   process.env.NEXT_BUILD_ID = BuildId;
-  process.env.OPEN_NEXT_BUILD_ID = NextConfig.deploymentId ?? BuildId;
+  process.env.OPEN_NEXT_BUILD_ID = ${JSON.stringify(OpenNextBuildId)};
   process.env.NEXT_PREVIEW_MODE_ID = PrerenderManifest?.preview?.previewModeId;
 `;
                 return { contents };

package/dist/types/cache.d.ts

@@ -57,11 +57,22 @@ export interface CacheHandlerContext {
     _requestHeaders: never;
     fetchCacheKeyPrefix?: string;
 }
+/**
+ * The lifetime of a cache entry, as Next.js passes it to `set()` in `ctx.cacheControl`.
+ */
+export interface CacheControl {
+    revalidate: number | false;
+    expire?: number;
+}
 export interface CacheHandlerValue {
     lastModified?: number;
     age?: number;
     cacheState?: string;
     value: IncrementalCacheValue | null;
+    /**
+     * The lifetime of the entry, only read by Next.js 16.4+.
+     */
+    cacheControl?: CacheControl;
 }
 export type Extension = "cache" | "fetch" | "composable";
 type MetaHeaders = {
@@ -104,10 +115,7 @@ interface SetIncrementalFetchCacheContext {
 }
 interface SetIncrementalResponseCacheContext {
     fetchCache?: false;
-    cacheControl?: {
-        revalidate: number | false;
-        expire?: number;
-    };
+    cacheControl?: CacheControl;
     /**
      * True if the route is enabled for PPR.
      */

package/dist/types/global.d.ts

@@ -58,6 +58,13 @@ interface OpenNextRequestContext {
     writtenTags: Set<string>;
     /** Per-request in-memory cache. Overrides can use this to store data scoped to the current request. */
     requestCache: RequestCache;
+    /**
+     * Host of the request (`x-forwarded-host` or `host` header).
+     *
+     * Used by `res.revalidate()` to revalidate pages served by another split function.
+     * Only available in main functions.
+     */
+    host?: string;
 }
 declare global {
     /**

package/dist/types/open-next.d.ts

@@ -192,7 +192,10 @@ export interface InstallOptions {
     packages: string[];
     /** @default undefined */
     arch?: "x64" | "arm64";
-    /** @default undefined */
+    /**
+     * @default undefined
+     * @deprecated npm no longer supports the `--target` flag, so this option is ignored.
+     */
     nodeVersion?: string;
     /** @default undefined */
     libc?: "glibc" | "musl";

package/dist/types/overrides.d.ts

@@ -98,6 +98,11 @@ export type CacheValue<CacheType extends CacheEntryType> = (CacheType extends "f
      * This is available for page cache entry, but only at runtime.
      */
     revalidate?: number | false;
+    /**
+     * This is available for page cache entry, but only at runtime.
+     * The cache interceptor does not use it.
+     */
+    expire?: number;
 };
 export type IncrementalCache = {
     get<CacheType extends CacheEntryType = "cache">(key: string, cacheType?: CacheType): Promise<WithLastModified<CacheValue<CacheType>> | null>;
@@ -240,12 +245,54 @@ export type OriginResolver = BaseOverride & {
 export type ProxyExternalRequest = BaseOverride & {
     proxy: (event: InternalEvent) => Promise<InternalResult>;
 };
+/**
+ * Describes a path whose CDN entries must be invalidated.
+ *
+ * Includes the path before and after routing as well as the routes that matched
+ * while resolving the request.
+ */
 type CDNPath = {
+    /** The original request pathname before route resolution. */
     initialPath: string;
+    /** The effective request pathname after route resolution. */
     rawPath: string;
+    /** The routes that matched while resolving the request. */
     resolvedRoutes: ResolvedRoute[];
 };
+/**
+ * Invalidates CDN entries after on-demand revalidation.
+ *
+ * Implementations must support path invalidation and may additionally support
+ * native cache-tag invalidation.
+ */
 export type CDNInvalidationHandler = BaseOverride & {
+    /**
+     * Invalidates CDN entries associated with resolved paths.
+     *
+     * @param paths Paths and routing metadata for the entries to invalidate.
+     * @returns A promise that resolves when invalidation is complete.
+     */
     invalidatePaths: (paths: CDNPath[]) => Promise<void>;
+    /**
+     * Invalidates CDN entries associated with cache tags.
+     *
+     * Called once per `revalidateTag` call, after the tag cache has been updated,
+     * with the tags passed to Next.js as is: hard tags from `revalidateTag()` and
+     * soft tags (prefixed with `_N_T_/`) from `revalidatePath()`. Tags are not
+     * expanded, i.e. the hard tags of the paths matching a soft tag are not added.
+     *
+     * When provided, `invalidatePaths` is no longer called for tag revalidation.
+     * It is still used for `res.revalidate()` in the Pages Router.
+     * When omitted, OpenNext resolves the tags to paths and calls `invalidatePaths`.
+     *
+     * The CDN integration must associate cached entries with the same tags, both
+     * hard and soft, for invalidation to have an effect. For response-based CDN
+     * caches, the wrapper or converter must propagate the request's cache tags to
+     * the provider's response metadata.
+     *
+     * @param tags Cache tags associated with the entries to invalidate.
+     * @returns A promise that resolves when invalidation is complete.
+     */
+    invalidateTags?: (tags: string[]) => Promise<void>;
 };
 export {};

package/dist/utils/cache.js

@@ -45,7 +45,7 @@ export function getStaleLastModified(revalidate) {
         return 1;
     }
     if (typeof revalidate !== "number") {
-        // Without a revalidate value Next cannot derive an expire time either,
+        // The cache adapter then reports `{ revalidate: 1 }` without `expire` (see `getCacheControl`),
         // so the historical sentinel is still safe here.
         return 1;
     }