cdk-nextjs 0.6.1 → 0.7.0

package/lib/utils/base-path.d.ts

@@ -1,3 +1,8 @@
+/**
+ * Pure `basePath` and URL path helpers. Nothing here imports `aws-cdk-lib` or
+ * touches the filesystem, so the adapter and runtime bundles can import it as
+ * well as the constructs.
+ */
 import { NextjsType } from "../constants";
 /**
  * Reduces a `basePath` to a bare path segment so values that address the same
@@ -5,6 +10,31 @@ import { NextjsType } from "../constants";
  * without doubling separators.
  */
 export declare function normalizeBasePath(basePath?: string): string;
+/**
+ * Whether `path` is `prefix` or under it on a segment boundary, so `/docsearch`
+ * is not under `/docs`. An empty `prefix` matches nothing. Both sides must be in
+ * the same form (both with or both without the leading `/`).
+ */
+export declare function hasPathPrefix(path: string, prefix: string): boolean;
+/**
+ * A `basePath` as Next.js spells it and URLs start with it: one leading slash,
+ * no trailing one ("/base"), `""` for none. Accepts any spelling
+ * {@link normalizeBasePath} does.
+ */
+export declare function basePathPrefix(basePath?: string): string;
+/**
+ * Invalidation paths covering every URI of the app: what a deploy invalidates,
+ * and what the cache handler's oversized batches, retries after a quota error,
+ * and tags whose routes could not all be named fall back to.
+ *
+ * `/*` is the whole app only without a `basePath`. `/base/*` matches neither the
+ * app's root, `/base`, nor its RSC payload, `/base?_rsc=…` - the same root the
+ * `revalidatePath("/")` that overflowed may have named - so those are spelled
+ * out. `/base*` would cover them for one wildcard, but also every sibling
+ * prefix (`/base2`, `/basement`), which may be another app on the same
+ * distribution.
+ */
+export declare function wholeAppInvalidationPaths(basePath?: string): string[];
 /**
  * Joins path parts with a single "/", normalizing each (so no leading or
  * trailing slash survives, including on the result) and dropping the empty
@@ -12,18 +42,97 @@ export declare function normalizeBasePath(basePath?: string): string;
  */
 export declare function joinPath(...parts: (string | undefined)[]): string;
 /**
- * Read the Next.js app's own `basePath` out of `required-server-files.json`,
- * which `next build` writes into `.next` with the fully resolved config (so
- * this picks up a `basePath` computed in `next.config.js`, not only a literal
- * one). Normalized, empty when the app sets none.
+ * Prefixes an absolute app path (a health check path, say) with `basePath`,
+ * always returning a leading slash. An empty or unset `basePath` only
+ * normalizes that leading slash. Anything after the first segment is passed
+ * through as given, trailing slash included, since a `trailingSlash` app
+ * answers "/api/health" and "/api/health/" differently.
+ *
+ * Use this for paths handed to something that talks to the app directly — an ALB
+ * target group health check, the container's own health probe — since the app
+ * only answers under its own `basePath`.
  *
- * Degrades to `""` rather than throwing, since an unreadable file shouldn't
- * fail a deployment that would otherwise work. It warns because `""` is
- * indistinguishable from an app that genuinely sets no `basePath`: the
- * `NextjsType`s that derive `basePath` from the app would quietly not derive
- * it and 404 every static asset.
+ * Prefixes unconditionally, so `path` has to arrive as the app routes it,
+ * without `basePath`: for an app based at "/base", "/base/api/health" becomes
+ * "/base/base/api/health". Deliberately not special-cased — an app can route
+ * "/base/base/..." legitimately, and accepting both spellings would give the
+ * path two meanings. See `docs/breaking-changes.md` (0.6.0), which tells users
+ * who prefixed `healthCheckPath` by hand to drop the prefix.
  */
-export declare function readNextConfigBasePath(dotNextPath: string): string;
+export declare function prefixWithBasePath(basePath: string | undefined, path: string): string;
+/**
+ * The app's own `assetPrefix` as a path with a leading and no trailing slash
+ * ("/cdn"), or `""` when the app sets none.
+ *
+ * Returns `""` for an absolute `assetPrefix` ("https://cdn.example.com", or the
+ * protocol-relative "//cdn.example.com") too: that names an origin cdk-nextjs
+ * does not control, and it is the supported way to serve assets from elsewhere,
+ * so nothing about it is worth warning about. Use {@link assetPrefixPath} for
+ * what the *distribution* has to answer on, which includes the path an absolute
+ * prefix carries.
+ *
+ * Next.js applies `assetPrefix` on top of, not under, `basePath`, so the result
+ * is the whole prefix of a `_next/static` URL and must not be joined with
+ * `basePath`.
+ */
+export declare function relativeAssetPrefix(assetPrefix: string): string;
+/**
+ * Whether a path-style `assetPrefix` would go unanswered on this `NextjsType`,
+ * i.e. whether every bundle would 404.
+ *
+ * `assetPrefix` moves every bundle URL to `<assetPrefix>/_next/static/...` while
+ * the objects keep their `<basePath>/_next/static/...` S3 keys. The Global
+ * `NextjsType`s answer that with a cache behavior of their own
+ * (`NextjsDistribution`); the regional ones have nothing that maps the prefix
+ * back — API Gateway's `_next/static` resource and the container's own files are
+ * both under the unprefixed path.
+ *
+ * A prefix equal to the app's own `basePath` is **not** unserved, because that is
+ * the value Next.js resolves `assetPrefix` to when `basePath` is set and
+ * `assetPrefix` is not: `.next/required-server-files.json` comes back as
+ * `{"assetPrefix":"/prod","basePath":"/prod"}` for an app that only ever set
+ * `basePath`. Without that exemption the warning fired on every regional
+ * deployment that sets a `basePath` at all — including `examples/regional-functions`
+ * — telling users their bundles would 404 at the one path that does serve them.
+ * `NextjsDistribution.resolveAssetPrefix` drops the prefix for the same reason.
+ *
+ * Both sides go through `normalizeBasePath` because they arrive in different
+ * shapes: `nextConfigAssetPrefix` carries a leading slash (`"/prod"`),
+ * `nextConfigBasePath` does not (`"prod"`).
+ */
+export declare function isAssetPrefixUnserved(nextjsType: NextjsType, nextConfigAssetPrefix: string, nextConfigBasePath?: string): boolean;
+/**
+ * The *path* every bundle URL carries, whichever form `assetPrefix` takes: "/cdn"
+ * for `assetPrefix: "/cdn"` and for `assetPrefix:
+ * "https://cdn.example.com/cdn"` alike, `""` when there is none (an absolute
+ * prefix with no path, or no prefix at all).
+ *
+ * An absolute prefix's path counts because `next build` compiles a `beforeFiles`
+ * rewrite of its own for it — `/cdn/_next/:path+ → /_next/:path+` — so `next
+ * start` serves every bundle under that path as well as under `/_next`. A CDN
+ * fronting this deployment at that path therefore has to be answered, and the
+ * distribution's `assetPrefix` behavior is what answers it. Measured against
+ * `test/e2e/app-dir/asset-prefix-absolute`; see `docs/harness-coverage.md`.
+ * Shared with `NextjsDistribution`, whose `assetPrefix` prop a user can also
+ * set by hand.
+ */
+export declare function assetPrefixPath(assetPrefix: string): string;
+/**
+ * The path prefix API Gateway strips before matching resources, as far as synth
+ * can tell. Only read by `resolveBasePath` for `REGIONAL_FUNCTIONS`.
+ */
+export interface ApiGatewayPrefix {
+    /**
+     * The stage name on the execute-api endpoint, or the base path mapping on a
+     * custom domain (`""` when mapped at the root). `undefined` when it is not
+     * known at synth — a token — in which case nothing is derived.
+     */
+    readonly strippedPrefix?: string;
+    /** Whether a custom domain is configured through `restApiProps.domainName`. */
+    readonly customDomain: boolean;
+}
+/** `RestApi`'s own defaults: the `prod` stage, no custom domain. */
+export declare const DEFAULT_API_GATEWAY_PREFIX: ApiGatewayPrefix;
 /**
  * Settles on the single `basePath` the infrastructure should be built around,
  * given the CDK `basePath` prop and the Next.js app's own `basePath`
@@ -36,5 +145,8 @@ export declare function readNextConfigBasePath(dotNextPath: string): string;
  * land under), the config is the prefix the app emits its own links and asset
  * hrefs under — so how strictly they have to line up, and whether one can stand
  * in for the other, depends on how the `NextjsType` routes static requests.
+ *
+ * `apiGateway` is only read for `REGIONAL_FUNCTIONS`, and only when the prop is
+ * unset: see `deriveApiGatewayBasePath`.
  */
-export declare function resolveBasePath(nextjsType: NextjsType, propBasePath?: string, nextConfigBasePath?: string): string | undefined;
+export declare function resolveBasePath(nextjsType: NextjsType, propBasePath?: string, nextConfigBasePath?: string, apiGateway?: ApiGatewayPrefix): string | undefined;