cdk-nextjs 0.6.2 → 0.7.0

package/lib/runtime/deployment-root.d.ts

@@ -0,0 +1,13 @@
+/**
+ * The deployment root, derived from where the running shell sits.
+ *
+ * Synth copies the bundled shells and `manifest.json` into
+ * `<deploymentRoot>/${RUNTIME_DIR_NAME}/`, so the root is this file's parent's
+ * parent. Derived rather than read from `LAMBDA_TASK_ROOT` or the image
+ * `WORKDIR`, so that both shells agree and a consumer overriding `WORKDIR` in
+ * their own Dockerfile cannot break path resolution.
+ *
+ * @param shellDir the directory the calling shell was loaded from
+ * (`dirname(fileURLToPath(import.meta.url))`).
+ */
+export declare function deploymentRootOf(shellDir: string): string;

package/lib/runtime/deployment-root.js

@@ -0,0 +1,29 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.deploymentRootOf = deploymentRootOf;
+const node_path_1 = require("node:path");
+const manifest_1 = require("./manifest");
+/**
+ * The deployment root, derived from where the running shell sits.
+ *
+ * Synth copies the bundled shells and `manifest.json` into
+ * `<deploymentRoot>/${RUNTIME_DIR_NAME}/`, so the root is this file's parent's
+ * parent. Derived rather than read from `LAMBDA_TASK_ROOT` or the image
+ * `WORKDIR`, so that both shells agree and a consumer overriding `WORKDIR` in
+ * their own Dockerfile cannot break path resolution.
+ *
+ * @param shellDir the directory the calling shell was loaded from
+ * (`dirname(fileURLToPath(import.meta.url))`).
+ */
+function deploymentRootOf(shellDir) {
+    if ((0, node_path_1.basename)(shellDir) !== manifest_1.RUNTIME_DIR_NAME) {
+        // A synth-side packaging mistake. Caught here because the alternative
+        // symptom is "manifest.json not found" one directory away from the truth.
+        throw new Error(`The cdk-nextjs runtime expected to be deployed at ` +
+            `<deploymentRoot>/${manifest_1.RUNTIME_DIR_NAME}/ but is running from ` +
+            `"${shellDir}". Every manifest path resolves against the deployment ` +
+            `root, so it cannot be inferred from anywhere else.`);
+    }
+    return (0, node_path_1.dirname)(shellDir);
+}
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiZGVwbG95bWVudC1yb290LmpzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vLi4vc3JjL3J1bnRpbWUvZGVwbG95bWVudC1yb290LnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiI7O0FBZUEsNENBWUM7QUEzQkQseUNBQThDO0FBQzlDLHlDQUE4QztBQUU5Qzs7Ozs7Ozs7Ozs7R0FXRztBQUNILFNBQWdCLGdCQUFnQixDQUFDLFFBQWdCO0lBQy9DLElBQUksSUFBQSxvQkFBUSxFQUFDLFFBQVEsQ0FBQyxLQUFLLDJCQUFnQixFQUFFLENBQUM7UUFDNUMsc0VBQXNFO1FBQ3RFLDBFQUEwRTtRQUMxRSxNQUFNLElBQUksS0FBSyxDQUNiLG9EQUFvRDtZQUNsRCxvQkFBb0IsMkJBQWdCLHdCQUF3QjtZQUM1RCxJQUFJLFFBQVEseURBQXlEO1lBQ3JFLG9EQUFvRCxDQUN2RCxDQUFDO0lBQ0osQ0FBQztJQUNELE9BQU8sSUFBQSxtQkFBTyxFQUFDLFFBQVEsQ0FBQyxDQUFDO0FBQzNCLENBQUMiLCJzb3VyY2VzQ29udGVudCI6WyJpbXBvcnQgeyBiYXNlbmFtZSwgZGlybmFtZSB9IGZyb20gXCJub2RlOnBhdGhcIjtcbmltcG9ydCB7IFJVTlRJTUVfRElSX05BTUUgfSBmcm9tIFwiLi9tYW5pZmVzdFwiO1xuXG4vKipcbiAqIFRoZSBkZXBsb3ltZW50IHJvb3QsIGRlcml2ZWQgZnJvbSB3aGVyZSB0aGUgcnVubmluZyBzaGVsbCBzaXRzLlxuICpcbiAqIFN5bnRoIGNvcGllcyB0aGUgYnVuZGxlZCBzaGVsbHMgYW5kIGBtYW5pZmVzdC5qc29uYCBpbnRvXG4gKiBgPGRlcGxveW1lbnRSb290Pi8ke1JVTlRJTUVfRElSX05BTUV9L2AsIHNvIHRoZSByb290IGlzIHRoaXMgZmlsZSdzIHBhcmVudCdzXG4gKiBwYXJlbnQuIERlcml2ZWQgcmF0aGVyIHRoYW4gcmVhZCBmcm9tIGBMQU1CREFfVEFTS19ST09UYCBvciB0aGUgaW1hZ2VcbiAqIGBXT1JLRElSYCwgc28gdGhhdCBib3RoIHNoZWxscyBhZ3JlZSBhbmQgYSBjb25zdW1lciBvdmVycmlkaW5nIGBXT1JLRElSYCBpblxuICogdGhlaXIgb3duIERvY2tlcmZpbGUgY2Fubm90IGJyZWFrIHBhdGggcmVzb2x1dGlvbi5cbiAqXG4gKiBAcGFyYW0gc2hlbGxEaXIgdGhlIGRpcmVjdG9yeSB0aGUgY2FsbGluZyBzaGVsbCB3YXMgbG9hZGVkIGZyb21cbiAqIChgZGlybmFtZShmaWxlVVJMVG9QYXRoKGltcG9ydC5tZXRhLnVybCkpYCkuXG4gKi9cbmV4cG9ydCBmdW5jdGlvbiBkZXBsb3ltZW50Um9vdE9mKHNoZWxsRGlyOiBzdHJpbmcpOiBzdHJpbmcge1xuICBpZiAoYmFzZW5hbWUoc2hlbGxEaXIpICE9PSBSVU5USU1FX0RJUl9OQU1FKSB7XG4gICAgLy8gQSBzeW50aC1zaWRlIHBhY2thZ2luZyBtaXN0YWtlLiBDYXVnaHQgaGVyZSBiZWNhdXNlIHRoZSBhbHRlcm5hdGl2ZVxuICAgIC8vIHN5bXB0b20gaXMgXCJtYW5pZmVzdC5qc29uIG5vdCBmb3VuZFwiIG9uZSBkaXJlY3RvcnkgYXdheSBmcm9tIHRoZSB0cnV0aC5cbiAgICB0aHJvdyBuZXcgRXJyb3IoXG4gICAgICBgVGhlIGNkay1uZXh0anMgcnVudGltZSBleHBlY3RlZCB0byBiZSBkZXBsb3llZCBhdCBgICtcbiAgICAgICAgYDxkZXBsb3ltZW50Um9vdD4vJHtSVU5USU1FX0RJUl9OQU1FfS8gYnV0IGlzIHJ1bm5pbmcgZnJvbSBgICtcbiAgICAgICAgYFwiJHtzaGVsbERpcn1cIi4gRXZlcnkgbWFuaWZlc3QgcGF0aCByZXNvbHZlcyBhZ2FpbnN0IHRoZSBkZXBsb3ltZW50IGAgK1xuICAgICAgICBgcm9vdCwgc28gaXQgY2Fubm90IGJlIGluZmVycmVkIGZyb20gYW55d2hlcmUgZWxzZS5gLFxuICAgICk7XG4gIH1cbiAgcmV0dXJuIGRpcm5hbWUoc2hlbGxEaXIpO1xufVxuIl19

package/lib/runtime/dispatch.d.ts

@@ -0,0 +1,331 @@
+/**
+ * Request dispatch: URL in, routing decision out.
+ *
+ * All route matching is delegated to `@next/routing`'s `resolveRoutes`, the
+ * first-party package `next start` was refactored to expose. Reimplementing
+ * redirects/rewrites/i18n/dynamic-route matching is what previous versions of
+ * this construct did, and it is the thing this rewrite exists to delete.
+ *
+ * This module is pure decision-making: it never touches the filesystem, never
+ * requires an entrypoint, and never builds a `Response`. It returns a
+ * {@link DispatchResult} and the caller (the runtime core, step 4) acts on it.
+ * That split is what makes it unit-testable against the committed
+ * `onBuildComplete` fixtures with no AWS and no Next.js server.
+ */
+import { MiddlewareContext, MiddlewareResult, ResolveRoutesQuery, ResolveRoutesResult, RouteInvocationTarget } from "@next/routing";
+import { AdapterEntrypoint, AdapterManifest } from "./manifest";
+/**
+ * Runs the app's middleware for one request. Supplied by `MiddlewareRunner` in
+ * `./middleware`.
+ *
+ * `MiddlewareContext` carries no method — `resolveRoutes` never needs one — but
+ * middleware very much does (`if (request.method === "POST")`), so dispatch adds
+ * it from the request it was given. The `Response` middleware returned comes
+ * back beside the result, because `resolveRoutes` reports `middlewareResponded`
+ * without it.
+ */
+export type MiddlewareInvoker = (ctx: MiddlewareContext & {
+    readonly method: string;
+}) => Promise<MiddlewareResult & {
+    readonly response: Response;
+}>;
+export interface DispatcherOptions {
+    readonly manifest: AdapterManifest;
+    /**
+     * The files under `public/`, from `readPublicFiles`: unencoded paths relative
+     * to it. Served ahead of every route, as `next start` serves them.
+     * @default - no `public/` files
+     */
+    readonly publicFiles?: readonly string[];
+}
+export interface DispatchRequest {
+    readonly method: string;
+    readonly url: URL;
+    readonly headers: Headers;
+    /**
+     * Always a stream — `resolveRoutes` requires one because middleware may read
+     * the body. Use an already-closed stream for GET/HEAD.
+     */
+    readonly body: ReadableStream;
+    /**
+     * Required whenever `manifest.middleware` is non-null. `resolveRoutes` decides
+     * *whether* to call it from `routing.middlewareMatchers`; we only supply the
+     * how.
+     */
+    readonly invokeMiddleware?: MiddlewareInvoker;
+}
+interface DispatchResultBase {
+    /**
+     * Headers to merge into the response: `headers()` rules, the immutable
+     * `cache-control` for `_next/static`, and anything middleware set via
+     * `NextResponse.next({ headers })`. Never request headers.
+     */
+    readonly responseHeaders: Headers;
+    /** Status forced by a matched route, if any. */
+    readonly status?: number;
+}
+/** A route we must invoke. */
+export interface DispatchEntrypointResult extends DispatchResultBase {
+    readonly kind: "entrypoint";
+    readonly entrypoint: AdapterEntrypoint;
+    /** The matched template, i.e. the `manifest.entrypoints` key. */
+    readonly resolvedPathname: string;
+    /** The *concrete* pathname + query to invoke the route with. */
+    readonly invocationTarget: RouteInvocationTarget;
+    /** Request headers as middleware left them. */
+    readonly requestHeaders: Headers;
+}
+/** A file in `manifest.staticFiles` or `public/`: read off disk, not invoked. */
+export interface DispatchStaticFileResult extends DispatchResultBase {
+    readonly kind: "static-file";
+    readonly pathname: string;
+    /** Repo-root-relative key inside the deployment root. */
+    readonly filePath: string;
+    readonly source: StaticFileSource;
+    /**
+     * Request headers as middleware left them, for the 404 the runtime renders
+     * when the file is not in the package after all.
+     */
+    readonly requestHeaders: Headers;
+}
+/**
+ * Where a static file came from, which decides what else it is allowed to do.
+ *
+ * - `public` — a file in `public/`.
+ * - `next-static` — `<distDir>/static`, the client bundles.
+ * - `server` — a build output under `<distDir>/server`: prerendered HTML, a
+ *   static metadata route's `.body`.
+ *
+ * The first two are what `next start` serves as plain files, with `send`, and
+ * only to GET and HEAD (`router-server.js`, the `fsPath` branch); the third it
+ * serves by invoking the route it came from.
+ */
+export type StaticFileSource = "public" | "next-static" | "server";
+/** `/_next/image`: our own optimizer, deliberately reached after middleware. */
+export interface DispatchImageOptimizationResult extends DispatchResultBase {
+    readonly kind: "image-optimization";
+    readonly url: URL;
+    readonly requestHeaders: Headers;
+}
+export interface DispatchRedirectResult extends DispatchResultBase {
+    readonly kind: "redirect";
+    readonly location: string;
+    readonly status: number;
+}
+/** A rewrite to another origin: proxy the request through. */
+export interface DispatchExternalRewriteResult extends DispatchResultBase {
+    readonly kind: "external-rewrite";
+    readonly url: URL;
+    readonly requestHeaders: Headers;
+}
+/** Middleware returned its own response: send it. */
+export interface DispatchMiddlewareRespondedResult extends DispatchResultBase {
+    readonly kind: "middleware-responded";
+    readonly response: Response;
+}
+/** A matched route forced a status with nothing to invoke. */
+export interface DispatchDirectResponseResult extends DispatchResultBase {
+    readonly kind: "response";
+    readonly status: number;
+}
+export interface DispatchNotFoundResult extends DispatchResultBase {
+    readonly kind: "not-found";
+    /** What failed to resolve. For logging. */
+    readonly pathname: string;
+    readonly requestHeaders: Headers;
+}
+export type DispatchResult = DispatchEntrypointResult | DispatchStaticFileResult | DispatchImageOptimizationResult | DispatchRedirectResult | DispatchExternalRewriteResult | DispatchMiddlewareRespondedResult | DispatchDirectResponseResult | DispatchNotFoundResult;
+/**
+ * How to produce a 404 or 500 body. Resolved once per locale from the manifest
+ * (see {@link statusTargets}); honoring `notFound()` from a route is the
+ * runtime core's job, not dispatch's.
+ */
+export type StatusTarget = {
+    readonly kind: "entrypoint";
+    readonly pathname: string;
+    readonly entrypoint: AdapterEntrypoint;
+} | {
+    readonly kind: "static-file";
+    readonly pathname: string;
+    readonly filePath: string;
+} | {
+    readonly kind: "none";
+};
+export declare class Dispatcher {
+    private readonly options;
+    /** The 404 to render for a request to a URL; see {@link statusTargets}. */
+    readonly notFoundFor: (url: URL) => StatusTarget;
+    private readonly routes;
+    private readonly i18n;
+    private readonly table;
+    private readonly imagePathname;
+    private readonly trailingSlash;
+    constructor(options: DispatcherOptions);
+    get manifest(): AdapterManifest;
+    /**
+     * Drop the `trailingSlash` slash a resolved pathname may carry, so it can be
+     * looked up in `entrypoints`/`staticFiles` and rendered under the same cache
+     * key as its prerender. A no-op unless the app sets `trailingSlash`.
+     */
+    private normalizePathname;
+    /** The request path with `basePath` removed, which is what i18n applies to. */
+    private withoutBasePath;
+    /**
+     * Put the locale in front of a request for the app's root *here*, when the
+     * locale is the one the request is already in.
+     *
+     * `resolveRoutes` prefixes the locale itself, as `${basePath}/${locale}${pathname}`
+     * — which for the root turns `/` into `/en-US/`. The slash-stripping 308 that
+     * `next build` always compiles into `routing.beforeMiddleware` then matches it,
+     * so `GET /` came back as a redirect no `next start` sends: measured against
+     * `test/e2e/i18n-support-catchall`, where `/` answers 200. Next.js's own router
+     * special-cases exactly this (`resolve-routes.ts`: `pathname === '/' ?
+     * `/${defaultLocale}` : …`).
+     *
+     * With `trailingSlash`, the prefixed root keeps its slash (`/en-US/`): the
+     * slash-*adding* 308 that build compiles instead matches `/en-US` the same
+     * way, and `/en-US/` is the canonical URL `next start` serves with a 200.
+     *
+     * Only the root, and only when no redirect is owed: a request whose detected
+     * locale is *not* the default has to reach `resolveRoutes`, which answers it
+     * with the 307 Next.js sends — after middleware has had the request, which is
+     * the ordering that matters and the reason this does not redirect itself.
+     */
+    private withRootLocale;
+    /**
+     * Repair the two things `resolveRoutes` gets wrong about a redirect it built
+     * from the locale-prefixed root — the same `${basePath}/${locale}${pathname}`
+     * concatenation as in {@link withRootLocale}, this time reported as a location:
+     *
+     * - the stray trailing slash (`/nl/`, where Next.js sends `/nl`), which
+     *   otherwise costs a second round trip to the 308 that strips it, and
+     * - the absolute URL, where Next.js sends a path. Both are legal, but a test
+     *   asserting `headers.location` sees the difference, and so does any client
+     *   comparing it to a link.
+     */
+    private normalizeRedirectLocation;
+    /**
+     * The `headers()` rules a request matched, for a response middleware wrote
+     * itself.
+     *
+     * They compile into `routing.beforeMiddleware`, and `resolveRoutes` applies
+     * them there, but when middleware answers it returns `{ middlewareResponded:
+     * true }` and nothing else, so they were lost: a middleware 401 went out
+     * without the app's HSTS and CSP. `next start` sends them with it (its
+     * `resolve-routes.js` sets them on the response before middleware runs). So
+     * that one phase is run again on its own — no middleware, no files, nothing
+     * after it — which leaves exactly the headers it set.
+     */
+    private beforeMiddlewareHeaders;
+    /**
+     * The URL to optimize, once `/_next/image` has resolved: as middleware
+     * rewrote it, or as received — or, when a `next.config` rewrite is what put
+     * the request on the image path, rebuilt from the query `resolveRoutes`
+     * resolved, which is the only place that rewrite's destination query is.
+     */
+    private imageUrl;
+    dispatch(request: DispatchRequest): Promise<DispatchResult>;
+}
+/**
+ * Normalize the two shapes `resolveRoutes` reports a redirect in.
+ *
+ * `ResolveRoutesResult.redirect` is documented, and an i18n locale-detection 307
+ * arrives that way, but the rest — the slash-stripping 308, a middleware
+ * `NextResponse.redirect()` — arrive instead as a bare `status` with `location`
+ * in `resolvedHeaders`. `next.config` `redirects()` too: they compile to routes
+ * carrying `headers: { Location }` plus `status`. Both shapes are handled, and
+ * {@link Dispatcher.normalizeRedirectLocation} then puts the location itself in
+ * the form Next.js sends.
+ */
+export declare function toRedirect(result: ResolveRoutesResult, responseHeaders: Headers): {
+    location: string;
+    status: number;
+} | undefined;
+/**
+ * Correct the `nxtP` route params in a resolved query from `routeMatches`.
+ *
+ * `@next/routing` expands a dynamic route's destination
+ * (`/[id]/[id2]?nxtPid=$nxtPid&nxtPid2=$nxtPid2`) by looping over the source
+ * regex's named groups and doing one global string replace per group name. Group
+ * names are substituted in insertion order, so `$nxtPid` — a *prefix* of
+ * `$nxtPid2` — is replaced first and leaves the trailing `2` behind as a
+ * literal: `/a/b` resolves with `nxtPid2=a2` instead of `nxtPid2=b`. Next.js
+ * recovers `params` from exactly these query values (`RouteModule.prepare`), so
+ * the page renders `id2: "a2"` — measured against
+ * `test/e2e/app-dir/use-params`, whose fixture is `app/[id]/[id2]/page.tsx`.
+ *
+ * `routeMatches` is the raw capture map, before any destination expansion, so it
+ * is the authority for every param it names. Only keys the expansion already
+ * produced are overwritten: adding others would invent params for a rewrite that
+ * deliberately dropped them.
+ *
+ * The same prefix collision reaches positional placeholders (`$1` inside `$10`,
+ * so a route with ten or more captures), and `next.config` `rewrites()`
+ * destinations that interpolate their own query values. Those are not route
+ * params and are left alone — there is no second source of truth to repair them
+ * from.
+ *
+ * The second correction is the opposite shape: a param the route *has* but the
+ * request did not fill. An optional catchall's group is the only one a match can
+ * leave unset — `^/optional\-catchall(?:/(?<nxtPparams>.+?))?(?:/)?$` against
+ * `/optional-catchall` — and both `routeMatches` and the expanded query keep the
+ * key with no value: `{ nxtPparams: undefined }`, which the `@next/routing` types
+ * do not admit. The key is what matters, not the value. `RouteModule.prepare`
+ * recovers a param for every `nxtP` key it finds, so a layout reading `params`
+ * renders a segment that was never requested — as `["undefined"]`, because
+ * `URLSearchParams.append` stringifies — where `next start` gives it no `params`
+ * key at all. Measured against `test/e2e/app-dir/layout-params`, whose fixture is
+ * `app/optional-catchall/[[...params]]`. No other param shape can be legitimately
+ * unfilled — a required segment captures `[^/]+?` and a required catchall `.+?` —
+ * so an unfilled value `routeMatches` does not vouch for is always this.
+ */
+export declare function repairRouteParamQuery(query: ResolveRoutesQuery, routeMatches: Record<string, string | undefined>): ResolveRoutesQuery;
+/**
+ * Route params to hand Next.js out-of-band, for the one request shape the `nxtP`
+ * query contract cannot carry: a capture containing an encoded `/`. `undefined`
+ * — the common case — means the contract is lossless and nothing special is
+ * needed.
+ *
+ * The contract normally is lossless, which is why {@link NextjsRuntime} passes
+ * route params as query values everywhere else. But `RouteModule.prepare`
+ * recovers them by running `normalizeQueryParams` — which calls
+ * `decodeQueryPathParameter`, a **second** `decodeURIComponent`, on every
+ * de-prefixed value because "when deployed to Vercel the value may be encoded" —
+ * and then `normalizeDynamicRouteParams`, which splits a string repeat param on
+ * `/` because "query values from the proxy aren't already split into arrays".
+ * Two decodes and a split: `nxtPrest=..%252F..%252Fserver-reference-manifest`
+ * (what the contract asks for, and what we send) arrives as the three params
+ * `['..', '..', 'server-reference-manifest']` rather than the one the client
+ * requested. The resolved pathname built back out of those is
+ * `/pages-cache/../../server-reference-manifest`, and `normalizePagePath` throws
+ * `Requested and resolved page mismatch` on it when the cache asks for a key —
+ * so a `_next/data` request for a catch-all whose segment contains `%2F` 500s.
+ * Measured against `test/e2e/incremental-cache-path-traversal`. No encoding can
+ * fix it from this side: whatever survives two decodes still gets split.
+ *
+ * `next start` never hits it because its `router-server` sets
+ * `requestMeta.params` instead, which `prepare` takes as-is
+ * (`route-module.ts`: `getRequestMeta(req, 'params')`) with no decode and no
+ * split. That is what this reproduces — narrowly, only for the affected
+ * requests, so that the documented query contract stays the path for everything
+ * else.
+ *
+ * The `nxtP` values have to leave the query as well as arrive in `params`.
+ * `prepare` prefers the query over `params` when both parse and are the same
+ * size, so leaving them in would just restore the split. Dropping them also
+ * matches `next start`, which has no `nxtP` query at all.
+ */
+export declare function outOfBandRouteParams(query: ResolveRoutesQuery, resolvedPathname: string): {
+    params: Record<string, string | string[]>;
+    query: ResolveRoutesQuery;
+} | undefined;
+/**
+ * {@link statusTarget} for every locale, resolved once, and a lookup of the
+ * request's: in an i18n app, the prerender of the locale the URL is in
+ * (`/fr/nope` gets `/fr/404`), and otherwise of the domain's default locale —
+ * which is how `next start` picks the locale it renders a status page in. A
+ * request whose URL could not be parsed, `undefined`, gets the default
+ * locale's.
+ */
+export declare function statusTargets(manifest: AdapterManifest, status: 404 | 500): (url: URL | undefined) => StatusTarget;
+export {};