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

main
ts 838 lines 33.5 KB
Raw
1 import * as queues from "@distilled.cloud/cloudflare/queues";
2 import * as workers from "@distilled.cloud/cloudflare/workers";
3 import { isResolved } from "alchemy/Diff";
4 import * as ProviderLayer from "alchemy/Local/ProviderLayer";
5 import * as RpcProvider from "alchemy/Local/RpcProvider";
6 import * as Provider from "alchemy/Provider";
7 import { Resource } from "alchemy/Resource";
8 import { Stack } from "alchemy/Stack";
9 import * as Effect from "effect/Effect";
10 import * as Layer from "effect/Layer";
11 import * as MutableHashMap from "effect/MutableHashMap";
12 import * as Option from "effect/Option";
13 import * as Schedule from "effect/Schedule";
14 import * as Stream from "effect/Stream";
15 import { CloudflareEnvironment } from "../CloudflareEnvironment.ts";
16 import { localAccountId } from "../LocalAccount.ts";
17 import {
18 isLiveId,
19 LOCAL_PROVIDERS_URL,
20 LocalRuntimeState,
21 localRuntimeServices,
22 } from "../LocalRuntime.ts";
23 import type { Providers } from "../Providers.ts";
24
25 export type ConsumerProps = {
26 /**
27 * The queue ID to attach the consumer to.
28 */
29 queueId: string;
30 /**
31 * Name of the Worker script that will consume messages.
32 */
33 scriptName: string;
34 /**
35 * Name of the queue that receives messages after `maxRetries` failed
36 * deliveries.
37 *
38 * Cloudflare does not drain or alert on a dead-letter queue. A message
39 * left there expires after the queue's retention period, so give the
40 * dead-letter queue its own consumer.
41 */
42 deadLetterQueue?: string;
43 /**
44 * Consumer settings.
45 */
46 settings?: ConsumerSettings;
47 };
48
49 export interface ConsumerSettings {
50 /**
51 * The maximum number of messages per batch.
52 * @default 10
53 */
54 batchSize?: number;
55 /**
56 * The maximum number of concurrent consumer invocations.
57 */
58 maxConcurrency?: number;
59 /**
60 * The maximum number of retries for a message.
61 * @default 3
62 */
63 maxRetries?: number;
64 /**
65 * The maximum time to wait for a batch to fill, in milliseconds.
66 * @default 5000
67 */
68 maxWaitTimeMs?: number;
69 /**
70 * The number of seconds to wait before retrying a message.
71 */
72 retryDelay?: number;
73 }
74
75 export type Consumer = Resource<
76 "Cloudflare.Queues.Consumer",
77 ConsumerProps,
78 {
79 consumerId: string;
80 queueId: string;
81 scriptName: string;
82 accountId: string;
83 deadLetterQueue?: string;
84 settings?: ConsumerSettings;
85 /**
86 * Dev only, live queues only: the real queue's name, resolved from the
87 * cloud so the local runtime can wire the broker + pull loop for a
88 * locally-running consumer of an `Alchemy.remote()` queue.
89 */
90 queueName?: string;
91 /**
92 * Dev only, live queues only: id of the `http_pull` consumer attached
93 * to the real queue so the local runtime can drain it via the HTTP
94 * pull API. Deleted when this resource is deleted.
95 */
96 pullConsumerId?: string;
97 },
98 never,
99 Providers
100 >;
101
102 /**
103 * A Cloudflare Queue Consumer that processes messages from a Queue.
104 *
105 * Register a Worker as a consumer of a Queue. The Worker's `queue()`
106 * handler will be invoked with batches of messages.
107 *
108 * Cloudflare allows at most one Worker consumer per queue (HTTP-pull
109 * consumers can coexist). The reconciler enforces this: if the queue
110 * already has a Worker consumer pointing at a different logical Worker's
111 * script, the deploy fails with a clear error rather than silently
112 * adopting it. A stranded consumer from a prior generation of the *same*
113 * Worker (identified by the scripts' ownership tags) is rebuilt in place.
114 * ### Registering a Consumer
115 * **Example:** Basic consumer
116 * ```typescript
117 * const queue = yield* Cloudflare.Queues.Queue("MyQueue");
118 * const worker = yield* Cloudflare.Worker("Worker", { ... });
119 *
120 * yield* Cloudflare.Queues.Consumer("MyConsumer", {
121 * queueId: queue.queueId,
122 * scriptName: worker.workerName,
123 * });
124 * ```
125 *
126 * **Example:** Consumer with settings
127 * ```typescript
128 * yield* Cloudflare.Queues.Consumer("MyConsumer", {
129 * queueId: queue.queueId,
130 * scriptName: worker.workerName,
131 * settings: {
132 * batchSize: 50,
133 * maxRetries: 5,
134 * maxWaitTimeMs: 10000,
135 * },
136 * });
137 * ```
138 *
139 * ### Dead-Lettering Failed Messages
140 * **Example:** Consume the dead-letter queue
141 * ```typescript
142 * const dlq = yield* Cloudflare.Queues.Queue("MyDeadLetterQueue");
143 *
144 * yield* Cloudflare.Queues.Consumer("MyConsumer", {
145 * queueId: queue.queueId,
146 * scriptName: worker.workerName,
147 * deadLetterQueue: dlq.queueName,
148 * settings: { maxRetries: 3 },
149 * });
150 *
151 * // Without a consumer, dead-lettered messages expire unseen.
152 * yield* Cloudflare.Queues.Consumer("MyDeadLetterConsumer", {
153 * queueId: dlq.queueId,
154 * scriptName: worker.workerName,
155 * });
156 * ```
157 *
158 * **Example:** Dead-letter to a queue in another stack
159 * ```typescript
160 * const dlq = yield* Cloudflare.Queues.Queue.ref("DeadLetters", {
161 * stack: "shared",
162 * stage: "production",
163 * });
164 *
165 * yield* Cloudflare.Queues.Consumer("MyConsumer", {
166 * queueId: queue.queueId,
167 * scriptName: worker.workerName,
168 * deadLetterQueue: dlq.queueName,
169 * });
170 * ```
171 *
172 * **Example:** Dead-letter to a queue by name
173 * ```typescript
174 * yield* Cloudflare.Queues.Consumer("MyConsumer", {
175 * queueId: queue.queueId,
176 * scriptName: worker.workerName,
177 * deadLetterQueue: "orders-dead-letters",
178 * });
179 * ```
180 *
181 * @resource
182 * @product Queues
183 * @category Storage & Databases
184 */
185 export const Consumer = Resource<Consumer>("Cloudflare.Queues.Consumer", {
186 aliases: ["Cloudflare.QueueConsumer"],
187 });
188
189 /**
190 * Find and detach every worker queue-consumer pointing at `scriptName`.
191 * Queue consumers have no by-script lookup, so scan the account's queues
192 * (the list response inlines each queue's consumers). Waits until each
193 * detach propagates to the workers subsystem so a follow-up deleteScript
194 * doesn't re-race the conflict.
195 *
196 * Shared by the Worker provider's script delete (QueueConsumerConflict
197 * recovery) and the Queue provider's orphaned-script cleanup.
198 *
199 * @internal
200 */
201 export const detachQueueConsumersOfScript = Effect.fn(function* (
202 accountId: string,
203 scriptName: string,
204 ) {
205 const pages = yield* queues.listQueues.pages({ accountId }).pipe(
206 Stream.runCollect,
207 Effect.catchTag("InvalidRoute", () => Effect.succeed([])),
208 );
209 const targets = Array.from(pages).flatMap((page) =>
210 (page.result ?? []).flatMap((queue) =>
211 (queue.consumers ?? []).flatMap((consumer) =>
212 queue.queueId &&
213 consumer.type === "worker" &&
214 consumer.consumerId &&
215 "scriptName" in consumer &&
216 consumer.scriptName === scriptName
217 ? [{ queueId: queue.queueId, consumerId: consumer.consumerId }]
218 : [],
219 ),
220 ),
221 );
222 yield* Effect.forEach(
223 targets,
224 ({ queueId, consumerId }) =>
225 queues.deleteConsumer({ accountId, queueId, consumerId }).pipe(
226 Effect.catchTag(["ConsumerNotFound", "QueueNotFound"], () => Effect.void),
227 Effect.andThen(
228 queues.getConsumer({ accountId, queueId, consumerId }).pipe(
229 Effect.flatMap(() => Effect.fail("still-attached" as const)),
230 Effect.catchTag(["ConsumerNotFound", "QueueNotFound"], () => Effect.void),
231 Effect.retry({
232 while: (e) => e === "still-attached",
233 schedule: Schedule.max([Schedule.spaced("1 second"), Schedule.recurs(30)]),
234 }),
235 Effect.ignore,
236 ),
237 ),
238 ),
239 { concurrency: 5, discard: true },
240 );
241 });
242
243 // Cloudflare allows a single Worker consumer per queue, so the
244 // first match in the paginated stream is the only one. Using
245 // `.items` defeats single-page lookups that would otherwise
246 // miss late-arriving consumers under eventual consistency.
247 const findWorkerConsumer = (acct: string, queueId: string) =>
248 queues.listConsumers.items({ accountId: acct, queueId }).pipe(
249 Stream.map(toObserved),
250 Stream.filter((c): c is ObservedConsumer => c !== undefined),
251 Stream.runHead,
252 Effect.map(Option.getOrUndefined),
253 // A queue created earlier in the same plan is eventually consistent:
254 // listConsumers can transiently 404 (`QueueNotFound`, code 11000) before
255 // the fresh queue is visible to the consumers API. Treat that as "no
256 // consumer yet" — the caller falls through to createConsumer, which
257 // retries QueueNotFound until the queue propagates.
258 Effect.catchTag("QueueNotFound", () => Effect.undefined),
259 );
260
261 export const ConsumerProviderLive = () =>
262 Provider.succeed(Consumer, {
263 // The `consumerId` is not marked as stable because if you start in dev mode, the ID will change on first deploy.
264 stables: ["accountId"],
265 // Queue consumers are sub-resources of a queue with no account-wide
266 // enumeration API, so fan out: list every queue in the account, then
267 // list each queue's consumers and keep the worker ones (the only kind
268 // this resource manages, matching `read`/`reconcile`).
269 list: Effect.fn(function* () {
270 const { accountId } = yield* yield* CloudflareEnvironment;
271 const queueIds = yield* queues.listQueues.pages({ accountId }).pipe(
272 Stream.runCollect,
273 Effect.map((chunk) =>
274 Array.from(chunk).flatMap((page) =>
275 (page.result ?? []).map((q) => q.queueId).filter((id): id is string => id != null),
276 ),
277 ),
278 // Account not entitled for Queues — nothing to enumerate.
279 Effect.catchTag("InvalidRoute", () => Effect.succeed<string[]>([])),
280 );
281 const rows = yield* Effect.forEach(
282 queueIds,
283 (queueId) =>
284 queues.listConsumers.pages({ accountId, queueId }).pipe(
285 Stream.runCollect,
286 Effect.map((chunk) =>
287 Array.from(chunk).flatMap((page) =>
288 (page.result ?? []).flatMap((c): Consumer["Attributes"][] => {
289 if (c.type !== "worker" || !c.consumerId) return [];
290 const s = c.settings ?? undefined;
291 return [
292 {
293 consumerId: c.consumerId,
294 queueId,
295 scriptName: c.scriptName ?? "",
296 accountId,
297 deadLetterQueue: c.deadLetterQueue ?? undefined,
298 settings: s
299 ? {
300 batchSize: s.batchSize ?? undefined,
301 maxConcurrency: s.maxConcurrency ?? undefined,
302 maxRetries: s.maxRetries ?? undefined,
303 maxWaitTimeMs: s.maxWaitTimeMs ?? undefined,
304 retryDelay: s.retryDelay ?? undefined,
305 }
306 : undefined,
307 },
308 ];
309 }),
310 ),
311 ),
312 // Queue deleted mid-list or partial entitlement — skip it.
313 Effect.catchTag(["QueueNotFound", "InvalidRoute"], () =>
314 Effect.succeed<Consumer["Attributes"][]>([]),
315 ),
316 ),
317 { concurrency: 10 },
318 );
319 return rows.flat();
320 }),
321 diff: Effect.fn(function* ({ olds, news, output }) {
322 const { accountId } = yield* yield* CloudflareEnvironment;
323 if (!isResolved(news)) return undefined;
324 // If either contain `dev:` IDs, we need to update to live ones.
325 // The live resource doesn't exist yet, so there's no need to replace even when we otherwise would.
326 if (!isLiveId(output?.queueId) || !isLiveId(output?.consumerId)) {
327 return { action: "update" };
328 }
329 if ((output?.accountId ?? accountId) !== accountId) {
330 return { action: "replace" } as const;
331 }
332 // Queue change requires replacement — consumerId is bound
333 // to a queue and the API has no "move consumer" verb.
334 if (output?.queueId && news.queueId !== output.queueId) {
335 return { action: "replace", deleteFirst: true } as const;
336 }
337 // Settings / DLQ / script drift is an update. We DON'T
338 // escalate scriptName changes to `replace` because the
339 // engine resolves cross-resource Output<string> refs (a
340 // sibling Worker's `workerName`) lazily — when the upstream
341 // Worker is created in the same plan, `news` is partially
342 // unresolved at diff time and `isResolved(news)` short-
343 // circuits up top. Falling through to "update" lets the
344 // engine call reconcile with fully-resolved `news`, where
345 // we detect script drift and rebuild the consumer in
346 // place (Cloudflare's PUT silently ignores `script_name`
347 // changes, so reconcile does delete-then-create).
348 if (
349 JSON.stringify(olds.settings ?? {}) !== JSON.stringify(news.settings ?? {}) ||
350 (olds.deadLetterQueue ?? undefined) !== (news.deadLetterQueue ?? undefined) ||
351 (output?.scriptName !== undefined && news.scriptName !== output.scriptName)
352 ) {
353 return { action: "update" } as const;
354 }
355 }),
356 reconcile: Effect.fn(function* ({ news, output }) {
357 const { accountId } = yield* yield* CloudflareEnvironment;
358 const acct = output?.accountId ?? accountId;
359 // Only use `output.queueId` if it's a live ID (i.e. no `dev:` prefix).
360 // Otherwise, the lookup will fail because the request is malformed.
361 const queueId = isLiveId(output?.queueId) ? output.queueId : news.queueId;
362
363 // Delete a consumer and wait for Cloudflare's worker subsystem to
364 // drop its claim on the old script so createConsumer below doesn't
365 // race the queue↔script propagation lag.
366 const detachConsumer = Effect.fn(function* (consumerId: string) {
367 yield* queues
368 .deleteConsumer({ accountId: acct, queueId, consumerId })
369 .pipe(Effect.catchTag("ConsumerNotFound", () => Effect.void));
370 yield* queues.getConsumer({ accountId: acct, queueId, consumerId }).pipe(
371 Effect.flatMap(() => Effect.fail("still-attached" as const)),
372 Effect.catchTag("ConsumerNotFound", () => Effect.void),
373 Effect.retry({
374 while: (e) => e === "still-attached",
375 schedule: Schedule.max([Schedule.spaced("1 second"), Schedule.recurs(30)]),
376 }),
377 Effect.ignore,
378 );
379 });
380
381 // Observe — prefer the cached consumerId, then fall back to
382 // listConsumers (paginated) to recover from out-of-band
383 // deletes or partial state-persistence failures. Track
384 // whether the observation came from the cached id or the
385 // list scan: a different-script worker consumer found via
386 // the list scan is potentially foreign (state was lost,
387 // someone else attached the consumer), and silently
388 // updating it could clobber another team's wiring.
389 let observed: ObservedConsumer | undefined;
390 let owned = false;
391 if (isLiveId(output?.consumerId)) {
392 const fetched = yield* queues
393 .getConsumer({ accountId: acct, queueId, consumerId: output.consumerId })
394 .pipe(Effect.catchTag("ConsumerNotFound", () => Effect.undefined));
395 if (fetched) {
396 observed = toObserved(fetched);
397 owned = observed !== undefined;
398 }
399 }
400 if (!observed) {
401 observed = yield* findWorkerConsumer(acct, queueId);
402 }
403
404 // Owned consumer pointing at a different script: rebuild
405 // it in place. Cloudflare's PUT consumer silently ignores
406 // `script_name` changes on existing consumers (the live
407 // record stays pinned to the original worker), and the
408 // platform allows only one Worker consumer per queue, so
409 // the only path to re-point is delete-then-create.
410 if (
411 owned &&
412 observed &&
413 observed.scriptName !== undefined &&
414 observed.scriptName !== news.scriptName
415 ) {
416 yield* detachConsumer(observed.consumerId);
417 observed = undefined;
418 owned = false;
419 }
420
421 // A consumer found via the list scan (state loss) pointing at a
422 // different script. Probe the script it points at: when it no
423 // longer exists, or is a *prior generation of the same logical
424 // Worker* (same `alchemy:stack/stage/id` ownership tags as the
425 // configured script — replacements mint a new physical name, and
426 // a crashed apply can strand the old generation's consumer with
427 // its state entry lost), the wiring is ours to rebuild. Any other
428 // script — another team's, or a *different* Worker in this stack
429 // (a real misconfiguration: two consumers declared for one queue)
430 // — is refused loudly rather than silently stolen.
431 if (
432 observed &&
433 !owned &&
434 observed.scriptName !== undefined &&
435 observed.scriptName !== news.scriptName
436 ) {
437 const scriptTags = Effect.fn(function* (scriptName: string) {
438 const settings = yield* workers
439 .getScriptScriptAndVersionSetting({ accountId: acct, scriptName })
440 .pipe(
441 Effect.catchTag(["WorkerNotFound", "WorkerHasNoVersions"], () => Effect.undefined),
442 );
443 return settings === undefined ? undefined : new Set(settings.tags ?? []);
444 });
445 const observedTags = yield* scriptTags(observed.scriptName);
446 let staleGeneration = observedTags === undefined;
447 if (observedTags !== undefined) {
448 const stack = yield* Stack;
449 const desiredTags = news.scriptName ? yield* scriptTags(news.scriptName) : undefined;
450 const observedId = Array.from(observedTags).find((t) => t.startsWith("alchemy:id:"));
451 staleGeneration =
452 observedId !== undefined &&
453 observedTags.has(`alchemy:stack:${stack.name}`) &&
454 observedTags.has(`alchemy:stage:${stack.stage}`) &&
455 desiredTags !== undefined &&
456 desiredTags.has(observedId) &&
457 desiredTags.has(`alchemy:stack:${stack.name}`) &&
458 desiredTags.has(`alchemy:stage:${stack.stage}`);
459 }
460 if (!staleGeneration) {
461 return yield* Effect.die(
462 `Cloudflare queue "${queueId}" already has a worker ` +
463 `consumer for script "${observed.scriptName}", but this ` +
464 `resource is configured for "${news.scriptName}" and ` +
465 `local state for the consumer was missing. Each queue ` +
466 `can have only one worker consumer — delete the ` +
467 `existing one, update scriptName to match, or restore ` +
468 `the consumer's state entry before redeploying.`,
469 );
470 }
471 yield* detachConsumer(observed.consumerId);
472 observed = undefined;
473 }
474
475 // Ensure — create if missing. ConsumerAlreadyExists is the
476 // race signal: another reconcile or peer beat us to it.
477 // Re-run the lookup; the paginated stream tolerates the
478 // single-page eventual-consistency window the previous
479 // implementation missed.
480 let consumerId: string;
481 if (!observed) {
482 const created = yield* queues
483 .createConsumer({
484 accountId: acct,
485 queueId,
486 scriptName: news.scriptName,
487 type: "worker",
488 deadLetterQueue: news.deadLetterQueue,
489 settings: news.settings,
490 })
491 .pipe(
492 // Two eventual-consistency races on a fresh deploy, both
493 // retried on the same bounded schedule:
494 // - QueueHandlerMissing (11001): the sibling Worker resource
495 // pre-creates a placeholder script with no `queue` handler;
496 // Cloudflare returns 11001 until the real reconcile uploads
497 // the handler.
498 // - QueueNotFound (11000): the queue was created earlier in
499 // this same plan but isn't yet visible to the consumers API.
500 Effect.tapError((e) =>
501 e._tag === "QueueHandlerMissing" || e._tag === "QueueNotFound"
502 ? Effect.logDebug(
503 `Consumer create: not ready for worker ` +
504 `"${news.scriptName}" (${e._tag}), retrying`,
505 )
506 : Effect.void,
507 ),
508 Effect.retry({
509 while: (e) => e._tag === "QueueHandlerMissing" || e._tag === "QueueNotFound",
510 schedule: queueHandlerReadinessSchedule,
511 }),
512 Effect.catchTag("ConsumerAlreadyExists", (cause) =>
513 Effect.gen(function* () {
514 const match = yield* findWorkerConsumer(acct, queueId);
515 if (!match) {
516 return yield* Effect.die(
517 `Cloudflare reported a worker consumer already ` +
518 `exists on queue "${queueId}", but listConsumers ` +
519 `returned none. Retry the deploy; if this ` +
520 `persists, the queue is in an inconsistent ` +
521 `state. Underlying error: ${cause.message}`,
522 );
523 }
524 if (match.scriptName !== undefined && match.scriptName !== news.scriptName) {
525 return yield* Effect.die(
526 `Cloudflare queue "${queueId}" already has a ` +
527 `worker consumer for script "${match.scriptName}", ` +
528 `but this resource is configured for ` +
529 `"${news.scriptName}". Each queue can have only ` +
530 `one worker consumer — delete the existing one ` +
531 `or update scriptName to match before redeploying.`,
532 );
533 }
534 return match;
535 }),
536 ),
537 );
538 consumerId = created.consumerId!;
539 } else {
540 consumerId = observed.consumerId;
541 }
542
543 // Sync — Cloudflare replaces all mutable fields on
544 // updateConsumer, so always issue this so adoption converges
545 // and settings drift gets corrected on every reconcile.
546 // updateConsumer hits the same "queue handler missing" race
547 // window as create when the worker is mid-upload, so apply
548 // the same bounded retry.
549 yield* queues
550 .updateConsumer({
551 accountId: acct,
552 queueId,
553 consumerId,
554 scriptName: news.scriptName,
555 type: "worker",
556 settings: news.settings,
557 deadLetterQueue: news.deadLetterQueue,
558 })
559 .pipe(
560 Effect.retry({
561 while: (e) => e._tag === "QueueHandlerMissing",
562 schedule: queueHandlerReadinessSchedule,
563 }),
564 );
565
566 yield* queues.getConsumer({ accountId: acct, queueId, consumerId }).pipe(
567 Effect.flatMap((fetched) =>
568 toObserved(fetched)?.scriptName === news.scriptName
569 ? Effect.void
570 : Effect.fail("ScriptUnbound" as const),
571 ),
572 Effect.catchTag("ConsumerNotFound", () => Effect.fail("ScriptUnbound" as const)),
573 Effect.retry({
574 while: (e) => e === "ScriptUnbound",
575 schedule: queueHandlerReadinessSchedule,
576 }),
577 );
578
579 return {
580 consumerId,
581 queueId,
582 scriptName: news.scriptName!,
583 accountId: acct,
584 deadLetterQueue: news.deadLetterQueue,
585 settings: news.settings,
586 };
587 }),
588 delete: Effect.fn(function* ({ output }) {
589 // If the consumerId is a `dev:` ID, the resource only exists locally, so we don't need to delete it from Cloudflare.
590 if (!isLiveId(output.consumerId)) return;
591
592 yield* queues
593 .deleteConsumer({
594 accountId: output.accountId,
595 queueId: output.queueId,
596 consumerId: output.consumerId,
597 })
598 .pipe(Effect.catchTag("ConsumerNotFound", () => Effect.void));
599
600 // Block until Cloudflare's worker subsystem stops claiming
601 // the script as a queue consumer. Without this the
602 // sibling Worker.delete races on `QueueConsumerConflict`
603 // (code 10064) — `deleteConsumer` returns success on the
604 // queue subsystem before the script-side view propagates.
605 yield* queues
606 .getConsumer({
607 accountId: output.accountId,
608 queueId: output.queueId,
609 consumerId: output.consumerId,
610 })
611 .pipe(
612 Effect.flatMap(() => Effect.fail("still-attached" as const)),
613 Effect.catchTag("ConsumerNotFound", () => Effect.void),
614 Effect.retry({
615 while: (e) => e === "still-attached",
616 schedule: Schedule.max([Schedule.spaced("1 second"), Schedule.recurs(30)]),
617 }),
618 Effect.ignore,
619 );
620 }),
621 read: Effect.fn(function* ({ output }) {
622 if (output?.consumerId) {
623 const fetched = yield* queues
624 .getConsumer({
625 accountId: output.accountId,
626 queueId: output.queueId,
627 consumerId: output.consumerId,
628 })
629 .pipe(Effect.catchTag("ConsumerNotFound", () => Effect.undefined));
630 if (fetched) {
631 return {
632 consumerId: fetched.consumerId!,
633 queueId: output.queueId,
634 scriptName: toObserved(fetched)?.scriptName ?? output.scriptName,
635 accountId: output.accountId,
636 deadLetterQueue: output.deadLetterQueue,
637 settings: output.settings,
638 };
639 }
640 }
641 // Fallback: a state loss can leave us without a consumerId
642 // even though the consumer is still alive on Cloudflare. The
643 // queue allows only one worker consumer, so finding it via
644 // listConsumers is unambiguous.
645 if (output?.queueId && output?.accountId) {
646 const match = yield* findWorkerConsumer(output.accountId, output.queueId);
647 if (match) {
648 return {
649 consumerId: match.consumerId,
650 queueId: output.queueId,
651 scriptName: match.scriptName ?? output.scriptName,
652 accountId: output.accountId,
653 deadLetterQueue: output.deadLetterQueue,
654 settings: output.settings,
655 };
656 }
657 }
658 return undefined;
659 }),
660 });
661
662 type ObservedConsumer = { consumerId: string; scriptName: string | undefined };
663
664 const toObserved = (c: {
665 consumerId?: string | null;
666 scriptName?: string | null;
667 type?: "worker" | "http_pull" | null;
668 }): ObservedConsumer | undefined =>
669 c.consumerId && c.type === "worker"
670 ? { consumerId: c.consumerId, scriptName: c.scriptName ?? undefined }
671 : undefined;
672
673 // ~60s budget — Worker reconcile uploads typically land in 2–10s,
674 // but a fresh container/asset deploy can stretch that.
675 const queueHandlerReadinessSchedule = Schedule.max([
676 Schedule.spaced("2 seconds"),
677 Schedule.recurs(30),
678 ]);
679
680 export const ConsumerProviderLocal = () =>
681 RpcProvider.effect(
682 Consumer,
683 LOCAL_PROVIDERS_URL,
684 Effect.gen(function* () {
685 const localRuntimeState = yield* LocalRuntimeState;
686
687 // Restart the locally running workerd instances (if any) for the
688 // given scripts so start-time queue-consumer wiring is re-read from
689 // `localRuntimeState.queueConsumers`. See `workerRestarts` on
690 // {@link LocalRuntimeState}.
691 const restartScripts = (scriptNames: ReadonlyArray<string>) =>
692 Effect.forEach(
693 scriptNames,
694 (scriptName) =>
695 MutableHashMap.get(localRuntimeState.workerRestarts, scriptName).pipe(
696 Option.match({ onNone: () => Effect.void, onSome: (restart) => restart }),
697 ),
698 { discard: true },
699 );
700
701 return {
702 list: () =>
703 Effect.sync(() => Array.from(MutableHashMap.values(localRuntimeState.queueConsumers))),
704 diff: Effect.fn(function* ({ news, output }) {
705 if (!output) return { action: "update" };
706 // A real (non-`dev:`) consumerId on a local-mode row is legacy
707 // damage from pre-stamping dev runs — replace so the new
708 // generation mints a true local identity (delete best-effort
709 // detaches the stray live consumer).
710 if (isLiveId(output.consumerId)) {
711 return { action: "replace" };
712 }
713 if (!isResolved(news)) return undefined;
714 const accountId = isLiveId(news.queueId)
715 ? (yield* yield* CloudflareEnvironment).accountId
716 : yield* localAccountId;
717 if (output.queueId !== news.queueId || output.accountId !== accountId) {
718 return { action: "replace" };
719 }
720 if (
721 JSON.stringify(output.settings ?? {}) !== JSON.stringify(news.settings ?? {}) ||
722 output.scriptName !== news.scriptName ||
723 output.deadLetterQueue !== news.deadLetterQueue
724 ) {
725 return { action: "update" };
726 }
727 // If the resource is a noop, add it to the local runtime state so it's available downstream.
728 // We do it here instead of in the reconcile function so it doesn't appear as an update.
729 MutableHashMap.set(localRuntimeState.queueConsumers, output.consumerId, output);
730 return { action: "noop" };
731 }),
732 read: Effect.fn(function* ({ output }) {
733 if (!output?.consumerId) return undefined;
734 return MutableHashMap.get(localRuntimeState.queueConsumers, output.consumerId).pipe(
735 Option.getOrUndefined,
736 );
737 }),
738 reconcile: Effect.fn(function* ({ news, output }) {
739 const accountId = isLiveId(news.queueId)
740 ? (yield* yield* CloudflareEnvironment).accountId
741 : yield* localAccountId;
742 // A LIVE queue (`Alchemy.remote()`) consumed by a LOCAL worker:
743 // Cloudflare only pushes to deployed consumers, so the local
744 // runtime drains the real queue via the HTTP pull API instead.
745 // Observe the queue (name + existing consumers) and ensure an
746 // `http_pull` consumer exists for the pull loop to lease from.
747 let queueName: string | undefined;
748 let pullConsumerId: string | undefined;
749 if (isLiveId(news.queueId)) {
750 const queue = yield* queues.getQueue({ accountId, queueId: news.queueId });
751 queueName = queue.queueName ?? undefined;
752 const existingPull = (queue.consumers ?? []).find((c) => c.type === "http_pull");
753 if (existingPull?.consumerId) {
754 pullConsumerId = existingPull.consumerId;
755 } else {
756 const created = yield* queues.createConsumer({
757 accountId,
758 queueId: news.queueId,
759 type: "http_pull",
760 settings: {
761 batchSize: news.settings?.batchSize,
762 maxRetries: news.settings?.maxRetries,
763 retryDelay: news.settings?.retryDelay,
764 },
765 });
766 pullConsumerId =
767 ("consumerId" in created ? created.consumerId : undefined) ?? undefined;
768 }
769 }
770 const consumer: Consumer["Attributes"] = {
771 // Never carry a real (non-`dev:`) consumer id forward onto a
772 // local row — it belongs to a live consumer this row no longer
773 // manages (legacy pre-stamping damage).
774 consumerId:
775 output?.consumerId && !isLiveId(output.consumerId)
776 ? output.consumerId
777 : `dev:${crypto.randomUUID()}`,
778 queueId: news.queueId,
779 scriptName: news.scriptName,
780 deadLetterQueue: news.deadLetterQueue,
781 accountId,
782 settings: news.settings,
783 queueName,
784 pullConsumerId,
785 };
786 MutableHashMap.set(localRuntimeState.queueConsumers, consumer.consumerId, consumer);
787 // A local workerd instance only reads its queue-consumer wiring
788 // at start time, and this reconcile races the sibling Worker's
789 // start (the Worker's `precreate` resolves `scriptName` before
790 // workerd is up). Restart any already-running instance so it
791 // picks up the new wiring; if the worker hasn't served yet this
792 // is a no-op and its first serve observes the map we just set.
793 yield* restartScripts(
794 output && output.scriptName !== consumer.scriptName
795 ? [output.scriptName, consumer.scriptName]
796 : [consumer.scriptName],
797 );
798 return consumer;
799 }),
800 delete: Effect.fn(function* ({ output }) {
801 MutableHashMap.remove(localRuntimeState.queueConsumers, output.consumerId);
802 yield* restartScripts([output.scriptName]);
803 // Legacy local-mode rows written before providerMode stamping can
804 // carry a real consumer's id — detach the live consumer too so
805 // migrating the row to a true local identity doesn't strand it on
806 // the queue (a stranded worker consumer blocks every future
807 // createConsumer with ConsumerAlreadyExists).
808 if (isLiveId(output.consumerId) && isLiveId(output.queueId)) {
809 yield* queues
810 .deleteConsumer({
811 accountId: output.accountId,
812 queueId: output.queueId,
813 consumerId: output.consumerId,
814 })
815 .pipe(Effect.catchTag(["ConsumerNotFound", "QueueNotFound"], () => Effect.void));
816 }
817 // Remove the http_pull consumer this row attached to its live
818 // queue. Idempotent: gone-already (or queue deleted first) is
819 // success.
820 if (output.pullConsumerId && isLiveId(output.queueId)) {
821 yield* queues
822 .deleteConsumer({
823 accountId: output.accountId,
824 queueId: output.queueId,
825 consumerId: output.pullConsumerId,
826 })
827 .pipe(Effect.catchTag(["ConsumerNotFound", "QueueNotFound"], () => Effect.void));
828 }
829 }),
830 };
831 }),
832 );
833
834 export const ConsumerProvider = () =>
835 ProviderLayer.dual(Consumer, {
836 local: () => ConsumerProviderLocal().pipe(Layer.provide(localRuntimeServices())),
837 live: () => ConsumerProviderLive(),
838 });