The best way to control Claude Code, Codex and more from any computer or phone
| 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 | }); |