@composurecdk/cloudfront 0.4.3 → 0.4.5

package/README.md

@@ -177,6 +177,59 @@ for (const alarm of Object.values(result.alarms)) {
 }
 ```
 
+## Cross-region alarm builder
+
+CloudFront emits all metrics to `us-east-1` only. CloudWatch alarms are regional, so alarms created in any other region never fire — they exist but receive no data. When the distribution lives in a stack outside `us-east-1`, use `createCloudFrontAlarmBuilder` to put the alarms in a separate `us-east-1` stack.
+
+The standalone builder reads the distribution's result (including the inline-function entries) and produces the same alarm surface — distribution-level recommended alarms, per-function recommended alarms, and any custom `addAlarm` alarms.
+
+```ts
+import { compose, ref } from "@composurecdk/core";
+import {
+  createDistributionBuilder,
+  createCloudFrontAlarmBuilder,
+  type DistributionBuilderResult,
+} from "@composurecdk/cloudfront";
+
+compose(
+  {
+    cdn: createDistributionBuilder()
+      .origin(siteOrigin)
+      .defaultBehavior({
+        functions: [{ eventType: FunctionEventType.VIEWER_REQUEST, code }],
+      })
+      .recommendedAlarms(false), // suppress all alarms in the dist's own stack
+
+    cdnAlarms: createCloudFrontAlarmBuilder()
+      .distribution(ref<DistributionBuilderResult>("cdn"))
+      .recommendedAlarms({ errorRate: { threshold: 2 } })
+      .addAlarm("custom4xx", (a) =>
+        a
+          .metric(
+            () =>
+              new Metric({
+                namespace: "AWS/CloudFront",
+                metricName: "4xxErrorRate",
+                statistic: "Average",
+              }),
+          )
+          .threshold(5)
+          .greaterThan(),
+      ),
+  },
+  { cdn: [], cdnAlarms: ["cdn"] },
+)
+  .withStacks({
+    cdn: siteStack, // e.g. eu-west-2
+    cdnAlarms: usEast1Stack, // typically your existing certStack
+  })
+  .build(app, "App");
+```
+
+Set `crossRegionReferences: true` on both stacks so CDK can export `DistributionId` from the site stack and import it in the alarm stack.
+
+`recommendedAlarms: false` on `createDistributionBuilder` is the master kill switch for both distribution-level and per-function recommended alarms. Custom alarms added via `addAlarm` are unaffected — call `.addAlarm()` on the standalone alarm builder if you want those to live in the us-east-1 stack too.
+
 ## Examples
 
 - [StaticWebsiteStack](../examples/src/static-website/app.ts) — S3 + CloudFront static website with OAC, error pages, and content deployment

package/dist/alarm-config.d.ts

@@ -5,9 +5,8 @@ import type { AlarmConfig } from "@composurecdk/cloudwatch";
  * Set individual alarms to `false` to disable them, or provide an
  * {@link AlarmConfig} to tune thresholds.
  *
- * Function-level alarms (FunctionValidationErrors, FunctionExecutionErrors,
- * FunctionThrottles) require per-function dimensions and are not created
- * automatically. Use {@link IDistributionBuilder.addAlarm} to add them.
+ * Function-level alarms are created automatically for every inline function
+ * declared on a behavior — see {@link FunctionAlarmConfig} to tune them.
  *
  * @see https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/Best_Practice_Recommended_Alarms_AWS_Services.html#CloudFront
  */
@@ -42,4 +41,58 @@ export interface DistributionAlarmConfig {
      */
     originLatency?: AlarmConfig | false;
 }
+/**
+ * Controls which recommended alarms are created for a CloudFront Function
+ * declared inline on a cache behavior. All alarms are enabled by default
+ * with AWS-recommended thresholds. Set individual alarms to `false` to
+ * disable them, or provide an {@link AlarmConfig} to tune thresholds.
+ *
+ * CloudFront Function metrics are emitted in the `us-east-1` region only
+ * (CloudFront is a global service). The alarms live in the stack's region —
+ * if that is not `us-east-1`, the alarms will not receive data.
+ *
+ * @see https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/monitoring-functions.html
+ */
+export interface FunctionAlarmConfig {
+    /**
+     * Per-function switch: set to `false` to disable all recommended alarms
+     * for this one function. Individual alarms can also be disabled via their
+     * own entry. The global kill switch is
+     * {@link DistributionBuilderProps.recommendedAlarms} `: false` on the
+     * surrounding distribution builder, which suppresses every recommended
+     * alarm regardless of per-function settings.
+     * @default true
+     */
+    enabled?: boolean;
+    /**
+     * Alarm when the function raises runtime exceptions while processing a
+     * viewer request or response.
+     *
+     * Metric: `AWS/CloudFront FunctionExecutionErrors`, statistic Sum,
+     * period 1 minute. Default threshold: > 0 errors.
+     *
+     * @see https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/monitoring-functions.html
+     */
+    executionErrors?: AlarmConfig | false;
+    /**
+     * Alarm when the function returns an event object that fails validation
+     * (e.g. malformed headers, unsupported response shape).
+     *
+     * Metric: `AWS/CloudFront FunctionValidationErrors`, statistic Sum,
+     * period 1 minute. Default threshold: > 0 errors.
+     *
+     * @see https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/monitoring-functions.html
+     */
+    validationErrors?: AlarmConfig | false;
+    /**
+     * Alarm when the function is throttled — typically because it exceeded
+     * the 1ms compute-utilization budget.
+     *
+     * Metric: `AWS/CloudFront FunctionThrottles`, statistic Sum,
+     * period 1 minute. Default threshold: > 0 throttles.
+     *
+     * @see https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/cloudfront-function-restrictions.html
+     */
+    throttles?: AlarmConfig | false;
+}
 //# sourceMappingURL=alarm-config.d.ts.map

package/dist/alarm-config.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"alarm-config.d.ts","sourceRoot":"","sources":["../src/alarm-config.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC;AAE5D;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,uBAAuB;IACtC;;;;OAIG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;IAElB;;;;;;;OAOG;IACH,SAAS,CAAC,EAAE,WAAW,GAAG,KAAK,CAAC;IAEhC;;;;;;;;;;;;OAYG;IACH,aAAa,CAAC,EAAE,WAAW,GAAG,KAAK,CAAC;CACrC"}
+{"version":3,"file":"alarm-config.d.ts","sourceRoot":"","sources":["../src/alarm-config.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC;AAE5D;;;;;;;;;;GAUG;AACH,MAAM,WAAW,uBAAuB;IACtC;;;;OAIG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;IAElB;;;;;;;OAOG;IACH,SAAS,CAAC,EAAE,WAAW,GAAG,KAAK,CAAC;IAEhC;;;;;;;;;;;;OAYG;IACH,aAAa,CAAC,EAAE,WAAW,GAAG,KAAK,CAAC;CACrC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,mBAAmB;IAClC;;;;;;;;OAQG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;IAElB;;;;;;;;OAQG;IACH,eAAe,CAAC,EAAE,WAAW,GAAG,KAAK,CAAC;IAEtC;;;;;;;;OAQG;IACH,gBAAgB,CAAC,EAAE,WAAW,GAAG,KAAK,CAAC;IAEvC;;;;;;;;OAQG;IACH,SAAS,CAAC,EAAE,WAAW,GAAG,KAAK,CAAC;CACjC"}

package/dist/alarm-defaults.d.ts

@@ -4,11 +4,25 @@ interface DistributionAlarmDefaults {
     errorRate: Required<AlarmConfig>;
     originLatency: Required<AlarmConfig>;
 }
+interface FunctionAlarmDefaults {
+    enabled: true;
+    executionErrors: Required<AlarmConfig>;
+    validationErrors: Required<AlarmConfig>;
+    throttles: Required<AlarmConfig>;
+}
 /**
  * AWS-recommended default alarm configuration for CloudFront distributions.
  *
  * @see https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/Best_Practice_Recommended_Alarms_AWS_Services.html#CloudFront
  */
 export declare const DISTRIBUTION_ALARM_DEFAULTS: DistributionAlarmDefaults;
+/**
+ * Default alarm configuration for CloudFront Functions declared inline on
+ * a cache behavior. Any non-zero count of errors or throttles is worth
+ * investigating since a function executes on every viewer request/response.
+ *
+ * @see https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/monitoring-functions.html
+ */
+export declare const FUNCTION_ALARM_DEFAULTS: FunctionAlarmDefaults;
 export {};
 //# sourceMappingURL=alarm-defaults.d.ts.map

package/dist/alarm-defaults.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"alarm-defaults.d.ts","sourceRoot":"","sources":["../src/alarm-defaults.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC;AAE5D,UAAU,yBAAyB;IACjC,OAAO,EAAE,IAAI,CAAC;IACd,SAAS,EAAE,QAAQ,CAAC,WAAW,CAAC,CAAC;IACjC,aAAa,EAAE,QAAQ,CAAC,WAAW,CAAC,CAAC;CACtC;AAED;;;;GAIG;AACH,eAAO,MAAM,2BAA2B,EAAE,yBAyBzC,CAAC"}
+{"version":3,"file":"alarm-defaults.d.ts","sourceRoot":"","sources":["../src/alarm-defaults.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC;AAE5D,UAAU,yBAAyB;IACjC,OAAO,EAAE,IAAI,CAAC;IACd,SAAS,EAAE,QAAQ,CAAC,WAAW,CAAC,CAAC;IACjC,aAAa,EAAE,QAAQ,CAAC,WAAW,CAAC,CAAC;CACtC;AAED,UAAU,qBAAqB;IAC7B,OAAO,EAAE,IAAI,CAAC;IACd,eAAe,EAAE,QAAQ,CAAC,WAAW,CAAC,CAAC;IACvC,gBAAgB,EAAE,QAAQ,CAAC,WAAW,CAAC,CAAC;IACxC,SAAS,EAAE,QAAQ,CAAC,WAAW,CAAC,CAAC;CAClC;AAED;;;;GAIG;AACH,eAAO,MAAM,2BAA2B,EAAE,yBAyBzC,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,uBAAuB,EAAE,qBA0BrC,CAAC"}

package/dist/alarm-defaults.js

@@ -28,4 +28,35 @@ export const DISTRIBUTION_ALARM_DEFAULTS = {
         treatMissingData: TreatMissingData.NOT_BREACHING,
     },
 };
+/**
+ * Default alarm configuration for CloudFront Functions declared inline on
+ * a cache behavior. Any non-zero count of errors or throttles is worth
+ * investigating since a function executes on every viewer request/response.
+ *
+ * @see https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/monitoring-functions.html
+ */
+export const FUNCTION_ALARM_DEFAULTS = {
+    enabled: true,
+    /** Any execution error indicates a runtime fault on the edge; threshold 0. */
+    executionErrors: {
+        threshold: 0,
+        evaluationPeriods: 1,
+        datapointsToAlarm: 1,
+        treatMissingData: TreatMissingData.NOT_BREACHING,
+    },
+    /** Any validation error indicates the function returned a bad event; threshold 0. */
+    validationErrors: {
+        threshold: 0,
+        evaluationPeriods: 1,
+        datapointsToAlarm: 1,
+        treatMissingData: TreatMissingData.NOT_BREACHING,
+    },
+    /** Any throttle indicates the function exceeded its 1ms compute budget; threshold 0. */
+    throttles: {
+        threshold: 0,
+        evaluationPeriods: 1,
+        datapointsToAlarm: 1,
+        treatMissingData: TreatMissingData.NOT_BREACHING,
+    },
+};
 //# sourceMappingURL=alarm-defaults.js.map

package/dist/alarm-defaults.js.map

@@ -1 +1 @@
-{"version":3,"file":"alarm-defaults.js","sourceRoot":"","sources":["../src/alarm-defaults.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,MAAM,4BAA4B,CAAC;AAS9D;;;;GAIG;AACH,MAAM,CAAC,MAAM,2BAA2B,GAA8B;IACpE,OAAO,EAAE,IAAI;IAEb;;;OAGG;IACH,SAAS,EAAE;QACT,SAAS,EAAE,CAAC;QACZ,iBAAiB,EAAE,CAAC;QACpB,iBAAiB,EAAE,CAAC;QACpB,gBAAgB,EAAE,gBAAgB,CAAC,aAAa;KACjD;IAED;;;;OAIG;IACH,aAAa,EAAE;QACb,SAAS,EAAE,IAAI;QACf,iBAAiB,EAAE,CAAC;QACpB,iBAAiB,EAAE,CAAC;QACpB,gBAAgB,EAAE,gBAAgB,CAAC,aAAa;KACjD;CACF,CAAC"}
+{"version":3,"file":"alarm-defaults.js","sourceRoot":"","sources":["../src/alarm-defaults.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,MAAM,4BAA4B,CAAC;AAgB9D;;;;GAIG;AACH,MAAM,CAAC,MAAM,2BAA2B,GAA8B;IACpE,OAAO,EAAE,IAAI;IAEb;;;OAGG;IACH,SAAS,EAAE;QACT,SAAS,EAAE,CAAC;QACZ,iBAAiB,EAAE,CAAC;QACpB,iBAAiB,EAAE,CAAC;QACpB,gBAAgB,EAAE,gBAAgB,CAAC,aAAa;KACjD;IAED;;;;OAIG;IACH,aAAa,EAAE;QACb,SAAS,EAAE,IAAI;QACf,iBAAiB,EAAE,CAAC;QACpB,iBAAiB,EAAE,CAAC;QACpB,gBAAgB,EAAE,gBAAgB,CAAC,aAAa;KACjD;CACF,CAAC;AAEF;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,uBAAuB,GAA0B;IAC5D,OAAO,EAAE,IAAI;IAEb,8EAA8E;IAC9E,eAAe,EAAE;QACf,SAAS,EAAE,CAAC;QACZ,iBAAiB,EAAE,CAAC;QACpB,iBAAiB,EAAE,CAAC;QACpB,gBAAgB,EAAE,gBAAgB,CAAC,aAAa;KACjD;IAED,qFAAqF;IACrF,gBAAgB,EAAE;QAChB,SAAS,EAAE,CAAC;QACZ,iBAAiB,EAAE,CAAC;QACpB,iBAAiB,EAAE,CAAC;QACpB,gBAAgB,EAAE,gBAAgB,CAAC,aAAa;KACjD;IAED,wFAAwF;IACxF,SAAS,EAAE;QACT,SAAS,EAAE,CAAC;QACZ,iBAAiB,EAAE,CAAC;QACpB,iBAAiB,EAAE,CAAC;QACpB,gBAAgB,EAAE,gBAAgB,CAAC,aAAa;KACjD;CACF,CAAC"}

package/dist/behavior-function-alarms.d.ts

@@ -0,0 +1,44 @@
+import type { Function as CfFunction, FunctionEventType } from "aws-cdk-lib/aws-cloudfront";
+import type { AlarmDefinition } from "@composurecdk/cloudwatch";
+import type { FunctionAlarmConfig } from "./alarm-config.js";
+/**
+ * Converts a CloudFront cache-behavior path pattern into a PascalCase slug
+ * suitable for alarm keys and CDK construct ids. A single leading `/` is
+ * dropped (the common case), interior `/` becomes `Slash` so sibling patterns
+ * don't collide, `*` becomes `Star`, and `?` becomes `Q`. Other
+ * non-alphanumeric characters are stripped.
+ *
+ * Examples:
+ * - `/api/*` → `ApiSlashStar`
+ * - `/api*`  → `ApiStar` (distinct from `/api/*`)
+ * - `*.html` → `StarHtml`
+ * - `images/*` → `ImagesSlashStar`
+ *
+ * @internal
+ */
+export declare function pathPatternSlug(pattern: string): string;
+/**
+ * Converts a {@link FunctionEventType} value (e.g. `"viewer-request"`) into
+ * PascalCase (e.g. `"ViewerRequest"`) for use in alarm keys and construct ids.
+ *
+ * @internal
+ */
+export declare function eventTypePascal(eventType: FunctionEventType): string;
+/**
+ * Builds the prefix used for every alarm key produced for a given inline
+ * function — e.g. `defaultBehaviorViewerRequest` or `behaviorApiStarViewerRequest`.
+ * Pass `null` for the default behavior.
+ *
+ * @internal
+ */
+export declare function behaviorFunctionKeyPrefix(pathPattern: string | null, eventType: FunctionEventType): string;
+/**
+ * Produces fully-resolved {@link AlarmDefinition}s for the three AWS-recommended
+ * CloudFront Function alarms — execution errors, validation errors, throttles —
+ * scoped to a single behavior + event type so the keys and descriptions stay
+ * actionable when the same underlying function is used on multiple behaviors.
+ *
+ * @internal
+ */
+export declare function resolveBehaviorFunctionAlarmDefinitions(pathPattern: string | null, eventType: FunctionEventType, fn: CfFunction, config: FunctionAlarmConfig | false | undefined): AlarmDefinition[];
+//# sourceMappingURL=behavior-function-alarms.d.ts.map

package/dist/behavior-function-alarms.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"behavior-function-alarms.d.ts","sourceRoot":"","sources":["../src/behavior-function-alarms.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,QAAQ,IAAI,UAAU,EAAE,iBAAiB,EAAE,MAAM,4BAA4B,CAAC;AAC5F,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,0BAA0B,CAAC;AAEhE,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAC;AA0B7D;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAUvD;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,SAAS,EAAE,iBAAiB,GAAG,MAAM,CAKpE;AAED;;;;;;GAMG;AACH,wBAAgB,yBAAyB,CACvC,WAAW,EAAE,MAAM,GAAG,IAAI,EAC1B,SAAS,EAAE,iBAAiB,GAC3B,MAAM,CAIR;AAUD;;;;;;;GAOG;AACH,wBAAgB,uCAAuC,CACrD,WAAW,EAAE,MAAM,GAAG,IAAI,EAC1B,SAAS,EAAE,iBAAiB,EAC5B,EAAE,EAAE,UAAU,EACd,MAAM,EAAE,mBAAmB,GAAG,KAAK,GAAG,SAAS,GAC9C,eAAe,EAAE,CAyDnB"}

package/dist/behavior-function-alarms.js

@@ -0,0 +1,136 @@
+import { Duration } from "aws-cdk-lib";
+import { ComparisonOperator, Metric, Stats } from "aws-cdk-lib/aws-cloudwatch";
+import { resolveAlarmConfig } from "@composurecdk/cloudwatch";
+import { FUNCTION_ALARM_DEFAULTS } from "./alarm-defaults.js";
+const METRIC_PERIOD = Duration.minutes(1);
+const METRIC_PERIOD_LABEL = `${String(METRIC_PERIOD.toMinutes())} minute`;
+/**
+ * CloudFront Function metrics are emitted in the `us-east-1` region only
+ * (CloudFront is a global service). Metric dimensions are
+ * `FunctionName` + `Region=Global`.
+ *
+ * @see https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/monitoring-functions.html
+ */
+function functionMetric(fn, metricName) {
+    return new Metric({
+        namespace: "AWS/CloudFront",
+        metricName,
+        dimensionsMap: {
+            FunctionName: fn.functionName,
+            Region: "Global",
+        },
+        statistic: Stats.SUM,
+        period: METRIC_PERIOD,
+    });
+}
+/**
+ * Converts a CloudFront cache-behavior path pattern into a PascalCase slug
+ * suitable for alarm keys and CDK construct ids. A single leading `/` is
+ * dropped (the common case), interior `/` becomes `Slash` so sibling patterns
+ * don't collide, `*` becomes `Star`, and `?` becomes `Q`. Other
+ * non-alphanumeric characters are stripped.
+ *
+ * Examples:
+ * - `/api/*` → `ApiSlashStar`
+ * - `/api*`  → `ApiStar` (distinct from `/api/*`)
+ * - `*.html` → `StarHtml`
+ * - `images/*` → `ImagesSlashStar`
+ *
+ * @internal
+ */
+export function pathPatternSlug(pattern) {
+    const stripped = pattern.startsWith("/") ? pattern.slice(1) : pattern;
+    return stripped
+        .replace(/\//g, " Slash ")
+        .replace(/\*/g, " Star ")
+        .replace(/\?/g, " Q ")
+        .split(/[^A-Za-z0-9]+/)
+        .filter(Boolean)
+        .map((part) => part.charAt(0).toUpperCase() + part.slice(1).toLowerCase())
+        .join("");
+}
+/**
+ * Converts a {@link FunctionEventType} value (e.g. `"viewer-request"`) into
+ * PascalCase (e.g. `"ViewerRequest"`) for use in alarm keys and construct ids.
+ *
+ * @internal
+ */
+export function eventTypePascal(eventType) {
+    return eventType
+        .split("-")
+        .map((part) => part.charAt(0).toUpperCase() + part.slice(1).toLowerCase())
+        .join("");
+}
+/**
+ * Builds the prefix used for every alarm key produced for a given inline
+ * function — e.g. `defaultBehaviorViewerRequest` or `behaviorApiStarViewerRequest`.
+ * Pass `null` for the default behavior.
+ *
+ * @internal
+ */
+export function behaviorFunctionKeyPrefix(pathPattern, eventType) {
+    const scope = pathPattern === null ? "defaultBehavior" : `behavior${pathPatternSlug(pathPattern)}`;
+    return `${scope}${eventTypePascal(eventType)}`;
+}
+function behaviorFunctionScopeLabel(pathPattern, eventType) {
+    const scope = pathPattern === null ? "default behavior" : `behavior "${pathPattern}"`;
+    return `${scope} (${eventType})`;
+}
+/**
+ * Produces fully-resolved {@link AlarmDefinition}s for the three AWS-recommended
+ * CloudFront Function alarms — execution errors, validation errors, throttles —
+ * scoped to a single behavior + event type so the keys and descriptions stay
+ * actionable when the same underlying function is used on multiple behaviors.
+ *
+ * @internal
+ */
+export function resolveBehaviorFunctionAlarmDefinitions(pathPattern, eventType, fn, config) {
+    if (config === false)
+        return [];
+    if (config?.enabled === false)
+        return [];
+    const keyPrefix = behaviorFunctionKeyPrefix(pathPattern, eventType);
+    const scopeLabel = behaviorFunctionScopeLabel(pathPattern, eventType);
+    const definitions = [];
+    if (config?.executionErrors !== false) {
+        const cfg = resolveAlarmConfig(config?.executionErrors, FUNCTION_ALARM_DEFAULTS.executionErrors);
+        definitions.push({
+            key: `${keyPrefix}ExecutionErrors`,
+            metric: functionMetric(fn, "FunctionExecutionErrors"),
+            threshold: cfg.threshold,
+            comparisonOperator: ComparisonOperator.GREATER_THAN_THRESHOLD,
+            evaluationPeriods: cfg.evaluationPeriods,
+            datapointsToAlarm: cfg.datapointsToAlarm,
+            treatMissingData: cfg.treatMissingData,
+            description: `CloudFront Function on ${scopeLabel} is raising execution errors. Threshold: > ${String(cfg.threshold)} errors in ${METRIC_PERIOD_LABEL}.`,
+        });
+    }
+    if (config?.validationErrors !== false) {
+        const cfg = resolveAlarmConfig(config?.validationErrors, FUNCTION_ALARM_DEFAULTS.validationErrors);
+        definitions.push({
+            key: `${keyPrefix}ValidationErrors`,
+            metric: functionMetric(fn, "FunctionValidationErrors"),
+            threshold: cfg.threshold,
+            comparisonOperator: ComparisonOperator.GREATER_THAN_THRESHOLD,
+            evaluationPeriods: cfg.evaluationPeriods,
+            datapointsToAlarm: cfg.datapointsToAlarm,
+            treatMissingData: cfg.treatMissingData,
+            description: `CloudFront Function on ${scopeLabel} is producing validation errors. Threshold: > ${String(cfg.threshold)} errors in ${METRIC_PERIOD_LABEL}.`,
+        });
+    }
+    if (config?.throttles !== false) {
+        const cfg = resolveAlarmConfig(config?.throttles, FUNCTION_ALARM_DEFAULTS.throttles);
+        definitions.push({
+            key: `${keyPrefix}Throttles`,
+            metric: functionMetric(fn, "FunctionThrottles"),
+            threshold: cfg.threshold,
+            comparisonOperator: ComparisonOperator.GREATER_THAN_THRESHOLD,
+            evaluationPeriods: cfg.evaluationPeriods,
+            datapointsToAlarm: cfg.datapointsToAlarm,
+            treatMissingData: cfg.treatMissingData,
+            description: `CloudFront Function on ${scopeLabel} is being throttled — likely exceeding its 1ms compute budget. Threshold: > ${String(cfg.threshold)} throttles in ${METRIC_PERIOD_LABEL}.`,
+        });
+    }
+    return definitions;
+}
+//# sourceMappingURL=behavior-function-alarms.js.map

package/dist/behavior-function-alarms.js.map

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

package/dist/cloudfront-alarm-builder.d.ts

@@ -0,0 +1,133 @@
+import { type Distribution } from "aws-cdk-lib/aws-cloudfront";
+import { type Alarm } from "aws-cdk-lib/aws-cloudwatch";
+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 { DistributionBuilderResult } from "./distribution-builder.js";
+/**
+ * Configuration properties for {@link createCloudFrontAlarmBuilder}.
+ *
+ * The standalone alarm builder mirrors the alarm surface that
+ * {@link createDistributionBuilder} creates by default. It exists so that
+ * alarms can be created in a different stack from the distribution itself —
+ * specifically a `us-east-1` stack, since CloudFront emits all metrics there
+ * regardless of the distribution's stack region.
+ */
+export interface CloudFrontAlarmBuilderProps {
+    /**
+     * Configuration for AWS-recommended CloudWatch alarms — distribution-level
+     * (5xx error rate, origin latency) and per-function (execution errors,
+     * validation errors, throttles).
+     *
+     * Mirrors {@link DistributionBuilderProps.recommendedAlarms}. Set to
+     * `false` to disable all recommended alarms; per-function alarms further
+     * respect each function's own {@link InlineFunctionDefinition.recommendedAlarms}
+     * value. Custom alarms added via {@link ICloudFrontAlarmBuilder.addAlarm}
+     * are unaffected.
+     *
+     * No alarm actions are configured by default. Use `alarmActionsPolicy` (or
+     * an `afterBuild` hook) to wire SNS or other actions onto the resulting
+     * alarms.
+     *
+     * @see https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/Best_Practice_Recommended_Alarms_AWS_Services.html#CloudFront
+     */
+    recommendedAlarms?: DistributionAlarmConfig | false;
+}
+/**
+ * The build output of an {@link ICloudFrontAlarmBuilder}.
+ */
+export interface CloudFrontAlarmBuilderResult {
+    /**
+     * The CloudWatch alarms created by this builder, keyed by alarm name. Uses
+     * the same key scheme as {@link DistributionBuilderResult.alarms}.
+     */
+    alarms: Record<string, Alarm>;
+}
+/**
+ * A fluent builder for CloudFront-related CloudWatch alarms, decoupled from
+ * the distribution itself. Use this when the distribution lives in a stack
+ * outside `us-east-1` — route this builder's component into a us-east-1
+ * stack via `compose().withStacks()` so the alarms land where CloudFront
+ * actually emits metrics.
+ *
+ * @see {@link createCloudFrontAlarmBuilder}
+ */
+export type ICloudFrontAlarmBuilder = IBuilder<CloudFrontAlarmBuilderProps, CloudFrontAlarmBuilder>;
+/**
+ * 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 declare function buildCloudFrontAlarms(scope: IConstruct, id: string, target: Pick<DistributionBuilderResult, "distribution" | "functions">, options?: {
+    recommendedAlarms?: DistributionAlarmConfig | false;
+    customAlarms?: AlarmDefinitionBuilder<Distribution>[];
+}): Record<string, Alarm>;
+declare class CloudFrontAlarmBuilder implements Lifecycle<CloudFrontAlarmBuilderResult> {
+    #private;
+    props: Partial<CloudFrontAlarmBuilderProps>;
+    /**
+     * 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: Resolvable<DistributionBuilderResult>): 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: string, configure: (alarm: AlarmDefinitionBuilder<Distribution>) => AlarmDefinitionBuilder<Distribution>): this;
+    build(scope: IConstruct, id: string, context?: Record<string, object>): CloudFrontAlarmBuilderResult;
+}
+/**
+ * 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 declare function createCloudFrontAlarmBuilder(): ICloudFrontAlarmBuilder;
+export {};
+//# sourceMappingURL=cloudfront-alarm-builder.d.ts.map

package/dist/cloudfront-alarm-builder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cloudfront-alarm-builder.d.ts","sourceRoot":"","sources":["../src/cloudfront-alarm-builder.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,YAAY,EAAE,MAAM,4BAA4B,CAAC;AAC/D,OAAO,EAAE,KAAK,KAAK,EAAE,MAAM,4BAA4B,CAAC;AAExD,OAAO,EAAE,KAAK,UAAU,EAAE,MAAM,YAAY,CAAC;AAC7C,OAAO,EAEL,KAAK,QAAQ,EACb,KAAK,SAAS,EAEd,KAAK,UAAU,EAChB,MAAM,oBAAoB,CAAC;AAE5B,OAAO,EAAE,sBAAsB,EAAgB,MAAM,0BAA0B,CAAC;AAChF,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,mBAAmB,CAAC;AAGjE,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,2BAA2B,CAAC;AAE3E;;;;;;;;GAQG;AACH,MAAM,WAAW,2BAA2B;IAC1C;;;;;;;;;;;;;;;;OAgBG;IACH,iBAAiB,CAAC,EAAE,uBAAuB,GAAG,KAAK,CAAC;CACrD;AAED;;GAEG;AACH,MAAM,WAAW,4BAA4B;IAC3C;;;OAGG;IACH,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;CAC/B;AAED;;;;;;;;GAQG;AACH,MAAM,MAAM,uBAAuB,GAAG,QAAQ,CAAC,2BAA2B,EAAE,sBAAsB,CAAC,CAAC;AAsBpG;;;;;;;;;GASG;AACH,wBAAgB,qBAAqB,CACnC,KAAK,EAAE,UAAU,EACjB,EAAE,EAAE,MAAM,EACV,MAAM,EAAE,IAAI,CAAC,yBAAyB,EAAE,cAAc,GAAG,WAAW,CAAC,EACrE,OAAO,GAAE;IACP,iBAAiB,CAAC,EAAE,uBAAuB,GAAG,KAAK,CAAC;IACpD,YAAY,CAAC,EAAE,sBAAsB,CAAC,YAAY,CAAC,EAAE,CAAC;CAClD,GACL,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,CAyBvB;AAED,cAAM,sBAAuB,YAAW,SAAS,CAAC,4BAA4B,CAAC;;IAC7E,KAAK,EAAE,OAAO,CAAC,2BAA2B,CAAC,CAAM;IAIjD;;;;;;;;;OASG;IACH,YAAY,CAAC,YAAY,EAAE,UAAU,CAAC,yBAAyB,CAAC,GAAG,IAAI;IAKvE;;;;;;;;OAQG;IACH,QAAQ,CACN,GAAG,EAAE,MAAM,EACX,SAAS,EAAE,CACT,KAAK,EAAE,sBAAsB,CAAC,YAAY,CAAC,KACxC,sBAAsB,CAAC,YAAY,CAAC,GACxC,IAAI;IAKP,KAAK,CACH,KAAK,EAAE,UAAU,EACjB,EAAE,EAAE,MAAM,EACV,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAC/B,4BAA4B;CAehC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,wBAAgB,4BAA4B,IAAI,uBAAuB,CAEtE"}