@composurecdk/lambda 0.6.0 → 0.8.0

package/README.md

@@ -49,16 +49,92 @@ const handler = createFunctionBuilder()
   .build(stack, "MyFunction");
 ```
 
+## Execution role
+
+By default, `createFunctionBuilder` creates an explicit IAM execution role with an inline `LogsWriter` policy scoped to the function's auto-created log group:
+
+- `logs:CreateLogStream` and `logs:PutLogEvents` on the function's specific log group ARN.
+- No `logs:CreateLogGroup` (the builder pre-creates the group).
+- No `AWSLambdaBasicExecutionRole` managed policy — that policy grants the same actions on `*`, allowing a compromised function to write to any log group in the account.
+
+The role is exposed on the build result:
+
+```ts
+const result = createFunctionBuilder()
+  .runtime(Runtime.NODEJS_22_X)
+  .handler("index.handler")
+  .code(Code.fromAsset("lambda"))
+  .build(stack, "MyFunction");
+
+result.role; // IRole — the execution role attached to the function
+```
+
+CDK continues to layer X-Ray, VPC, KMS-env, DLQ, and EFS permissions onto the role automatically based on the function's other props.
+
+### Extending the default role: `.configureRole(fn)`
+
+For least-privilege grants alongside the defaults:
+
+```ts
+import { createStatementBuilder } from "@composurecdk/iam";
+
+const handler = createFunctionBuilder()
+  .runtime(Runtime.NODEJS_22_X)
+  .handler("index.handler")
+  .code(Code.fromAsset("lambda"))
+  .configureRole((role) =>
+    role.addInlinePolicyStatements("OrdersRead", [
+      createStatementBuilder()
+        .allow()
+        .actions(["dynamodb:GetItem", "dynamodb:Query"])
+        .resources([table.tableArn]),
+    ]),
+  );
+```
+
+The callback receives the internal [`IRoleBuilder`](../iam/README.md). Calling `configureRole` more than once replaces the previous callback. The reserved `LogsWriter` name throws at build time if added a second time.
+
+### Supplying a role: `.role(role)`
+
+For a fully external role. The builder skips creating its own role and **does not** auto-attach the `LogsWriter` policy — the caller takes responsibility for permissions. Accepts a concrete `IRole` or a `ref(...)` for cross-component wiring under `compose`:
+
+```ts
+import { compose, ref } from "@composurecdk/core";
+import { createServiceRoleBuilder, type RoleBuilderResult } from "@composurecdk/iam";
+
+compose(
+  {
+    sharedRole: createServiceRoleBuilder("lambda.amazonaws.com"),
+    handler: createFunctionBuilder()
+      .runtime(Runtime.NODEJS_22_X)
+      .handler("index.handler")
+      .code(Code.fromAsset("lambda"))
+      .role(ref("sharedRole", (r: RoleBuilderResult) => r.role)),
+  },
+  { sharedRole: [], handler: ["sharedRole"] },
+).build(stack, "MySystem");
+```
+
+### Escape hatch: `.useCdkAutoRole()`
+
+Opt back into CDK's auto-created role attached to `AWSLambdaBasicExecutionRole`. Not the recommended path — it re-introduces the wildcard log surface — but available for matching an existing stack's logical IDs during a phased migration.
+
+`.role()`, `.configureRole()`, and `.useCdkAutoRole()` are mutually exclusive; combining any two throws at build time.
+
 ## Recommended Alarms
 
 The builder creates [AWS-recommended CloudWatch alarms](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/Best_Practice_Recommended_Alarms_AWS_Services.html#Lambda) by default. No alarm actions are configured — access alarms from the build result to add SNS topics or other actions.
 
-| Alarm                  | Metric                            | Default threshold           | Created when                          |
-| ---------------------- | --------------------------------- | --------------------------- | ------------------------------------- |
-| `errors`               | Errors (Sum, 1 min)               | > 0                         | Always                                |
-| `throttles`            | Throttles (Sum, 1 min)            | > 0                         | Always                                |
-| `duration`             | Duration (p99, 1 min)             | > 90% of configured timeout | `timeout` is set                      |
-| `concurrentExecutions` | ConcurrentExecutions (Max, 1 min) | >= 80% of reserved limit    | `reservedConcurrentExecutions` is set |
+| Alarm                    | Metric                            | Default threshold           | Created when                          |
+| ------------------------ | --------------------------------- | --------------------------- | ------------------------------------- |
+| `errors`                 | Errors (Sum, 1 min)               | > 0                         | Always                                |
+| `throttles`              | Throttles (Sum, 1 min)            | > 0                         | Always                                |
+| `duration`               | Duration (p99, 1 min)             | > 90% of configured timeout | `timeout` is set                      |
+| `concurrentExecutions`   | ConcurrentExecutions (Max, 1 min) | >= 80% of reserved limit    | `reservedConcurrentExecutions` is set |
+| `<key>FailedInvocations` | FailedInvokeEventCount (Sum)      | > 0                         | An SQS event source is attached       |
+| `<key>DroppedEvents`     | DroppedEventCount (Sum)           | > 0                         | An SQS event source is attached       |
+
+The event-source alarms are contextual: one pair is created per event source attached via `addEventSource` (see [Event sources](#event-sources)) whose kind emits per-mapping ESM metrics. Each alarm's key is the event source's key suffixed with `FailedInvocations` / `DroppedEvents` — e.g. an event source added as `"orders"` produces `ordersFailedInvocations` and `ordersDroppedEvents`. The `eventSourceFailedInvocations` / `eventSourceDroppedEvents` fields on `recommendedAlarms` tune every such alarm.
 
 The defaults are exported as `FUNCTION_ALARM_DEFAULTS` for visibility and testing:
 
@@ -144,7 +220,63 @@ for (const alarm of Object.values(result.alarms)) {
 }
 ```
 
+## Event sources
+
+`addEventSource(key, source)` wires a queue or stream to the function. A Lambda
+function can have many event sources of mixed types, so the hook is repeatable
+and keyed — the resolved sources are exposed on `result.eventSources`.
+
+Pass a `ComposureEventSource` from a factory (`sqsEventSource`), which carries
+its own `Resolvable` so the source queue can be a `ref()` to a sibling
+component, or a bare CDK `IEventSource` as an escape hatch.
+
+```ts
+import { compose, ref } from "@composurecdk/core";
+import { createFunctionBuilder, sqsEventSource } from "@composurecdk/lambda";
+import { createQueueBuilder } from "@composurecdk/sqs";
+
+const system = compose(
+  {
+    orders: createQueueBuilder().queueName("orders"),
+    processor: createFunctionBuilder()
+      .runtime(Runtime.NODEJS_22_X)
+      .handler("index.handler")
+      .code(Code.fromAsset("lambda"))
+      .addEventSource("orders", sqsEventSource(ref("orders", (r) => r.queue))),
+  },
+  { orders: [], processor: ["orders"] },
+);
+```
+
+The source is attached _after_ the function and its least-privilege execution
+role exist, so the `source.bind(fn)` that `addEventSource` performs grants the
+queue-consume permission onto the builder's role rather than CDK's auto-role.
+
+### Secure defaults
+
+`sqsEventSource` applies AWS-recommended defaults, each overridable via the
+second `props` argument and exported as `DEFAULT_SQS_EVENT_SOURCE_PROPS`:
+
+| Property                  | Default                     | Rationale                                                                                          |
+| ------------------------- | --------------------------- | -------------------------------------------------------------------------------------------------- |
+| `reportBatchItemFailures` | `true`                      | A single poison message fails only its own record, not the whole batch. CDK defaults this `false`. |
+| `metricsConfig`           | `{ metrics: [EventCount] }` | Enables the per-mapping ESM metrics that back the event-source contextual alarms.                  |
+
+### Cross-component invariants
+
+AWS Well-Architected guidance spans the queue and the function — the source
+queue's visibility timeout should be ≥ 6× the function timeout, and its redrive
+`maxReceiveCount` should be ≥ 5 before the DLQ. These are **not** enforced
+today (the queue often arrives as an unresolved `ref()`); they are tracked in
+[#123](https://github.com/laazyj/composureCDK/issues/123) and
+[#124](https://github.com/laazyj/composureCDK/issues/124).
+
+`kinesisEventSource` / `dynamoEventSource` and the stream-only `IteratorAge`
+alarm are deferred — see [#120](https://github.com/laazyj/composureCDK/issues/120)
+and [#121](https://github.com/laazyj/composureCDK/issues/121).
+
 ## Examples
 
 - [DualFunctionStack](../examples/src/dual-function-app.ts) — Two Lambda functions with recommended alarms, custom alarms, and SNS alarm actions
 - [MultiStackApp](../examples/src/multi-stack-app.ts) — Lambda split across stacks via `.withStacks()`, wired with `ref`
+- [OrderProcessorStack](../examples/src/order-processor-app.ts) — SQS queue wired to a Lambda consumer via `sqsEventSource`

package/dist/{alarm-config.d.ts → commonjs/alarm-config.d.ts}

@@ -80,5 +80,35 @@ export interface FunctionAlarmConfig {
      * @see https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/Best_Practice_Recommended_Alarms_AWS_Services.html#Lambda
      */
     concurrentExecutions?: PercentageAlarmConfig | false;
+    /**
+     * Alarm when an event source fails to invoke the function.
+     *
+     * Contextual: one alarm is created per event source attached via
+     * {@link IFunctionBuilder.addEventSource} whose kind emits per-mapping ESM
+     * metrics (currently SQS). The created alarm's key is the event source's
+     * key suffixed with `FailedInvocations` (e.g. `ordersFailedInvocations`);
+     * this config tunes every such alarm.
+     *
+     * Metric: `AWS/Lambda FailedInvokeEventCount`, statistic Sum, period 1
+     * minute, dimensioned on the event source mapping. Default threshold: > 0.
+     *
+     * @see https://aws.amazon.com/blogs/compute/introducing-new-event-source-mapping-esm-metrics-for-aws-lambda/
+     */
+    eventSourceFailedInvocations?: AlarmConfig | false;
+    /**
+     * Alarm when an event source drops events after exhausting retries or TTL.
+     *
+     * Contextual: one alarm is created per event source attached via
+     * {@link IFunctionBuilder.addEventSource} whose kind emits per-mapping ESM
+     * metrics (currently SQS). The created alarm's key is the event source's
+     * key suffixed with `DroppedEvents` (e.g. `ordersDroppedEvents`); this
+     * config tunes every such alarm.
+     *
+     * Metric: `AWS/Lambda DroppedEventCount`, statistic Sum, period 1 minute,
+     * dimensioned on the event source mapping. Default threshold: > 0.
+     *
+     * @see https://aws.amazon.com/blogs/compute/introducing-new-event-source-mapping-esm-metrics-for-aws-lambda/
+     */
+    eventSourceDroppedEvents?: AlarmConfig | false;
 }
 //# sourceMappingURL=alarm-config.d.ts.map

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

@@ -0,0 +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,MAAM,qBAAqB,GAAG,IAAI,CAAC,WAAW,EAAE,WAAW,CAAC,GAAG;IACnE;;;OAGG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B,CAAC;AAEF;;;GAGG;AACH,MAAM,MAAM,6BAA6B,GAAG,QAAQ,CAAC,IAAI,CAAC,qBAAqB,EAAE,WAAW,CAAC,CAAC,CAAC;AAE/F;;;;;;;GAOG;AACH,MAAM,WAAW,mBAAmB;IAClC;;;;OAIG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;IAElB;;;;;;;OAOG;IACH,MAAM,CAAC,EAAE,WAAW,GAAG,KAAK,CAAC;IAE7B;;;;;;;OAOG;IACH,SAAS,CAAC,EAAE,WAAW,GAAG,KAAK,CAAC;IAEhC;;;;;;;;;;OAUG;IACH,QAAQ,CAAC,EAAE,qBAAqB,GAAG,KAAK,CAAC;IAEzC;;;;;;;;;;OAUG;IACH,oBAAoB,CAAC,EAAE,qBAAqB,GAAG,KAAK,CAAC;IAErD;;;;;;;;;;;;;OAaG;IACH,4BAA4B,CAAC,EAAE,WAAW,GAAG,KAAK,CAAC;IAEnD;;;;;;;;;;;;;OAaG;IACH,wBAAwB,CAAC,EAAE,WAAW,GAAG,KAAK,CAAC;CAChD"}

package/dist/commonjs/alarm-config.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=alarm-config.js.map

package/dist/{alarm-config.js.map → commonjs/alarm-config.js.map}

@@ -1 +1 @@
-{"version":3,"file":"alarm-config.js","sourceRoot":"","sources":["../src/alarm-config.ts"],"names":[],"mappings":""}
+{"version":3,"file":"alarm-config.js","sourceRoot":"","sources":["../../src/alarm-config.ts"],"names":[],"mappings":""}

package/dist/{alarm-defaults.d.ts → commonjs/alarm-defaults.d.ts}

@@ -6,6 +6,8 @@ interface FunctionAlarmDefaults {
     throttles: AlarmConfigDefaults;
     duration: PercentageAlarmConfigDefaults;
     concurrentExecutions: PercentageAlarmConfigDefaults;
+    eventSourceFailedInvocations: AlarmConfigDefaults;
+    eventSourceDroppedEvents: AlarmConfigDefaults;
 }
 /**
  * AWS-recommended default alarm configuration for Lambda functions.

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

@@ -0,0 +1 @@
+{"version":3,"file":"alarm-defaults.d.ts","sourceRoot":"","sources":["../../src/alarm-defaults.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAC;AACpE,OAAO,KAAK,EAAE,6BAA6B,EAAE,MAAM,mBAAmB,CAAC;AAEvE,UAAU,qBAAqB;IAC7B,OAAO,EAAE,IAAI,CAAC;IACd,MAAM,EAAE,mBAAmB,CAAC;IAC5B,SAAS,EAAE,mBAAmB,CAAC;IAC/B,QAAQ,EAAE,6BAA6B,CAAC;IACxC,oBAAoB,EAAE,6BAA6B,CAAC;IACpD,4BAA4B,EAAE,mBAAmB,CAAC;IAClD,wBAAwB,EAAE,mBAAmB,CAAC;CAC/C;AAED;;;;GAIG;AACH,eAAO,MAAM,uBAAuB,EAAE,qBAwDrC,CAAC"}

package/dist/commonjs/alarm-defaults.js

@@ -0,0 +1,61 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FUNCTION_ALARM_DEFAULTS = void 0;
+const aws_cloudwatch_1 = require("aws-cdk-lib/aws-cloudwatch");
+/**
+ * AWS-recommended default alarm configuration for Lambda functions.
+ *
+ * @see https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/Best_Practice_Recommended_Alarms_AWS_Services.html#Lambda
+ */
+exports.FUNCTION_ALARM_DEFAULTS = {
+    enabled: true,
+    /** Any error is worth investigating; threshold 0. */
+    errors: {
+        threshold: 0,
+        evaluationPeriods: 1,
+        datapointsToAlarm: 1,
+        treatMissingData: aws_cloudwatch_1.TreatMissingData.NOT_BREACHING,
+    },
+    /** Any throttle indicates capacity pressure; threshold 0. */
+    throttles: {
+        threshold: 0,
+        evaluationPeriods: 1,
+        datapointsToAlarm: 1,
+        treatMissingData: aws_cloudwatch_1.TreatMissingData.NOT_BREACHING,
+    },
+    /**
+     * p99 duration approaching timeout indicates risk of timeouts.
+     * 90% of the configured timeout — early warning before hard failures.
+     */
+    duration: {
+        thresholdPercent: 0.9,
+        evaluationPeriods: 3,
+        datapointsToAlarm: 3,
+        treatMissingData: aws_cloudwatch_1.TreatMissingData.NOT_BREACHING,
+    },
+    /**
+     * Concurrent executions approaching reserved concurrency indicates
+     * risk of throttling. 80% of the reserved limit — early warning.
+     */
+    concurrentExecutions: {
+        thresholdPercent: 0.8,
+        evaluationPeriods: 3,
+        datapointsToAlarm: 3,
+        treatMissingData: aws_cloudwatch_1.TreatMissingData.NOT_BREACHING,
+    },
+    /** Any failed invocation from an event source is worth investigating; threshold 0. */
+    eventSourceFailedInvocations: {
+        threshold: 0,
+        evaluationPeriods: 1,
+        datapointsToAlarm: 1,
+        treatMissingData: aws_cloudwatch_1.TreatMissingData.NOT_BREACHING,
+    },
+    /** Any dropped event is lost work; threshold 0. */
+    eventSourceDroppedEvents: {
+        threshold: 0,
+        evaluationPeriods: 1,
+        datapointsToAlarm: 1,
+        treatMissingData: aws_cloudwatch_1.TreatMissingData.NOT_BREACHING,
+    },
+};
+//# sourceMappingURL=alarm-defaults.js.map

package/dist/commonjs/alarm-defaults.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"alarm-defaults.js","sourceRoot":"","sources":["../../src/alarm-defaults.ts"],"names":[],"mappings":";;;AAAA,+DAA8D;AAc9D;;;;GAIG;AACU,QAAA,uBAAuB,GAA0B;IAC5D,OAAO,EAAE,IAAI;IAEb,qDAAqD;IACrD,MAAM,EAAE;QACN,SAAS,EAAE,CAAC;QACZ,iBAAiB,EAAE,CAAC;QACpB,iBAAiB,EAAE,CAAC;QACpB,gBAAgB,EAAE,iCAAgB,CAAC,aAAa;KACjD;IAED,6DAA6D;IAC7D,SAAS,EAAE;QACT,SAAS,EAAE,CAAC;QACZ,iBAAiB,EAAE,CAAC;QACpB,iBAAiB,EAAE,CAAC;QACpB,gBAAgB,EAAE,iCAAgB,CAAC,aAAa;KACjD;IAED;;;OAGG;IACH,QAAQ,EAAE;QACR,gBAAgB,EAAE,GAAG;QACrB,iBAAiB,EAAE,CAAC;QACpB,iBAAiB,EAAE,CAAC;QACpB,gBAAgB,EAAE,iCAAgB,CAAC,aAAa;KACjD;IAED;;;OAGG;IACH,oBAAoB,EAAE;QACpB,gBAAgB,EAAE,GAAG;QACrB,iBAAiB,EAAE,CAAC;QACpB,iBAAiB,EAAE,CAAC;QACpB,gBAAgB,EAAE,iCAAgB,CAAC,aAAa;KACjD;IAED,sFAAsF;IACtF,4BAA4B,EAAE;QAC5B,SAAS,EAAE,CAAC;QACZ,iBAAiB,EAAE,CAAC;QACpB,iBAAiB,EAAE,CAAC;QACpB,gBAAgB,EAAE,iCAAgB,CAAC,aAAa;KACjD;IAED,mDAAmD;IACnD,wBAAwB,EAAE;QACxB,SAAS,EAAE,CAAC;QACZ,iBAAiB,EAAE,CAAC;QACpB,iBAAiB,EAAE,CAAC;QACpB,gBAAgB,EAAE,iCAAgB,CAAC,aAAa;KACjD;CACF,CAAC"}

package/dist/commonjs/defaults.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"defaults.d.ts","sourceRoot":"","sources":["../../src/defaults.ts"],"names":[],"mappings":"AAAA,OAAO,EAA0B,KAAK,aAAa,EAAE,MAAM,wBAAwB,CAAC;AAEpF;;;;GAIG;AACH,eAAO,MAAM,iBAAiB,EAAE,OAAO,CAAC,aAAa,CAapD,CAAC"}

package/dist/commonjs/defaults.js

@@ -0,0 +1,23 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FUNCTION_DEFAULTS = void 0;
+const aws_lambda_1 = require("aws-cdk-lib/aws-lambda");
+/**
+ * Secure, AWS-recommended defaults applied to every Lambda function built
+ * with {@link createFunctionBuilder}. Each property can be individually
+ * overridden via the builder's fluent API.
+ */
+exports.FUNCTION_DEFAULTS = {
+    /**
+     * Enable AWS X-Ray active tracing for distributed request tracking.
+     * @see https://docs.aws.amazon.com/wellarchitected/latest/serverless-applications-lens/opex-distributed-tracing.html
+     */
+    tracing: aws_lambda_1.Tracing.ACTIVE,
+    /**
+     * Emit logs as structured JSON for CloudWatch Logs Insights auto-discovery
+     * and consistent querying across services.
+     * @see https://docs.aws.amazon.com/wellarchitected/latest/serverless-applications-lens/opex-logging.html
+     */
+    loggingFormat: aws_lambda_1.LoggingFormat.JSON,
+};
+//# sourceMappingURL=defaults.js.map

package/dist/commonjs/defaults.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"defaults.js","sourceRoot":"","sources":["../../src/defaults.ts"],"names":[],"mappings":";;;AAAA,uDAAoF;AAEpF;;;;GAIG;AACU,QAAA,iBAAiB,GAA2B;IACvD;;;OAGG;IACH,OAAO,EAAE,oBAAO,CAAC,MAAM;IAEvB;;;;OAIG;IACH,aAAa,EAAE,0BAAa,CAAC,IAAI;CAClC,CAAC"}

package/dist/commonjs/event-sources/composure-event-source.d.ts

@@ -0,0 +1,76 @@
+import type { IEventSource } from "aws-cdk-lib/aws-lambda";
+import type { Resolvable } from "@composurecdk/core";
+/**
+ * Discriminator for the kind of event source a {@link ComposureEventSource}
+ * wraps. `FunctionBuilder` keys its contextual alarms and invariant checks
+ * off this value so it never has to `instanceof` CDK internals.
+ *
+ * `"unknown"` is the kind assigned to a bare {@link IEventSource} passed
+ * straight to {@link IFunctionBuilder.addEventSource} as an escape hatch —
+ * the builder still attaches it, but cannot reason about it.
+ */
+export type EventSourceKind = "sqs" | "unknown";
+/** @internal — brands {@link ComposureEventSource} so the guard is unambiguous. */
+declare const COMPOSURE_EVENT_SOURCE: unique symbol;
+/**
+ * A `Resolvable`-aware event source produced by a ComposureCDK factory
+ * (e.g. {@link sqsEventSource}).
+ *
+ * Follows the `events/targets` factory shape — the factory wraps the
+ * underlying CDK event source and resolves any `ref()` to a sibling
+ * component at build time — and additionally tags it with a
+ * {@link EventSourceKind} discriminator so `FunctionBuilder` can pick the
+ * right contextual alarms without inspecting CDK internals.
+ *
+ * Construct one via a factory rather than by hand; the brand is private.
+ */
+export interface ComposureEventSource {
+    /** @internal */
+    readonly [COMPOSURE_EVENT_SOURCE]: true;
+    /** The kind of source, used to dispatch contextual alarms and checks. */
+    readonly kind: EventSourceKind;
+    /**
+     * The wrapped CDK event source, deferred behind a {@link Resolvable} when
+     * the factory was handed a `ref()` to a sibling component's output.
+     */
+    readonly source: Resolvable<IEventSource>;
+}
+/** @internal — assembles a branded {@link ComposureEventSource}. */
+export declare function composureEventSource(kind: EventSourceKind, source: Resolvable<IEventSource>): ComposureEventSource;
+/**
+ * Reads the event source mapping UUID off a bound CDK source, keyed by
+ * {@link EventSourceKind}. Defined only for kinds whose per-mapping ESM
+ * metrics back contextual alarms (currently SQS); `FunctionBuilder` invokes
+ * the reader after `addEventSource` so the binding exists. Keying off `kind`
+ * — like {@link EVENT_SOURCE_ALARM_SPECS} — keeps the builder from
+ * `instanceof`-ing CDK source classes.
+ *
+ * @internal
+ */
+export declare const EVENT_SOURCE_MAPPING_ID_READERS: Record<EventSourceKind, ((bound: IEventSource) => string) | undefined>;
+/**
+ * Type guard distinguishing a {@link ComposureEventSource} from a bare
+ * {@link IEventSource} escape-hatch value.
+ */
+export declare function isComposureEventSource(value: ComposureEventSource | IEventSource): value is ComposureEventSource;
+/**
+ * An event source resolved and attached to a function during build, carrying
+ * the metadata the alarm machinery needs to emit contextual alarms.
+ *
+ * @internal — the contract between `FunctionBuilder.build()` and the
+ *   event-source alarm machinery in `function-alarms.ts`.
+ */
+export interface AttachedEventSource {
+    /** The key the source was registered under via `addEventSource`. */
+    key: string;
+    /** The kind of source, used to dispatch contextual alarms. */
+    kind: EventSourceKind;
+    /**
+     * The event source mapping UUID, populated for kinds whose per-mapping
+     * ESM metrics back contextual alarms (currently SQS only). The contextual
+     * alarms key off this dimension.
+     */
+    eventSourceMappingId?: string;
+}
+export {};
+//# sourceMappingURL=composure-event-source.d.ts.map

package/dist/commonjs/event-sources/composure-event-source.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"composure-event-source.d.ts","sourceRoot":"","sources":["../../../src/event-sources/composure-event-source.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC;AAE3D,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAErD;;;;;;;;GAQG;AACH,MAAM,MAAM,eAAe,GAAG,KAAK,GAAG,SAAS,CAAC;AAEhD,mFAAmF;AACnF,QAAA,MAAM,sBAAsB,eAAgD,CAAC;AAE7E;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,oBAAoB;IACnC,gBAAgB;IAChB,QAAQ,CAAC,CAAC,sBAAsB,CAAC,EAAE,IAAI,CAAC;IAExC,yEAAyE;IACzE,QAAQ,CAAC,IAAI,EAAE,eAAe,CAAC;IAE/B;;;OAGG;IACH,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAC,YAAY,CAAC,CAAC;CAC3C;AAED,oEAAoE;AACpE,wBAAgB,oBAAoB,CAClC,IAAI,EAAE,eAAe,EACrB,MAAM,EAAE,UAAU,CAAC,YAAY,CAAC,GAC/B,oBAAoB,CAEtB;AAED;;;;;;;;;GASG;AACH,eAAO,MAAM,+BAA+B,EAAE,MAAM,CAClD,eAAe,EACf,CAAC,CAAC,KAAK,EAAE,YAAY,KAAK,MAAM,CAAC,GAAG,SAAS,CAO9C,CAAC;AAEF;;;GAGG;AACH,wBAAgB,sBAAsB,CACpC,KAAK,EAAE,oBAAoB,GAAG,YAAY,GACzC,KAAK,IAAI,oBAAoB,CAE/B;AAED;;;;;;GAMG;AACH,MAAM,WAAW,mBAAmB;IAClC,oEAAoE;IACpE,GAAG,EAAE,MAAM,CAAC;IAEZ,8DAA8D;IAC9D,IAAI,EAAE,eAAe,CAAC;IAEtB;;;;OAIG;IACH,oBAAoB,CAAC,EAAE,MAAM,CAAC;CAC/B"}

package/dist/commonjs/event-sources/composure-event-source.js

@@ -0,0 +1,36 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EVENT_SOURCE_MAPPING_ID_READERS = void 0;
+exports.composureEventSource = composureEventSource;
+exports.isComposureEventSource = isComposureEventSource;
+/** @internal — brands {@link ComposureEventSource} so the guard is unambiguous. */
+const COMPOSURE_EVENT_SOURCE = Symbol.for("composurecdk.lambda.eventSource");
+/** @internal — assembles a branded {@link ComposureEventSource}. */
+function composureEventSource(kind, source) {
+    return { [COMPOSURE_EVENT_SOURCE]: true, kind, source };
+}
+/**
+ * Reads the event source mapping UUID off a bound CDK source, keyed by
+ * {@link EventSourceKind}. Defined only for kinds whose per-mapping ESM
+ * metrics back contextual alarms (currently SQS); `FunctionBuilder` invokes
+ * the reader after `addEventSource` so the binding exists. Keying off `kind`
+ * — like {@link EVENT_SOURCE_ALARM_SPECS} — keeps the builder from
+ * `instanceof`-ing CDK source classes.
+ *
+ * @internal
+ */
+exports.EVENT_SOURCE_MAPPING_ID_READERS = {
+    // Safe: the `"sqs"` kind is only ever assigned by `sqsEventSource()`, which
+    // constructs the `SqsEventSource` in the same call — kind and concrete class
+    // move in lockstep.
+    sqs: (bound) => bound.eventSourceMappingId,
+    unknown: undefined,
+};
+/**
+ * Type guard distinguishing a {@link ComposureEventSource} from a bare
+ * {@link IEventSource} escape-hatch value.
+ */
+function isComposureEventSource(value) {
+    return COMPOSURE_EVENT_SOURCE in value;
+}
+//# sourceMappingURL=composure-event-source.js.map

package/dist/commonjs/event-sources/composure-event-source.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"composure-event-source.js","sourceRoot":"","sources":["../../../src/event-sources/composure-event-source.ts"],"names":[],"mappings":";;;AA6CA,oDAKC;AA2BD,wDAIC;AAlED,mFAAmF;AACnF,MAAM,sBAAsB,GAAG,MAAM,CAAC,GAAG,CAAC,iCAAiC,CAAC,CAAC;AA4B7E,oEAAoE;AACpE,SAAgB,oBAAoB,CAClC,IAAqB,EACrB,MAAgC;IAEhC,OAAO,EAAE,CAAC,sBAAsB,CAAC,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC;AAC1D,CAAC;AAED;;;;;;;;;GASG;AACU,QAAA,+BAA+B,GAGxC;IACF,4EAA4E;IAC5E,6EAA6E;IAC7E,oBAAoB;IACpB,GAAG,EAAE,CAAC,KAAK,EAAE,EAAE,CAAE,KAAwB,CAAC,oBAAoB;IAC9D,OAAO,EAAE,SAAS;CACnB,CAAC;AAEF;;;GAGG;AACH,SAAgB,sBAAsB,CACpC,KAA0C;IAE1C,OAAO,sBAAsB,IAAI,KAAK,CAAC;AACzC,CAAC"}

package/dist/commonjs/event-sources/sqs-event-source.d.ts

@@ -0,0 +1,54 @@
+import { type SqsEventSourceProps } from "aws-cdk-lib/aws-lambda-event-sources";
+import type { IQueue } from "aws-cdk-lib/aws-sqs";
+import { type Resolvable } from "@composurecdk/core";
+import { type ComposureEventSource } from "./composure-event-source.js";
+/**
+ * Secure, AWS-recommended defaults applied to every SQS event source built
+ * with {@link sqsEventSource}. Each property can be overridden via the
+ * factory's `props` argument.
+ */
+export declare const DEFAULT_SQS_EVENT_SOURCE_PROPS: Pick<SqsEventSourceProps, "reportBatchItemFailures" | "metricsConfig">;
+/**
+ * Wraps an SQS queue as a Lambda {@link IEventSource}, deferring resolution
+ * when the queue is a `ref()` to a sibling component's output.
+ *
+ * Follows the `events/targets` factory shape: register the result with
+ * {@link IFunctionBuilder.addEventSource} and the builder resolves the
+ * `ref()`, attaches the source, and (because `addEventSource` calls
+ * `source.bind(fn)`) grants the function's least-privilege execution role
+ * permission to consume the queue.
+ *
+ * Applies {@link DEFAULT_SQS_EVENT_SOURCE_PROPS}; pass `props` to override.
+ *
+ * ## Cross-component invariants (not enforced)
+ *
+ * AWS Well-Architected guidance spans the queue and the function:
+ * - the source queue's visibility timeout should be ≥ 6× the function
+ *   timeout, leaving room for Lambda to retry a throttled batch;
+ * - the source queue's redrive `maxReceiveCount` should be ≥ 5 before the DLQ.
+ *
+ * These are not validated here — the queue often arrives as a `ref()` that is
+ * not resolvable at configuration time. Tracked in laazyj/composureCDK#123
+ * and #124.
+ *
+ * @param queue - The source queue, concrete or a `ref()` to a sibling.
+ * @param props - Overrides for {@link DEFAULT_SQS_EVENT_SOURCE_PROPS} and any
+ *   other {@link SqsEventSourceProps}.
+ *
+ * @example
+ * ```ts
+ * compose(
+ *   {
+ *     orders: createQueueBuilder().queueName("orders"),
+ *     processor: createFunctionBuilder()
+ *       .runtime(Runtime.NODEJS_22_X)
+ *       .handler("index.handler")
+ *       .code(Code.fromAsset("lambda"))
+ *       .addEventSource("orders", sqsEventSource(ref("orders", (r) => r.queue))),
+ *   },
+ *   { orders: [], processor: ["orders"] },
+ * );
+ * ```
+ */
+export declare function sqsEventSource(queue: Resolvable<IQueue>, props?: SqsEventSourceProps): ComposureEventSource;
+//# sourceMappingURL=sqs-event-source.d.ts.map

package/dist/commonjs/event-sources/sqs-event-source.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sqs-event-source.d.ts","sourceRoot":"","sources":["../../../src/event-sources/sqs-event-source.ts"],"names":[],"mappings":"AAEA,OAAO,EAAkB,KAAK,mBAAmB,EAAE,MAAM,sCAAsC,CAAC;AAChG,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,qBAAqB,CAAC;AAClD,OAAO,EAAS,KAAK,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAC5D,OAAO,EAAE,KAAK,oBAAoB,EAAwB,MAAM,6BAA6B,CAAC;AAE9F;;;;GAIG;AACH,eAAO,MAAM,8BAA8B,EAAE,IAAI,CAC/C,mBAAmB,EACnB,yBAAyB,GAAG,eAAe,CAkB5C,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AACH,wBAAgB,cAAc,CAC5B,KAAK,EAAE,UAAU,CAAC,MAAM,CAAC,EACzB,KAAK,CAAC,EAAE,mBAAmB,GAC1B,oBAAoB,CAMtB"}

package/dist/commonjs/event-sources/sqs-event-source.js

@@ -0,0 +1,80 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_SQS_EVENT_SOURCE_PROPS = void 0;
+exports.sqsEventSource = sqsEventSource;
+const aws_lambda_1 = require("aws-cdk-lib/aws-lambda");
+const aws_lambda_event_sources_1 = require("aws-cdk-lib/aws-lambda-event-sources");
+const core_1 = require("@composurecdk/core");
+const composure_event_source_js_1 = require("./composure-event-source.js");
+/**
+ * Secure, AWS-recommended defaults applied to every SQS event source built
+ * with {@link sqsEventSource}. Each property can be overridden via the
+ * factory's `props` argument.
+ */
+exports.DEFAULT_SQS_EVENT_SOURCE_PROPS = {
+    /**
+     * Report partial batch failures so a single poison message does not fail
+     * the whole batch and force redelivery of already-processed records. CDK
+     * defaults this to `false`.
+     * @see https://aws.amazon.com/blogs/compute/implementing-aws-well-architected-best-practices-for-amazon-sqs-part-3/
+     * @see https://docs.aws.amazon.com/lambda/latest/dg/with-sqs.html#services-sqs-batchfailurereporting
+     */
+    reportBatchItemFailures: true,
+    /**
+     * Enable the per-mapping `EventCount` ESM metrics (`FailedInvokeEventCount`,
+     * `DroppedEventCount`, …). They emit only when opted in, and the
+     * event-source contextual alarms on {@link IFunctionBuilder} depend on them.
+     * @see https://aws.amazon.com/blogs/compute/introducing-new-event-source-mapping-esm-metrics-for-aws-lambda/
+     */
+    metricsConfig: { metrics: [aws_lambda_1.MetricType.EVENT_COUNT] },
+};
+/**
+ * Wraps an SQS queue as a Lambda {@link IEventSource}, deferring resolution
+ * when the queue is a `ref()` to a sibling component's output.
+ *
+ * Follows the `events/targets` factory shape: register the result with
+ * {@link IFunctionBuilder.addEventSource} and the builder resolves the
+ * `ref()`, attaches the source, and (because `addEventSource` calls
+ * `source.bind(fn)`) grants the function's least-privilege execution role
+ * permission to consume the queue.
+ *
+ * Applies {@link DEFAULT_SQS_EVENT_SOURCE_PROPS}; pass `props` to override.
+ *
+ * ## Cross-component invariants (not enforced)
+ *
+ * AWS Well-Architected guidance spans the queue and the function:
+ * - the source queue's visibility timeout should be ≥ 6× the function
+ *   timeout, leaving room for Lambda to retry a throttled batch;
+ * - the source queue's redrive `maxReceiveCount` should be ≥ 5 before the DLQ.
+ *
+ * These are not validated here — the queue often arrives as a `ref()` that is
+ * not resolvable at configuration time. Tracked in laazyj/composureCDK#123
+ * and #124.
+ *
+ * @param queue - The source queue, concrete or a `ref()` to a sibling.
+ * @param props - Overrides for {@link DEFAULT_SQS_EVENT_SOURCE_PROPS} and any
+ *   other {@link SqsEventSourceProps}.
+ *
+ * @example
+ * ```ts
+ * compose(
+ *   {
+ *     orders: createQueueBuilder().queueName("orders"),
+ *     processor: createFunctionBuilder()
+ *       .runtime(Runtime.NODEJS_22_X)
+ *       .handler("index.handler")
+ *       .code(Code.fromAsset("lambda"))
+ *       .addEventSource("orders", sqsEventSource(ref("orders", (r) => r.queue))),
+ *   },
+ *   { orders: [], processor: ["orders"] },
+ * );
+ * ```
+ */
+function sqsEventSource(queue, props) {
+    const merged = { ...exports.DEFAULT_SQS_EVENT_SOURCE_PROPS, ...props };
+    const source = (0, core_1.isRef)(queue)
+        ? queue.map((resolved) => new aws_lambda_event_sources_1.SqsEventSource(resolved, merged))
+        : new aws_lambda_event_sources_1.SqsEventSource(queue, merged);
+    return (0, composure_event_source_js_1.composureEventSource)("sqs", source);
+}
+//# sourceMappingURL=sqs-event-source.js.map

package/dist/commonjs/event-sources/sqs-event-source.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sqs-event-source.js","sourceRoot":"","sources":["../../../src/event-sources/sqs-event-source.ts"],"names":[],"mappings":";;;AA4EA,wCASC;AApFD,uDAAoD;AACpD,mFAAgG;AAEhG,6CAA4D;AAC5D,2EAA8F;AAE9F;;;;GAIG;AACU,QAAA,8BAA8B,GAGvC;IACF;;;;;;OAMG;IACH,uBAAuB,EAAE,IAAI;IAE7B;;;;;OAKG;IACH,aAAa,EAAE,EAAE,OAAO,EAAE,CAAC,uBAAU,CAAC,WAAW,CAAC,EAAE;CACrD,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AACH,SAAgB,cAAc,CAC5B,KAAyB,EACzB,KAA2B;IAE3B,MAAM,MAAM,GAAwB,EAAE,GAAG,sCAA8B,EAAE,GAAG,KAAK,EAAE,CAAC;IACpF,MAAM,MAAM,GAA6B,IAAA,YAAK,EAAC,KAAK,CAAC;QACnD,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,QAAQ,EAAE,EAAE,CAAC,IAAI,yCAAc,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC;QAC/D,CAAC,CAAC,IAAI,yCAAc,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC;IACtC,OAAO,IAAA,gDAAoB,EAAC,KAAK,EAAE,MAAM,CAAC,CAAC;AAC7C,CAAC"}

package/dist/{function-alarms.d.ts → commonjs/function-alarms.d.ts}

@@ -4,12 +4,13 @@ import type { IConstruct } from "constructs";
 import type { AlarmDefinition } from "@composurecdk/cloudwatch";
 import { AlarmDefinitionBuilder } from "@composurecdk/cloudwatch";
 import type { FunctionAlarmConfig } from "./alarm-config.js";
+import type { AttachedEventSource } from "./event-sources/composure-event-source.js";
 /**
  * Resolves the recommended alarm configuration into fully-resolved
  * {@link AlarmDefinition}s, applying contextual logic for timeout-based
  * duration and reserved-concurrency-based concurrent execution alarms.
  */
-export declare function resolveFunctionAlarmDefinitions(fn: LambdaFunction, config: FunctionAlarmConfig | undefined, props: Pick<FunctionProps, "timeout" | "reservedConcurrentExecutions">): AlarmDefinition[];
+export declare function resolveFunctionAlarmDefinitions(fn: LambdaFunction, config: FunctionAlarmConfig | undefined, props: Pick<FunctionProps, "timeout" | "reservedConcurrentExecutions">, eventSources?: AttachedEventSource[]): AlarmDefinition[];
 /**
  * Creates AWS-recommended CloudWatch alarms for a Lambda function,
  * merging recommended definitions with any custom alarm builders.
@@ -19,10 +20,12 @@ export declare function resolveFunctionAlarmDefinitions(fn: LambdaFunction, conf
  * @param fn - The Lambda function to create alarms for.
  * @param config - User-provided alarm configuration, or `false` to disable all.
  * @param props - The merged function props, used for contextual alarm thresholds.
+ * @param eventSources - Event sources attached to the function, used for
+ *   per-event-source contextual alarms.
  * @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#Lambda
  */
-export declare function createFunctionAlarms(scope: IConstruct, id: string, fn: LambdaFunction, config: FunctionAlarmConfig | false | undefined, props: Pick<FunctionProps, "timeout" | "reservedConcurrentExecutions">, customAlarms?: AlarmDefinitionBuilder<LambdaFunction>[]): Record<string, Alarm>;
+export declare function createFunctionAlarms(scope: IConstruct, id: string, fn: LambdaFunction, config: FunctionAlarmConfig | false | undefined, props: Pick<FunctionProps, "timeout" | "reservedConcurrentExecutions">, eventSources?: AttachedEventSource[], customAlarms?: AlarmDefinitionBuilder<LambdaFunction>[]): Record<string, Alarm>;
 //# sourceMappingURL=function-alarms.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"function-alarms.d.ts","sourceRoot":"","sources":["../../src/function-alarms.ts"],"names":[],"mappings":"AACA,OAAO,EACL,KAAK,KAAK,EAKX,MAAM,4BAA4B,CAAC;AACpC,OAAO,KAAK,EAAE,QAAQ,IAAI,cAAc,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAC;AACxF,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAC7C,OAAO,KAAK,EAAE,eAAe,EAAa,MAAM,0BAA0B,CAAC;AAC3E,OAAO,EAAE,sBAAsB,EAAoC,MAAM,0BAA0B,CAAC;AACpG,OAAO,KAAK,EACV,mBAAmB,EAGpB,MAAM,mBAAmB,CAAC;AAE3B,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,2CAA2C,CAAC;AA2CrF;;;;GAIG;AACH,wBAAgB,+BAA+B,CAC7C,EAAE,EAAE,cAAc,EAClB,MAAM,EAAE,mBAAmB,GAAG,SAAS,EACvC,KAAK,EAAE,IAAI,CAAC,aAAa,EAAE,SAAS,GAAG,8BAA8B,CAAC,EACtE,YAAY,GAAE,mBAAmB,EAAO,GACvC,eAAe,EAAE,CAqGnB;AAiBD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,oBAAoB,CAClC,KAAK,EAAE,UAAU,EACjB,EAAE,EAAE,MAAM,EACV,EAAE,EAAE,cAAc,EAClB,MAAM,EAAE,mBAAmB,GAAG,KAAK,GAAG,SAAS,EAC/C,KAAK,EAAE,IAAI,CAAC,aAAa,EAAE,SAAS,GAAG,8BAA8B,CAAC,EACtE,YAAY,GAAE,mBAAmB,EAAO,EACxC,YAAY,GAAE,sBAAsB,CAAC,cAAc,CAAC,EAAO,GAC1D,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,CAUvB"}