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

main
ts 303 lines 11.7 KB
Raw
1 import type * as cf from "@cloudflare/workers-types";
2 import * as Namespace from "alchemy/Namespace";
3 import type { FunctionContext } from "alchemy/Runtime/Function";
4 import { RuntimeContext } from "alchemy/RuntimeContext";
5 import * as DurationUtil from "alchemy/Util/Duration";
6 import * as Cause from "effect/Cause";
7 import * as Context from "effect/Context";
8 import * as Duration from "effect/Duration";
9 import * as Effect from "effect/Effect";
10 import * as Layer from "effect/Layer";
11 import * as Stream from "effect/Stream";
12 import { isWorkerEvent, Worker } from "../Workers/Worker.ts";
13 import { Consumer } from "./Consumer.ts";
14 import type { Queue } from "./Queue.ts";
15
16 /**
17 * Subscriber settings — the same shape Cloudflare's `Consumer`
18 * accepts. `consumeQueueMessages(queue, props, handler)` passes these
19 * through to the auto-created `Cloudflare.Queues.Consumer` so a single
20 * call captures both runtime and deploy-time intent.
21 */
22 export interface MessagesProps {
23 /** Maximum messages per batch. */
24 batchSize?: number;
25 /** Maximum concurrent invocations. */
26 maxConcurrency?: number;
27 /** Maximum delivery attempts before dead-lettering. */
28 maxRetries?: number;
29 /**
30 * Wait time before flushing a partial batch. Rounded up to whole
31 * milliseconds when forwarded to Cloudflare.
32 */
33 maxWaitTime?: Duration.Input;
34 /**
35 * Backoff applied to a retry. Rounded up to whole seconds when
36 * forwarded to Cloudflare.
37 */
38 retryDelay?: Duration.Input;
39 /**
40 * Queue that receives messages after `maxRetries` failed deliveries.
41 * Pass the Queue resource, a `Queue.ref(...)` to one, or a queue name.
42 *
43 * Cloudflare does not drain or alert on a dead-letter queue. A message
44 * left there expires after the queue's retention period, so call
45 * `consumeQueueMessages` on the dead-letter queue as well to log,
46 * persist, or alert on what arrives.
47 */
48 deadLetterQueue?: string | Queue;
49 }
50
51 /**
52 * Convert a {@link MessagesProps} (with `Duration.Input` time fields)
53 * into the numeric settings shape Cloudflare's `Consumer` API
54 * expects. `maxWaitTime` is rounded up to whole milliseconds and
55 * `retryDelay` to whole seconds.
56 *
57 * Exposed for testing and for callers that want to mirror the
58 * conversion when wiring `Consumer` directly.
59 */
60 export const toConsumerSettings = (props: MessagesProps) => ({
61 batchSize: props.batchSize,
62 maxConcurrency: props.maxConcurrency,
63 maxRetries: props.maxRetries,
64 maxWaitTimeMs: DurationUtil.toMillis(props.maxWaitTime),
65 retryDelay: DurationUtil.toSeconds(props.retryDelay),
66 });
67
68 /**
69 * A single queue message handed to the subscribe handler. Mirrors
70 * Cloudflare's runtime `Message<Body>` shape so per-message
71 * `ack()` / `retry()` semantics match the platform docs.
72 */
73 export type Message<Body = unknown> = cf.Message<Body>;
74
75 /**
76 * Subscribe to a Cloudflare Queue with an Effect stream handler.
77 *
78 * Mirrors `AWS.SQS.consumeQueueMessages(queue, handler)` on the
79 * Cloudflare side. Wires both halves of the consumer in one call:
80 *
81 * - **Runtime**: registers a `queue` event listener on the Worker.
82 * Each batch is piped through `process` as a `Stream.Stream`.
83 * - **Deploy-time**: yields a `Cloudflare.Queues.Consumer` resource
84 * so Cloudflare actually dispatches messages from `queue` to
85 * this Worker. No manual `Consumer` wiring needed in
86 * `alchemy.run.ts`.
87 *
88 * Acking semantics: if `process` succeeds, every message in the
89 * batch is `ack()`ed; if it fails, every message is `retry()`ed
90 * and Cloudflare applies `maxRetries` / `retryDelay` from the
91 * settings before dead-lettering. Per-message control is still
92 * available by calling `msg.ack()` / `msg.retry()` inside the
93 * handler.
94 *
95 * ### Consuming a Queue
96 * **Example:** Handle each batch as a Stream
97 * ```typescript
98 * yield* Cloudflare.Queues.consumeQueueMessages<MyEvent>(queueResource, (stream) =>
99 * Stream.runForEach(stream, (msg) => Effect.log(`event ${msg.body.id}`)),
100 * );
101 * ```
102 *
103 * ### Tuning Batching and Retries
104 * **Example:** Batch size, wait time, and retry backoff
105 * ```typescript
106 * yield* Cloudflare.Queues.consumeQueueMessages<MyEvent>(
107 * queueResource,
108 * {
109 * batchSize: 25,
110 * maxRetries: 3,
111 * maxWaitTime: "5 seconds",
112 * retryDelay: Duration.seconds(30),
113 * },
114 * (stream) => Stream.runForEach(stream, (msg) => Effect.log(`event ${msg.body.id}`)),
115 * );
116 * ```
117 *
118 * ### Dead-Lettering Failed Messages
119 * A message that fails `maxRetries` times moves to `deadLetterQueue`.
120 * Cloudflare does not drain or alert on that queue, so consume it too.
121 * Otherwise the message expires there unseen.
122 *
123 * **Example:** Dead-letter to a Queue resource and consume it
124 * ```typescript
125 * const deadLetters = yield* Cloudflare.Queues.Queue("DeadLetters");
126 *
127 * yield* Cloudflare.Queues.consumeQueueMessages<MyEvent>(
128 * queueResource,
129 * { maxRetries: 3, deadLetterQueue: deadLetters },
130 * (stream) => Stream.runForEach(stream, (msg) => Effect.log(`event ${msg.body.id}`)),
131 * );
132 *
133 * yield* Cloudflare.Queues.consumeQueueMessages<MyEvent>(deadLetters, (stream) =>
134 * Stream.runForEach(stream, (msg) =>
135 * Effect.logError(`dead-lettered ${msg.body.id} after ${msg.attempts} attempts`),
136 * ),
137 * );
138 * ```
139 *
140 * **Example:** Dead-letter to a queue in another stack
141 * ```typescript
142 * // Deploy the "shared" stack first; its Worker consumes the dead-letter queue.
143 * yield* Cloudflare.Queues.consumeQueueMessages<MyEvent>(
144 * queueResource,
145 * {
146 * maxRetries: 3,
147 * deadLetterQueue: yield* Cloudflare.Queues.Queue.ref("DeadLetters", {
148 * stack: "shared",
149 * stage: "production",
150 * }),
151 * },
152 * (stream) => Stream.runForEach(stream, (msg) => Effect.log(`event ${msg.body.id}`)),
153 * );
154 * ```
155 *
156 * **Example:** Dead-letter to a queue by name
157 * ```typescript
158 * // A queue Alchemy doesn't manage; something else must consume it.
159 * yield* Cloudflare.Queues.consumeQueueMessages<MyEvent>(
160 * queueResource,
161 * { maxRetries: 3, deadLetterQueue: "orders-dead-letters" },
162 * (stream) => Stream.runForEach(stream, (msg) => Effect.log(`event ${msg.body.id}`)),
163 * );
164 * ```
165 *
166 * @binding
167 * @product Queues
168 * @category Storage & Databases
169 */
170 export function consumeQueueMessages<Body = unknown>(
171 queue: Queue,
172 process: (stream: Stream.Stream<Message<Body>>) => Effect.Effect<void, unknown, any>,
173 ): Effect.Effect<void, never, EventSource>;
174 export function consumeQueueMessages<Body = unknown>(
175 queue: Queue,
176 props: MessagesProps,
177 process: (stream: Stream.Stream<Message<Body>>) => Effect.Effect<void, unknown, any>,
178 ): Effect.Effect<void, never, EventSource>;
179 export function consumeQueueMessages<Body = unknown>(
180 queue: Queue,
181 propsOrProcess:
182 | MessagesProps
183 | ((stream: Stream.Stream<Message<Body>>) => Effect.Effect<void, unknown, any>),
184 maybeProcess?: (stream: Stream.Stream<Message<Body>>) => Effect.Effect<void, unknown, any>,
185 ): Effect.Effect<void, never, EventSource> {
186 const [props, process] =
187 typeof propsOrProcess === "function"
188 ? [{} as MessagesProps, propsOrProcess]
189 : [propsOrProcess, maybeProcess!];
190 return EventSource.use((source) => source<Body>(queue, props, process));
191 }
192
193 // `Req` is the handler's requirements. The service registers the
194 // handler with the Worker's runtime context, where the runtime
195 // machinery provides bindings and `WorkerEnvironment` when the
196 // dispatch fires — so the requirement is satisfied at handler
197 // invocation, NOT at subscribe time. We drop `Req` from the return
198 // to keep init effects clean (mirrors `AWS.SQS.EventSourceService`).
199 export type EventSourceService = <Body = unknown>(
200 queue: Queue,
201 props: MessagesProps,
202 process: (stream: Stream.Stream<Message<Body>>) => Effect.Effect<void, unknown, any>,
203 ) => Effect.Effect<void, never, never>;
204
205 /**
206 * Service tag for the Cloudflare Queue event source. Provided by
207 * {@link EventSourceLive} on the Worker's runtime layer.
208 */
209 export class EventSource extends Context.Service<EventSource, EventSourceService>()(
210 "Cloudflare.Queues.EventSource",
211 ) {}
212
213 /**
214 * Runtime layer for {@link consumeQueueMessages}. Wires each
215 * `consumeQueueMessages(queue, handler)` call in the Worker init phase to
216 * a `queue` event listener on the runtime context, and (at deploy
217 * time) yields the matching `Cloudflare.Queues.Consumer` resource so
218 * Cloudflare dispatches messages from the queue to this Worker.
219 *
220 * Provide alongside other Cloudflare runtime layers (e.g.
221 * `WriteQueueBinding`) on the Worker effect.
222 */
223 export const EventSourceLive = Layer.effect(
224 EventSource,
225 Effect.gen(function* () {
226 const host = yield* Worker;
227 return Effect.fn(function* <Body, Req>(
228 queue: Queue,
229 props: MessagesProps,
230 process: (stream: Stream.Stream<Message<Body>>) => Effect.Effect<void, unknown, any>,
231 ) {
232 // Deploy-time: yield the Consumer resource as a sibling of the
233 // Worker so Cloudflare dispatches messages from the queue to it.
234 // Skipped once running inside the deployed Worker (the global
235 // guard), where the only work is registering the runtime handler
236 // below. Namespaced under the host so the Consumer's logical
237 // identity matches the previous Binding.Policy.
238 if (!globalThis.__ALCHEMY_RUNTIME__) {
239 yield* Namespace.push(
240 host.LogicalId,
241 // The engine creates / updates / destroys the Consumer
242 // alongside the Worker's lifecycle; the consumer's
243 // reconciler waits for the Worker upload to expose the
244 // `queue` handler before completing (see PR #257 for the
245 // 11001 retry).
246 Consumer(`${queue.LogicalId}Consumer`, {
247 queueId: queue.queueId,
248 scriptName: host.workerName,
249 settings: toConsumerSettings(props),
250 deadLetterQueue:
251 typeof props.deadLetterQueue === "string"
252 ? props.deadLetterQueue
253 : props.deadLetterQueue?.queueName,
254 }),
255 );
256 }
257
258 // Resolve the runtime context per-call rather than at layer
259 // construction. Capturing it on the layer would leak the
260 // requirement past `PlatformServices` exclusion when the
261 // Worker typechecks its init effect.
262 const ctx = (yield* RuntimeContext) as unknown as FunctionContext;
263 // Capture the queue-name accessor once; the listener body
264 // re-resolves it per event via `yield* QueueName`. A worker
265 // can consume multiple queues — each subscribe registers its
266 // own listener and they all see every queue event, so the
267 // queue-name match is what scopes the handler.
268 const QueueName = yield* queue.queueName;
269
270 yield* ctx.listen<void, Req>((event) => {
271 if (!isWorkerEvent(event) || event.type !== "queue") return;
272 const batch = event.input as cf.MessageBatch<Body>;
273
274 return Effect.gen(function* () {
275 const queueName = yield* QueueName;
276 if (batch.queue !== queueName) return;
277
278 yield* process(Stream.fromIterable(batch.messages)).pipe(
279 Effect.tap(() =>
280 Effect.sync(() => {
281 for (const msg of batch.messages) msg.ack();
282 }),
283 ),
284 Effect.onError((cause) =>
285 Effect.sync(() => {
286 // Surface the failure so the operator sees what
287 // tripped the retry path; without this the only
288 // signal is the message reappearing on the next
289 // attempt.
290 console.error(
291 `[EventSource] handler failed on queue ` +
292 `"${queueName}": ${Cause.pretty(cause)}`,
293 );
294 for (const msg of batch.messages) msg.retry();
295 }),
296 ),
297 Effect.ignoreCause,
298 );
299 });
300 });
301 }) as EventSourceService;
302 }),
303 );