@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 188 lines 6.34 KB
Raw
1 import type * as Lambda from "@distilled.cloud/aws/lambda";
2 import * as Binding from "alchemy/Binding";
3 import type * as Duration from "effect/Duration";
4 import * as Effect from "effect/Effect";
5 import type { Stream as KinesisStream } from "./Stream.ts";
6
7 export type KinesisEventRecord = import("aws-lambda").KinesisStreamRecord;
8
9 export type KinesisStreamEvent = import("aws-lambda").KinesisStreamEvent;
10
11 /**
12 * Lambda's partial-batch response for Kinesis. Report the `sequenceNumber`
13 * of the first record that failed as `itemIdentifier`; Lambda checkpoints
14 * before it and retries from there.
15 */
16 export type KinesisStreamBatchResponse = import("aws-lambda").KinesisStreamBatchResponse;
17
18 /**
19 * Handler for one delivered batch of Kinesis records: receives the
20 * {@link KinesisStreamEvent} and returns Lambda's
21 * {@link KinesisStreamBatchResponse} (or `void` when every record succeeded).
22 * A failure or defect retries the whole batch.
23 */
24 export type StreamRecordsHandler<E = never, Req = never> = (
25 event: KinesisStreamEvent,
26 ) => Effect.Effect<KinesisStreamBatchResponse | void, E, Req>;
27
28 export interface StreamEventSourceProps {
29 /**
30 * The maximum number of records in each batch that Lambda pulls from the stream.
31 * @default 100
32 */
33 batchSize?: number;
34 /**
35 * The maximum amount of time that Lambda spends gathering records before
36 * invoking the function, e.g. `"5 seconds"` or `Duration.seconds(5)`.
37 * Rounded to whole seconds on the wire.
38 * @default 0
39 */
40 maximumBatchingWindow?: Duration.Input;
41 /**
42 * The position in the stream from which Lambda starts reading.
43 * @default "LATEST"
44 */
45 startingPosition?: "TRIM_HORIZON" | "LATEST" | "AT_TIMESTAMP";
46 /**
47 * The timestamp to start reading from when `startingPosition` is `AT_TIMESTAMP`.
48 */
49 startingPositionTimestamp?: Date;
50 /**
51 * The number of batches to process from each shard concurrently.
52 * @default 1
53 */
54 parallelizationFactor?: number;
55 /**
56 * Split the batch in two and retry if the function returns an error.
57 * @default false
58 */
59 bisectBatchOnFunctionError?: boolean;
60 /**
61 * Discard records older than the specified age, e.g. `"1 hour"` or
62 * `Duration.hours(1)`. Rounded to whole seconds on the wire. Omit to never
63 * discard records by age.
64 */
65 maximumRecordAge?: Duration.Input;
66 /**
67 * Discard records after the specified number of retries.
68 * @default -1
69 */
70 maximumRetryAttempts?: number;
71 /**
72 * The duration of a processing window for tumbling windows, e.g.
73 * `"30 seconds"` or `Duration.seconds(30)`. Rounded to whole seconds on
74 * the wire (0–900 seconds).
75 */
76 tumblingWindow?: Duration.Input;
77 /**
78 * A list of current response type enums applied to the event source mapping.
79 */
80 functionResponseTypes?: "ReportBatchItemFailures"[];
81 /**
82 * A destination for records that failed processing.
83 */
84 destinationConfig?: Lambda.DestinationConfig;
85 /**
86 * Filter criteria to control which records are sent to the function.
87 */
88 filterCriteria?: Lambda.FilterCriteria;
89 /**
90 * The ARN of an AWS KMS key to encrypt the filter criteria.
91 */
92 kmsKeyArn?: string;
93 /**
94 * Metrics configuration for the event source mapping.
95 */
96 metricsConfig?: Lambda.EventSourceMappingMetricsConfig;
97 }
98
99 /**
100 * Event source connecting a Kinesis `Stream` to the hosting compute.
101 *
102 * The contract is a `Binding.Service`; the Lambda implementation layer
103 * (`AWS.Lambda.StreamEventSource`) creates an event source mapping on the
104 * stream, grants the read IAM actions, and hands each delivered batch of
105 * `aws:kinesis` records to the handler. Use the {@link consumeStreamRecords} helper
106 * rather than calling the service directly.
107 * ### Consuming Records
108 * **Example:** Process Stream Records in a Lambda Function
109 * ```typescript
110 * export default MyFunction.make(
111 * { main: import.meta.url },
112 * Effect.gen(function* () {
113 * const stream = yield* AWS.Kinesis.Stream("OrdersStream");
114 *
115 * // init — registers the event source mapping and the record handler
116 * yield* AWS.Kinesis.consumeStreamRecords(
117 * stream,
118 * { startingPosition: "LATEST", batchSize: 10 },
119 * Effect.fn(function* (event) {
120 * for (const record of event.Records) {
121 * yield* Effect.log(Buffer.from(record.kinesis.data, "base64").toString("utf8"));
122 * }
123 * }),
124 * );
125 *
126 * return {};
127 * }).pipe(Effect.provide(AWS.Lambda.StreamEventSource)),
128 * );
129 * ```
130 *
131 * @binding
132 */
133 export interface StreamEventSource extends Binding.Service<
134 StreamEventSource,
135 "AWS.Kinesis.StreamEventSource",
136 StreamEventSourceService
137 > {}
138
139 export const StreamEventSource = Binding.Service<StreamEventSource>(
140 "AWS.Kinesis.StreamEventSource",
141 );
142
143 export type StreamEventSourceService = <E = never, Req = never>(
144 stream: KinesisStream,
145 props: StreamEventSourceProps,
146 process: StreamRecordsHandler<E, Req>,
147 ) => Effect.Effect<void, never, never>;
148
149 /**
150 * Subscribe a runtime to batches of records from a Kinesis stream.
151 *
152 * The Lambda runtime implementation creates an event source mapping and hands
153 * each delivered {@link KinesisStreamEvent} (only the records from `stream`)
154 * to the handler. Return a {@link KinesisStreamBatchResponse} naming the
155 * first failed record's `sequenceNumber` to checkpoint before it, or `void`
156 * when every record succeeded. If the handler fails, the whole batch is
157 * retried.
158 *
159 * Each batch runs inside a `process <stream>` span (`SpanKind.CONSUMER`).
160 *
161 * @example Checkpoint at the first failed record
162 * ```typescript
163 * const sendMessage = yield* AWS.SQS.SendMessage(queue);
164 *
165 * yield* AWS.Kinesis.consumeStreamRecords(
166 * stream,
167 * { startingPosition: "LATEST" },
168 * Effect.fn(function* (event) {
169 * for (const record of event.Records) {
170 * const ok = yield* sendMessage({
171 * MessageBody: Buffer.from(record.kinesis.data, "base64").toString("utf8"),
172 * }).pipe(
173 * Effect.as(true),
174 * Effect.catchCause(() => Effect.succeed(false)),
175 * );
176 * if (!ok) {
177 * return { batchItemFailures: [{ itemIdentifier: record.kinesis.sequenceNumber }] };
178 * }
179 * }
180 * }),
181 * );
182 * ```
183 */
184 export const consumeStreamRecords = <S extends KinesisStream, E = never, Req = never>(
185 stream: S,
186 props: StreamEventSourceProps = {},
187 process: StreamRecordsHandler<E, Req>,
188 ) => StreamEventSource.use((source) => source(stream, props, process));