cdk-nextjs 0.6.2 → 0.7.0

package/lib/runtime/core.d.ts

@@ -0,0 +1,234 @@
+import type { IncomingHttpHeaders } from "node:http";
+import { Readable } from "node:stream";
+import { RouteInOtherGroupError } from "./entrypoints";
+import { ResponseSink } from "./http/sink";
+import { AdapterManifest } from "./manifest";
+/** One request, normalized by a shell. */
+export interface RuntimeRequest {
+    readonly method: string;
+    /** Origin-form target exactly as received: path + query, never absolute. */
+    readonly url: string;
+    readonly headers: IncomingHttpHeaders;
+    readonly body?: Readable | Buffer;
+    readonly remoteAddress?: string;
+    /** `false` behind a TLS-terminating ALB. Only affects the synthesized socket. */
+    readonly encrypted?: boolean;
+    /**
+     * Aborted when the client disconnects. Wiring it to `res.destroy()` is what
+     * makes `request.signal.onabort` fire inside route handlers.
+     */
+    readonly signal?: AbortSignal;
+    /**
+     * Whether `x-forwarded-host` names the host the client asked for. Only the
+     * shell can know: it is `true` for a Function URL event whose SigV4 Lambda
+     * verified. That is any IAM-authorized invoker — in practice CloudFront's
+     * Origin Access Control, whose viewer-request function overwrites the header
+     * with the viewer's `Host` (CloudFront has to replace `Host` itself with the
+     * Function URL's domain), plus principals granted `lambda:InvokeFunctionUrl`,
+     * who could replace the function's code anyway. It is also what
+     * `proxyExternal` drops OAC's signature on. Everywhere else the header is
+     * whatever the client sent, and it is
+     * ignored, as `next start` ignores it without `experimental.trustHostHeader`.
+     */
+    readonly trustForwardedHost?: boolean;
+    /**
+     * Set by {@link NextjsRuntime.handleInternally} for the in-process requests it
+     * makes: called with the `RouteInOtherGroupError` the route threw, instead of
+     * logging the misrouted-request warning, which describes a CloudFront or API
+     * Gateway problem this is not.
+     */
+    readonly onRouteInOtherGroup?: (error: RouteInOtherGroupError) => void;
+}
+export interface NextjsRuntimeOptions {
+    /**
+     * Absolute path to the deployment root — the staged tree every manifest key
+     * resolves against. `LAMBDA_TASK_ROOT` for Functions, the image `WORKDIR` for
+     * Containers; both shells derive it from their own location instead.
+     */
+    readonly deploymentRoot: string;
+    readonly manifest: AdapterManifest;
+    /** `CDK_NEXTJS_STATIC_ASSETS_BUCKET_NAME`. */
+    readonly bucket?: string;
+    /** `CDK_NEXTJS_STATIC_ASSETS_KEY_PREFIX`. */
+    readonly bucketKeyPrefix?: string;
+}
+export declare class NextjsRuntime {
+    private readonly options;
+    private readonly entrypoints;
+    private readonly dispatcher;
+    private readonly middleware?;
+    private readonly images;
+    /** The 500 ladder; see `statusTargets`. */
+    private readonly errorTargetFor;
+    /** The assets bucket, when `public/` files are served from it. */
+    private readonly publicBucket?;
+    constructor(options: NextjsRuntimeOptions);
+    get manifest(): AdapterManifest;
+    handle(request: RuntimeRequest, sink: ResponseSink): Promise<void>;
+    private route;
+    /**
+     * 404 or 500 when `pathname` is the prerendered `/404` or `/500` page — under
+     * `basePath` and, in an i18n app, any locale (`/fr/404`) — and `undefined`
+     * otherwise. `next start` matches the page, not the URL, so the locale does
+     * not matter.
+     */
+    private statusPageStatus;
+    /**
+     * `next start`'s answer to a path nothing serves (`router-server.js`, the
+     * "404 case"), for both ways of getting here: dispatch matched nothing, or it
+     * matched a build asset that is not in the package.
+     *
+     * No-store, always. A prerendered `/_not-found` would otherwise send its
+     * cache entry's year-long `s-maxage`, and the CDN would keep the 404 past the
+     * deploy that adds the route. Set rather than forced: Next's page handlers
+     * only write a `Cache-Control` when none is set (`sendRenderResult`,
+     * `pages-handler.js`), which is exactly how `next start`'s own no-store here
+     * survives the render. `render404` is not this path: a `notFound()` from an
+     * ISR page is cacheable for that page's revalidate period.
+     *
+     * A missing `_next/static` file, and a GET or HEAD whose `Sec-Fetch-Dest`
+     * says it cannot display HTML (an `<img>`, a script, a font), get a
+     * plain-text `Not Found` instead of the rendered page — nothing would show
+     * it, and rendering it is the expensive part.
+     *
+     * Everything else renders the app's 404 as the path that was asked for, not
+     * as `/_not-found`: the App Router serializes the canonical URL into the RSC
+     * payload, so a client hydrated off a `/_not-found` payload reports the wrong
+     * `usePathname()` and pushes the wrong history entry. It renders with the
+     * request headers middleware set, too — a CSP nonce, say.
+     */
+    private sendUnmatched;
+    /**
+     * One on-demand revalidation, run against this runtime rather than over the
+     * network. Wired in as `requestMeta.revalidate`; see the comment there.
+     *
+     * The response is thrown away — only its status matters — but it goes through
+     * the full {@link handle}, so the entrypoint sees a request with
+     * `x-prerender-revalidate` on it and writes the fresh entry through the cache
+     * handler exactly as a request from outside would. `handle` awaits its own
+     * `waitUntil` work, so the new entry is committed before `res.revalidate()`
+     * resolves, which is what callers that revalidate and then redirect depend on.
+     *
+     * The accept/throw rule is `NextServer#revalidate`'s, verbatim: a revalidation
+     * is successful if it was cached or answered 200, and `notFound: true`
+     * legitimately answers 404 for an `unstable_onlyGenerated` caller. Anything
+     * else throws, and `res.revalidate()` turns it into `Failed to revalidate
+     * <path>: <message>`.
+     */
+    private revalidate;
+    /**
+     * An image optimization source that is not a file: `<Image src="/api/avatar">`
+     * served by a route handler. Wired in as the optimizer's `fetchInternal`, and
+     * run in process for the reasons {@link revalidate} is — `next start` fetches
+     * the source from itself over loopback, which here would be a second billed
+     * invocation through CloudFront.
+     *
+     * Only the authority is forwarded, as `next start`'s `fetchInternalImage`
+     * forwards none of the viewer's headers: the source is cached and served to
+     * everyone, so it must not depend on one viewer's cookies.
+     */
+    private fetchInternal;
+    /**
+     * One request through {@link handle}, answered to this runtime instead of a
+     * client: the head, the body when it is wanted, and the error when the route
+     * is packaged into another `functionGroups` group. `handle` awaits the
+     * request's `waitUntil` work too, so whatever the render wrote is committed by
+     * the time this resolves.
+     *
+     * The body is kept only when `maximumBody` is set. One past it fails the
+     * response stream, which stops the route writing, and comes back as
+     * `tooLarge` rather than held in memory.
+     */
+    private handleInternally;
+    /**
+     * App Router builds an invocable `/_not-found`, Pages Router a prerendered
+     * `404.html` (per locale under i18n) or else `/_error`; see `statusTargets`.
+     */
+    private sendNotFound;
+    /**
+     * Turn a thrown error into a response, rendering the app's error page when it
+     * has one.
+     *
+     * Next.js's own page handlers catch, report and then *rethrow* ("rethrow so
+     * that we can handle serving error page", `pages-handler.ts`), which makes the
+     * error page the host's job — the same division of labor as `render404`. Without
+     * this ladder every throw answered a bare `text/plain` 500 and a custom
+     * `pages/_error` was dead code (`test/e2e/async-modules`, whose `/make-error`
+     * throws in `getServerSideProps`).
+     *
+     * Once the head is out there is nothing to say — destroying the stream is what
+     * tells the client the response is truncated rather than complete.
+     */
+    private sendError;
+    /**
+     * A prerendered 404 or 500 page, or `false` when it cannot be read and the
+     * caller's plain-text fallback should answer. Read rather than `serveStatic`,
+     * which keeps the status already set but would answer a `Range` request with
+     * a 206 of the error page, and add `ETag`, `Last-Modified` and, where none is
+     * set yet, a public `Cache-Control` to it.
+     */
+    private sendHtmlFile;
+}
+/**
+ * The request headers with {@link INTERNAL_HEADERS} removed, and `x-nextjs-data`
+ * put back for a `_next/data` request, which is what `next start`'s
+ * `resolveRoutes` does (`setIsNextDataRequest`) right after stripping it: the
+ * header is internal, but Next's handlers and middleware still read it — it is
+ * how a data request gets `x-nextjs-matched-path` — so a real data request has
+ * to keep it.
+ */
+export declare function withoutInternalHeaders(headers: IncomingHttpHeaders, target: string, basePath: string): IncomingHttpHeaders;
+/**
+ * The `[route, dataRoute]` pairs a revalidated page is cached under at the edge.
+ *
+ * In an i18n app the Next client always puts the locale in a data href, the
+ * default locale included (`/_next/data/<id>/en/blog.json`, and `…/en.json` for
+ * the root), so the unprefixed data route names nothing CloudFront holds. The
+ * page is one locale's — `res.revalidate("/blog")` regenerates the default
+ * locale's, `"/fr/blog"` French — and the default locale's HTML is reachable,
+ * and cached, both with and without its prefix, so its two pairs share a data
+ * route, which the caller sends once.
+ */
+export declare function revalidatedPageRoutes(route: string, manifest: Pick<AdapterManifest, "buildId" | "config">): Array<[string, string]>;
+/**
+ * Read the manifest and pin the layout it describes.
+ *
+ * `process.cwd()` is load-bearing and there is exactly one chance to get it
+ * right: Next.js inlines `relative(buildCwd, projectDir)` into every entrypoint
+ * and resolves it against the *runtime* cwd to find
+ * `required-server-files.json`, the prerender manifest, and the app's chunks.
+ * `assertBuildCwd` in `build-outputs.ts` keeps that inlined value `""`, so the
+ * whole invariant reduces to "cwd is the staged project dir" — asserted rather
+ * than assumed, because getting it wrong produces a
+ * `Cannot find module …/required-server-files.json` from inside compiled Next.js
+ * code with no indication that the layout is the problem.
+ */
+export declare function loadRuntime(deploymentRoot: string): Promise<NextjsRuntime>;
+export interface SplitBody {
+    /** What `req` reads: the entrypoint's copy. */
+    readonly forRequest?: Readable | Buffer;
+    /** What `resolveRoutes` hands middleware. */
+    readonly forDispatch: ReadableStream;
+    /**
+     * Called once dispatch has returned, with whether middleware answered the
+     * request itself. Lets go of whichever copy nothing will read any more.
+     */
+    releaseUnread(middlewareResponded: boolean): void;
+}
+/**
+ * `resolveRoutes` hands `requestBody` to middleware, which consumes it, while the
+ * entrypoint needs the same bytes — the same problem `next-server` solves with
+ * `getCloneableBody()`. Only split when there is middleware to feed: teeing costs
+ * a buffer copy of every upload on a path that would otherwise be a straight pipe.
+ *
+ * A `tee()` buffers, for the branch that is behind, every chunk the other one
+ * has read — so a branch that is never read holds the whole body. Middleware
+ * that doesn't read the body is the common case (and its matcher may not even
+ * have run it), after which the entrypoint streaming an upload would pile all
+ * of it up in the middleware branch: the whole upload in memory, on a
+ * container that serves other requests. So once dispatch returns, the branch
+ * with no reader left is cancelled — the middleware one, or the entrypoint one
+ * when middleware answered and `req` will never be read. Cancelling one
+ * branch leaves the source and the other branch running.
+ */
+export declare function splitBody(body: Readable | Buffer | undefined, hasMiddleware: boolean): SplitBody;