cdk-nextjs 0.6.1 → 0.7.0

package/lib/adapter/function-groups.d.ts

@@ -0,0 +1,215 @@
+/**
+ * The implicit group every unassigned route falls into. Reserved as a group
+ * name: it is also the construct id suffix and the function whose URL backs the
+ * distribution's default behavior.
+ */
+export declare const DEFAULT_FUNCTION_GROUP = "default";
+/**
+ * How the resolved groups reach `onBuildComplete`, which cannot read CDK props —
+ * it runs inside `next build`. `CDK_NEXTJS_INIT_CACHE_DIR` is the precedent.
+ */
+export declare const FUNCTION_GROUPS_ENV_VAR = "CDK_NEXTJS_FUNCTION_GROUPS";
+/** The part of a group the build side needs. */
+export interface FunctionGroupSpec {
+    readonly name: string;
+    readonly routes: string[];
+}
+/** One route template and the entrypoint it invokes. */
+export interface RouteEntry {
+    /** Basepath-prefixed route template, exactly as `manifest.entrypoints` keys it. */
+    readonly template: string;
+    /**
+     * What identifies the entrypoint: the build side passes its `filePath`, since
+     * that is what gets staged. Two templates sharing one are never split apart.
+     */
+    readonly entrypointId: string;
+    /**
+     * The entrypoint's `AdapterEntrypointType`. Only `"page"` changes anything: a
+     * Pages Router page is also requested at `/_next/data/<buildId>/<page>.json`,
+     * so that URL has to reach the page's group too.
+     */
+    readonly type?: string;
+}
+/**
+ * One behavior the edge routes a group on. The Functions root constructs deploy
+ * exactly these, in order: a CloudFront behavior each, or the API Gateway
+ * resources for each distinct `route`.
+ */
+export interface GroupBehavior {
+    readonly group: string;
+    /**
+     * The group pattern (`/blog/**`) the behavior was generated from, or the
+     * optional catch-all parent {@link routedPatterns} added.
+     */
+    readonly route: string;
+    /**
+     * The CloudFront path pattern, before basePath and without a leading slash
+     * (`blog/*`, `_next/data/<buildId>/blog/*`).
+     */
+    readonly pattern: string;
+}
+/** What {@link assignRoutesToGroups} decided. */
+export interface GroupAssignment {
+    /** Group name → the templates packaged into it, `default` included. */
+    readonly templates: Record<string, string[]>;
+    /**
+     * Every group behavior, most specific first: the order CloudFront has to see
+     * them in, since it stops at the first match. Recorded rather than
+     * recomputed at synth, so the behaviors deployed are the ones this
+     * assignment was checked against.
+     */
+    readonly behaviors: GroupBehavior[];
+}
+/** What {@link assignRoutesToGroups} needs to know besides the routes. */
+export interface AssignRoutesOptions {
+    /** `next.config` `basePath`, which every manifest template carries. */
+    readonly basePath: string;
+    /**
+     * Next.js's build ID — the segment in `/_next/data/<buildId>/…` URLs, which is
+     * `ctx.buildId` and `.next/BUILD_ID`, not cdk-nextjs's deployment-suffixed
+     * one. Required when any entry is a Pages Router page.
+     */
+    readonly buildId?: string;
+    /** `next.config` `trailingSlash`. */
+    readonly trailingSlash?: boolean;
+    /**
+     * `ctx.routing`: the `next.config` rewrites whose source and destination
+     * have to land in one group, and Next.js's own dynamic route order, which
+     * decides the template a URL resolves to.
+     */
+    readonly routing: RoutingRules;
+}
+/** One `ctx.routing` rewrite, reduced to the fields read here. */
+export interface RewriteRule {
+    /** The path-to-regexp source, basePath included (`/old/:path*`). */
+    readonly source?: string;
+    readonly destination?: string;
+}
+/** The part of `ctx.routing` {@link assignRoutesToGroups} reads. */
+export interface RoutingRules {
+    readonly beforeFiles?: readonly RewriteRule[];
+    readonly afterFiles?: readonly RewriteRule[];
+    readonly fallback?: readonly RewriteRule[];
+    /** Next.js's own template matchers, used to resolve a rewrite's destination. */
+    readonly dynamicRoutes?: readonly {
+        readonly sourceRegex: string;
+        readonly destination?: string;
+    }[];
+}
+/**
+ * The literal characters a CloudFront path pattern may contain: its alphabet
+ * (`A-Z a-z 0-9 _ - . * $ / ~ " ' @ : +` and `&`) less the two wildcards, which
+ * `validateRoutePattern` only accepts as a trailing `/**`. `nextjs-distribution.ts`
+ * adds the wildcards back to encode `public/` names.
+ *
+ * @see https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/DownloadDistValuesCacheBehavior.html#DownloadDistValuesPathPattern
+ */
+export declare const PATH_PATTERN_LITERAL: RegExp;
+/**
+ * Read {@link FUNCTION_GROUPS_ENV_VAR}. `undefined` — not the empty array — when
+ * unset, because "no splitting" and "split into nothing" are different requests
+ * and only the first is valid.
+ */
+export declare function parseFunctionGroupsEnv(value: string | undefined): FunctionGroupSpec[] | undefined;
+/**
+ * Splitting and `i18n` are mutually exclusive, and it is a CloudFront limit
+ * again.
+ *
+ * With `i18n` configured, every route template is locale-prefixed
+ * (`/en/pricing`, `/de/pricing`), so honoring a `/pricing` group would take one
+ * behavior *per locale per pattern* — a budget of 75 behaviors spent in a handful
+ * of routes. The alternative, a `*` in the locale position, matches any first
+ * segment and would capture routes belonging to other groups. Neither is
+ * something to do silently, so refuse instead.
+ */
+export declare function assertNoI18nSplitting(i18n: unknown): void;
+/**
+ * Reject everything that cannot be honored, at the earliest of the two sides to
+ * see it. Called from both, because either can be the first: `next build` runs
+ * before synth reads the manifest, but a `skipBuild: true` consumer inverts that.
+ */
+export declare function validateFunctionGroups(groups: readonly FunctionGroupSpec[]): void;
+/**
+ * Split every route template across the groups, longest matching pattern first,
+ * then prove that the edge routes every URL each file serves to the group that
+ * file was packaged into.
+ *
+ * Its `templates` are keyed by group name and always contain
+ * {@link DEFAULT_FUNCTION_GROUP}, so callers can iterate them as the complete set
+ * of functions to deploy. The default group is allowed to be empty of *templates*
+ * — it still serves `/_next/image`, any static file, and anything the
+ * distribution's catch-all behavior sends it.
+ *
+ * `basePath` is prepended to each pattern before matching, because manifest
+ * templates are basePath-prefixed and consumers write the routes their app
+ * declares.
+ *
+ * Packaging matches patterns against *templates*, but CloudFront routes *URLs*,
+ * and a file answers URLs none of its templates spells: an optional catch-all's
+ * parent, the `trailingSlash` form, a Pages Router data URL, every other
+ * template it shares (root params synthesize `/en` and `/de` from one
+ * `[locale]` page). An interception route is worse: it is never requested at its
+ * own path at all. So after matching, intercepting files move to the group of
+ * the URL they intercept ({@link reassignInterceptingFiles}), and the result is
+ * replayed through the same behaviors `NextjsDistribution` deploys
+ * ({@link assertEdgeReachesEveryFile}, {@link assertRewritesStayInGroup}). A URL
+ * that would reach a function without its file throws here, during `next build`,
+ * rather than answering 404 once deployed.
+ */
+export declare function assignRoutesToGroups(groups: readonly FunctionGroupSpec[], entries: readonly RouteEntry[], options: AssignRoutesOptions): GroupAssignment;
+/**
+ * The patterns a group is *routed* on: the ones it declares, plus the parent
+ * path of every optional catch-all a subtree pattern moved into it.
+ *
+ * `/blog/[[...slug]]` serves `/blog` as well as everything under it, and
+ * `/blog/**` moves the whole file — but deploys as `blog/*`, which does not
+ * match `/blog`. So the parent is routed automatically, as an exact pattern of
+ * its own; declaring `/blog` by hand is a pattern with no route of its own and
+ * is rejected as a typo, with a hint pointing here. Nothing else a subtree owns
+ * needs this: a file whose parent URL is its subtree's base can only be an
+ * optional catch-all, since Next.js rejects `app/blog/page.tsx` next to it.
+ *
+ * @param ownedTemplates the templates assigned to the group, basePath-prefixed
+ *   as `manifest.groups` records them
+ */
+export declare function routedPatterns(routes: readonly string[], ownedTemplates: readonly string[], basePath: string): string[];
+/**
+ * CloudFront path patterns for one group pattern, without a leading slash —
+ * the form `NextjsDistribution.getPathPattern` expects, so the basePath is
+ * added there rather than here.
+ *
+ * Two patterns come back when the group owns a Pages Router route: its RSC-era
+ * equivalent is a second URL space, `/_next/data/<buildId>/<route>.json`, which
+ * the default behavior would otherwise send to the default group.
+ *
+ * A third comes back for an exact route in a `trailingSlash` app, where the
+ * canonical URL is `/pricing/` rather than `/pricing`: the bare pattern does not
+ * match it, so without this every request for the route the user actually links to
+ * falls through to the default group's function — which, for a Pages Router API
+ * route, has no entrypoint for it at all. Subtree patterns need no variant
+ * (`pricing/*` already matches `/pricing/`), and neither do the data URLs, which
+ * never carry the slash.
+ */
+export declare function pathPatternsFor(route: string, options: {
+    hasDataRoutes: boolean;
+    trailingSlash?: boolean;
+    buildId?: string;
+}): string[];
+/**
+ * The route an interception route intercepts: `/feed/(..)photo/[id]` →
+ * `/photo/[id]`. `extractInterceptionRouteInformation` from
+ * `next/dist/shared/lib/router/utils/interception-routes.js`, restated because
+ * this file is bundled without `next`. The template is already a normalized app
+ * path (no route groups, no `@slot`s), so none of its normalization is needed.
+ * Next.js's interception rewrite matches exactly this path, and only with a
+ * `Next-Url` header — which CloudFront does not route on.
+ */
+export declare function interceptedRoute(path: string): string | undefined;
+/**
+ * CloudFront path pattern matching: anchored at both ends, `*` for any run of
+ * characters `/` included, `?` for exactly one, case-sensitive. `pattern` has to
+ * carry the leading slash CloudFront implies.
+ *
+ * @see https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/DownloadDistValuesCacheBehavior.html#DownloadDistValuesPathPattern
+ */
+export declare function cloudFrontPatternRegex(pattern: string): RegExp;