@opennextjs/aws 4.1.13 → 4.1.15

package/dist/core/routing/routeParamPlaceholder.js

@@ -0,0 +1,42 @@
+import { dynamicRouteMatcher } from "./routeMatcher";
+// The placeholders of a route pattern: `[slug]`, `[...slug]` or `[[...slug]]`
+const PLACEHOLDER_REGEX = /\[\[\.\.\.[^\]]+\]\]|\[(?:\.\.\.)?[^\]]+\]/g;
+// A placeholder starts with `[`, which is either literal or percent encoded in the pathname
+const OPENING_BRACKET_REGEX = /\[|%5b/i;
+/**
+ * Returns whether a segment of the pathname is the placeholder of a matched dynamic App Router page.
+ *
+ * Next.js versions before 16.4.5 treat a param whose value is its placeholder (e.g. `[slug]` for `[slug]`) as an
+ * unresolved fallback param. Such values are not legitimate and must not reach Next.js.
+ *
+ * Segments are decoded like Next.js decodes param values (catch-all values are split on `/` first).
+ * Segments with a malformed percent encoding never match.
+ * Pathnames without an opening bracket return early, without matching the dynamic routes.
+ *
+ * @param pathname The internal pathname, which may include the basePath, a locale prefix and a trailing slash
+ * @returns Whether a segment of the pathname is a placeholder of a matched dynamic App Router page
+ */
+export function hasRouteParamPlaceholder(pathname) {
+    if (!OPENING_BRACKET_REGEX.test(pathname)) {
+        return false;
+    }
+    const placeholders = new Set(dynamicRouteMatcher(pathname)
+        .filter(({ type }) => type === "app")
+        .flatMap(({ route }) => route.match(PLACEHOLDER_REGEX) ?? []));
+    return (placeholders.size > 0 &&
+        pathname.split("/").some((segment) => placeholders.has(safeDecode(segment))));
+}
+/**
+ * Decodes a URI component without throwing.
+ *
+ * @param value The encoded value
+ * @returns The decoded value, or an empty string when the encoding is malformed
+ */
+function safeDecode(value) {
+    try {
+        return decodeURIComponent(value);
+    }
+    catch {
+        return "";
+    }
+}

package/dist/core/routingHandler.js

@@ -6,6 +6,7 @@ import { detectLocale } from "./routing/i18n";
 import { fixDataPage, getNextConfigHeaders, handleBeforeFilesRewrites, handleFallbackFalse, handleRedirects, handleRewrites, } from "./routing/matcher";
 import { handleMiddleware } from "./routing/middleware";
 import { dynamicRouteMatcher, staticRouteMatcher, } from "./routing/routeMatcher";
+import { hasRouteParamPlaceholder } from "./routing/routeParamPlaceholder";
 import { constructNextUrl, normalizeLocationHeader } from "./routing/util";
 export const MIDDLEWARE_HEADER_PREFIX = "x-middleware-response-";
 export const MIDDLEWARE_HEADER_PREFIX_LEN = MIDDLEWARE_HEADER_PREFIX.length;
@@ -159,7 +160,7 @@ export default async function routingHandler(event, { assetResolver }) {
         const isRouteFoundBeforeAllRewrites = isStaticRoute || isDynamicRoute || isExternalRewrite;
         // Resolve against the final internal pathname after every rewrite phase.
         // These ordered matches are also the authoritative cache owner candidates.
-        const resolvedRoutes = [
+        let resolvedRoutes = [
             ...staticRouteMatcher(eventOrResult.rawPath),
             ...dynamicRouteMatcher(eventOrResult.rawPath),
         ];
@@ -169,7 +170,12 @@ export default async function routingHandler(event, { assetResolver }) {
             isNextImageRoute ||
             // We need to check again once all rewrites have been applied
             staticRouteMatcher(eventOrResult.rawPath).length > 0 ||
-            dynamicRouteMatcher(eventOrResult.rawPath).length > 0)) {
+            dynamicRouteMatcher(eventOrResult.rawPath).length > 0) ||
+            // Next.js versions before 16.4.5 treat a param whose value is its placeholder (e.g. `[slug]`) as unresolved.
+            // Next.js receives both the rawPath and the URL pathname, which is normalized (e.g. dot segments).
+            (!isExternalRewrite &&
+                [eventOrResult.rawPath, new URL(eventOrResult.url).pathname].some(hasRouteParamPlaceholder))) {
+            resolvedRoutes = [];
             eventOrResult = {
                 ...eventOrResult,
                 rawPath: "/404",

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/http/framing.d.ts

@@ -0,0 +1,35 @@
+import type { ServerResponse } from "node:http";
+import { type Writable } from "node:stream";
+/**
+ * Largest `content-length` that is verified by buffering the body.
+ *
+ * It matches the largest response compressed by CloudFront, which only compresses responses with a `content-length`.
+ * Larger responses are streamed without `content-length`.
+ */
+export declare const MAX_VERIFIED_CONTENT_LENGTH = 10000000;
+/**
+ * Writes the head of a Node.js `ServerResponse` and returns the stream to write the body to.
+ *
+ * The framing headers set by the app may not match the body that is actually written (e.g. a `fetch()` response
+ * body is decoded but keeps the upstream `content-length`). The bytes past a stale `content-length` would stay on
+ * the keep-alive connection and be read as the next response.
+ *
+ * - `transfer-encoding` is always removed, Node.js picks the transfer coding.
+ * - A `content-length` that is not a valid length is removed.
+ * - `content-length` is kept for HEAD requests and 304 responses, Node.js does not write a body for them.
+ * - Otherwise `content-length` is only kept when the body has exactly the declared length. The body is buffered
+ *   until this is known, and the head is written then, so the first byte is only sent once the whole body is
+ *   received. When the length doesn't match, or is larger than `MAX_VERIFIED_CONTENT_LENGTH`, `content-length` is
+ *   removed and Node.js frames the body itself (chunked on HTTP/1.1).
+ *
+ * The status code and the headers are always validated synchronously, even when the head is written later.
+ *
+ * @param res The Node.js response.
+ * @param method The request method.
+ * @param statusCode The response status code.
+ * @param headers The response headers, keys are matched case-insensitively.
+ * @returns The stream to write the body to.
+ * @throws When the status code or a header is invalid, or the headers were already sent (same errors as
+ *   `res.writeHead()`).
+ */
+export declare function writeResponseHead(res: ServerResponse, method: string | undefined, statusCode: number, headers: Record<string, string>): Writable;

package/dist/http/framing.js

@@ -0,0 +1,181 @@
+import { Transform } from "node:stream";
+import { error } from "../adapters/logger";
+/**
+ * Largest `content-length` that is verified by buffering the body.
+ *
+ * It matches the largest response compressed by CloudFront, which only compresses responses with a `content-length`.
+ * Larger responses are streamed without `content-length`.
+ */
+export const MAX_VERIFIED_CONTENT_LENGTH = 10_000_000;
+/**
+ * Writes the head of a Node.js `ServerResponse` and returns the stream to write the body to.
+ *
+ * The framing headers set by the app may not match the body that is actually written (e.g. a `fetch()` response
+ * body is decoded but keeps the upstream `content-length`). The bytes past a stale `content-length` would stay on
+ * the keep-alive connection and be read as the next response.
+ *
+ * - `transfer-encoding` is always removed, Node.js picks the transfer coding.
+ * - A `content-length` that is not a valid length is removed.
+ * - `content-length` is kept for HEAD requests and 304 responses, Node.js does not write a body for them.
+ * - Otherwise `content-length` is only kept when the body has exactly the declared length. The body is buffered
+ *   until this is known, and the head is written then, so the first byte is only sent once the whole body is
+ *   received. When the length doesn't match, or is larger than `MAX_VERIFIED_CONTENT_LENGTH`, `content-length` is
+ *   removed and Node.js frames the body itself (chunked on HTTP/1.1).
+ *
+ * The status code and the headers are always validated synchronously, even when the head is written later.
+ *
+ * @param res The Node.js response.
+ * @param method The request method.
+ * @param statusCode The response status code.
+ * @param headers The response headers, keys are matched case-insensitively.
+ * @returns The stream to write the body to.
+ * @throws When the status code or a header is invalid, or the headers were already sent (same errors as
+ *   `res.writeHead()`).
+ */
+export function writeResponseHead(res, method, statusCode, headers) {
+    validateHead(res, statusCode);
+    let contentLength;
+    for (const [key, value] of Object.entries(headers)) {
+        const lowerKey = key.toLowerCase();
+        if (lowerKey === "content-length") {
+            contentLength = value;
+        }
+        else if (lowerKey !== "transfer-encoding") {
+            // `setHeader()` validates the header like `writeHead()` does
+            res.setHeader(key, value);
+        }
+    }
+    const expectedLength = parseContentLength(contentLength);
+    if (!Number.isNaN(expectedLength) &&
+        (method?.toUpperCase() === "HEAD" || statusCode === 304)) {
+        res.setHeader("content-length", String(expectedLength));
+        res.writeHead(statusCode);
+        res.flushHeaders();
+        return res;
+    }
+    if (statusCode === 204 || !(expectedLength <= MAX_VERIFIED_CONTENT_LENGTH)) {
+        res.writeHead(statusCode);
+        res.flushHeaders();
+        return res;
+    }
+    const body = new ContentLengthVerifier(res, statusCode, expectedLength);
+    body.pipe(res);
+    return body;
+}
+/**
+ * Checks that the head can be written, the way `res.writeHead()` does.
+ *
+ * The headers are validated by `res.setHeader()`.
+ *
+ * @param res The Node.js response.
+ * @param statusCode The response status code.
+ * @throws {Error} When the headers were already sent (code `ERR_HTTP_HEADERS_SENT`).
+ * @throws {RangeError} When the status code is not in 100-999 (code `ERR_HTTP_INVALID_STATUS_CODE`).
+ */
+function validateHead(res, statusCode) {
+    if (res.headersSent) {
+        throw Object.assign(new Error("Cannot write headers after they are sent to the client"), { code: "ERR_HTTP_HEADERS_SENT" });
+    }
+    const code = statusCode | 0;
+    if (code < 100 || code > 999) {
+        throw Object.assign(new RangeError(`Invalid status code: ${statusCode}`), {
+            code: "ERR_HTTP_INVALID_STATUS_CODE",
+        });
+    }
+}
+/**
+ * Parses a `content-length` header value.
+ *
+ * @param contentLength The header value.
+ * @returns The length, or `NaN` when the value is missing or not a valid length.
+ */
+function parseContentLength(contentLength) {
+    const value = contentLength?.trim() ?? "";
+    const length = /^\d+$/.test(value) ? Number(value) : Number.NaN;
+    return Number.isSafeInteger(length) ? length : Number.NaN;
+}
+/**
+ * Buffers the body until it is known whether it has the declared length, then writes the head and the body.
+ *
+ * The headers, other than `content-length`, are already set on the response.
+ */
+class ContentLengthVerifier extends Transform {
+    res;
+    statusCode;
+    expectedLength;
+    chunks = [];
+    length = 0;
+    headWritten = false;
+    /**
+     * @param res The Node.js response.
+     * @param statusCode The response status code, already validated.
+     * @param expectedLength The declared `content-length`.
+     */
+    constructor(res, statusCode, expectedLength) {
+        super();
+        this.res = res;
+        this.statusCode = statusCode;
+        this.expectedLength = expectedLength;
+    }
+    /**
+     * Buffers the chunk until the head is written, then passes it through.
+     *
+     * The head is written without `content-length` as soon as the body is longer than declared.
+     *
+     * @param chunk The body chunk.
+     * @param _encoding Unused, chunks are buffers.
+     * @param callback Called once the chunk is processed.
+     */
+    _transform(chunk, _encoding, callback) {
+        if (this.headWritten) {
+            callback(null, chunk);
+            return;
+        }
+        this.chunks.push(chunk);
+        this.length += chunk.length;
+        if (this.length > this.expectedLength) {
+            this.writeHead(false);
+        }
+        callback();
+    }
+    /**
+     * Writes the head, when not already written, once the whole body is received.
+     *
+     * @param callback Called once the head and the buffered chunks are written.
+     */
+    _flush(callback) {
+        if (!this.headWritten) {
+            this.writeHead(this.length === this.expectedLength);
+        }
+        callback();
+    }
+    /**
+     * Writes the head and the buffered chunks.
+     *
+     * This runs from the stream callbacks, where a thrown error would be uncaught and crash the process. The
+     * head is validated synchronously in `writeResponseHead()`, if writing it still fails, the response is destroyed.
+     *
+     * @param keepContentLength Whether the body has the declared length.
+     */
+    writeHead(keepContentLength) {
+        this.headWritten = true;
+        const chunks = this.chunks;
+        this.chunks = [];
+        try {
+            if (keepContentLength) {
+                this.res.setHeader("content-length", String(this.expectedLength));
+            }
+            this.res.writeHead(this.statusCode);
+        }
+        catch (e) {
+            error("Failed to write the response head", e);
+            this.res.destroy();
+            // Without an error, no `error` event is emitted
+            this.destroy();
+            return;
+        }
+        for (const chunk of chunks) {
+            this.push(chunk);
+        }
+    }
+}

package/dist/http/util.d.ts

@@ -8,6 +8,17 @@ export declare const convertHeader: (header: http.OutgoingHttpHeader) => string;
  * @returns A list of Set-Cookie header
  */
 export declare function parseSetCookieHeader(cookies: string | string[] | null | undefined): string[];
+/**
+ * Converts the headers of a response returned by an edge function.
+ *
+ * `Set-Cookie` headers are returned as a list.
+ * The internal `x-middleware-set-cookie` header is dropped: `NextResponse` sets it when
+ * `response.cookies` is modified (i.e. in a route handler) and it contains the `HttpOnly` cookies.
+ *
+ * @param headers The headers of the response
+ * @returns The response headers to send to the client
+ */
+export declare function convertEdgeResponseHeaders(headers: Pick<Headers, "forEach" | "getSetCookie">): Record<string, string | string[]>;
 /**
  *
  * Get the query object from an iterable of [key, value] pairs

package/dist/http/util.js

@@ -58,6 +58,32 @@ export function parseSetCookieHeader(cookies) {
     }
     return cookies;
 }
+/**
+ * Converts the headers of a response returned by an edge function.
+ *
+ * `Set-Cookie` headers are returned as a list.
+ * The internal `x-middleware-set-cookie` header is dropped: `NextResponse` sets it when
+ * `response.cookies` is modified (i.e. in a route handler) and it contains the `HttpOnly` cookies.
+ *
+ * @param headers The headers of the response
+ * @returns The response headers to send to the client
+ */
+export function convertEdgeResponseHeaders(headers) {
+    const responseHeaders = {};
+    headers.forEach((value, key) => {
+        const lowerKey = key.toLowerCase();
+        // Headers.forEach folds same-name headers; use getSetCookie() below instead.
+        if (lowerKey === "set-cookie" || lowerKey === "x-middleware-set-cookie") {
+            return;
+        }
+        responseHeaders[key] = value;
+    });
+    const setCookies = headers.getSetCookie();
+    if (setCookies.length > 0) {
+        responseHeaders["set-cookie"] = setCookies;
+    }
+    return responseHeaders;
+}
 /**
  *
  * Get the query object from an iterable of [key, value] pairs

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/proxyExternalRequest/fetch.js

@@ -4,7 +4,11 @@ const fetchProxy = {
     // @ts-ignore
     proxy: async (internalEvent) => {
         const { url, headers: eventHeaders, method, body } = internalEvent;
-        const headers = Object.fromEntries(Object.entries(eventHeaders).filter(([key]) => key.toLowerCase() !== "cf-connecting-ip"));
+        const headers = Object.fromEntries(Object.entries(eventHeaders).filter(([key]) => !["cf-connecting-ip", "x-forwarded-host"].includes(key.toLowerCase())));
+        // Like Next.js, do not relay the `x-forwarded-host` sent by the client
+        if (eventHeaders.host) {
+            headers["x-forwarded-host"] = eventHeaders.host;
+        }
         const response = await fetch(url, {
             method,
             headers,

package/dist/overrides/proxyExternalRequest/node.js

@@ -6,6 +6,7 @@ function filterHeadersForProxy(headers) {
     const filteredHeaders = {};
     const disallowedHeaders = [
         "host",
+        "x-forwarded-host",
         "connection",
         "via",
         "x-cache",
@@ -30,6 +31,10 @@ const nodeProxy = {
         debug("proxyRequest", url);
         return new Promise((resolve, reject) => {
             const filteredHeaders = filterHeadersForProxy(headers);
+            // Like Next.js, do not relay the `x-forwarded-host` sent by the client
+            if (headers.host) {
+                filteredHeaders["x-forwarded-host"] = headers.host;
+            }
             debug("filteredHeaders", filteredHeaders);
             const req = request(url, {
                 headers: filteredHeaders,

package/dist/overrides/wrappers/express-dev.js

@@ -1,6 +1,7 @@
 import path from "node:path";
 import express from "express";
 import { NextConfig } from "../../adapters/config/index.js";
+import { writeResponseHead } from "../../http/framing.js";
 import { getMonorepoRelativePath } from "../../utils/normalize-path.js";
 const wrapper = async (handler, converter) => {
     const app = express();
@@ -16,8 +17,7 @@ const wrapper = async (handler, converter) => {
         const internalEvent = await converter.convertFrom(req);
         const streamCreator = {
             writeHeaders: (prelude) => {
-                res.writeHead(prelude.statusCode, prelude.headers);
-                return res;
+                return writeResponseHead(res, req.method, prelude.statusCode, prelude.headers);
             },
         };
         await imageHandler(internalEvent, { streamCreator });
@@ -34,9 +34,7 @@ const wrapper = async (handler, converter) => {
         const streamCreator = {
             writeHeaders: (prelude) => {
                 res.setHeader("Set-Cookie", prelude.cookies);
-                res.writeHead(prelude.statusCode, prelude.headers);
-                res.flushHeaders();
-                return res;
+                return writeResponseHead(res, req.method, prelude.statusCode, prelude.headers);
             },
             onFinish: () => { },
             abortSignal: abortController.signal,

package/dist/overrides/wrappers/node.js

@@ -1,4 +1,5 @@
 import { createServer } from "node:http";
+import { writeResponseHead } from "../../http/framing.js";
 import { debug, error } from "../../adapters/logger";
 const wrapper = async (handler, converter) => {
     const server = createServer(async (req, res) => {
@@ -7,9 +8,7 @@ const wrapper = async (handler, converter) => {
         const streamCreator = {
             writeHeaders: (prelude) => {
                 res.setHeader("Set-Cookie", prelude.cookies);
-                res.writeHead(prelude.statusCode, prelude.headers);
-                res.flushHeaders();
-                return res;
+                return writeResponseHead(res, req.method, prelude.statusCode, prelude.headers);
             },
             abortSignal: abortController.signal,
         };

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.d.ts

@@ -1,4 +1,18 @@
 import type { CacheValue, NextModeTagCacheWriteInput, OriginalTagCacheWriteInput, WithLastModified } from "../types/overrides.js";
+/**
+ * Computes the key used to store a composable (`"use cache"`) entry.
+ *
+ * The cache key provided by Next.js embeds the serialized arguments of the cached function and may
+ * contain any UTF-16 string. Storage backends transform keys (path normalization, URL parsing,
+ * UTF-8 encoding, ...) which could map distinct Next.js keys to the same stored entry.
+ *
+ * The storage key is the sha256 of the exact UTF-16 code units of the cache key, as a 64 characters
+ * lowercase hex string that every backend can store as is.
+ *
+ * @param cacheKey The cache key provided by Next.js
+ * @returns The key to use for the incremental cache and the tag cache
+ */
+export declare function getComposableCacheStorageKey(cacheKey: string): string;
 /**
  *
  * @param key The key for that specific cache entry