alchemy 2.0.0-beta.34 → 2.0.0-beta.35

package/src/Cloudflare/Queue/QueueConsumer.ts

@@ -1,11 +1,20 @@
 import * as queues from "@distilled.cloud/cloudflare/queues";
 import * as Effect from "effect/Effect";
+import * as Option from "effect/Option";
+import * as Schedule from "effect/Schedule";
+import * as Stream from "effect/Stream";
 import { isResolved } from "../../Diff.ts";
 import * as Provider from "../../Provider.ts";
 import { Resource } from "../../Resource.ts";
 import { CloudflareEnvironment } from "../CloudflareEnvironment.ts";
 import type { Providers } from "../Providers.ts";
 
+// ~60s budget — Worker reconcile uploads typically land in 2–10s,
+// but a fresh container/asset deploy can stretch that.
+const queueHandlerReadinessSchedule = Schedule.spaced("2 seconds").pipe(
+  Schedule.both(Schedule.recurs(30)),
+);
+
 export type QueueConsumerProps = {
   /**
    * The queue ID to attach the consumer to.
@@ -68,6 +77,11 @@ export type QueueConsumer = Resource<
  * Register a Worker as a consumer of a Queue. The Worker's `queue()`
  * handler will be invoked with batches of messages.
  *
+ * Cloudflare allows at most one Worker consumer per queue (HTTP-pull
+ * consumers can coexist). The reconciler enforces this: if the queue
+ * already has a Worker consumer pointing at a different script, the
+ * deploy fails with a clear error rather than silently adopting it.
+ *
  * @section Registering a Consumer
  * @example Basic consumer
  * ```typescript
@@ -97,6 +111,20 @@ export const QueueConsumer = Resource<QueueConsumer>(
   "Cloudflare.QueueConsumer",
 );
 
+type ObservedConsumer = {
+  consumerId: string;
+  script: string | undefined;
+};
+
+const toObserved = (c: {
+  consumerId?: string | null;
+  script?: string | null;
+  type?: "worker" | "http_pull" | null;
+}): ObservedConsumer | undefined =>
+  c.consumerId && c.type === "worker"
+    ? { consumerId: c.consumerId, script: c.script ?? undefined }
+    : undefined;
+
 export const QueueConsumerProvider = () =>
   Provider.effect(
     QueueConsumer,
@@ -106,7 +134,21 @@ export const QueueConsumerProvider = () =>
       const getConsumer = yield* queues.getConsumer;
       const updateConsumer = yield* queues.updateConsumer;
       const deleteConsumer = yield* queues.deleteConsumer;
-      const listConsumers = yield* queues.listConsumers;
+
+      // Cloudflare allows a single Worker consumer per queue, so the
+      // first match in the paginated stream is the only one. Using
+      // `.items` defeats single-page lookups that would otherwise
+      // miss late-arriving consumers under eventual consistency.
+      const findWorkerConsumer = (
+        acct: string,
+        queueId: string,
+      ): Effect.Effect<ObservedConsumer | undefined, any, any> =>
+        queues.listConsumers.items({ accountId: acct, queueId }).pipe(
+          Stream.map(toObserved),
+          Stream.filter((c): c is ObservedConsumer => c !== undefined),
+          Stream.runHead,
+          Effect.map(Option.getOrUndefined),
+        );
 
       return {
         stables: ["consumerId", "accountId"],
@@ -115,18 +157,29 @@ export const QueueConsumerProvider = () =>
           if ((output?.accountId ?? accountId) !== accountId) {
             return { action: "replace" } as const;
           }
-          // Queue change requires replacement
+          // Queue change requires replacement — consumerId is bound
+          // to a queue and the API has no "move consumer" verb.
           if (output?.queueId && news.queueId !== output.queueId) {
-            return { action: "replace" } as const;
-          }
-          // Script change requires replacement
-          if (output?.scriptName && news.scriptName !== output.scriptName) {
-            return { action: "replace" } as const;
+            return { action: "replace", deleteFirst: true } as const;
           }
-          // Settings change is an update
+          // Settings / DLQ / script drift is an update. We DON'T
+          // escalate scriptName changes to `replace` because the
+          // engine resolves cross-resource Output<string> refs (a
+          // sibling Worker's `workerName`) lazily — when the upstream
+          // Worker is created in the same plan, `news` is partially
+          // unresolved at diff time and `isResolved(news)` short-
+          // circuits up top. Falling through to "update" lets the
+          // engine call reconcile with fully-resolved `news`, where
+          // we detect script drift and rebuild the consumer in
+          // place (Cloudflare's PUT silently ignores `script_name`
+          // changes, so reconcile does delete-then-create).
           if (
             JSON.stringify(olds.settings ?? {}) !==
-            JSON.stringify(news.settings ?? {})
+              JSON.stringify(news.settings ?? {}) ||
+            (olds.deadLetterQueue ?? undefined) !==
+              (news.deadLetterQueue ?? undefined) ||
+            (output?.scriptName !== undefined &&
+              news.scriptName !== output.scriptName)
           ) {
             return { action: "update" } as const;
           }
@@ -136,33 +189,101 @@ export const QueueConsumerProvider = () =>
           const queueId =
             output?.queueId ?? (news.queueId as unknown as string);
 
-          // Observe — re-fetch the cached consumer; fall back to a list
-          // scan filtered by script so we recover from out-of-band
-          // deletes or partial state-persistence failures (the create
-          // call may have written the consumer but lost the response).
-          let observed:
-            | { consumerId?: string | null; script?: string | null }
-            | undefined;
+          // Observe — prefer the cached consumerId, then fall back to
+          // listConsumers (paginated) to recover from out-of-band
+          // deletes or partial state-persistence failures. Track
+          // whether the observation came from the cached id or the
+          // list scan: a different-script worker consumer found via
+          // the list scan is potentially foreign (state was lost,
+          // someone else attached the consumer), and silently
+          // updating it could clobber another team's wiring.
+          let observed: ObservedConsumer | undefined;
+          let owned = false;
           if (output?.consumerId) {
-            observed = yield* getConsumer({
+            const fetched = yield* getConsumer({
               accountId: acct,
-              queueId: output.queueId,
+              queueId,
               consumerId: output.consumerId,
-            }).pipe(Effect.catch(() => Effect.succeed(undefined)));
+            }).pipe(
+              Effect.catchTag("ConsumerNotFound", () =>
+                Effect.succeed(undefined),
+              ),
+            );
+            if (fetched) {
+              observed = toObserved(fetched);
+              owned = observed !== undefined;
+            }
           }
           if (!observed) {
-            const existing = yield* listConsumers({
+            observed = yield* findWorkerConsumer(acct, queueId);
+          }
+
+          // Owned consumer pointing at a different script: rebuild
+          // it in place. Cloudflare's PUT consumer silently ignores
+          // `script_name` changes on existing consumers (the live
+          // record stays pinned to the original worker), and the
+          // platform allows only one Worker consumer per queue, so
+          // the only path to re-point is delete-then-create.
+          if (
+            owned &&
+            observed &&
+            observed.script !== undefined &&
+            observed.script !== news.scriptName
+          ) {
+            yield* deleteConsumer({
               accountId: acct,
               queueId,
-            });
-            observed = existing.result.find(
-              (c) => "script" in c && c.script === news.scriptName,
+              consumerId: observed.consumerId,
+            }).pipe(Effect.catchTag("ConsumerNotFound", () => Effect.void));
+            // Wait for Cloudflare's worker subsystem to drop its
+            // claim on the old script so createConsumer below
+            // doesn't race the queue↔script propagation lag.
+            yield* getConsumer({
+              accountId: acct,
+              queueId,
+              consumerId: observed.consumerId,
+            }).pipe(
+              Effect.flatMap(() => Effect.fail("still-attached" as const)),
+              Effect.catchTag("ConsumerNotFound", () => Effect.void),
+              Effect.retry({
+                while: (e) => e === "still-attached",
+                schedule: Schedule.spaced("1 second").pipe(
+                  Schedule.both(Schedule.recurs(30)),
+                ),
+              }),
+              Effect.ignore,
             );
+            observed = undefined;
+            owned = false;
           }
 
-          // Ensure — create if missing. The Cloudflare API rejects a
-          // duplicate consumer (same queue + script), so we tolerate
-          // that race by adopting the existing one via list.
+          // Refuse to take over a foreign consumer on the state-loss
+          // path. With `owned=false` we found this via the list scan
+          // and the script mismatch means it belongs to another
+          // resource or was created out-of-band — silent adoption
+          // would clobber that.
+          if (
+            observed &&
+            !owned &&
+            observed.script !== undefined &&
+            observed.script !== news.scriptName
+          ) {
+            return yield* Effect.die(
+              `Cloudflare queue "${queueId}" already has a worker ` +
+                `consumer for script "${observed.script}", but this ` +
+                `resource is configured for "${news.scriptName}" and ` +
+                `local state for the consumer was missing. Each queue ` +
+                `can have only one worker consumer — delete the ` +
+                `existing one, update scriptName to match, or restore ` +
+                `the consumer's state entry before redeploying.`,
+            );
+          }
+
+          // Ensure — create if missing. ConsumerAlreadyExists is the
+          // race signal: another reconcile or peer beat us to it.
+          // Re-run the lookup; the paginated stream tolerates the
+          // single-page eventual-consistency window the previous
+          // implementation missed.
           let consumerId: string;
           if (!observed) {
             const created = yield* createConsumer({
@@ -173,41 +294,79 @@ export const QueueConsumerProvider = () =>
               deadLetterQueue: news.deadLetterQueue,
               settings: news.settings,
             }).pipe(
-              Effect.catch(() =>
+              // The sibling Worker resource pre-creates a placeholder
+              // script with no `queue` handler; Cloudflare returns
+              // code 11001 until the real reconcile uploads the
+              // handler. Retry until the upload propagates (capped),
+              // then surface a real failure if it never does.
+              Effect.tapError((e) =>
+                e._tag === "QueueHandlerMissing"
+                  ? Effect.logDebug(
+                      `QueueConsumer create: worker ` +
+                        `"${news.scriptName}" has no queue handler ` +
+                        `yet (code 11001), retrying`,
+                    )
+                  : Effect.void,
+              ),
+              Effect.retry({
+                while: (e) => e._tag === "QueueHandlerMissing",
+                schedule: queueHandlerReadinessSchedule,
+              }),
+              Effect.catchTag("ConsumerAlreadyExists", (cause) =>
                 Effect.gen(function* () {
-                  const existing = yield* listConsumers({
-                    accountId: acct,
-                    queueId,
-                  });
-                  const match = existing.result.find(
-                    (c) => "script" in c && c.script === news.scriptName,
-                  );
-                  if (match && match.consumerId) {
-                    return match;
+                  const match = yield* findWorkerConsumer(acct, queueId);
+                  if (!match) {
+                    return yield* Effect.die(
+                      `Cloudflare reported a worker consumer already ` +
+                        `exists on queue "${queueId}", but listConsumers ` +
+                        `returned none. Retry the deploy; if this ` +
+                        `persists, the queue is in an inconsistent ` +
+                        `state. Underlying error: ${cause.message}`,
+                    );
                   }
-                  return yield* Effect.die(
-                    `Consumer for script "${news.scriptName}" on queue "${queueId}" already exists but could not be found`,
-                  );
+                  if (
+                    match.script !== undefined &&
+                    match.script !== news.scriptName
+                  ) {
+                    return yield* Effect.die(
+                      `Cloudflare queue "${queueId}" already has a ` +
+                        `worker consumer for script "${match.script}", ` +
+                        `but this resource is configured for ` +
+                        `"${news.scriptName}". Each queue can have only ` +
+                        `one worker consumer — delete the existing one ` +
+                        `or update scriptName to match before redeploying.`,
+                    );
+                  }
+                  return match;
                 }),
               ),
             );
             consumerId = created.consumerId!;
           } else {
-            consumerId = observed.consumerId!;
-            // Sync — update settings and dead-letter target on the
-            // existing consumer. The Cloudflare API replaces all mutable
-            // fields per call, so always issue this so adoption converges.
-            yield* updateConsumer({
-              accountId: acct,
-              queueId,
-              consumerId,
-              scriptName: news.scriptName,
-              type: "worker",
-              settings: news.settings,
-              deadLetterQueue: news.deadLetterQueue,
-            });
+            consumerId = observed.consumerId;
           }
 
+          // Sync — Cloudflare replaces all mutable fields on
+          // updateConsumer, so always issue this so adoption converges
+          // and settings drift gets corrected on every reconcile.
+          // updateConsumer hits the same "queue handler missing" race
+          // window as create when the worker is mid-upload, so apply
+          // the same bounded retry.
+          yield* updateConsumer({
+            accountId: acct,
+            queueId,
+            consumerId,
+            scriptName: news.scriptName,
+            type: "worker",
+            settings: news.settings,
+            deadLetterQueue: news.deadLetterQueue,
+          }).pipe(
+            Effect.retry({
+              while: (e) => e._tag === "QueueHandlerMissing",
+              schedule: queueHandlerReadinessSchedule,
+            }),
+          );
+
           return {
             consumerId,
             queueId,
@@ -220,26 +379,69 @@ export const QueueConsumerProvider = () =>
             accountId: output.accountId,
             queueId: output.queueId,
             consumerId: output.consumerId,
-          }).pipe(Effect.catch(() => Effect.void));
+          }).pipe(Effect.catchTag("ConsumerNotFound", () => Effect.void));
+
+          // Block until Cloudflare's worker subsystem stops claiming
+          // the script as a queue consumer. Without this the
+          // sibling Worker.delete races on `QueueConsumerConflict`
+          // (code 10064) — `deleteConsumer` returns success on the
+          // queue subsystem before the script-side view propagates.
+          yield* getConsumer({
+            accountId: output.accountId,
+            queueId: output.queueId,
+            consumerId: output.consumerId,
+          }).pipe(
+            Effect.flatMap(() => Effect.fail("still-attached" as const)),
+            Effect.catchTag("ConsumerNotFound", () => Effect.void),
+            Effect.retry({
+              while: (e) => e === "still-attached",
+              schedule: Schedule.spaced("1 second").pipe(
+                Schedule.both(Schedule.recurs(30)),
+              ),
+            }),
+            Effect.ignore,
+          );
         }),
         read: Effect.fn(function* ({ output }) {
           if (output?.consumerId) {
-            return yield* getConsumer({
+            const fetched = yield* getConsumer({
               accountId: output.accountId,
               queueId: output.queueId,
               consumerId: output.consumerId,
             }).pipe(
-              Effect.map((consumer) => ({
-                consumerId: consumer.consumerId!,
+              Effect.catchTag("ConsumerNotFound", () =>
+                Effect.succeed(undefined),
+              ),
+            );
+            if (fetched) {
+              return {
+                consumerId: fetched.consumerId!,
                 queueId: output.queueId,
                 scriptName:
-                  ("script" in consumer
-                    ? (consumer.script as string)
+                  ("script" in fetched && typeof fetched.script === "string"
+                    ? fetched.script
                     : output.scriptName) ?? output.scriptName,
                 accountId: output.accountId,
-              })),
-              Effect.catch(() => Effect.succeed(undefined)),
+              };
+            }
+          }
+          // Fallback: a state loss can leave us without a consumerId
+          // even though the consumer is still alive on Cloudflare. The
+          // queue allows only one worker consumer, so finding it via
+          // listConsumers is unambiguous.
+          if (output?.queueId && output?.accountId) {
+            const match = yield* findWorkerConsumer(
+              output.accountId,
+              output.queueId,
             );
+            if (match) {
+              return {
+                consumerId: match.consumerId,
+                queueId: output.queueId,
+                scriptName: match.script ?? output.scriptName,
+                accountId: output.accountId,
+              };
+            }
           }
           return undefined;
         }),

package/src/Cloudflare/Queue/QueueEventSource.ts

@@ -0,0 +1,234 @@
+import type * as cf from "@cloudflare/workers-types";
+import * as Cause from "effect/Cause";
+import * as Context from "effect/Context";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as Stream from "effect/Stream";
+import * as Binding from "../../Binding.ts";
+import type { ResourceLike } from "../../Resource.ts";
+import { RuntimeContext } from "../../RuntimeContext.ts";
+import type { FunctionContext } from "../../Serverless/Function.ts";
+import { isWorker, isWorkerEvent } from "../Workers/Worker.ts";
+import type { Queue } from "./Queue.ts";
+import { QueueConsumer } from "./QueueConsumer.ts";
+
+/**
+ * Subscriber settings — the same shape Cloudflare's `QueueConsumer`
+ * accepts. `messages(queue, props).subscribe(...)` passes these
+ * through to the auto-created `Cloudflare.QueueConsumer` so a single
+ * call captures both runtime and deploy-time intent.
+ */
+export interface MessagesProps {
+  /** Maximum messages per batch. */
+  batchSize?: number;
+  /** Maximum concurrent invocations. */
+  maxConcurrency?: number;
+  /** Maximum delivery attempts before dead-lettering. */
+  maxRetries?: number;
+  /** Wait time, in ms, before flushing a partial batch. */
+  maxWaitTimeMs?: number;
+  /** Backoff, in seconds, applied to a retry. */
+  retryDelay?: number;
+  /** Optional dead-letter queue name. */
+  deadLetterQueue?: string;
+}
+
+/**
+ * A single queue message handed to the subscribe handler. Mirrors
+ * Cloudflare's runtime `Message<Body>` shape so per-message
+ * `ack()` / `retry()` semantics match the platform docs.
+ */
+export type QueueMessage<Body = unknown> = cf.Message<Body>;
+
+/**
+ * Subscribe to a Cloudflare Queue with an Effect stream handler.
+ *
+ * Mirrors `AWS.SQS.messages(queue).subscribe(...)` on the
+ * Cloudflare side. Wires both halves of the consumer in one call:
+ *
+ * - **Runtime**: registers a `queue` event listener on the Worker.
+ *   Each batch is piped through `process` as a `Stream.Stream`.
+ * - **Deploy-time**: yields a `Cloudflare.QueueConsumer` resource
+ *   so Cloudflare actually dispatches messages from `queue` to
+ *   this Worker. No manual `QueueConsumer` wiring needed in
+ *   `alchemy.run.ts`.
+ *
+ * Acking semantics: if `process` succeeds, every message in the
+ * batch is `ack()`ed; if it fails, every message is `retry()`ed
+ * and Cloudflare applies `maxRetries` / `retryDelay` from the
+ * settings before dead-lettering. Per-message control is still
+ * available by calling `msg.ack()` / `msg.retry()` inside the
+ * handler.
+ *
+ * @example
+ * ```typescript
+ * import * as Cloudflare from "alchemy/Cloudflare";
+ * import * as Effect from "effect/Effect";
+ * import * as Stream from "effect/Stream";
+ *
+ * yield* Cloudflare.messages<MyEvent>(queueResource, {
+ *   batchSize: 25,
+ *   maxRetries: 3,
+ * }).subscribe((stream) =>
+ *   Stream.runForEach(stream, (msg) =>
+ *     Effect.log(`event ${msg.body.id}`),
+ *   ),
+ * );
+ * ```
+ */
+export const messages = <Body = unknown>(
+  queue: Queue,
+  props: MessagesProps = {},
+) => ({
+  subscribe: <Req = never>(
+    process: (
+      stream: Stream.Stream<QueueMessage<Body>>,
+    ) => Effect.Effect<void, unknown, Req>,
+  ) =>
+    QueueEventSource.use((source) => source<Body, Req>(queue, props, process)),
+});
+
+// `Req` is the handler's requirements. The service registers the
+// handler with the Worker's runtime context, where the runtime
+// machinery provides bindings and `WorkerEnvironment` when the
+// dispatch fires — so the requirement is satisfied at handler
+// invocation, NOT at subscribe time. We drop `Req` from the return
+// to keep init effects clean (mirrors `AWS.SQS.QueueEventSourceService`).
+export type QueueEventSourceService = <Body = unknown, Req = never>(
+  queue: Queue,
+  props: MessagesProps,
+  process: (
+    stream: Stream.Stream<QueueMessage<Body>>,
+  ) => Effect.Effect<void, unknown, Req>,
+) => Effect.Effect<void, never, never>;
+
+/**
+ * Service tag for the Cloudflare Queue event source. Provided by
+ * {@link QueueEventSourceLive} on the Worker's runtime layer.
+ */
+export class QueueEventSource extends Context.Service<
+  QueueEventSource,
+  QueueEventSourceService
+>()("Cloudflare.Queue.QueueEventSource") {}
+
+/**
+ * Deploy-time policy that yields a `Cloudflare.QueueConsumer`
+ * resource pointing the host Worker at the queue. Provided in
+ * `Cloudflare.providers()` and used by {@link QueueEventSourceLive}
+ * via `yield* QueueEventSourcePolicy(...)`. At runtime the policy
+ * is absent, so the call is a no-op.
+ */
+export class QueueEventSourcePolicy extends Binding.Policy<
+  QueueEventSourcePolicy,
+  (queue: Queue, props: MessagesProps) => Effect.Effect<void>
+>()("Cloudflare.Queue.QueueEventSource") {}
+
+export const QueueEventSourcePolicyLive = QueueEventSourcePolicy.layer.succeed(
+  // Cast: yielding `QueueConsumer(...)` requires the Cloudflare
+  // `Providers` services, which the deploy-time stack provides
+  // when this policy runs (the worker's init scope inherits the
+  // stack's services). `Binding.Policy.layer.succeed` types the
+  // body as `Effect<void, never, never>` to keep most policies
+  // simple; we step around that constraint here because we
+  // genuinely need to spawn a sibling resource at deploy time.
+  ((host: ResourceLike, queue: Queue, props: MessagesProps) =>
+    Effect.gen(function* () {
+      if (!isWorker(host)) {
+        return yield* Effect.die(
+          `Cloudflare.messages(...).subscribe(...) is only supported on ` +
+            `Cloudflare.Worker hosts (got '${host.Type}').`,
+        );
+      }
+      // Yield the QueueConsumer resource as a sibling of the
+      // Worker. The engine creates / updates / destroys it
+      // alongside the Worker's lifecycle; the consumer's
+      // reconciler waits for the Worker upload to expose the
+      // `queue` handler before completing (see PR #257 for the
+      // 11001 retry).
+      yield* QueueConsumer(`${queue.LogicalId}Consumer`, {
+        queueId: queue.queueId,
+        scriptName: host.workerName,
+        settings: props,
+        deadLetterQueue: props.deadLetterQueue,
+      });
+    })) as unknown as (
+    host: ResourceLike,
+    queue: Queue,
+    props: MessagesProps,
+  ) => Effect.Effect<void>,
+);
+
+/**
+ * Runtime layer for {@link messages}. Wires each
+ * `messages(queue).subscribe(...)` call in the Worker init phase to
+ * a `queue` event listener on the runtime context, and asks the
+ * deploy-time policy ({@link QueueEventSourcePolicy}, provided in
+ * `Cloudflare.providers()`) to yield the matching
+ * `Cloudflare.QueueConsumer` resource.
+ *
+ * Provide alongside other Cloudflare runtime layers (e.g.
+ * `QueueBindingLive`) on the Worker effect.
+ */
+export const QueueEventSourceLive = Layer.effect(
+  QueueEventSource,
+  Effect.gen(function* () {
+    const policy = yield* QueueEventSourcePolicy;
+    return Effect.fn(function* <Body, Req>(
+      queue: Queue,
+      props: MessagesProps,
+      process: (
+        stream: Stream.Stream<QueueMessage<Body>>,
+      ) => Effect.Effect<void, unknown, Req>,
+    ) {
+      // Deploy-time: ensure the QueueConsumer resource exists. At
+      // runtime this Layer's `policy` resolves to the no-op variant
+      // (Binding.Policy provides that automatically via
+      // `Effect.serviceOption`), so this becomes a no-op.
+      yield* policy(queue, props);
+
+      // Resolve the runtime context per-call rather than at layer
+      // construction. Capturing it on the layer would leak the
+      // requirement past `PlatformServices` exclusion when the
+      // Worker typechecks its init effect.
+      const ctx = (yield* RuntimeContext) as unknown as FunctionContext;
+      // Capture the queue-name accessor once; the listener body
+      // re-resolves it per event via `yield* QueueName`. A worker
+      // can consume multiple queues — each subscribe registers its
+      // own listener and they all see every queue event, so the
+      // queue-name match is what scopes the handler.
+      const QueueName = yield* queue.queueName;
+
+      yield* ctx.listen<void, Req>((event) => {
+        if (!isWorkerEvent(event) || event.type !== "queue") return;
+        const batch = event.input as cf.MessageBatch<Body>;
+
+        return Effect.gen(function* () {
+          const queueName = yield* QueueName;
+          if (batch.queue !== queueName) return;
+
+          yield* process(Stream.fromIterable(batch.messages)).pipe(
+            Effect.tap(() =>
+              Effect.sync(() => {
+                for (const msg of batch.messages) msg.ack();
+              }),
+            ),
+            Effect.onError((cause) =>
+              Effect.sync(() => {
+                // Surface the failure so the operator sees what
+                // tripped the retry path; without this the only
+                // signal is the message reappearing on the next
+                // attempt.
+                console.error(
+                  `[QueueEventSource] handler failed on queue ` +
+                    `"${queueName}": ${Cause.pretty(cause)}`,
+                );
+                for (const msg of batch.messages) msg.retry();
+              }),
+            ),
+            Effect.catchCause(() => Effect.void),
+          );
+        });
+      });
+    }) as QueueEventSourceService;
+  }),
+);

package/src/Cloudflare/Queue/index.ts

@@ -1,3 +1,4 @@
 export * from "./Queue.ts";
 export * from "./QueueBinding.ts";
 export * from "./QueueConsumer.ts";
+export * from "./QueueEventSource.ts";