@swirls/looms 0.3.0 → 0.5.0

package/dist/cloudflare/memory-queue.d.ts

@@ -0,0 +1,18 @@
+import { Effect } from 'effect';
+import type { QueueBatchLike } from './queue-consumer';
+import type { QueueEffectMessage } from './queue-message';
+import type { QueuePullSource } from './queue-pull';
+import type { QueueProducer } from './queue-worker';
+export interface MemoryQueueOptions {
+    /** Redeliveries before a message moves to the dead-letter list. Default 3, as on Cloudflare. */
+    readonly maxRetries?: number;
+}
+/** A queue in process memory with Cloudflare's lease, retry, and dead-letter behavior. */
+export interface MemoryQueue extends QueueProducer, QueuePullSource {
+    /** Messages still held, leased or not. */
+    size(): number;
+    deadLetters(): ReadonlyArray<QueueEffectMessage>;
+    /** Lease visible messages as a push batch, the way a Worker's `queue` handler receives them. */
+    batch(size?: number): Effect.Effect<QueueBatchLike>;
+}
+export declare function createMemoryQueue(options?: MemoryQueueOptions): MemoryQueue;

package/dist/cloudflare/memory-queue.js

@@ -0,0 +1,53 @@
+import { Clock, Effect } from 'effect';
+export function createMemoryQueue(options = {}) {
+    const maxRetries = options.maxRetries ?? 3;
+    let entries = [];
+    const dead = [];
+    let nextLease = 0;
+    const settleAt = (now, acks, retries) => {
+        entries = entries.filter((entry) => entry.leaseId === undefined || !acks.includes(entry.leaseId));
+        for (const retry of retries) {
+            const entry = entries.find((candidate) => candidate.leaseId === retry.leaseId);
+            if (entry) {
+                entry.leaseId = undefined;
+                entry.visibleAt = now + retry.delaySeconds * 1_000;
+            }
+        }
+    };
+    const pull = (batchSize, visibilityTimeoutMs) => Effect.map(Clock.currentTimeMillis, (now) => {
+        const visible = entries.filter((entry) => entry.visibleAt <= now);
+        const exhausted = visible.filter((entry) => entry.deliveries > maxRetries);
+        dead.push(...exhausted.map((entry) => entry.body));
+        entries = entries.filter((entry) => !exhausted.includes(entry));
+        const leased = visible
+            .filter((entry) => entry.deliveries <= maxRetries)
+            .slice(0, batchSize)
+            .map((entry) => {
+            nextLease += 1;
+            entry.deliveries += 1;
+            entry.visibleAt = now + visibilityTimeoutMs;
+            entry.leaseId = `lease_${nextLease}`;
+            return { leaseId: entry.leaseId, body: entry.body, attempts: entry.deliveries };
+        });
+        return { messages: leased, backlog: entries.length };
+    });
+    const settle = (acks, retries) => Effect.map(Clock.currentTimeMillis, (now) => settleAt(now, acks, retries));
+    return {
+        send: (message) => {
+            entries.push({ body: message, deliveries: 0, visibleAt: 0, leaseId: undefined });
+            return Promise.resolve();
+        },
+        pull,
+        settle,
+        size: () => entries.length,
+        deadLetters: () => [...dead],
+        batch: (size = 100) => pull(size, 30_000).pipe(Effect.map(({ messages }) => ({
+            messages: messages.map((message) => ({
+                body: message.body,
+                attempts: message.attempts,
+                ack: () => Effect.runSync(settle([message.leaseId], [])),
+                retry: (retry) => Effect.runSync(settle([], [{ leaseId: message.leaseId, delaySeconds: retry?.delaySeconds ?? 0 }])),
+            })),
+        }))),
+    };
+}

package/dist/cloudflare/queue-consumer.d.ts

@@ -0,0 +1,52 @@
+import { Effect } from 'effect';
+import { type BlobStore, type EventInput, type JsonValue, type SecretContext, type WorkerCallback, type WorkerCallbackInput, type WorkerCallbackResult, type WorkerSecretsResult } from '@swirls/looms/core';
+import { type QueueEffectMessage, type QueueMessageLike } from './queue-message';
+/** The worker half of the Looms HTTP API. `createLoomsClient({ baseUrl, workerCallbackToken })` is one. */
+export interface WorkerCallbackClient {
+    workerCallback(runId: string, input: WorkerCallbackInput): Promise<WorkerCallbackResult>;
+    workerSecrets(runId: string, attempt: WorkerCallback): Promise<WorkerSecretsResult>;
+}
+/** The attempt a handler runs, with its input read back from the blob store when it was offloaded. */
+export interface QueueTask extends Omit<QueueEffectMessage, 'v' | 'input' | 'inputRef'> {
+    readonly input: JsonValue;
+}
+export interface QueueTaskContext {
+    /** Aborts once Looms asks the attempt to stop or no longer counts it as running. */
+    readonly signal: AbortSignal;
+    /** Report progress. A later attempt receives the last `details` as `task.details`. */
+    heartbeat(details?: JsonValue): Promise<void>;
+    /** The run's secret context. Rejects once the attempt is no longer running. */
+    secrets(): Promise<SecretContext>;
+}
+export type QueueTaskHandler = (task: QueueTask, ctx: QueueTaskContext) => Promise<ReadonlyArray<EventInput>> | ReadonlyArray<EventInput>;
+declare const QueueTaskError_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("effect/Cause").YieldableError & {
+    readonly _tag: "QueueTaskError";
+} & Readonly<A>;
+/** Throw from a handler to control how Looms treats the failed attempt. */
+export declare class QueueTaskError extends QueueTaskError_base<{
+    readonly message: string;
+    /** Fail the effect even when the retry policy has attempts left. */
+    readonly nonRetryable?: boolean;
+    /** Wait at least this long before the next attempt. */
+    readonly retryAfterMs?: number;
+}> {
+}
+export interface QueueConsumerOptions {
+    readonly handlers: Readonly<Record<string, QueueTaskHandler>>;
+    readonly callbacks: WorkerCallbackClient;
+    /** Reads inputs the producer offloaded. Use the store the producer writes to. */
+    readonly blobs?: BlobStore;
+}
+export interface QueueBatchLike {
+    readonly messages: ReadonlyArray<QueueMessageLike>;
+}
+/**
+ * Run one delivery. The message is acked as soon as Looms accepts `started`, and Looms owns every
+ * retry after that through heartbeat and start-to-close timeouts. A duplicate or stale delivery is
+ * acked without running. A message that cannot be started yet is retried by the queue, and one that
+ * never starts ends in the dead-letter queue, where the schedule-to-start timeout recovers it.
+ */
+export declare function processQueueMessage(message: QueueMessageLike, options: QueueConsumerOptions): Effect.Effect<void>;
+/** A push consumer: call it from the Worker's `queue(batch)` handler. */
+export declare function queueConsumer(options: QueueConsumerOptions): (batch: QueueBatchLike) => Promise<void>;
+export {};

package/dist/cloudflare/queue-consumer.js

@@ -0,0 +1,102 @@
+import { Data, Effect } from 'effect';
+import { resolveJson, } from '@swirls/looms/core';
+import { readQueueEffectMessage, } from './queue-message.js';
+/** Throw from a handler to control how Looms treats the failed attempt. */
+export class QueueTaskError extends Data.TaggedError('QueueTaskError') {
+}
+class CallbackError extends Data.TaggedError('CallbackError') {
+}
+/**
+ * Run one delivery. The message is acked as soon as Looms accepts `started`, and Looms owns every
+ * retry after that through heartbeat and start-to-close timeouts. A duplicate or stale delivery is
+ * acked without running. A message that cannot be started yet is retried by the queue, and one that
+ * never starts ends in the dead-letter queue, where the schedule-to-start timeout recovers it.
+ */
+export function processQueueMessage(message, options) {
+    const task = readQueueEffectMessage(message);
+    const handler = task && options.handlers[task.type];
+    const redeliver = Effect.sync(() => message.retry({ delaySeconds: redeliveryDelay(message.attempts) }));
+    if (!task || !handler) {
+        return redeliver;
+    }
+    const attempt = { effectId: task.effectId, attempt: task.attempt };
+    return callback(() => options.callbacks.workerCallback(task.runId, { ...attempt, kind: 'started' })).pipe(Effect.matchEffect({
+        onFailure: () => redeliver,
+        onSuccess: (started) => Effect.sync(() => message.ack()).pipe(Effect.andThen(started.status === 'accepted'
+            ? runAttempt(task, attempt, handler, started.cancelRequested, options)
+            : Effect.void)),
+    }));
+}
+/** A push consumer: call it from the Worker's `queue(batch)` handler. */
+export function queueConsumer(options) {
+    return (batch) => Effect.runPromise(Effect.forEach(batch.messages, (message) => processQueueMessage(message, options), {
+        concurrency: 'unbounded',
+        discard: true,
+    }));
+}
+function runAttempt(task, attempt, handler, cancelRequested, options) {
+    const controller = new AbortController();
+    if (cancelRequested) {
+        controller.abort();
+    }
+    const report = (input) => callback(() => options.callbacks.workerCallback(task.runId, input)).pipe(Effect.ignore);
+    const ctx = {
+        signal: controller.signal,
+        heartbeat: (details) => Effect.runPromise(callback(() => options.callbacks.workerCallback(task.runId, details === undefined
+            ? { ...attempt, kind: 'heartbeat' }
+            : { ...attempt, kind: 'heartbeat', details })).pipe(Effect.map((result) => {
+            if (result.status !== 'accepted' || result.cancelRequested) {
+                controller.abort();
+            }
+        }))),
+        secrets: () => Effect.runPromise(callback(() => options.callbacks.workerSecrets(task.runId, attempt)).pipe(Effect.flatMap((result) => {
+            if (result.status === 'accepted') {
+                return Effect.succeed(result.secrets);
+            }
+            controller.abort();
+            return Effect.fail(new CallbackError({ message: `the attempt is ${result.status}` }));
+        }))),
+    };
+    return taskInput(task, options.blobs).pipe(Effect.flatMap((input) => Effect.tryPromise({
+        try: () => Promise.resolve(handler({ ...taskFields(task), input }, ctx)),
+        catch: (cause) => cause instanceof QueueTaskError
+            ? cause
+            : new QueueTaskError({
+                message: cause instanceof Error ? cause.message : String(cause),
+            }),
+    })), Effect.matchEffect({
+        onSuccess: (events) => report({ ...attempt, kind: 'complete', events }),
+        onFailure: (error) => report(controller.signal.aborted
+            ? { ...attempt, kind: 'cancelled' }
+            : {
+                ...attempt,
+                kind: 'fail',
+                error: error.message,
+                nonRetryable: error.nonRetryable,
+                retryAfterMs: error.retryAfterMs,
+            }),
+    }));
+}
+function taskFields(task) {
+    const { v: _v, input: _input, inputRef: _inputRef, ...fields } = task;
+    return fields;
+}
+function taskInput(task, blobs) {
+    if (!task.inputRef) {
+        return Effect.succeed(task.input ?? null);
+    }
+    if (!blobs) {
+        return Effect.fail(new QueueTaskError({ message: 'the input was offloaded and the consumer has no blob store' }));
+    }
+    return resolveJson(task.inputRef, blobs).pipe(Effect.mapError((error) => new QueueTaskError({ message: `could not read the input: ${error.message}` })));
+}
+function callback(call) {
+    return Effect.tryPromise({
+        try: call,
+        catch: (cause) => new CallbackError({ message: cause instanceof Error ? cause.message : String(cause) }),
+    });
+}
+/** Seconds before the queue redelivers a message that could not start: 1, 2, 4, ... up to 60. */
+function redeliveryDelay(attempts) {
+    return Math.min(60, 2 ** Math.max(0, attempts - 1));
+}

package/dist/cloudflare/queue-message.d.ts

@@ -0,0 +1,31 @@
+import { type BlobRef, type JsonValue, type TraceContext } from '@swirls/looms/core';
+import type { EffectWorkerDeadlines } from '@swirls/looms/runtime';
+/**
+ * One effect attempt on a Cloudflare Queue. It never carries the run's secrets; the consumer reads
+ * them through the worker callback API. Exactly one of `input` and `inputRef` is set.
+ */
+export interface QueueEffectMessage {
+    readonly v: 1;
+    readonly runId: string;
+    readonly effectId: string;
+    readonly attempt: number;
+    readonly type: string;
+    readonly input?: JsonValue;
+    /** Set instead of `input` when the input would push the message over the queue's size limit. */
+    readonly inputRef?: BlobRef;
+    /** Progress from the previous attempt's last heartbeat. */
+    readonly details?: JsonValue;
+    readonly trace?: TraceContext;
+    readonly deadlines?: EffectWorkerDeadlines;
+}
+/** A delivered message, shaped like a Cloudflare `Message`. */
+export interface QueueMessageLike {
+    readonly body: unknown;
+    readonly attempts: number;
+    ack(): void;
+    retry(options?: {
+        readonly delaySeconds?: number;
+    }): void;
+}
+/** `undefined` unless the body is a version 1 message with exactly one of `input` and `inputRef`. */
+export declare function readQueueEffectMessage(message: QueueMessageLike): QueueEffectMessage | undefined;

package/dist/cloudflare/queue-message.js

@@ -0,0 +1,33 @@
+import { Option, Schema } from 'effect';
+import { isBlobRef, TraceContextSchema, } from '@swirls/looms/core';
+const QueueEffectMessageSchema = Schema.Struct({
+    v: Schema.Literal(1),
+    runId: Schema.String,
+    effectId: Schema.String,
+    attempt: Schema.Finite,
+    type: Schema.String,
+    input: Schema.optional(Schema.Json),
+    inputRef: Schema.optional(Schema.Json),
+    details: Schema.optional(Schema.Json),
+    trace: Schema.optional(TraceContextSchema),
+    deadlines: Schema.optional(Schema.Struct({
+        scheduleToStartAt: Schema.optional(Schema.Finite),
+        startToCloseTimeoutMs: Schema.optional(Schema.Finite),
+        heartbeatTimeoutMs: Schema.optional(Schema.Finite),
+    })),
+});
+const decodeMessage = Schema.decodeUnknownOption(QueueEffectMessageSchema);
+/** `undefined` unless the body is a version 1 message with exactly one of `input` and `inputRef`. */
+export function readQueueEffectMessage(message) {
+    return Option.match(decodeMessage(message.body), {
+        onNone: () => undefined,
+        onSome: ({ inputRef, ...decoded }) => {
+            if (inputRef === undefined) {
+                return decoded.input === undefined ? undefined : decoded;
+            }
+            return decoded.input === undefined && isBlobRef(inputRef)
+                ? { ...decoded, inputRef }
+                : undefined;
+        },
+    });
+}

package/dist/cloudflare/queue-pull.d.ts

@@ -0,0 +1,62 @@
+import { Effect } from 'effect';
+import { type QueueConsumerOptions } from './queue-consumer';
+export interface PulledQueueMessage {
+    readonly leaseId: string;
+    readonly body: unknown;
+    /** Deliveries so far, including this one. */
+    readonly attempts: number;
+}
+export interface QueuePullResult {
+    readonly messages: ReadonlyArray<PulledQueueMessage>;
+    /** Messages waiting in the queue, when the source reports it. */
+    readonly backlog?: number;
+}
+export interface QueueLeaseRetry {
+    readonly leaseId: string;
+    readonly delaySeconds: number;
+}
+declare const QueuePullError_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("effect/Cause").YieldableError & {
+    readonly _tag: "QueuePullError";
+} & Readonly<A>;
+export declare class QueuePullError extends QueuePullError_base<{
+    readonly message: string;
+    readonly status?: number;
+}> {
+}
+/** Where a pull consumer leases messages from. `cloudflareQueuePullSource` reads a Cloudflare Queue. */
+export interface QueuePullSource {
+    readonly pull: (batchSize: number, visibilityTimeoutMs: number) => Effect.Effect<QueuePullResult, QueuePullError>;
+    readonly settle: (acks: ReadonlyArray<string>, retries: ReadonlyArray<QueueLeaseRetry>) => Effect.Effect<void, QueuePullError>;
+}
+export interface QueuePullConsumerOptions extends QueueConsumerOptions {
+    readonly source: QueuePullSource;
+    /** Attempts run at once. Default 8. */
+    readonly concurrency?: number;
+    /** How long a leased message stays hidden. Acks land long before; default 30 s. */
+    readonly visibilityTimeoutMs?: number;
+    /** The longest wait between pulls that come back empty or fail. Default 5 s. */
+    readonly maxIdleMs?: number;
+    /** How often buffered acks and retries are sent. Default 250 ms. */
+    readonly ackIntervalMs?: number;
+    /** A pull or ack request failed. The consumer backs off and keeps going. */
+    readonly onError?: (error: QueuePullError) => void;
+}
+export interface QueuePullConsumer {
+    /** Messages waiting in the queue at the last pull, for autoscaling. */
+    backlog(): number | undefined;
+    inFlight(): number;
+    /** Stop pulling, let running attempts finish, and send the last acks. Call it on SIGTERM. */
+    stop(): Promise<void>;
+}
+/** Lease messages from `source` and run them with the same handlers as {@link queueConsumer}. */
+export declare function createQueuePullConsumer(options: QueuePullConsumerOptions): QueuePullConsumer;
+export interface CloudflareQueuePullSourceOptions {
+    readonly accountId: string;
+    readonly queueId: string;
+    /** An API token with Queues edit permission. */
+    readonly token: string;
+    readonly fetch?: typeof fetch;
+}
+/** The Cloudflare Queues HTTP pull API. The producer must send `contentType: 'json'`. */
+export declare function cloudflareQueuePullSource(options: CloudflareQueuePullSourceOptions): QueuePullSource;
+export {};

package/dist/cloudflare/queue-pull.js

@@ -0,0 +1,130 @@
+import { Data, Deferred, Effect, Fiber, FiberSet, Option, Predicate, Schema, Semaphore, } from 'effect';
+import { stringifyJson } from '@swirls/looms/core';
+import { processQueueMessage } from './queue-consumer.js';
+export class QueuePullError extends Data.TaggedError('QueuePullError') {
+}
+const MAX_PULL_BATCH = 100;
+const MIN_IDLE_MS = 50;
+/** Lease messages from `source` and run them with the same handlers as {@link queueConsumer}. */
+export function createQueuePullConsumer(options) {
+    const concurrency = Math.max(1, options.concurrency ?? 8);
+    const visibilityTimeoutMs = options.visibilityTimeoutMs ?? 30_000;
+    const maxIdleMs = options.maxIdleMs ?? 5_000;
+    const slots = Semaphore.makeUnsafe(concurrency);
+    const stopping = Deferred.makeUnsafe();
+    let backlog;
+    let inFlight = 0;
+    let acks = [];
+    let retries = [];
+    const reportError = (error) => Effect.sync(() => options.onError?.(error));
+    const flush = Effect.suspend(() => {
+        if (acks.length === 0 && retries.length === 0) {
+            return Effect.void;
+        }
+        const settled = options.source.settle(acks, retries);
+        acks = [];
+        retries = [];
+        return settled.pipe(Effect.catchTag('QueuePullError', reportError));
+    });
+    const lease = (message) => ({
+        body: message.body,
+        attempts: message.attempts,
+        ack: () => {
+            acks.push(message.leaseId);
+        },
+        retry: (retry) => {
+            retries.push({ leaseId: message.leaseId, delaySeconds: retry?.delaySeconds ?? 0 });
+        },
+    });
+    const untilStopped = (effect) => Effect.raceFirst(effect, Deferred.await(stopping));
+    const run = Effect.gen(function* () {
+        const running = yield* FiberSet.make();
+        const flusher = yield* Effect.forkScoped(Effect.forever(Effect.sleep(options.ackIntervalMs ?? 250).pipe(Effect.andThen(flush))));
+        let idleMs = 0;
+        while (!(yield* Deferred.isDone(stopping))) {
+            yield* untilStopped(Semaphore.withPermits(slots, 1)(Effect.void));
+            if (yield* Deferred.isDone(stopping)) {
+                break;
+            }
+            const pulled = yield* options.source
+                .pull(Math.min(concurrency - inFlight, MAX_PULL_BATCH), visibilityTimeoutMs)
+                .pipe(Effect.catchTag('QueuePullError', (error) => reportError(error).pipe(Effect.as({ messages: [] }))));
+            backlog = pulled.backlog ?? backlog;
+            for (const message of pulled.messages) {
+                inFlight += 1;
+                yield* FiberSet.run(running, Semaphore.withPermits(slots, 1)(processQueueMessage(lease(message), options)).pipe(Effect.ensuring(Effect.sync(() => {
+                    inFlight -= 1;
+                }))));
+            }
+            idleMs =
+                pulled.messages.length > 0 ? 0 : Math.min(maxIdleMs, Math.max(MIN_IDLE_MS, idleMs * 2));
+            if (idleMs > 0) {
+                yield* untilStopped(Effect.sleep(idleMs));
+            }
+        }
+        yield* FiberSet.awaitEmpty(running);
+        yield* Fiber.interrupt(flusher);
+        yield* flush;
+    });
+    const fiber = Effect.runFork(Effect.scoped(run));
+    return {
+        backlog: () => backlog,
+        inFlight: () => inFlight,
+        stop: () => Effect.runPromise(Deferred.succeed(stopping, undefined).pipe(Effect.andThen(Fiber.join(fiber)))),
+    };
+}
+const PullResponseSchema = Schema.Struct({
+    result: Schema.Struct({
+        message_backlog_count: Schema.optional(Schema.Finite),
+        messages: Schema.Array(Schema.Struct({
+            lease_id: Schema.String,
+            attempts: Schema.Finite,
+            body: Schema.Json,
+        })),
+    }),
+});
+const decodePullResponse = Schema.decodeUnknownEffect(PullResponseSchema);
+const decodeJsonText = Schema.decodeUnknownOption(Schema.fromJsonString(Schema.Json));
+/** The Cloudflare Queues HTTP pull API. The producer must send `contentType: 'json'`. */
+export function cloudflareQueuePullSource(options) {
+    const fetchImpl = options.fetch ?? fetch;
+    const endpoint = `https://api.cloudflare.com/client/v4/accounts/${encodeURIComponent(options.accountId)}/queues/${encodeURIComponent(options.queueId)}/messages`;
+    const post = (path, body) => Effect.tryPromise({
+        try: () => fetchImpl(`${endpoint}/${path}`, {
+            method: 'POST',
+            headers: {
+                authorization: `Bearer ${options.token}`,
+                'content-type': 'application/json',
+            },
+            body: stringifyJson(body),
+        }),
+        catch: (cause) => new QueuePullError({ message: cause instanceof Error ? cause.message : String(cause) }),
+    }).pipe(Effect.filterOrFail((response) => response.ok, (response) => new QueuePullError({
+        message: `Cloudflare Queues ${path} returned ${response.status}`,
+        status: response.status,
+    })));
+    return {
+        pull: (batchSize, visibilityTimeoutMs) => post('pull', { batch_size: batchSize, visibility_timeout_ms: visibilityTimeoutMs }).pipe(Effect.flatMap((response) => Effect.tryPromise({
+            try: () => response.json(),
+            catch: () => new QueuePullError({ message: 'the pull response is not JSON' }),
+        })), Effect.flatMap((json) => decodePullResponse(json).pipe(Effect.mapError(() => new QueuePullError({ message: 'unexpected pull response' })))), Effect.map(({ result }) => ({
+            backlog: result.message_backlog_count,
+            messages: result.messages.map((message) => ({
+                leaseId: message.lease_id,
+                attempts: message.attempts,
+                body: jsonBody(message.body),
+            })),
+        }))),
+        settle: (acks, retries) => post('ack', {
+            acks: acks.map((leaseId) => ({ lease_id: leaseId })),
+            retries: retries.map((retry) => ({
+                lease_id: retry.leaseId,
+                delay_seconds: retry.delaySeconds,
+            })),
+        }).pipe(Effect.asVoid),
+    };
+}
+/** The pull API returns a JSON message's body as its JSON text. */
+function jsonBody(body) {
+    return Predicate.isString(body) ? Option.getOrElse(decodeJsonText(body), () => body) : body;
+}

package/dist/cloudflare/queue-worker.d.ts

@@ -0,0 +1,39 @@
+import { type Types } from 'effect';
+import { type BlobStore } from '@swirls/looms/core';
+import type { EffectWorker } from '@swirls/looms/runtime';
+import type { QueueEffectMessage } from './queue-message';
+/** Leaves room under Cloudflare's 128 KB message limit. */
+export declare const DEFAULT_MAX_QUEUE_MESSAGE_BYTES = 100000;
+/** A Cloudflare Queue producer binding, or anything that sends the same way. */
+export interface QueueProducer {
+    send(message: QueueEffectMessage, options?: {
+        readonly contentType?: 'json';
+    }): Promise<void>;
+}
+export interface QueueRoute {
+    readonly handles: ReadonlyArray<string> | ((type: string) => boolean);
+    readonly queue: QueueProducer;
+}
+export interface CloudflareQueueWorkerOptions {
+    /** The first route that handles an effect type gets its attempts. */
+    readonly routes: ReadonlyArray<QueueRoute>;
+    /** Holds an input that would push a message past `maxMessageBytes`. Without it, that dispatch fails. */
+    readonly blobs?: BlobStore;
+    readonly maxMessageBytes?: number;
+}
+declare const QueueDispatchError_base: new <A extends Record<string, any> = {}>(args: Types.VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("effect/Cause").YieldableError & {
+    readonly _tag: "QueueDispatchError";
+} & Readonly<A>;
+export declare class QueueDispatchError extends QueueDispatchError_base<{
+    readonly message: string;
+}> {
+}
+/**
+ * An {@link EffectWorker} that sends each attempt to a Cloudflare Queue. A send the queue rejects
+ * (a 429, for one) fails the attempt under the effect's retry policy. A message the queue accepts
+ * and later dead-letters is recovered by the effect's schedule-to-start timeout, which every routed
+ * effect must set. Cancellation reaches a running attempt through its callback responses, since a
+ * queued message cannot be recalled.
+ */
+export declare function cloudflareQueueWorker(options: CloudflareQueueWorkerOptions): EffectWorker;
+export {};

package/dist/cloudflare/queue-worker.js

@@ -0,0 +1,62 @@
+import { Data, Effect, Predicate } from 'effect';
+import { claimJson, utf8JsonBytes } from '@swirls/looms/core';
+/** Leaves room under Cloudflare's 128 KB message limit. */
+export const DEFAULT_MAX_QUEUE_MESSAGE_BYTES = 100_000;
+export class QueueDispatchError extends Data.TaggedError('QueueDispatchError') {
+}
+/**
+ * An {@link EffectWorker} that sends each attempt to a Cloudflare Queue. A send the queue rejects
+ * (a 429, for one) fails the attempt under the effect's retry policy. A message the queue accepts
+ * and later dead-letters is recovered by the effect's schedule-to-start timeout, which every routed
+ * effect must set. Cancellation reaches a running attempt through its callback responses, since a
+ * queued message cannot be recalled.
+ */
+export function cloudflareQueueWorker(options) {
+    const routeFor = (type) => options.routes.find((route) => Predicate.isFunction(route.handles) ? route.handles(type) : route.handles.includes(type));
+    return {
+        dispatchSemantics: 'acknowledged',
+        handles: (type) => routeFor(type) !== undefined,
+        dispatch: (task) => Effect.runPromise(sendTask(task, routeFor(task.type), options)),
+    };
+}
+function sendTask(task, route, options) {
+    if (!route) {
+        return Effect.fail(new QueueDispatchError({ message: `no queue route handles "${task.type}"` }));
+    }
+    return queueMessage(task, options).pipe(Effect.flatMap((message) => Effect.tryPromise({
+        try: () => route.queue.send(message, { contentType: 'json' }),
+        catch: (cause) => new QueueDispatchError({
+            message: `queue send failed: ${cause instanceof Error ? cause.message : String(cause)}`,
+        }),
+    })));
+}
+function queueMessage(task, options) {
+    const message = {
+        v: 1,
+        runId: task.runId,
+        effectId: task.effectId,
+        attempt: task.attempt,
+        type: task.type,
+    };
+    if (task.details !== undefined) {
+        message.details = task.details;
+    }
+    if (task.trace) {
+        message.trace = task.trace;
+    }
+    if (task.deadlines) {
+        message.deadlines = task.deadlines;
+    }
+    const inline = { ...message, input: task.input };
+    const limit = options.maxMessageBytes ?? DEFAULT_MAX_QUEUE_MESSAGE_BYTES;
+    if (utf8JsonBytes(inline) <= limit) {
+        return Effect.succeed(inline);
+    }
+    const { blobs } = options;
+    if (!blobs) {
+        return Effect.fail(new QueueDispatchError({
+            message: `the "${task.type}" message is over ${limit} bytes and no blob store is configured`,
+        }));
+    }
+    return claimJson(task.input, blobs).pipe(Effect.tap((ref) => blobs.retain(task.runId, [ref.sha256])), Effect.map((inputRef) => ({ ...message, inputRef })), Effect.mapError((error) => new QueueDispatchError({ message: `could not store the input: ${error.message}` })));
+}

package/dist/cloudflare/r2-blob-store.d.ts

@@ -0,0 +1,33 @@
+import { type BlobStore } from '@swirls/looms/core';
+export interface R2ObjectBodyLike {
+    arrayBuffer(): Promise<ArrayBuffer>;
+}
+export interface R2ListResult {
+    readonly objects: ReadonlyArray<{
+        readonly key: string;
+    }>;
+    readonly truncated: boolean;
+    readonly cursor?: string;
+}
+/**
+ * Structural subset of a Cloudflare `R2Bucket` binding. An `R2Bucket` satisfies it.
+ */
+export interface R2StoredObject {
+    readonly key: string;
+}
+export interface R2BucketLike {
+    put(key: string, value: Uint8Array): Promise<R2StoredObject>;
+    get(key: string): Promise<R2ObjectBodyLike | null>;
+    head(key: string): Promise<R2StoredObject | null>;
+    delete(key: string): Promise<void>;
+    list(options?: {
+        prefix?: string;
+        cursor?: string;
+    }): Promise<R2ListResult>;
+}
+/**
+ * Content-addressed blob store in R2 under `looms/blobs/`. Every run's Durable Object can
+ * share one bucket: each run writes its own reference markers, and a body is deleted only
+ * after no marker for it remains.
+ */
+export declare function r2BlobStore(bucket: R2BucketLike): BlobStore;