@devries-cameron20 / t3code Mirror · read-only
Fork 0

The best way to control Claude Code, Codex and more from any computer or phone

Mirrored from https://github.com/Camo67/t3code.git

Synced Nov 21, 04:45 UTC

main
ts 1,068 lines 44.2 KB
Raw
1 import * as lambda from "@distilled.cloud/aws/lambda";
2 import { deepEqual, isResolved } from "alchemy/Diff";
3 import * as Provider from "alchemy/Provider";
4 import { Resource } from "alchemy/Resource";
5 import { createInternalTags, diffTags, hasTags, tagRecord } from "alchemy/Tags";
6 import { toWireSeconds } from "alchemy/Util/Duration";
7 import * as Data from "effect/Data";
8 import type * as Duration from "effect/Duration";
9 import * as Effect from "effect/Effect";
10 import * as Option from "effect/Option";
11 import * as Schedule from "effect/Schedule";
12 import * as Stream from "effect/Stream";
13 import { AWSEnvironment } from "../Environment.ts";
14 import { plainJson } from "../internal/Observe.ts";
15 import type { Providers } from "../Providers.ts";
16
17 export type StartingPosition = "TRIM_HORIZON" | "LATEST" | "AT_TIMESTAMP";
18
19 /** Internal retry signal: the mapping has not reached its desired state yet. */
20 class MappingNotSettled extends Data.TaggedError("MappingNotSettled")<{
21 readonly state: string | undefined;
22 }> {}
23
24 /**
25 * An SQS queue's visibility timeout is shorter than the function's Lambda
26 * timeout, which AWS refuses for an SQS event source. Lambda's timeout is the
27 * function's `timeout` plus its `timeoutMargin` (1 second by default).
28 */
29 export class QueueVisibilityTimeoutBelowFunctionTimeout extends Data.TaggedError(
30 "QueueVisibilityTimeoutBelowFunctionTimeout",
31 )<{
32 readonly functionName: string;
33 readonly eventSourceArn: string;
34 readonly message: string;
35 }> {}
36
37 /** AWS's rejection, restated with the setting to change. */
38 const visibilityTimeoutError = (
39 functionName: string,
40 eventSourceArn: string,
41 error: lambda.QueueVisibilityTimeoutTooShort,
42 ) =>
43 new QueueVisibilityTimeoutBelowFunctionTimeout({
44 functionName,
45 eventSourceArn,
46 message:
47 `${error.message ?? "Queue visibility timeout is less than Function timeout"}. ` +
48 "Lambda runs the function for its `timeout` plus `timeoutMargin` (1 second by " +
49 "default), so set the queue's `visibilityTimeout` to at least that sum (AWS " +
50 "recommends six times the function timeout), or lower the function's `timeout`.",
51 });
52
53 export type FunctionResponseType = "ReportBatchItemFailures";
54
55 export interface EventSourceMappingProps {
56 /**
57 * The name or ARN of the Lambda function to invoke.
58 */
59 functionName: string;
60 /**
61 * The ARN of the event source (SQS queue, Kinesis stream, DynamoDB stream, etc.).
62 */
63 eventSourceArn: string;
64 /**
65 * The maximum number of records in each batch that Lambda pulls and sends to the function.
66 *
67 * - SQS: default 10, max 10,000 (FIFO max 10)
68 * - Kinesis: default 100, max 10,000
69 * - DynamoDB Streams: default 100, max 10,000
70 */
71 batchSize?: number;
72 /**
73 * The maximum amount of time that Lambda spends gathering records before
74 * invoking the function (e.g. `"5 seconds"`). Rounded to whole seconds on
75 * the wire.
76 * @default 0
77 */
78 maximumBatchingWindow?: Duration.Input;
79 /**
80 * Whether the event source mapping is active.
81 * @default true
82 */
83 enabled?: boolean;
84 /**
85 * The position in a stream from which to start reading. Required for Kinesis and DynamoDB Streams.
86 *
87 * - `LATEST` - Read only new records.
88 * - `TRIM_HORIZON` - Process all available records.
89 * - `AT_TIMESTAMP` - Start reading from a specific time.
90 */
91 startingPosition?: StartingPosition;
92 /**
93 * The timestamp to start reading from when `startingPosition` is `AT_TIMESTAMP`.
94 */
95 startingPositionTimestamp?: Date;
96 /**
97 * (Kinesis and DynamoDB Streams) The number of batches to process from each shard concurrently.
98 * @default 1
99 */
100 parallelizationFactor?: number;
101 /**
102 * (Kinesis and DynamoDB Streams) Split the batch in two and retry if the function returns an error.
103 * @default false
104 */
105 bisectBatchOnFunctionError?: boolean;
106 /**
107 * (Kinesis and DynamoDB Streams) Discard records older than the specified
108 * age (e.g. `"1 hour"`). Rounded to whole seconds on the wire.
109 * @default infinite (omit to never expire records)
110 */
111 maximumRecordAge?: Duration.Input;
112 /**
113 * (Kinesis and DynamoDB Streams) Discard records after the specified number of retries.
114 * @default -1 (infinite)
115 */
116 maximumRetryAttempts?: number;
117 /**
118 * (Kinesis and DynamoDB Streams) The duration of a processing window for
119 * tumbling windows (e.g. `"30 seconds"`). Rounded to whole seconds on the
120 * wire.
121 */
122 tumblingWindow?: Duration.Input;
123 /**
124 * A list of current response type enums applied to the event source mapping.
125 * Defaults to `["ReportBatchItemFailures"]` for SQS, Kinesis and DynamoDB
126 * Streams sources, and for other sources (e.g. Kafka/MSK) only when
127 * `provisionedPollerConfig.MinimumPollers` is set — they reject it otherwise.
128 * @default ["ReportBatchItemFailures"] (SQS, Kinesis, DynamoDB Streams)
129 */
130 functionResponseTypes?: FunctionResponseType[];
131 /**
132 * (SQS) Scaling configuration for the event source.
133 */
134 scalingConfig?: lambda.ScalingConfig;
135 /**
136 * (Kinesis and DynamoDB Streams) A destination for records that failed processing.
137 */
138 destinationConfig?: lambda.DestinationConfig;
139 /**
140 * Filter criteria to control which records are sent to the function.
141 */
142 filterCriteria?: lambda.FilterCriteria;
143 /**
144 * The ARN of an AWS KMS key to encrypt the filter criteria.
145 */
146 kmsKeyArn?: string;
147 /**
148 * Metrics configuration for the event source mapping. Defaulted only for
149 * SQS, Kinesis and DynamoDB Streams sources, or other sources (Kafka/MSK)
150 * with `provisionedPollerConfig.MinimumPollers` set.
151 * @default { Metrics: ["EventCount"] } (where supported)
152 */
153 metricsConfig?: lambda.EventSourceMappingMetricsConfig;
154 /**
155 * (SQS, MSK, self-managed Kafka) Provisioned poller configuration.
156 */
157 provisionedPollerConfig?: lambda.ProvisionedPollerConfig;
158 /**
159 * (Amazon MSK) Configuration for an Amazon Managed Streaming for Apache Kafka event source.
160 */
161 amazonManagedKafkaEventSourceConfig?: lambda.AmazonManagedKafkaEventSourceConfig;
162 /**
163 * (Self-managed Kafka) Configuration for a self-managed Apache Kafka event source.
164 */
165 selfManagedKafkaEventSourceConfig?: lambda.SelfManagedKafkaEventSourceConfig;
166 /**
167 * (Self-managed Kafka) The self-managed Apache Kafka cluster for the event source.
168 */
169 selfManagedEventSource?: lambda.SelfManagedEventSource;
170 /**
171 * (Amazon MQ, MSK, self-managed Kafka) Source access configuration for VPC, authentication, etc.
172 */
173 sourceAccessConfigurations?: lambda.SourceAccessConfiguration[];
174 /**
175 * (Amazon MSK, self-managed Kafka) The Kafka topic name(s).
176 */
177 topics?: string[];
178 /**
179 * (Amazon MQ) The name of the Amazon MQ broker destination queue to consume.
180 */
181 queues?: string[];
182 /**
183 * (Amazon DocumentDB) Configuration for a DocumentDB event source.
184 */
185 documentDBEventSourceConfig?: lambda.DocumentDBEventSourceConfig;
186 /**
187 * (Amazon MSK and self-managed Apache Kafka) The logging configuration for the event source.
188 */
189 loggingConfig?: lambda.LoggingConfig;
190 /**
191 * Tags to associate with the event source mapping.
192 */
193 tags?: Record<string, string>;
194 }
195
196 export interface EventSourceMapping extends Resource<
197 "AWS.Lambda.EventSourceMapping",
198 EventSourceMappingProps,
199 {
200 /**
201 * The UUID of the event source mapping.
202 */
203 uuid: string;
204 /**
205 * The ARN of the event source mapping.
206 */
207 eventSourceMappingArn: string;
208 /**
209 * The ARN of the Lambda function.
210 */
211 functionArn: string;
212 /**
213 * The current state of the event source mapping.
214 */
215 state: string;
216 /**
217 * Enabled state, batching, retry, failure-destination, filter, scaling
218 * and metrics settings (those the props declare, plus the ones Alchemy
219 * defaults), and the tags, as observed. Lets `alchemy drift` detect a
220 * consumer disabled or reconfigured out of band.
221 */
222 configuration?: Record<string, unknown>;
223 },
224 never,
225 Providers
226 > {}
227
228 /**
229 * Connects an event source — an SQS queue, Kinesis stream, DynamoDB stream,
230 * Amazon MQ broker, or Kafka topic — to a Lambda function so that records are
231 * polled from the source and delivered to the function in batches.
232 *
233 * Most stacks create mappings indirectly through the higher-level event-source
234 * helpers (`SQS.consumeQueueMessages(queue, ...)`,
235 * `Kinesis.consumeStreamRecords(stream, ...)`, `DynamoDB.consumeTableChanges(table, ...)`),
236 * which wire up the matching IAM permissions automatically. Use this resource
237 * directly when you need full control over batching, starting position, retry
238 * behavior, or filtering.
239 *
240 * ### Polling an SQS Queue
241 * SQS is the simplest source: no `startingPosition` is needed because there is
242 * no stream cursor. Lambda long-polls the queue and invokes the function with
243 * up to `batchSize` messages, and `functionName` plus `eventSourceArn` are the
244 * only required props.
245 *
246 * **Example:** Subscribe a function to a queue
247 * ```typescript
248 * import * as AWS from "@alchemy.run/aws";
249 *
250 * const queue = yield* AWS.SQS.Queue("Jobs", {});
251 * const worker = yield* AWS.Lambda.Function("Worker", {
252 * main: "./src/worker.ts",
253 * });
254 *
255 * const mapping = yield* AWS.Lambda.EventSourceMapping("JobsToWorker", {
256 * functionName: worker.functionName,
257 * eventSourceArn: queue.queueArn,
258 * batchSize: 10,
259 * maximumBatchingWindow: "5 seconds",
260 * });
261 * ```
262 *
263 * This delivers up to 10 messages per invocation, waiting up to 5 seconds to
264 * fill a batch before invoking. Increasing the batching window trades latency
265 * for fewer, larger invocations — useful for amortizing cold starts or
266 * downstream write costs on bursty queues.
267 *
268 * ### Streaming from Kinesis & DynamoDB
269 * Stream sources (Kinesis and DynamoDB Streams) deliver records in shard order
270 * and therefore require a `startingPosition` that tells Lambda where in the
271 * shard to begin reading. These sources also unlock the stream-only tuning
272 * knobs covered in the next sections.
273 *
274 * **Example:** Process a Kinesis stream from the latest records
275 * ```typescript
276 * import * as AWS from "@alchemy.run/aws";
277 *
278 * const stream = yield* AWS.Kinesis.Stream("Events", {});
279 * const consumer = yield* AWS.Lambda.Function("Consumer", {
280 * main: "./src/consumer.ts",
281 * });
282 *
283 * const mapping = yield* AWS.Lambda.EventSourceMapping("EventsToConsumer", {
284 * functionName: consumer.functionName,
285 * eventSourceArn: stream.streamArn,
286 * startingPosition: "LATEST",
287 * batchSize: 100,
288 * });
289 * ```
290 *
291 * `startingPosition: "LATEST"` skips any backlog and only processes records
292 * written after the mapping is created — the right choice for live event
293 * pipelines where replaying history would be wasteful or incorrect.
294 *
295 * **Example:** Replay a DynamoDB stream from the beginning
296 * ```typescript
297 * import * as AWS from "@alchemy.run/aws";
298 *
299 * const table = yield* AWS.DynamoDB.Table("Orders", {
300 * partitionKey: { name: "id", type: "S" },
301 * });
302 * const handler = yield* AWS.Lambda.Function("OrdersStream", {
303 * main: "./src/orders.ts",
304 * });
305 *
306 * const mapping = yield* AWS.Lambda.EventSourceMapping("OrdersToHandler", {
307 * functionName: handler.functionName,
308 * eventSourceArn: table.latestStreamArn!,
309 * startingPosition: "TRIM_HORIZON",
310 * });
311 * ```
312 *
313 * `TRIM_HORIZON` starts at the oldest record still in the stream, so the
314 * function processes the full available history before catching up to new
315 * writes — use it when every change matters (e.g. building a projection).
316 *
317 * **Example:** Start reading from a specific timestamp
318 * ```typescript
319 * const mapping = yield* AWS.Lambda.EventSourceMapping("EventsFromTime", {
320 * functionName: consumer.functionName,
321 * eventSourceArn: stream.streamArn,
322 * startingPosition: "AT_TIMESTAMP",
323 * startingPositionTimestamp: new Date("2026-01-01T00:00:00Z"),
324 * });
325 * ```
326 *
327 * `AT_TIMESTAMP` (Kinesis only) begins at the first record on or after
328 * `startingPositionTimestamp`, letting you reprocess a known time range without
329 * replaying the entire stream.
330 *
331 * ### Tuning Throughput
332 * For stream sources, throughput is governed by how records are batched and how
333 * many batches run in parallel per shard. These knobs let you balance
334 * end-to-end latency against invocation count and downstream load.
335 *
336 * **Example:** Increase parallelism and use tumbling windows
337 * ```typescript
338 * const mapping = yield* AWS.Lambda.EventSourceMapping("HighThroughput", {
339 * functionName: consumer.functionName,
340 * eventSourceArn: stream.streamArn,
341 * startingPosition: "LATEST",
342 * batchSize: 500,
343 * maximumBatchingWindow: "10 seconds",
344 * parallelizationFactor: 5,
345 * tumblingWindow: "30 seconds",
346 * });
347 * ```
348 *
349 * `parallelizationFactor` runs up to 5 concurrent batches per shard (records
350 * with the same partition key still stay in order), while
351 * `tumblingWindow` aggregates results across sequential batches for
352 * windowed stream processing. Raising `batchSize`/`maximumBatchingWindow`
353 * favors fewer, larger invocations.
354 *
355 * ### Error Handling & Retries
356 * For stream sources a single poison-pill record can block a shard forever.
357 * These props bound retries, split failing batches, expire stale records, and
358 * route failures elsewhere instead of stalling the stream.
359 *
360 * **Example:** Bisect on error, cap retries, and expire old records
361 * ```typescript
362 * const dlq = yield* AWS.SQS.Queue("StreamFailures", {});
363 *
364 * const mapping = yield* AWS.Lambda.EventSourceMapping("ResilientStream", {
365 * functionName: consumer.functionName,
366 * eventSourceArn: stream.streamArn,
367 * startingPosition: "LATEST",
368 * bisectBatchOnFunctionError: true,
369 * maximumRetryAttempts: 3,
370 * maximumRecordAge: "1 hour",
371 * destinationConfig: {
372 * OnFailure: { Destination: dlq.queueArn },
373 * },
374 * });
375 * ```
376 *
377 * On a function error, `bisectBatchOnFunctionError` splits the batch in two and
378 * retries each half to isolate the bad record; after `maximumRetryAttempts` (or
379 * once a record is older than `maximumRecordAge`) the record is
380 * discarded and its metadata is sent to the `destinationConfig.OnFailure`
381 * target so it is never silently lost.
382 *
383 * **Example:** Report partial batch failures
384 * ```typescript
385 * const mapping = yield* AWS.Lambda.EventSourceMapping("PartialFailures", {
386 * functionName: handler.functionName,
387 * eventSourceArn: table.latestStreamArn!,
388 * startingPosition: "TRIM_HORIZON",
389 * functionResponseTypes: ["ReportBatchItemFailures"],
390 * });
391 * ```
392 *
393 * `functionResponseTypes: ["ReportBatchItemFailures"]` lets the function return
394 * only the IDs of records it failed to process, so Lambda retries just those
395 * instead of the whole batch — avoiding redundant reprocessing of records that
396 * already succeeded.
397 *
398 * ### Filtering Records
399 * Attach `filterCriteria` so the function is only invoked for records matching
400 * an event pattern. Filtering happens before invocation, so it cuts both cost
401 * and unnecessary cold starts. Encrypt the patterns with `kmsKeyArn` when they
402 * contain sensitive values.
403 *
404 * **Example:** Only deliver records where `type` is `"order"`
405 * ```typescript
406 * const mapping = yield* AWS.Lambda.EventSourceMapping("OrdersOnly", {
407 * functionName: worker.functionName,
408 * eventSourceArn: queue.queueArn,
409 * filterCriteria: {
410 * Filters: [{ Pattern: JSON.stringify({ body: { type: ["order"] } }) }],
411 * },
412 * kmsKeyArn:
413 * "arn:aws:kms:us-east-1:111122223333:key/abcd1234-...",
414 * });
415 * ```
416 *
417 * Each `Pattern` is a JSON event-pattern string; messages that don't match are
418 * dropped without invoking the function. The optional `kmsKeyArn` encrypts the
419 * stored filter criteria with your own KMS key instead of an AWS-managed one.
420 *
421 * ### Enabling & Disabling
422 * The `enabled` flag controls whether Lambda actively polls the source without
423 * deleting the mapping, so you can pause and resume delivery in place.
424 *
425 * **Example:** Create a paused mapping
426 * ```typescript
427 * const mapping = yield* AWS.Lambda.EventSourceMapping("PausedConsumer", {
428 * functionName: consumer.functionName,
429 * eventSourceArn: stream.streamArn,
430 * startingPosition: "LATEST",
431 * enabled: false,
432 * });
433 * ```
434 *
435 * With `enabled: false` the mapping exists but pulls no records — flip it back
436 * to `true` to resume. This is handy for maintenance windows or for staging a
437 * consumer before turning on traffic.
438 *
439 * ### Scaling & Provisioned Pollers
440 * Cap concurrency for SQS sources with `scalingConfig`, or reserve dedicated
441 * polling capacity (for Kafka/MSK and SQS) with `provisionedPollerConfig` to
442 * keep latency predictable under load.
443 *
444 * **Example:** Limit SQS concurrency and provision pollers
445 * ```typescript
446 * const mapping = yield* AWS.Lambda.EventSourceMapping("BoundedConsumer", {
447 * functionName: worker.functionName,
448 * eventSourceArn: queue.queueArn,
449 * scalingConfig: { MaximumConcurrency: 10 },
450 * provisionedPollerConfig: {
451 * MinimumPollers: 1,
452 * MaximumPollers: 20,
453 * },
454 * });
455 * ```
456 *
457 * `scalingConfig.MaximumConcurrency` caps how many function instances Lambda
458 * runs for this queue (protecting downstream systems), while
459 * `provisionedPollerConfig` keeps a pool of dedicated event pollers warm so
460 * throughput doesn't lag behind sudden spikes.
461 *
462 * ### Kafka, MQ & DocumentDB Sources
463 * Beyond AWS-native streams, an event source mapping can poll Amazon MSK,
464 * self-managed Apache Kafka, Amazon MQ brokers, and Amazon DocumentDB change
465 * streams. These sources use `topics`/`queues` to select what to consume,
466 * `sourceAccessConfigurations` for VPC and authentication wiring, and
467 * source-specific config props.
468 *
469 * **Example:** Consume a self-managed Kafka topic
470 * ```typescript
471 * const mapping = yield* AWS.Lambda.EventSourceMapping("KafkaConsumer", {
472 * functionName: consumer.functionName,
473 * eventSourceArn: stream.streamArn,
474 * topics: ["orders"],
475 * selfManagedEventSource: {
476 * Endpoints: { KAFKA_BOOTSTRAP_SERVERS: ["broker1:9092", "broker2:9092"] },
477 * },
478 * selfManagedKafkaEventSourceConfig: { ConsumerGroupId: "orders-consumer" },
479 * sourceAccessConfigurations: [
480 * { Type: "SASL_SCRAM_512_AUTH", URI: "arn:aws:secretsmanager:...:secret:kafka" },
481 * ],
482 * loggingConfig: { LogFormat: "JSON" },
483 * });
484 * ```
485 *
486 * `topics` names the Kafka topic(s) to read; `selfManagedEventSource.Endpoints`
487 * points at the brokers; `sourceAccessConfigurations` supplies the SASL/VPC
488 * credentials; and `selfManagedKafkaEventSourceConfig.ConsumerGroupId` pins the
489 * consumer group. For Amazon MSK use `amazonManagedKafkaEventSourceConfig`
490 * instead.
491 *
492 * **Example:** Consume an Amazon MQ queue and a DocumentDB change stream
493 * ```typescript
494 * const mqMapping = yield* AWS.Lambda.EventSourceMapping("MqConsumer", {
495 * functionName: worker.functionName,
496 * eventSourceArn: stream.streamArn,
497 * queues: ["orders-queue"],
498 * sourceAccessConfigurations: [
499 * { Type: "BASIC_AUTH", URI: "arn:aws:secretsmanager:...:secret:mq" },
500 * ],
501 * });
502 *
503 * const docDbMapping = yield* AWS.Lambda.EventSourceMapping("DocDbConsumer", {
504 * functionName: worker.functionName,
505 * eventSourceArn: stream.streamArn,
506 * documentDBEventSourceConfig: {
507 * DatabaseName: "shop",
508 * CollectionName: "orders",
509 * FullDocument: "UpdateLookup",
510 * },
511 * });
512 * ```
513 *
514 * For Amazon MQ, `queues` names the broker destination to consume and
515 * `sourceAccessConfigurations` carries the broker credentials; for DocumentDB,
516 * `documentDBEventSourceConfig` selects the database/collection and whether full
517 * documents are delivered on updates.
518 *
519 * ### Metrics & Tags
520 * Opt into per-mapping CloudWatch metrics with `metricsConfig` and brand the
521 * mapping with your own `tags` (Alchemy also applies its internal ownership
522 * tags automatically).
523 *
524 * **Example:** Enable event metrics and add tags
525 * ```typescript
526 * const mapping = yield* AWS.Lambda.EventSourceMapping("ObservedConsumer", {
527 * functionName: worker.functionName,
528 * eventSourceArn: queue.queueArn,
529 * metricsConfig: { Metrics: ["EventCount"] },
530 * tags: { team: "payments", env: "prod" },
531 * });
532 * ```
533 *
534 * `metricsConfig.Metrics` turns on the named CloudWatch metrics (e.g.
535 * `EventCount`) for this mapping, and `tags` attaches arbitrary key/value pairs
536 * for cost allocation and discovery.
537 *
538 * @resource
539 */
540 export const EventSourceMapping = Resource<EventSourceMapping>("AWS.Lambda.EventSourceMapping");
541
542 export const EventSourceMappingProvider = () =>
543 Provider.effect(
544 EventSourceMapping,
545 Effect.gen(function* () {
546 const createEventSourceMappingTags = Effect.fn(function* (id: string) {
547 const internalTags = yield* createInternalTags(id);
548 return {
549 ...internalTags,
550 "alchemy::id": sanitizeAwsTagValue(internalTags["alchemy::id"]),
551 };
552 });
553
554 // ReportBatchItemFailures and MetricsConfig are only accepted for
555 // SQS / Kinesis / DynamoDB Streams, or for other sources (Kafka/MSK)
556 // in provisioned-poller mode — MSK rejects them otherwise ("... is only
557 // available for provisioned mode"). Only default them where valid.
558 const supportsDefaults = (props: EventSourceMappingProps): boolean =>
559 /^arn:[^:]+:(sqs|kinesis|dynamodb):/.test(String(props.eventSourceArn)) ||
560 props.provisionedPollerConfig?.MinimumPollers !== undefined;
561 const defaultFunctionResponseTypes = (
562 props: EventSourceMappingProps,
563 ): FunctionResponseType[] | undefined =>
564 props.functionResponseTypes ??
565 (supportsDefaults(props) ? ["ReportBatchItemFailures"] : undefined);
566 const defaultMetricsConfig = (
567 props: EventSourceMappingProps,
568 ): lambda.EventSourceMappingMetricsConfig | undefined =>
569 props.metricsConfig ?? (supportsDefaults(props) ? { Metrics: ["EventCount"] } : undefined);
570
571 const toCreateRequest = (
572 props: EventSourceMappingProps,
573 tags: Record<string, string>,
574 ): lambda.CreateEventSourceMappingRequest => ({
575 FunctionName: props.functionName as string,
576 EventSourceArn: props.eventSourceArn as string,
577 Enabled: props.enabled ?? true,
578 BatchSize: props.batchSize,
579 MaximumBatchingWindowInSeconds: toWireSeconds(props.maximumBatchingWindow),
580 StartingPosition: props.startingPosition,
581 StartingPositionTimestamp: props.startingPositionTimestamp,
582 ParallelizationFactor: props.parallelizationFactor,
583 BisectBatchOnFunctionError: props.bisectBatchOnFunctionError,
584 MaximumRecordAgeInSeconds: toWireSeconds(props.maximumRecordAge),
585 MaximumRetryAttempts: props.maximumRetryAttempts,
586 TumblingWindowInSeconds: toWireSeconds(props.tumblingWindow),
587 FunctionResponseTypes: defaultFunctionResponseTypes(props),
588 ScalingConfig: props.scalingConfig,
589 DestinationConfig: props.destinationConfig,
590 FilterCriteria: props.filterCriteria,
591 KMSKeyArn: props.kmsKeyArn,
592 MetricsConfig: defaultMetricsConfig(props),
593 ProvisionedPollerConfig: props.provisionedPollerConfig,
594 AmazonManagedKafkaEventSourceConfig: props.amazonManagedKafkaEventSourceConfig,
595 SelfManagedKafkaEventSourceConfig: props.selfManagedKafkaEventSourceConfig,
596 SelfManagedEventSource: props.selfManagedEventSource,
597 SourceAccessConfigurations: props.sourceAccessConfigurations,
598 Topics: props.topics,
599 Queues: props.queues,
600 DocumentDBEventSourceConfig: props.documentDBEventSourceConfig,
601 LoggingConfig: props.loggingConfig,
602 Tags: tags,
603 });
604
605 const withoutConsumerGroupId = <
606 C extends { ConsumerGroupId?: string; SchemaRegistryConfig?: unknown },
607 >(
608 config: C | undefined,
609 ): C | undefined =>
610 config?.SchemaRegistryConfig === undefined
611 ? undefined
612 : ({ ...config, ConsumerGroupId: undefined } as C);
613
614 const toUpdateRequest = (
615 uuid: string,
616 props: EventSourceMappingProps,
617 ): lambda.UpdateEventSourceMappingRequest => ({
618 UUID: uuid,
619 FunctionName: props.functionName as string,
620 Enabled: props.enabled ?? true,
621 BatchSize: props.batchSize,
622 MaximumBatchingWindowInSeconds: toWireSeconds(props.maximumBatchingWindow),
623 BisectBatchOnFunctionError: props.bisectBatchOnFunctionError,
624 MaximumRecordAgeInSeconds: toWireSeconds(props.maximumRecordAge),
625 MaximumRetryAttempts: props.maximumRetryAttempts,
626 TumblingWindowInSeconds: toWireSeconds(props.tumblingWindow),
627 FunctionResponseTypes: defaultFunctionResponseTypes(props),
628 ScalingConfig: props.scalingConfig,
629 DestinationConfig: props.destinationConfig,
630 FilterCriteria: props.filterCriteria,
631 KMSKeyArn: props.kmsKeyArn,
632 MetricsConfig: defaultMetricsConfig(props),
633 ProvisionedPollerConfig: props.provisionedPollerConfig,
634 // ConsumerGroupId is create-only — UpdateEventSourceMapping rejects it
635 // ("Unsupported '...consumerGroupId' parameter"); changing it replaces.
636 AmazonManagedKafkaEventSourceConfig: withoutConsumerGroupId(
637 props.amazonManagedKafkaEventSourceConfig,
638 ),
639 SelfManagedKafkaEventSourceConfig: withoutConsumerGroupId(
640 props.selfManagedKafkaEventSourceConfig,
641 ),
642 SourceAccessConfigurations: props.sourceAccessConfigurations,
643 DocumentDBEventSourceConfig: props.documentDBEventSourceConfig,
644 LoggingConfig: props.loggingConfig,
645 });
646
647 const configToAttrs = (
648 config: lambda.EventSourceMappingConfiguration,
649 ): EventSourceMapping["Attributes"] => ({
650 uuid: config.UUID!,
651 eventSourceMappingArn: config.EventSourceMappingArn!,
652 functionArn: config.FunctionArn!,
653 state: config.State!,
654 });
655
656 /**
657 * The settings reconcile converges, as observed. Update leaves an
658 * omitted field unchanged, so a field is observed only when the props
659 * declare it (or Alchemy defaults it). `read` and `reconcile` share it
660 * so a converged mapping reads unchanged.
661 */
662 const observeMappingConfiguration = (
663 config: lambda.EventSourceMappingConfiguration,
664 props: EventSourceMappingProps | undefined,
665 tags: Record<string, string>,
666 ) => {
667 const declared = <V>(key: keyof EventSourceMappingProps, value: V) =>
668 props?.[key] === undefined ? undefined : value;
669 return plainJson({
670 // Transitional states (Creating, Updating) count as enabled.
671 enabled: config.State !== "Disabled" && config.State !== "Disabling",
672 batchSize: declared("batchSize", config.BatchSize),
673 maximumBatchingWindowInSeconds: declared(
674 "maximumBatchingWindow",
675 config.MaximumBatchingWindowInSeconds,
676 ),
677 bisectBatchOnFunctionError: declared(
678 "bisectBatchOnFunctionError",
679 config.BisectBatchOnFunctionError,
680 ),
681 maximumRecordAgeInSeconds: declared("maximumRecordAge", config.MaximumRecordAgeInSeconds),
682 maximumRetryAttempts: declared("maximumRetryAttempts", config.MaximumRetryAttempts),
683 tumblingWindowInSeconds: declared("tumblingWindow", config.TumblingWindowInSeconds),
684 functionResponseTypes:
685 props === undefined || defaultFunctionResponseTypes(props) === undefined
686 ? undefined
687 : [...(config.FunctionResponseTypes ?? [])].sort(),
688 scalingConfig: declared("scalingConfig", config.ScalingConfig),
689 destinationConfig: declared("destinationConfig", config.DestinationConfig),
690 filterCriteria: declared("filterCriteria", config.FilterCriteria),
691 kmsKeyArn: declared("kmsKeyArn", config.KMSKeyArn),
692 metricsConfig:
693 props === undefined || defaultMetricsConfig(props) === undefined
694 ? undefined
695 : config.MetricsConfig,
696 provisionedPollerConfig: declared(
697 "provisionedPollerConfig",
698 config.ProvisionedPollerConfig,
699 ),
700 loggingConfig: declared("loggingConfig", config.LoggingConfig),
701 tags,
702 });
703 };
704
705 const readMappingTags = (mappingArn: string) =>
706 lambda.listTags({ Resource: mappingArn }).pipe(
707 retryTransient,
708 Effect.map((r) => tagRecord(r.Tags)),
709 );
710
711 const deleteMapping = (uuid: string) =>
712 lambda.deleteEventSourceMapping({ UUID: uuid }).pipe(
713 Effect.retry({
714 while: (e) =>
715 e._tag === "ResourceInUseException" || e._tag === "ResourceConflictException",
716 schedule: Schedule.max([Schedule.exponential(100), Schedule.recurs(20)]),
717 }),
718 Effect.catchTag("ResourceNotFoundException", () => Effect.void),
719 );
720
721 return {
722 stables: ["uuid", "eventSourceMappingArn"],
723 read: Effect.fn(function* ({ id, olds, output }) {
724 const { accountId, region } = yield* AWSEnvironment.current;
725 let config: lambda.EventSourceMappingConfiguration | undefined;
726 if (output?.uuid) {
727 config = yield* lambda
728 .getEventSourceMapping({ UUID: output.uuid })
729 .pipe(Effect.catchTag("ResourceNotFoundException", () => Effect.undefined));
730 } else if (olds?.functionName && olds.eventSourceArn) {
731 // No persisted UUID (interrupted create): find this stack's
732 // mapping for the function and source by its ownership tags.
733 const expectedInternalTags = yield* createEventSourceMappingTags(id);
734 config = yield* lambda.listEventSourceMappings
735 .pages({ FunctionName: olds.functionName })
736 .pipe(
737 Stream.flatMap((page) => Stream.fromIterable(page.EventSourceMappings ?? [])),
738 Stream.filter((m) => m.EventSourceArn === olds.eventSourceArn && !!m.UUID),
739 Stream.filterEffect((m) =>
740 readMappingTags(
741 `arn:aws:lambda:${region}:${accountId}:event-source-mapping:${m.UUID}`,
742 ).pipe(Effect.map((tags) => hasTags(expectedInternalTags, tags))),
743 ),
744 Stream.runHead,
745 Effect.map(Option.getOrUndefined),
746 Effect.catchTag("ResourceNotFoundException", () => Effect.undefined),
747 );
748 }
749 if (!config?.UUID || config.State === "Deleting") return undefined;
750 const tags = yield* readMappingTags(
751 `arn:aws:lambda:${region}:${accountId}:event-source-mapping:${config.UUID}`,
752 ).pipe(
753 Effect.catchTag("ResourceNotFoundException", () =>
754 Effect.succeed({} as Record<string, string>),
755 ),
756 );
757 return {
758 ...configToAttrs(config),
759 configuration: observeMappingConfiguration(config, olds, tags),
760 };
761 }),
762 diff: Effect.fn(function* ({ news, olds }) {
763 // `functionName` is required, so this narrows `news` to the props object.
764 if (!("functionName" in news)) return;
765 const sourceArn = news.eventSourceArn;
766 if (isResolved(sourceArn) && sourceArn !== olds.eventSourceArn) {
767 return { action: "replace" } as const;
768 }
769 // Lambda allows one mapping per function and source, so a replacement
770 // on the same source must delete the old mapping first.
771 const replace = { action: "replace", deleteFirst: true } as const;
772 if (
773 isResolved(news.startingPosition) &&
774 news.startingPosition !== olds.startingPosition
775 ) {
776 return replace;
777 }
778 if (
779 isResolved(news.startingPositionTimestamp) &&
780 news.startingPositionTimestamp?.getTime() !== olds.startingPositionTimestamp?.getTime()
781 ) {
782 return replace;
783 }
784 if (
785 isResolved(news.selfManagedEventSource) &&
786 !deepEqual(news.selfManagedEventSource, olds.selfManagedEventSource)
787 ) {
788 return replace;
789 }
790 if (
791 (isResolved(news.amazonManagedKafkaEventSourceConfig) &&
792 news.amazonManagedKafkaEventSourceConfig?.ConsumerGroupId !==
793 olds.amazonManagedKafkaEventSourceConfig?.ConsumerGroupId) ||
794 (isResolved(news.selfManagedKafkaEventSourceConfig) &&
795 news.selfManagedKafkaEventSourceConfig?.ConsumerGroupId !==
796 olds.selfManagedKafkaEventSourceConfig?.ConsumerGroupId)
797 ) {
798 return replace;
799 }
800 // An unresolved source ARN may or may not change: a replaced queue
801 // gets a new ARN, but a Table updated in place keeps its stream ARN
802 // while exposing it as unstable. Update in place and let `reconcile`
803 // move the mapping if the source really changed, so the mapping's
804 // identity is not stable for downstream consumers.
805 if (!isResolved(sourceArn)) {
806 return { action: "update", stables: [] } as const;
807 }
808 }),
809 reconcile: Effect.fn(function* ({ id, news, output, session }) {
810 const { accountId, region } = yield* AWSEnvironment.current;
811 const expectedInternalTags = yield* createEventSourceMappingTags(id);
812 const desiredTags = { ...expectedInternalTags, ...news.tags };
813
814 const functionName = news.functionName as string;
815 const eventSourceArn = news.eventSourceArn as string;
816
817 // Observe — find the existing mapping. UUIDs are server-assigned
818 // so we either trust `output.uuid` (fast path) or scan
819 // `listEventSourceMappings` and confirm ownership via tags
820 // (recovery from a state-persistence failure or adoption).
821 let config: lambda.EventSourceMappingConfiguration | undefined;
822 if (output?.uuid) {
823 config = yield* lambda
824 .getEventSourceMapping({ UUID: output.uuid })
825 .pipe(Effect.catchTag("ResourceNotFoundException", () => Effect.undefined));
826 }
827 // `updateEventSourceMapping` cannot change the source, so a mapping
828 // that reads another source (its source was replaced) is recreated
829 // for this source and the stale one deleted.
830 let stale: string | undefined;
831 if (config?.UUID && config.EventSourceArn !== eventSourceArn) {
832 stale = config.UUID;
833 config = undefined;
834 }
835 if (!config?.UUID) {
836 config = yield* lambda.listEventSourceMappings
837 .pages({ FunctionName: functionName })
838 .pipe(
839 Stream.mapEffect(
840 Effect.fn(function* (page) {
841 const mapping = page.EventSourceMappings?.find(
842 (m) => m.EventSourceArn === eventSourceArn,
843 );
844 if (mapping?.UUID) {
845 const { Tags } = yield* lambda
846 .listTags({
847 Resource: `arn:aws:lambda:${region}:${accountId}:event-source-mapping:${mapping.UUID}`,
848 })
849 .pipe(retryTransient);
850 if (hasTags(expectedInternalTags, Tags)) {
851 return mapping;
852 }
853 }
854 }),
855 ),
856 Stream.filter((item) => item !== undefined),
857 Stream.runHead,
858 Effect.map(Option.getOrUndefined),
859 );
860 }
861
862 // Ensure — create if no live mapping exists. Tolerate
863 // `ResourceConflictException` (peer reconciler raced ahead) by
864 // re-scanning to find the mapping by tag ownership.
865 if (!config?.UUID) {
866 config = yield* lambda
867 .createEventSourceMapping(toCreateRequest(news, desiredTags))
868 .pipe(
869 Effect.catchTags({
870 ResourceConflictException: () =>
871 lambda.listEventSourceMappings.pages({ FunctionName: functionName }).pipe(
872 Stream.mapEffect(
873 Effect.fn(function* (page) {
874 const mapping = page.EventSourceMappings?.find(
875 (m) => m.EventSourceArn === eventSourceArn,
876 );
877 if (mapping?.UUID) {
878 const { Tags } = yield* lambda
879 .listTags({
880 Resource: `arn:aws:lambda:${region}:${accountId}:event-source-mapping:${mapping.UUID}`,
881 })
882 .pipe(retryTransient);
883 if (hasTags(expectedInternalTags, Tags)) {
884 return mapping;
885 }
886 }
887 }),
888 ),
889 Stream.filter((item) => item !== undefined),
890 Stream.runHead,
891 Effect.map(Option.getOrUndefined),
892 Effect.flatMap((mapping) =>
893 mapping
894 ? Effect.succeed(mapping)
895 : Effect.die(
896 new Error(
897 `EventSourceMapping(${id}) not found on function ${functionName}`,
898 ),
899 ),
900 ),
901 ),
902 }),
903 retryPermissionsPropagation,
904 retryTransient,
905 Effect.catchTag("QueueVisibilityTimeoutTooShort", (error) =>
906 Effect.fail(visibilityTimeoutError(functionName, eventSourceArn, error)),
907 ),
908 );
909 }
910
911 if (!config?.UUID) {
912 return yield* Effect.die(
913 new Error(`EventSourceMapping(${id}) could not be reconciled`),
914 );
915 }
916
917 const uuid = config.UUID;
918 if (stale !== undefined && stale !== uuid) {
919 yield* deleteMapping(stale);
920 }
921 const mappingArn = `arn:aws:lambda:${region}:${accountId}:event-source-mapping:${uuid}`;
922
923 // Sync configuration — `updateEventSourceMapping` is a full PUT
924 // for mutable fields. We always send the full desired config so
925 // observed state converges. Retry `ResourceInUseException`
926 // (mapping is transitioning) and known IAM-propagation errors.
927 config = yield* lambda.updateEventSourceMapping(toUpdateRequest(uuid, news)).pipe(
928 Effect.retry({
929 while: (e: any) =>
930 e._tag === "ResourceInUseException" || e._tag === "ResourceConflictException",
931 schedule: Schedule.max([Schedule.exponential(100), Schedule.recurs(20)]),
932 }),
933 retryPermissionsPropagation,
934 retryTransient,
935 Effect.catchTag("QueueVisibilityTimeoutTooShort", (error) =>
936 Effect.fail(visibilityTimeoutError(functionName, eventSourceArn, error)),
937 ),
938 );
939
940 // Wait for the mapping to settle into its desired terminal state.
941 // A fresh mapping sits in `Creating` for up to ~a minute before
942 // Lambda actually starts polling — and for stream sources with
943 // `startingPosition: LATEST`, records written before polling
944 // starts are silently skipped. Returning early would hand the
945 // caller a mapping that looks deployed but drops events.
946 const desiredState = (news.enabled ?? true) ? "Enabled" : "Disabled";
947 if (config.State !== desiredState) {
948 config = yield* lambda.getEventSourceMapping({ UUID: uuid }).pipe(
949 Effect.flatMap((observed) =>
950 observed.State === desiredState
951 ? Effect.succeed(observed)
952 : Effect.fail(new MappingNotSettled({ state: observed.State })),
953 ),
954 Effect.retry({
955 while: (e) => e._tag === "MappingNotSettled",
956 schedule: Schedule.max([Schedule.spaced("2 seconds"), Schedule.recurs(45)]).pipe(
957 Schedule.tap(({ attempt }) =>
958 session.note(
959 `EventSourceMapping ${uuid}: waiting to become ${desiredState} (${(attempt + 1) * 2}s elapsed)`,
960 ),
961 ),
962 ),
963 }),
964 // Never wedge a deploy on a mapping stuck in transition —
965 // surface the observed state in the attributes instead.
966 Effect.catchTag("MappingNotSettled", () =>
967 lambda.getEventSourceMapping({ UUID: uuid }),
968 ),
969 );
970 }
971
972 // Sync tags — diff observed cloud tags against desired so
973 // adoption rewrites ownership tags correctly.
974 const observedTagsResp = yield* lambda
975 .listTags({ Resource: mappingArn })
976 .pipe(retryTransient);
977 const observedTags: Record<string, string> = Object.fromEntries(
978 Object.entries(observedTagsResp.Tags ?? {}).filter(
979 (entry): entry is [string, string] => typeof entry[1] === "string",
980 ),
981 );
982 const { removed, upsert } = diffTags(observedTags, desiredTags);
983
984 if (removed.length > 0) {
985 yield* lambda
986 .untagResource({ Resource: mappingArn, TagKeys: removed })
987 .pipe(retryTransient);
988 }
989 if (upsert.length > 0) {
990 const tagsToAdd: Record<string, string> = {};
991 for (const { Key, Value } of upsert) {
992 tagsToAdd[Key] = Value;
993 }
994 yield* lambda
995 .tagResource({ Resource: mappingArn, Tags: tagsToAdd })
996 .pipe(retryTransient);
997 }
998
999 yield* session.note(config.EventSourceMappingArn ?? uuid);
1000
1001 return {
1002 ...configToAttrs(config),
1003 configuration: observeMappingConfiguration(config, news, desiredTags),
1004 };
1005 }),
1006 delete: Effect.fn(function* ({ output }) {
1007 yield* deleteMapping(output.uuid);
1008 }),
1009 // `list()` — AWS account/region collection (§4a). Exhaustively
1010 // paginate `listEventSourceMappings` with no `FunctionName` filter to
1011 // enumerate every mapping in the current region, hydrating each into
1012 // the exact `Attributes` shape `reconcile`/`configToAttrs` returns.
1013 // The list response carries full `EventSourceMappingConfiguration`
1014 // objects, so there is no per-item `getEventSourceMapping` to issue —
1015 // hence no bounded fan-out or per-item `ResourceNotFoundException`
1016 // handling is required. We drop any partial entry missing a required
1017 // identifier field rather than emitting a malformed `Attributes`.
1018 list: () =>
1019 lambda.listEventSourceMappings.pages({}).pipe(
1020 Stream.runCollect,
1021 Effect.map((chunk) =>
1022 Array.from(chunk).flatMap((page) =>
1023 (page.EventSourceMappings ?? [])
1024 .filter(
1025 (
1026 config,
1027 ): config is lambda.EventSourceMappingConfiguration & {
1028 UUID: string;
1029 EventSourceMappingArn: string;
1030 FunctionArn: string;
1031 State: string;
1032 } =>
1033 config.UUID != null &&
1034 config.EventSourceMappingArn != null &&
1035 config.FunctionArn != null &&
1036 config.State != null,
1037 )
1038 .map(configToAttrs),
1039 ),
1040 ),
1041 ),
1042 };
1043 }),
1044 );
1045
1046 const retryTransient: <A, R, Err>(self: Effect.Effect<A, Err, R>) => Effect.Effect<A, Err, R> =
1047 Effect.retry({
1048 while: (e: any) =>
1049 e._tag === "InternalFailure" ||
1050 e._tag === "RequestExpired" ||
1051 e._tag === "ServiceException" ||
1052 e._tag === "ServiceUnavailable" ||
1053 e._tag === "ThrottlingException" ||
1054 e._tag === "TooManyRequestsException" ||
1055 e._tag === "RequestLimitExceeded" ||
1056 e._tag === "ResourceInUseException",
1057 schedule: Schedule.max([Schedule.exponential(100), Schedule.recurs(30)]),
1058 });
1059
1060 const retryPermissionsPropagation = Effect.retry({
1061 while: (e: { _tag: string }) =>
1062 e._tag === "ExecutionRoleNotAssumable" || e._tag === "ExecutionRoleMissingPermissions",
1063 schedule: Schedule.max([Schedule.exponential(100), Schedule.recurs(30)]),
1064 }) as <A, R, Err extends { _tag: string }>(
1065 self: Effect.Effect<A, Err, R>,
1066 ) => Effect.Effect<A, Err, R>;
1067
1068 const sanitizeAwsTagValue = (value: string) => value.replace(/[^\p{L}\p{Z}\p{N}_.:/=+\-@]/gu, "-");