cdk-nextjs 0.6.2 → 0.7.1

package/lib/nextjs-distribution.d.ts

@@ -8,7 +8,7 @@ import { Construct } from "constructs";
 import { NextjsType } from "./constants";
 import { OptionalDistributionProps } from "./generated-structs/OptionalDistributionProps";
 import { OptionalS3OriginBucketWithOACProps } from "./generated-structs/OptionalS3OriginBucketWithOACProps";
-import { PublicDirEntry } from "./nextjs-build/nextjs-build";
+import { NextjsFunctionGroupBehavior, PublicDirEntry } from "./nextjs-build/nextjs-build";
 export interface NextjsDistributionOverrides {
     readonly distributionProps?: OptionalDistributionProps;
     readonly imageBehaviorOptions?: AddBehaviorOptions;
@@ -19,7 +19,6 @@ export interface NextjsDistributionOverrides {
     readonly dynamicResponseHeadersPolicyProps?: ResponseHeadersPolicyProps;
     readonly dynamicFunctionUrlOriginWithOACProps?: FunctionUrlOriginWithOACProps;
     readonly dynamicVpcOriginWithEndpointProps?: VpcOriginWithEndpointProps;
-    readonly imageFunctionUrlOriginWithOACProps?: FunctionUrlOriginWithOACProps;
     readonly staticBehaviorOptions?: AddBehaviorOptions;
     readonly staticResponseHeadersPolicyProps?: ResponseHeadersPolicyProps;
     readonly s3BucketOriginProps?: OptionalS3OriginBucketWithOACProps;
@@ -30,6 +29,25 @@ export interface NextjsDistributionProps {
      * Must be provided if you want to serve static files.
      */
     readonly assetsBucket: IBucket;
+    /**
+     * The app's own `assetPrefix`. Next.js emits `<assetPrefix>/_next/static/...`
+     * for every bundle while the objects stay at `<basePath>/_next/static/...` in
+     * S3, so the prefix's path gets a cache behavior of its own that rewrites it
+     * away.
+     *
+     * Either form is accepted: a path ("/cdn"), or an absolute URL, in which case
+     * only its path counts ("https://cdn.example.com/cdn" behaves as "/cdn", and
+     * "https://cdn.example.com" needs no behavior at all). An absolute prefix's path
+     * matters because `next build` compiles a `/cdn/_next/:path+` rewrite of its
+     * own, so `next start` serves every bundle under it — a CDN fronting this
+     * distribution there has to be answered too.
+     *
+     * Applied on top of `basePath`, not under it, because that is how Next.js
+     * builds the URL.
+     *
+     * @default - none; pass `NextjsBuild.nextConfigAssetPrefixPath`
+     */
+    readonly assetPrefix?: string;
     /**
      * URI path prefix the app is served at. Surrounding slashes are normalized
      * away, so "/base", "base" and "/base/" all produce the same cache behaviors.
@@ -44,14 +62,6 @@ export interface NextjsDistributionProps {
      * Required if `NextjsType.GLOBAL_FUNCTIONS`
      */
     readonly functionUrl?: IFunctionUrl;
-    /**
-     * Function URL of the dedicated image optimization Lambda. Only applicable
-     * to `NextjsType.GLOBAL_FUNCTIONS`, and only when the dedicated image
-     * function is enabled. When omitted, the `_next/image*` behavior points at
-     * the dynamic origin, which serves image optimization from the Next.js
-     * server itself.
-     */
-    readonly imageFunctionUrl?: IFunctionUrl;
     /**
      * Required if `NextjsType.GLOBAL_CONTAINERS` or `NextjsType.REGIONAL_CONTAINERS`
      */
@@ -66,6 +76,37 @@ export interface NextjsDistributionProps {
      * add static behaviors to distribution.
      */
     readonly publicDirEntries: PublicDirEntry[];
+    /**
+     * The non-`default` function groups, the origins
+     * {@link functionGroupBehaviors} route to.
+     * @default - no splitting; the default behavior serves every dynamic route
+     */
+    readonly functionGroups?: NextjsDistributionFunctionGroup[];
+    /**
+     * `NextjsBuild.functionGroupBehaviors`: one cache behavior each, added in
+     * order, so the routes each group was packaged with reach it rather than the
+     * default function.
+     * @default - none
+     */
+    readonly functionGroupBehaviors?: NextjsFunctionGroupBehavior[];
+    /**
+     * The most cache behaviors the distribution may have, the default one
+     * included. cdk-nextjs counts what it adds against this at synth, so running
+     * out is a synth error naming what used them rather than a failed deploy.
+     *
+     * Raise it after raising the "Cache behaviors per distribution" quota for
+     * your account. Lower it by the behaviors a supplied {@link distribution}
+     * (or `overrides.distributionProps`) already has, which are not counted.
+     * @default 75 - CloudFront's default quota
+     * @see https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/cloudfront-limits.html#limits-web-distributions
+     */
+    readonly maxCacheBehaviors?: number;
+}
+/** A non-default function group and the origin its routes must reach. */
+export interface NextjsDistributionFunctionGroup {
+    readonly name: string;
+    /** The group's Lambda Function URL. */
+    readonly functionUrl: IFunctionUrl;
 }
 export declare class NextjsDistribution extends Construct {
     distribution: Distribution;
@@ -77,6 +118,13 @@ export declare class NextjsDistribution extends Construct {
      * relying on the caller having passed one.
      */
     private basePath;
+    /**
+     * `props.assetPrefix` normalized to a leading-slash path, `""` when the app
+     * sets none or sets one that already equals the `basePath` prefix — in which
+     * case the ordinary `_next/static*` behavior already covers it and a second one
+     * would be a duplicate pattern CloudFront rejects.
+     */
+    private assetPrefix;
     /**
      * Common security headers applied by default to all origins
      * @see https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/using-managed-response-headers-policies.html#managed-response-headers-policies-security
@@ -84,7 +132,6 @@ export declare class NextjsDistribution extends Construct {
     private commonSecurityHeadersBehavior;
     private staticOrigin;
     private dynamicOrigin;
-    private imageOrigin;
     private dynamicOriginResponsePolicy;
     private dynamicCloudFrontFunctionAssociations;
     private isFunctionCompute;
@@ -102,22 +149,17 @@ export declare class NextjsDistribution extends Construct {
     private getComment;
     private createStaticOrigin;
     private createDynamicOrigin;
-    /**
-     * A dedicated image optimization Lambda is only wired up when
-     * {@link NextjsDistributionProps.imageFunctionUrl} is supplied, which today
-     * only `NextjsType.GLOBAL_FUNCTIONS` does. Otherwise `_next/image*` keeps
-     * going to the dynamic origin, where the Next.js server optimizes images
-     * itself.
-     *
-     * The `_next/image*` behavior is kept either way: its cache policy
-     * (`queryStringBehavior: all()`, `accept` in the cache key) is the right one
-     * for image requests regardless of which origin answers them.
-     */
-    private createImageOrigin;
     /**
      * Lambda Function URLs "expect the `Host` header to contain the origin domain
      * name, not the domain name of the CloudFront distribution."
+     *
+     * A container origin also gets CloudFront's own headers, for
+     * `CloudFront-Forwarded-Proto`: without a certificate CloudFront reaches the
+     * ALB over plain HTTP, so the ALB's `X-Forwarded-Proto` is `http`, and the
+     * runtime would build every absolute URL (`request.url`, the origin a server
+     * action is forwarded to) as `http://` behind a viewer on HTTPS.
      * @see https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/using-managed-origin-request-policies.html#managed-origin-request-policy-all-viewer-except-host-header
+     * @see https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/using-managed-origin-request-policies.html#managed-origin-request-policy-all-viewer-and-cloudfront
      */
     private createDynamicOriginRequestPolicy;
     /**
@@ -128,15 +170,144 @@ export declare class NextjsDistribution extends Construct {
     private createDynamicCloudFrontFunctionAssociations;
     private createStaticBehaviorOptions;
     private createDynamicBehaviorOptions;
+    /**
+     * The behavior's function associations: an override's, plus the viewer-request
+     * function Global Functions depends on.
+     *
+     * Spreading the override's `functionAssociations` over ours would silently
+     * drop that function, and with it the only thing standing between a viewer's
+     * own `X-Forwarded-Host` and the runtime, which trusts that header on Function
+     * URL events (`lambda-event.ts`): host injection into redirects and absolute
+     * URLs, cached for other viewers because the header is not in the cache key.
+     * So ours is kept, and an override claiming VIEWER_REQUEST — which CloudFront
+     * allows only one of per behavior — is an error rather than a replacement.
+     */
+    private withDynamicFunctionAssociations;
+    /**
+     * `_next/image*` goes to the same origin as everything else — the Next.js
+     * server optimizes images in-process — but keeps its own behavior for the
+     * cache policy: `queryStringBehavior: all()` plus `accept` in the cache key is
+     * right for image requests and wrong for the rest.
+     */
     private createImageBehaviorOptions;
     /**
      * Creates or uses user specified CloudFront Distribution
      */
     private getDistribution;
     private addDynamicBehaviors;
+    /**
+     * Before any behavior is computed: the budget and the `public/` checks both
+     * generate the group patterns, and would otherwise fail first with a less
+     * useful message.
+     */
+    private validateFunctionGroupProps;
+    /**
+     * Every group behavior, final path pattern included, in the order
+     * {@link addFunctionGroupBehaviors} adds them.
+     */
+    private functionGroupBehaviors;
+    /**
+     * One behavior per group pattern, most specific first.
+     *
+     * The order is the whole mechanism. CloudFront evaluates behaviors in order
+     * and stops at the first whose path pattern matches, and `addBehavior`
+     * appends — so `api/*` added before `api/reports/*` would swallow every
+     * report request and send it to a function whose package has no report
+     * entrypoint. The adapter sorted the list when it checked it against how
+     * `assignRoutesToGroups` packaged the same routes, so it is added as it is.
+     */
+    private addFunctionGroupBehaviors;
+    /**
+     * `lambda:InvokeFunction` for CloudFront, which a Function URL behind OAC
+     * needs besides the `lambda:InvokeFunctionUrl` `FunctionUrlOrigin` grants,
+     * and scoped the same way: to this distribution, and to calls that come
+     * through the Function URL.
+     */
+    private grantInvoke;
+    /**
+     * The `assetPrefix` path that needs a behavior of its own, or `""` for none.
+     *
+     * An absolute prefix contributes its *path*: "https://cdn.example.com" needs no
+     * behavior, but "https://cdn.example.com/cdn" does, because `next build`
+     * compiles a `/cdn/_next/:path+` rewrite of its own and `next start` serves
+     * every bundle under that path — so a CDN fronting this distribution there has
+     * to be answered. A prefix equal to the `basePath` prefix is dropped — that is
+     * the Next.js default when `basePath` is set, and `_next/static*` already
+     * resolves under it, so adding a second identical pattern would make CloudFront
+     * reject the distribution.
+     */
+    private resolveAssetPrefix;
+    /**
+     * Serves `<assetPrefix>/_next/static/*` from the same S3 objects as
+     * `_next/static/*`.
+     *
+     * Needed because Next.js puts `assetPrefix` in front of every bundle URL it
+     * emits while the objects keep their `<basePath>/_next/static/...` keys, and
+     * `assetPrefix` sits on top of `basePath` rather than under it, so
+     * `getPathPattern` is deliberately not used here. Without this behavior the
+     * request falls through to the default one, reaches the compute origin, and
+     * 404s: the deployment package carries no `.next/static` directory at all.
+     *
+     * A viewer-request function does the rewrite because an S3 origin keys on the
+     * request URI and `originPath` can only prepend. The prefix is a synth-time
+     * literal, so the function is a fixed-length string operation rather than a
+     * parse.
+     */
+    private addAssetPrefixBehavior;
     private addStaticBehaviors;
+    /**
+     * The behavior path pattern for each top-level `public/` entry, final form:
+     * `/*` for a directory and the basePath prefix both applied.
+     *
+     * An entry whose name has no character CloudFront can spell is left out, with
+     * a warning, rather than given a pattern of nothing but wildcards. `фото/` is
+     * `????????/*` — any 8-byte first segment — and public/ behaviors are added
+     * ahead of every compute behavior, so it would send `/products/42` and
+     * `/settings/*` to S3, which answers 403. Leaving the entry out costs its own
+     * files instead: those requests reach the compute, which does not have them,
+     * and 404. One literal character is enough to keep a pattern narrow —
+     * `????????.jpg` only matches `.jpg` requests — so only the all-wildcard ones
+     * go.
+     *
+     * The length limit is checked here, on the final pattern, rather than in
+     * {@link toPathPattern}: the `/*` and the basePath count against it too, and a
+     * pattern that passed without them failed at deploy instead.
+     */
+    private publicPathPatterns;
+    /**
+     * Refuse a group behavior that a `public/` behavior would make unreachable.
+     *
+     * `public/` behaviors are added first, and CloudFront stops at the first match,
+     * so two cases send a group's route to S3 instead of its function — which is
+     * why this is checked at synth, where both sides are known:
+     * - the same pattern twice: `public/docs/` and `/docs/**` both deploy as
+     *   `docs/*`. The synth succeeded and CloudFront rejected the deploy.
+     * - a group pattern under a public directory: `/docs/guide/**` behind
+     *   `docs/*` deploys and never matches.
+     */
+    private assertNoPublicCollisions;
+    /**
+     * CloudFront has a per-distribution cache behavior quota, counting the default
+     * one — 75 unless raised, and `maxCacheBehaviors` says which — and there are
+     * three things competing for it: `public/` entries, function groups, and
+     * cdk-nextjs's own fixed set.
+     * Checked in one place so the error can say which to cut.
+     *
+     * @see https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/cloudfront-limits.html#limits-web-distributions
+     */
+    private assertBehaviorBudget;
     /**
      * Optionally prepends base path to given path pattern.
+     *
+     * A trailing slash on `pathPattern` is load-bearing and survives, which is why
+     * this concatenates rather than going through `joinPath`. The build's
+     * `functionGroupBehaviors` hold both "pricing" and "pricing/" for a
+     * `trailingSlash` app, and normalizing the second one collapsed it onto the
+     * first: `addBehavior` was
+     * then called twice with `/base/pricing`, which CloudFront rejects at deploy
+     * ("more than one cache behavior has the same path pattern"), and the
+     * canonical `/base/pricing/` was left to the `/base/*` catch-all — the misroute
+     * the second pattern exists to prevent.
      */
     private getPathPattern;
 }