@composurecdk/cloudfront 0.4.3 → 0.4.5

package/dist/cloudfront-alarm-builder.js

@@ -0,0 +1,131 @@
+import { Annotations, Stack, Token } from "aws-cdk-lib";
+import { Builder, resolve, } from "@composurecdk/core";
+import { AlarmDefinitionBuilder, createAlarms } from "@composurecdk/cloudwatch";
+import { resolveDistributionAlarmDefinitions } from "./distribution-alarms.js";
+import { resolveBehaviorFunctionAlarmDefinitions } from "./behavior-function-alarms.js";
+/**
+ * CloudFront metrics are emitted in `us-east-1` only. CloudWatch alarms are
+ * regional, so alarms created in any other region will never receive data.
+ * Warn (don't error) when alarms are being created outside `us-east-1`,
+ * unless the region is an unresolved token (env-agnostic stack — user knows
+ * best).
+ */
+function warnIfNotUsEast1(scope) {
+    const region = Stack.of(scope).region;
+    if (Token.isUnresolved(region))
+        return;
+    if (region === "us-east-1")
+        return;
+    Annotations.of(scope).addWarningV2("@composurecdk/cloudfront:alarm-region", `CloudFront metrics are emitted in us-east-1 only, but this stack is deployed ` +
+        `in "${region}". CloudWatch alarms created here will not fire. Deploy the ` +
+        `stack in us-east-1, or use createCloudFrontAlarmBuilder() routed to a ` +
+        `us-east-1 stack via compose().withStacks().`);
+}
+/**
+ * Shared alarm-assembly used by both {@link createDistributionBuilder} (in its
+ * own stack) and {@link createCloudFrontAlarmBuilder} (typically in a separate
+ * `us-east-1` stack). Materializes the recommended distribution-level alarms,
+ * the recommended per-function alarms, and any user-supplied custom alarms,
+ * emits the region warning if the resulting scope is not in `us-east-1`, and
+ * creates the alarm constructs.
+ *
+ * @internal
+ */
+export function buildCloudFrontAlarms(scope, id, target, options = {}) {
+    const recommended = options.recommendedAlarms;
+    const recommendedDefs = recommended === false || recommended?.enabled === false
+        ? []
+        : [
+            ...resolveDistributionAlarmDefinitions(target.distribution, recommended),
+            ...Object.values(target.functions).flatMap((entry) => resolveBehaviorFunctionAlarmDefinitions(entry.pathPattern, entry.eventType, entry.function, entry.recommendedAlarms)),
+        ];
+    const customAlarmDefs = options.customAlarms?.map((b) => b.resolve(target.distribution)) ?? [];
+    const allAlarmDefs = [...recommendedDefs, ...customAlarmDefs];
+    if (allAlarmDefs.length > 0) {
+        warnIfNotUsEast1(scope);
+    }
+    return createAlarms(scope, id, allAlarmDefs);
+}
+class CloudFrontAlarmBuilder {
+    props = {};
+    #distribution;
+    #customAlarms = [];
+    /**
+     * Sets the distribution to alarm on. Pass the result of
+     * {@link createDistributionBuilder} (or a {@link Ref} to it). The builder
+     * reads the distribution and any inline-function metadata from the result.
+     *
+     * Pair with `compose().withStacks()` to route this component into a
+     * `us-east-1` stack while the distribution itself lives elsewhere — set
+     * `crossRegionReferences: true` on both stacks so CDK can wire the
+     * `DistributionId` reference automatically.
+     */
+    distribution(distribution) {
+        this.#distribution = distribution;
+        return this;
+    }
+    /**
+     * Adds a custom alarm against the distribution. The configure callback
+     * receives a fresh {@link AlarmDefinitionBuilder} pre-set with the alarm's
+     * key; configure metric, threshold, comparison and any other options.
+     *
+     * The created alarm is materialized in this builder's stack — useful for
+     * cross-region setups where you want all CloudFront alarms to live with the
+     * recommended ones.
+     */
+    addAlarm(key, configure) {
+        this.#customAlarms.push(configure(new AlarmDefinitionBuilder(key)));
+        return this;
+    }
+    build(scope, id, context) {
+        if (!this.#distribution) {
+            throw new Error(`CloudFrontAlarmBuilder "${id}" requires a distribution. ` +
+                `Call .distribution() with a DistributionBuilderResult or a Ref to one.`);
+        }
+        const distribution = resolve(this.#distribution, context ?? {});
+        return {
+            alarms: buildCloudFrontAlarms(scope, id, distribution, {
+                recommendedAlarms: this.props.recommendedAlarms,
+                customAlarms: this.#customAlarms,
+            }),
+        };
+    }
+}
+/**
+ * Creates a new {@link ICloudFrontAlarmBuilder} for materializing CloudFront
+ * alarms in a stack separate from the distribution itself.
+ *
+ * The recommended use is multi-region deployments: the distribution lives in
+ * the site's stack (often outside `us-east-1` for latency or compliance
+ * reasons), and CloudFront alarms must live in a `us-east-1` stack so they
+ * can read the metrics CloudFront emits there.
+ *
+ * @example
+ * ```ts
+ * compose(
+ *   {
+ *     cdn: createDistributionBuilder()
+ *       .origin(...)
+ *       .defaultBehavior({ functions: [{ eventType, code }] })
+ *       .recommendedAlarms(false),           // suppress alarms in the dist's own stack
+ *
+ *     cdnAlarms: createCloudFrontAlarmBuilder()
+ *       .distribution(ref<DistributionBuilderResult>("cdn"))
+ *       .recommendedAlarms({ errorRate: { threshold: 2 } }),
+ *   },
+ *   { cdn: [], cdnAlarms: ["cdn"] },
+ * )
+ *   .withStacks({
+ *     cdn:       siteStack,    // eu-west-2
+ *     cdnAlarms: certStack,    // us-east-1 (existing ACM stack)
+ *   })
+ *   .build(app, "App");
+ * ```
+ *
+ * Set `crossRegionReferences: true` on both stacks so CDK can export the
+ * `DistributionId` from the site stack and import it in the alarm stack.
+ */
+export function createCloudFrontAlarmBuilder() {
+    return Builder(CloudFrontAlarmBuilder);
+}
+//# sourceMappingURL=cloudfront-alarm-builder.js.map

package/dist/cloudfront-alarm-builder.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cloudfront-alarm-builder.js","sourceRoot":"","sources":["../src/cloudfront-alarm-builder.ts"],"names":[],"mappings":"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"}

package/dist/defaults.d.ts

@@ -1,4 +1,4 @@
-import type { DistributionBuilderProps } from "./distribution-builder.js";
+import type { DistributionBuilderProps, InlineFunctionDefinition } from "./distribution-builder.js";
 /**
  * Secure, AWS-recommended defaults applied to every CloudFront distribution
  * built with {@link createDistributionBuilder}. Each property can be individually
@@ -9,4 +9,9 @@ import type { DistributionBuilderProps } from "./distribution-builder.js";
  * then the resolved origin is injected.
  */
 export declare const DISTRIBUTION_DEFAULTS: Partial<DistributionBuilderProps>;
+/**
+ * Defaults applied to every inline CloudFront Function declared on a cache
+ * behavior. User-provided properties take precedence.
+ */
+export declare const INLINE_FUNCTION_DEFAULTS: Partial<InlineFunctionDefinition>;
 //# sourceMappingURL=defaults.d.ts.map

package/dist/defaults.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"defaults.d.ts","sourceRoot":"","sources":["../src/defaults.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,2BAA2B,CAAC;AAE1E;;;;;;;;GAQG;AACH,eAAO,MAAM,qBAAqB,EAAE,OAAO,CAAC,wBAAwB,CAkDnE,CAAC"}
+{"version":3,"file":"defaults.d.ts","sourceRoot":"","sources":["../src/defaults.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAE,wBAAwB,EAAE,wBAAwB,EAAE,MAAM,2BAA2B,CAAC;AAEpG;;;;;;;;GAQG;AACH,eAAO,MAAM,qBAAqB,EAAE,OAAO,CAAC,wBAAwB,CAkDnE,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,wBAAwB,EAAE,OAAO,CAAC,wBAAwB,CAOtE,CAAC"}

package/dist/defaults.js

@@ -1,4 +1,4 @@
-import { HttpVersion, PriceClass, ResponseHeadersPolicy, SecurityPolicyProtocol, ViewerProtocolPolicy, } from "aws-cdk-lib/aws-cloudfront";
+import { FunctionRuntime, HttpVersion, PriceClass, ResponseHeadersPolicy, SecurityPolicyProtocol, ViewerProtocolPolicy, } from "aws-cdk-lib/aws-cloudfront";
 /**
  * Secure, AWS-recommended defaults applied to every CloudFront distribution
  * built with {@link createDistributionBuilder}. Each property can be individually
@@ -53,4 +53,16 @@ export const DISTRIBUTION_DEFAULTS = {
         responseHeadersPolicy: ResponseHeadersPolicy.SECURITY_HEADERS,
     },
 };
+/**
+ * Defaults applied to every inline CloudFront Function declared on a cache
+ * behavior. User-provided properties take precedence.
+ */
+export const INLINE_FUNCTION_DEFAULTS = {
+    /**
+     * Use the `cloudfront-js-2.0` runtime by default. It is a superset of
+     * `cloudfront-js-1.0` (async/await, `crypto.subtle`, KeyValueStore support).
+     * @see https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/functions-javascript-runtime-20.html
+     */
+    runtime: FunctionRuntime.JS_2_0,
+};
 //# sourceMappingURL=defaults.js.map

package/dist/defaults.js.map

@@ -1 +1 @@
-{"version":3,"file":"defaults.js","sourceRoot":"","sources":["../src/defaults.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,WAAW,EACX,UAAU,EACV,qBAAqB,EACrB,sBAAsB,EACtB,oBAAoB,GACrB,MAAM,4BAA4B,CAAC;AAGpC;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAsC;IACtE;;;;;OAKG;IACH,aAAa,EAAE,IAAI;IAEnB;;;;OAIG;IACH,UAAU,EAAE,UAAU,CAAC,eAAe;IAEtC;;;;OAIG;IACH,WAAW,EAAE,WAAW,CAAC,WAAW;IAEpC;;;OAGG;IACH,iBAAiB,EAAE,YAAY;IAE/B;;;;OAIG;IACH,sBAAsB,EAAE,sBAAsB,CAAC,aAAa;IAE5D,eAAe,EAAE;QACf;;;WAGG;QACH,oBAAoB,EAAE,oBAAoB,CAAC,iBAAiB;QAE5D;;;;WAIG;QACH,qBAAqB,EAAE,qBAAqB,CAAC,gBAAgB;KAC9D;CACF,CAAC"}
+{"version":3,"file":"defaults.js","sourceRoot":"","sources":["../src/defaults.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,eAAe,EACf,WAAW,EACX,UAAU,EACV,qBAAqB,EACrB,sBAAsB,EACtB,oBAAoB,GACrB,MAAM,4BAA4B,CAAC;AAGpC;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAsC;IACtE;;;;;OAKG;IACH,aAAa,EAAE,IAAI;IAEnB;;;;OAIG;IACH,UAAU,EAAE,UAAU,CAAC,eAAe;IAEtC;;;;OAIG;IACH,WAAW,EAAE,WAAW,CAAC,WAAW;IAEpC;;;OAGG;IACH,iBAAiB,EAAE,YAAY;IAE/B;;;;OAIG;IACH,sBAAsB,EAAE,sBAAsB,CAAC,aAAa;IAE5D,eAAe,EAAE;QACf;;;WAGG;QACH,oBAAoB,EAAE,oBAAoB,CAAC,iBAAiB;QAE5D;;;;WAIG;QACH,qBAAqB,EAAE,qBAAqB,CAAC,gBAAgB;KAC9D;CACF,CAAC;AAEF;;;GAGG;AACH,MAAM,CAAC,MAAM,wBAAwB,GAAsC;IACzE;;;;OAIG;IACH,OAAO,EAAE,eAAe,CAAC,MAAM;CAChC,CAAC"}

package/dist/distribution-alarms.d.ts

@@ -1,26 +1,9 @@
-import { type Alarm } from "aws-cdk-lib/aws-cloudwatch";
 import type { Distribution } from "aws-cdk-lib/aws-cloudfront";
-import type { IConstruct } from "constructs";
 import type { AlarmDefinition } from "@composurecdk/cloudwatch";
-import { AlarmDefinitionBuilder } from "@composurecdk/cloudwatch";
 import type { DistributionAlarmConfig } from "./alarm-config.js";
 /**
  * Resolves the recommended alarm configuration into fully-resolved
  * {@link AlarmDefinition}s for a CloudFront distribution.
  */
 export declare function resolveDistributionAlarmDefinitions(distribution: Distribution, config: DistributionAlarmConfig | undefined): AlarmDefinition[];
-/**
- * Creates AWS-recommended CloudWatch alarms for a CloudFront distribution,
- * merging recommended definitions with any custom alarm builders.
- *
- * @param scope - CDK construct scope for creating alarm constructs.
- * @param id - Base identifier for alarm construct ids.
- * @param distribution - The CloudFront distribution to create alarms for.
- * @param config - User-provided alarm configuration, or `false` to disable all.
- * @param customAlarms - Custom alarm builders added via `addAlarm()`.
- * @returns A record mapping alarm keys to their created Alarm constructs.
- *
- * @see https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/Best_Practice_Recommended_Alarms_AWS_Services.html#CloudFront
- */
-export declare function createDistributionAlarms(scope: IConstruct, id: string, distribution: Distribution, config: DistributionAlarmConfig | false | undefined, customAlarms?: AlarmDefinitionBuilder<Distribution>[]): Record<string, Alarm>;
 //# sourceMappingURL=distribution-alarms.d.ts.map

package/dist/distribution-alarms.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"distribution-alarms.d.ts","sourceRoot":"","sources":["../src/distribution-alarms.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,KAAK,KAAK,EAAqC,MAAM,4BAA4B,CAAC;AAC3F,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,4BAA4B,CAAC;AAC/D,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAC7C,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,0BAA0B,CAAC;AAChE,OAAO,EAAE,sBAAsB,EAAoC,MAAM,0BAA0B,CAAC;AACpG,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,mBAAmB,CAAC;AA2BjE;;;GAGG;AACH,wBAAgB,mCAAmC,CACjD,YAAY,EAAE,YAAY,EAC1B,MAAM,EAAE,uBAAuB,GAAG,SAAS,GAC1C,eAAe,EAAE,CAqCnB;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,wBAAwB,CACtC,KAAK,EAAE,UAAU,EACjB,EAAE,EAAE,MAAM,EACV,YAAY,EAAE,YAAY,EAC1B,MAAM,EAAE,uBAAuB,GAAG,KAAK,GAAG,SAAS,EACnD,YAAY,GAAE,sBAAsB,CAAC,YAAY,CAAC,EAAO,GACxD,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,CAUvB"}
+{"version":3,"file":"distribution-alarms.d.ts","sourceRoot":"","sources":["../src/distribution-alarms.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,4BAA4B,CAAC;AAC/D,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,0BAA0B,CAAC;AAEhE,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,mBAAmB,CAAC;AA2BjE;;;GAGG;AACH,wBAAgB,mCAAmC,CACjD,YAAY,EAAE,YAAY,EAC1B,MAAM,EAAE,uBAAuB,GAAG,SAAS,GAC1C,eAAe,EAAE,CAqCnB"}

package/dist/distribution-alarms.js

@@ -1,6 +1,6 @@
 import { Duration } from "aws-cdk-lib";
 import { ComparisonOperator, Metric, Stats } from "aws-cdk-lib/aws-cloudwatch";
-import { createAlarms, resolveAlarmConfig } from "@composurecdk/cloudwatch";
+import { resolveAlarmConfig } from "@composurecdk/cloudwatch";
 import { DISTRIBUTION_ALARM_DEFAULTS } from "./alarm-defaults.js";
 const METRIC_PERIOD = Duration.minutes(1);
 const METRIC_PERIOD_LABEL = `${String(METRIC_PERIOD.toMinutes())} minute`;
@@ -56,27 +56,4 @@ export function resolveDistributionAlarmDefinitions(distribution, config) {
     }
     return definitions;
 }
-/**
- * Creates AWS-recommended CloudWatch alarms for a CloudFront distribution,
- * merging recommended definitions with any custom alarm builders.
- *
- * @param scope - CDK construct scope for creating alarm constructs.
- * @param id - Base identifier for alarm construct ids.
- * @param distribution - The CloudFront distribution to create alarms for.
- * @param config - User-provided alarm configuration, or `false` to disable all.
- * @param customAlarms - Custom alarm builders added via `addAlarm()`.
- * @returns A record mapping alarm keys to their created Alarm constructs.
- *
- * @see https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/Best_Practice_Recommended_Alarms_AWS_Services.html#CloudFront
- */
-export function createDistributionAlarms(scope, id, distribution, config, customAlarms = []) {
-    if (config === false)
-        return {};
-    const enabled = config?.enabled ?? DISTRIBUTION_ALARM_DEFAULTS.enabled;
-    if (!enabled)
-        return {};
-    const recommended = resolveDistributionAlarmDefinitions(distribution, config);
-    const custom = customAlarms.map((b) => b.resolve(distribution));
-    return createAlarms(scope, id, [...recommended, ...custom]);
-}
 //# sourceMappingURL=distribution-alarms.js.map

package/dist/distribution-alarms.js.map

@@ -1 +1 @@
-{"version":3,"file":"distribution-alarms.js","sourceRoot":"","sources":["../src/distribution-alarms.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"distribution-alarms.js","sourceRoot":"","sources":["../src/distribution-alarms.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AACvC,OAAO,EAAE,kBAAkB,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,4BAA4B,CAAC;AAG/E,OAAO,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAC;AAE9D,OAAO,EAAE,2BAA2B,EAAE,MAAM,qBAAqB,CAAC;AAElE,MAAM,aAAa,GAAG,QAAQ,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC;AAC1C,MAAM,mBAAmB,GAAG,GAAG,MAAM,CAAC,aAAa,CAAC,SAAS,EAAE,CAAC,SAAS,CAAC;AAE1E;;;GAGG;AACH,SAAS,kBAAkB,CACzB,YAA0B,EAC1B,UAAkB,EAClB,SAAiB;IAEjB,OAAO,IAAI,MAAM,CAAC;QAChB,SAAS,EAAE,gBAAgB;QAC3B,UAAU;QACV,aAAa,EAAE;YACb,cAAc,EAAE,YAAY,CAAC,cAAc;YAC3C,MAAM,EAAE,QAAQ;SACjB;QACD,SAAS;QACT,MAAM,EAAE,aAAa;KACtB,CAAC,CAAC;AACL,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,mCAAmC,CACjD,YAA0B,EAC1B,MAA2C;IAE3C,IAAI,MAAM,EAAE,OAAO,KAAK,KAAK;QAAE,OAAO,EAAE,CAAC;IAEzC,MAAM,WAAW,GAAsB,EAAE,CAAC;IAE1C,IAAI,MAAM,EAAE,SAAS,KAAK,KAAK,EAAE,CAAC;QAChC,MAAM,GAAG,GAAG,kBAAkB,CAAC,MAAM,EAAE,SAAS,EAAE,2BAA2B,CAAC,SAAS,CAAC,CAAC;QACzF,WAAW,CAAC,IAAI,CAAC;YACf,GAAG,EAAE,WAAW;YAChB,MAAM,EAAE,kBAAkB,CAAC,YAAY,EAAE,cAAc,EAAE,KAAK,CAAC,OAAO,CAAC;YACvE,SAAS,EAAE,GAAG,CAAC,SAAS;YACxB,kBAAkB,EAAE,kBAAkB,CAAC,sBAAsB;YAC7D,iBAAiB,EAAE,GAAG,CAAC,iBAAiB;YACxC,iBAAiB,EAAE,GAAG,CAAC,iBAAiB;YACxC,gBAAgB,EAAE,GAAG,CAAC,gBAAgB;YACtC,WAAW,EAAE,oEAAoE,MAAM,CAAC,GAAG,CAAC,SAAS,CAAC,QAAQ,mBAAmB,GAAG;SACrI,CAAC,CAAC;IACL,CAAC;IAED,IAAI,MAAM,EAAE,aAAa,KAAK,KAAK,EAAE,CAAC;QACpC,MAAM,GAAG,GAAG,kBAAkB,CAC5B,MAAM,EAAE,aAAa,EACrB,2BAA2B,CAAC,aAAa,CAC1C,CAAC;QACF,WAAW,CAAC,IAAI,CAAC;YACf,GAAG,EAAE,eAAe;YACpB,MAAM,EAAE,kBAAkB,CAAC,YAAY,EAAE,eAAe,EAAE,KAAK,CAAC,UAAU,CAAC,EAAE,CAAC,CAAC;YAC/E,SAAS,EAAE,GAAG,CAAC,SAAS;YACxB,kBAAkB,EAAE,kBAAkB,CAAC,sBAAsB;YAC7D,iBAAiB,EAAE,GAAG,CAAC,iBAAiB;YACxC,iBAAiB,EAAE,GAAG,CAAC,iBAAiB;YACxC,gBAAgB,EAAE,GAAG,CAAC,gBAAgB;YACtC,WAAW,EAAE,uDAAuD,MAAM,CAAC,GAAG,CAAC,SAAS,CAAC,aAAa,mBAAmB,GAAG;SAC7H,CAAC,CAAC;IACL,CAAC;IAED,OAAO,WAAW,CAAC;AACrB,CAAC"}

package/dist/distribution-builder.d.ts

@@ -1,24 +1,133 @@
-import { Distribution, type DistributionProps, type IOrigin, type AddBehaviorOptions } from "aws-cdk-lib/aws-cloudfront";
+import { Distribution, type DistributionProps, type IOrigin, type AddBehaviorOptions, type BehaviorOptions, type Function as CfFunction, type FunctionCode, type FunctionEventType, type FunctionRuntime, type IKeyValueStore } from "aws-cdk-lib/aws-cloudfront";
 import { type ICertificate } from "aws-cdk-lib/aws-certificatemanager";
 import { type Alarm } from "aws-cdk-lib/aws-cloudwatch";
 import { type Bucket } from "aws-cdk-lib/aws-s3";
 import { type IConstruct } from "constructs";
 import { type IBuilder, type Lifecycle, type Resolvable } from "@composurecdk/core";
 import { AlarmDefinitionBuilder } from "@composurecdk/cloudwatch";
-import type { DistributionAlarmConfig } from "./alarm-config.js";
+import type { DistributionAlarmConfig, FunctionAlarmConfig } from "./alarm-config.js";
+/**
+ * Per-function metadata exposed on {@link DistributionBuilderResult.functions}.
+ * Bundles the CDK construct with the behavior context the builder used to
+ * create it. Consumers (notably {@link createCloudFrontAlarmBuilder}) use the
+ * `pathPattern`, `eventType`, and `recommendedAlarms` fields to reproduce the
+ * same recommended alarms in a different stack.
+ */
+export interface FunctionEntry {
+    /** The CloudFront Function created by the distribution builder. */
+    function: CfFunction;
+    /**
+     * The behavior the function is attached to. `null` for the default behavior;
+     * otherwise the path pattern (e.g. `"/api/*"`).
+     */
+    pathPattern: string | null;
+    /** The viewer event the function handles. */
+    eventType: FunctionEventType;
+    /**
+     * The {@link InlineFunctionDefinition.recommendedAlarms} value the user
+     * supplied for this function. Omitted entirely when the user did not
+     * provide one — consumers should treat that as "use defaults".
+     */
+    recommendedAlarms?: FunctionAlarmConfig | false;
+}
+/**
+ * A CloudFront Function declared inline on a cache behavior. The distribution
+ * builder creates the underlying {@link CfFunction} construct and wires it
+ * into the behavior's function associations. Recommended alarms for the
+ * function are emitted automatically, scoped to the behavior's path pattern.
+ *
+ * Only inline declarations are supported — there is no "bring your own
+ * function" escape hatch, because the whole point of owning the function is
+ * to emit path-scoped `FunctionExecutionErrors` / `FunctionValidationErrors`
+ * / `FunctionThrottles` alarms that couldn't be emitted from an external
+ * `IFunctionRef` (which exposes only an ARN, not a function name).
+ *
+ * @see https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/cloudfront-functions.html
+ */
+export interface InlineFunctionDefinition {
+    /** The viewer event that should invoke the function. */
+    eventType: FunctionEventType;
+    /** The source for the function — `FunctionCode.fromInline()` or `.fromFile()`. */
+    code: FunctionCode;
+    /**
+     * Explicit physical name for the function. Useful when operators search
+     * CloudWatch logs or metrics by function name rather than by ARN. If omitted,
+     * CDK generates a name derived from the construct path.
+     */
+    functionName?: string;
+    /**
+     * JavaScript runtime.
+     * @default FunctionRuntime.JS_2_0
+     */
+    runtime?: FunctionRuntime;
+    /** Optional comment stored on the function resource. */
+    comment?: string;
+    /**
+     * Key-value store to associate with the function. Only supported on the
+     * `cloudfront-js-2.0` runtime.
+     */
+    keyValueStore?: IKeyValueStore;
+    /**
+     * Per-function alarm configuration. Defaults to the three AWS-recommended
+     * alarms (execution errors, validation errors, throttles) each with
+     * threshold 0. Set to `false` to disable all alarms for this function, or
+     * override individual alarms via their config entry.
+     *
+     * **Region requirement:** CloudFront metrics are emitted in `us-east-1`
+     * only. CloudWatch alarms are regional, so these alarms will only fire if
+     * the containing stack is deployed in `us-east-1`. The builder emits a
+     * synth-time warning if this isn't the case.
+     *
+     * @see https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/monitoring-functions.html
+     */
+    recommendedAlarms?: FunctionAlarmConfig | false;
+}
+/**
+ * Configuration for the distribution's default cache behavior.
+ *
+ * The origin is set separately via {@link IDistributionBuilder.origin}. The
+ * `functionAssociations` field from {@link AddBehaviorOptions} is replaced by
+ * {@link functions}, which takes {@link InlineFunctionDefinition}s — the
+ * builder owns the CloudFront Function constructs so it can emit alarms for
+ * them.
+ */
+export interface DefaultBehaviorConfig extends Omit<AddBehaviorOptions, "functionAssociations"> {
+    /**
+     * CloudFront Functions to associate with the default behavior. At most one
+     * function per {@link FunctionEventType} is allowed.
+     */
+    functions?: InlineFunctionDefinition[];
+}
+/**
+ * Configuration for a path-pattern cache behavior attached to the distribution
+ * via {@link IDistributionBuilder.behavior}.
+ *
+ * Unlike {@link DefaultBehaviorConfig}, `origin` is required. It may be a
+ * concrete {@link IOrigin} or a {@link Resolvable} (typically a {@link ref})
+ * for cross-component wiring.
+ */
+export interface AdditionalBehaviorConfig extends Omit<BehaviorOptions, "origin" | "functionAssociations"> {
+    /** The origin for this behavior, concrete or resolved at build time. */
+    origin: Resolvable<IOrigin>;
+    /**
+     * CloudFront Functions to associate with this behavior. At most one
+     * function per {@link FunctionEventType} is allowed.
+     */
+    functions?: InlineFunctionDefinition[];
+}
 /**
  * Configuration properties for the CloudFront distribution builder.
  *
  * Extends the CDK {@link DistributionProps} with additional builder-specific
- * options. The `defaultBehavior` field is replaced with {@link AddBehaviorOptions}
- * (which excludes `origin`) because the origin is set separately via the
- * {@link IDistributionBuilder.origin | origin()} method, which supports
- * {@link Resolvable} for cross-component wiring.
+ * options. `defaultBehavior` accepts a {@link DefaultBehaviorConfig} with
+ * inline function definitions; additional behaviors are added via the
+ * {@link IDistributionBuilder.behavior} method rather than the raw
+ * `additionalBehaviors` record.
  *
  * The `enableLogging` CDK prop is replaced by {@link accessLogging}, which
  * auto-creates a logging bucket with secure defaults when enabled.
  */
-export interface DistributionBuilderProps extends Omit<DistributionProps, "defaultBehavior" | "enableLogging" | "certificate"> {
+export interface DistributionBuilderProps extends Omit<DistributionProps, "defaultBehavior" | "additionalBehaviors" | "enableLogging" | "certificate"> {
     /**
      * Whether to automatically create an S3 bucket for CloudFront standard
      * access logging.
@@ -44,36 +153,63 @@ export interface DistributionBuilderProps extends Omit<DistributionProps, "defau
      */
     certificate?: Resolvable<ICertificate>;
     /**
-     * Options for the default cache behavior, excluding `origin`.
-     *
-     * The origin is set via the {@link IDistributionBuilder.origin | origin()}
-     * method and injected at build time. All other behavior options (cache
-     * policy, function associations, viewer protocol policy, etc.) can be
-     * configured here.
+     * Configuration for the default cache behavior. The origin is set via
+     * {@link IDistributionBuilder.origin}. Inline CloudFront Functions declared
+     * in `functions` are created by the builder and receive path-scoped alarms
+     * automatically.
      */
-    defaultBehavior?: AddBehaviorOptions;
+    defaultBehavior?: DefaultBehaviorConfig;
     /**
-     * Configuration for AWS-recommended CloudWatch alarms.
+     * Configuration for AWS-recommended CloudWatch alarms at the **distribution**
+     * level (5xx error rate, origin latency).
+     *
+     * Per-function alarm shapes (`FunctionExecutionErrors`,
+     * `FunctionValidationErrors`, `FunctionThrottles`) are configured per
+     * function via {@link InlineFunctionDefinition.recommendedAlarms}, because
+     * their correct disposition depends on the behavior the function is
+     * attached to. The kill switch below (`recommendedAlarms: false`) still
+     * applies to function alarms — see below.
+     *
+     * **Region requirement:** CloudFront metrics are emitted in `us-east-1`
+     * only. CloudWatch alarms are regional, so every alarm created by this
+     * builder will only fire if the containing stack is deployed in
+     * `us-east-1`. The builder emits a synth-time warning if this isn't the
+     * case. For multi-region deployments, set `recommendedAlarms: false` here
+     * and use {@link createCloudFrontAlarmBuilder} routed to a `us-east-1`
+     * stack via `compose().withStacks()`.
      *
-     * By default, the builder creates recommended alarms for 5xx error rate
-     * and origin latency. Individual alarms can be customized or disabled.
-     * Set to `false` to disable all alarms.
+     * Set to `false` to disable all recommended alarms (both distribution-level
+     * and per-function). Custom alarms added via
+     * {@link IDistributionBuilder.addAlarm} are unaffected. To disable a single
+     * function's alarms, set `recommendedAlarms: false` on the corresponding
+     * {@link InlineFunctionDefinition}.
      *
-     * No alarm actions are configured by default since notification
-     * methods are user-specific. Access alarms from the build result
-     * or use an `afterBuild` hook to apply actions.
+     * No alarm actions are configured by default since notification methods
+     * are user-specific. Access alarms from the build result or use an
+     * `afterBuild` hook to apply actions.
      *
-     * Function-level alarms (FunctionValidationErrors, FunctionExecutionErrors,
-     * FunctionThrottles) require per-function dimensions. Use
-     * {@link IDistributionBuilder.addAlarm} to add them.
+     * @example Tighter dist-level threshold; function alarms unchanged.
+     * ```ts
+     * createDistributionBuilder()
+     *   .origin(siteOrigin)
+     *   .recommendedAlarms({ errorRate: { threshold: 2 } });
+     * ```
+     *
+     * @example Multi-region setup — suppress all alarms here, recreate them in
+     * a `us-east-1` stack via {@link createCloudFrontAlarmBuilder}.
+     * ```ts
+     * createDistributionBuilder()
+     *   .origin(siteOrigin)
+     *   .recommendedAlarms(false);
+     * ```
      *
      * @see https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/Best_Practice_Recommended_Alarms_AWS_Services.html#CloudFront
      */
     recommendedAlarms?: DistributionAlarmConfig | false;
 }
 /**
- * The build output of a {@link IDistributionBuilder}. Contains the CDK constructs
- * created during {@link Lifecycle.build}, keyed by role.
+ * The build output of an {@link IDistributionBuilder}. Contains the CDK
+ * constructs created during {@link Lifecycle.build}, keyed by role.
  */
 export interface DistributionBuilderResult {
     /** The CloudFront distribution construct created by the builder. */
@@ -84,42 +220,58 @@ export interface DistributionBuilderResult {
      */
     accessLogsBucket?: Bucket;
     /**
-     * CloudWatch alarms created for the distribution, keyed by alarm name.
-     *
-     * Includes both AWS-recommended alarms and any custom alarms added
-     * via {@link IDistributionBuilder.addAlarm}. Access individual alarms
-     * by key (e.g., `result.alarms.errorRate`).
-     *
-     * No alarm actions are configured — apply them via the result or an
-     * `afterBuild` hook.
+     * CloudFront Functions created by the builder for inline function
+     * definitions, keyed by `<behaviorScope><EventType>` —
+     * e.g. `defaultBehaviorViewerRequest`, `behaviorApiStarViewerRequest`.
+     * Each entry bundles the {@link CfFunction} with the behavior context
+     * (`pathPattern`, `eventType`) and the per-function `recommendedAlarms`
+     * config the user supplied. Empty if no inline functions were declared.
+     */
+    functions: Record<string, FunctionEntry>;
+    /**
+     * CloudWatch alarms created for the distribution and its inline functions,
+     * keyed by alarm name. Distribution-level keys: `errorRate`, `originLatency`.
+     * Function-level keys are prefixed by behavior scope and event type —
+     * e.g. `defaultBehaviorViewerRequestExecutionErrors`.
      *
-     * @see https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/Best_Practice_Recommended_Alarms_AWS_Services.html#CloudFront
+     * Includes both recommended alarms and custom alarms added via
+     * {@link IDistributionBuilder.addAlarm}. Empty when `recommendedAlarms` is
+     * `false` and no custom alarms were added. No alarm actions are configured.
      */
     alarms: Record<string, Alarm>;
 }
 /**
  * A fluent builder for configuring and creating a CloudFront distribution.
  *
- * Configuration properties from CDK {@link DistributionProps} are exposed as
- * overloaded getter/setter methods via the builder proxy. The origin is set
- * via the {@link origin} method, which accepts a concrete {@link IOrigin} or
- * a {@link Ref} for cross-component wiring.
+ * Properties from CDK {@link DistributionProps} are exposed as overloaded
+ * getter/setter methods. The origin is set via {@link origin}, which accepts
+ * a concrete {@link IOrigin} or a {@link Ref} for cross-component wiring.
+ * Additional cache behaviors are added via {@link behavior}, which takes a
+ * path pattern and a config including its own origin and inline functions.
  *
  * The builder implements {@link Lifecycle}, so it can be used directly as a
- * component in a {@link compose | composed system}. When built, it creates
- * a CloudFront distribution with the configured properties and returns a
- * {@link DistributionBuilderResult}.
+ * component in a {@link compose | composed system}. When built, it creates a
+ * CloudFront distribution, any inline CloudFront Functions declared on its
+ * behaviors, and AWS-recommended alarms scoped per-behavior.
  *
  * @example
  * ```ts
  * const cdn = createDistributionBuilder()
- *   .origin(ref("site", (r: BucketBuilderResult) =>
- *     S3BucketOrigin.withOriginAccessControl(r.bucket)))
- *   .errorResponses([{
- *     httpStatus: 404,
- *     responsePagePath: "/index.html",
- *     responseHttpStatus: 200,
- *   }]);
+ *   .origin(siteOrigin)
+ *   .defaultBehavior({
+ *     functions: [{
+ *       eventType: FunctionEventType.VIEWER_REQUEST,
+ *       code: FunctionCode.fromFile({ filePath: "src/edge/rewrite.js" }),
+ *     }],
+ *   })
+ *   .behavior("/api/*", {
+ *     origin: apiOrigin,
+ *     cachePolicy: CachePolicy.CACHING_DISABLED,
+ *     functions: [{
+ *       eventType: FunctionEventType.VIEWER_REQUEST,
+ *       code: FunctionCode.fromFile({ filePath: "src/edge/api-auth.js" }),
+ *     }],
+ *   });
  * ```
  */
 export type IDistributionBuilder = IBuilder<DistributionBuilderProps, DistributionBuilder>;
@@ -137,6 +289,15 @@ declare class DistributionBuilder implements Lifecycle<DistributionBuilderResult
      * @returns This builder for chaining.
      */
     origin(origin: Resolvable<IOrigin>): this;
+    /**
+     * Adds an additional cache behavior for a path pattern. The behavior's
+     * origin is required (concrete or Resolvable). Any inline functions are
+     * created by the builder and receive per-behavior alarms scoped to the
+     * path pattern.
+     *
+     * @throws If a behavior for the same path pattern has already been added.
+     */
+    behavior(pathPattern: string, config: AdditionalBehaviorConfig): this;
     build(scope: IConstruct, id: string, context?: Record<string, object>): DistributionBuilderResult;
 }
 /**
@@ -145,26 +306,27 @@ declare class DistributionBuilder implements Lifecycle<DistributionBuilderResult
  * This is the entry point for defining a CloudFront distribution component.
  * The returned builder exposes every {@link DistributionBuilderProps} property
  * as a fluent setter/getter, plus {@link IDistributionBuilder.origin | origin()}
- * for setting the default origin with Ref support. It implements {@link Lifecycle}
- * for use with {@link compose}.
+ * for setting the default origin with Ref support and
+ * {@link IDistributionBuilder.behavior | behavior()} for path-pattern behaviors.
+ * It implements {@link Lifecycle} for use with {@link compose}.
  *
  * @returns A fluent builder for a CloudFront distribution.
  *
  * @example
  * ```ts
  * const cdn = createDistributionBuilder()
- *   .origin(ref("site", (r: BucketBuilderResult) =>
+ *   .origin(ref<BucketBuilderResult>("site", (r) =>
  *     S3BucketOrigin.withOriginAccessControl(r.bucket)))
- *   .comment("Community website CDN");
- *
- * // Use standalone:
- * const result = cdn.build(stack, "CDN");
- *
- * // Or compose into a system:
- * const system = compose(
- *   { site: createBucketBuilder(), cdn },
- *   { site: [], cdn: ["site"] },
- * );
+ *   .defaultBehavior({
+ *     functions: [{
+ *       eventType: FunctionEventType.VIEWER_REQUEST,
+ *       code: FunctionCode.fromFile({ filePath: "src/edge/rewrite.js" }),
+ *     }],
+ *   })
+ *   .behavior("/api/*", {
+ *     origin: apiOrigin,
+ *     cachePolicy: CachePolicy.CACHING_DISABLED,
+ *   });
  * ```
  */
 export declare function createDistributionBuilder(): IDistributionBuilder;