better-ship 0.7.0 → 0.10.0

package/dist/cloudflare/queue.js

@@ -0,0 +1,419 @@
+import { U as AppError, a as createLogger, b as shouldRetryFailure, c as exponentialEqualJitterMs, d as classifyFailure, f as retryAfterSecondsOf, l as spreadJitterMs, u as classifyBoundaryError } from "../core-DC_4pOrI.js";
+import { i as MessageAlreadyProcessedError } from "../application-DYfcAy-Q.js";
+import { Result } from "better-result";
+
+//#region src/infrastructure/cloudflare/queue/queue-limits.ts
+/**
+* The Cloudflare Queues producer limits with metadata headroom, checked before each send so a
+* violation never reaches the binding. The dead letter has the same per-message limit.
+* https://developers.cloudflare.com/queues/platform/limits/
+*/
+const QUEUE_LIMITS = {
+	messageBytes: 127e3,
+	batchBytes: 25e4,
+	batchCount: 100
+};
+/** The size the binding measures: the JSON encoding of the body, in UTF-8 bytes. */
+function messageByteLength(message) {
+	return new TextEncoder().encode(JSON.stringify(message)).length;
+}
+/** Measure every message once. */
+function sizeMessages(messages) {
+	return messages.map((message) => ({
+		message,
+		bytes: messageByteLength(message)
+	}));
+}
+/** Whether one message is over the per-message limit. */
+function isOversized(sized) {
+	return sized.bytes > QUEUE_LIMITS.messageBytes;
+}
+/** Split a batch at the message-count and byte limits, keeping the order. */
+function chunkByLimits(sized) {
+	const chunks = [];
+	let current = [];
+	let bytes = 0;
+	for (const item of sized) {
+		const full = current.length >= QUEUE_LIMITS.batchCount || bytes + item.bytes > QUEUE_LIMITS.batchBytes;
+		if (current.length > 0 && full) {
+			chunks.push(current);
+			current = [];
+			bytes = 0;
+		}
+		current.push(item.message);
+		bytes += item.bytes;
+	}
+	if (current.length > 0) chunks.push(current);
+	return chunks;
+}
+
+//#endregion
+//#region src/infrastructure/cloudflare/queue/queue.errors.ts
+const QUEUE_OPERATION_MESSAGES = {
+	send: "Failed to send queue message",
+	send_batch: "Failed to send queue batch",
+	send_dlq: "Failed to send DLQ message"
+};
+/**
+* Cloudflare Queues error codes, by whether a repeat could change the answer. The reference
+* marks only 10201 and 10250 for retry; 10251 waits for processing, 15000 is nobody's call.
+* https://developers.cloudflare.com/queues/reference/error-codes/
+*/
+const QUEUE_ERROR_CLASSIFICATIONS = /* @__PURE__ */ new Map([
+	[10104, "terminal"],
+	[10106, "terminal"],
+	[10107, "terminal"],
+	[10201, "transient"],
+	[10202, "terminal"],
+	[10203, "terminal"],
+	[10204, "terminal"],
+	[10205, "terminal"],
+	[10206, "terminal"],
+	[10207, "terminal"],
+	[10208, "terminal"],
+	[10250, "transient"],
+	[10251, "transient"],
+	[10252, "terminal"],
+	[10253, "terminal"],
+	[15e3, "unknown"]
+]);
+function extractQueueErrorCode(cause) {
+	if (!(cause instanceof Error)) return void 0;
+	const match = /(\d{5})\)?\s*$/.exec(cause.message);
+	return match?.[1] === void 0 ? void 0 : Number(match[1]);
+}
+function classifyQueueBoundaryError(cause) {
+	const code = extractQueueErrorCode(cause);
+	return code === void 0 ? void 0 : QUEUE_ERROR_CLASSIFICATIONS.get(code);
+}
+/** Classify a raw Queue binding failure: the code table first, then Cloudflare's signals, then transport. */
+function classifyQueueError(cause) {
+	return classifyBoundaryError({
+		cause,
+		classifyBoundary: classifyQueueBoundaryError,
+		includeCloudflare: true
+	});
+}
+/** A send through a Queue binding failed. The classification says whether an immediate retry may help. */
+var QueueSendError = class extends AppError {
+	_tag = "QueueSendError";
+	classification;
+	operation;
+	constructor(args) {
+		super(QUEUE_OPERATION_MESSAGES[args.operation], { cause: args.cause });
+		this.classification = classifyQueueError(args.cause);
+		this.operation = args.operation;
+	}
+};
+/**
+* A message over the per-message cap can never be sent on any queue; the dead letter has the
+* same cap. The client detects it before the send, so it never comes from a platform error.
+*/
+var OversizedMessageError = class extends AppError {
+	_tag = "OversizedMessageError";
+	classification = "terminal";
+	messageName;
+	bytes;
+	limit;
+	constructor(args) {
+		super(`Queue message "${args.messageName}" is ${String(args.bytes)} bytes, over the ${String(args.limit)} limit`);
+		this.messageName = args.messageName;
+		this.bytes = args.bytes;
+		this.limit = args.limit;
+	}
+};
+/**
+* The dead letter did not accept an unparseable message. Always transient, whatever the send
+* failure was, so the source delivery retries instead of acknowledging and losing the body.
+*/
+var DeadLetterUnavailableError = class extends AppError {
+	_tag = "DeadLetterUnavailableError";
+	classification = "transient";
+	constructor(cause) {
+		super("The dead letter did not accept the message", { cause });
+	}
+};
+
+//#endregion
+//#region src/infrastructure/cloudflare/queue/queue-client.ts
+const logger$1 = createLogger("queue-client");
+/** Immediate retries of one binding call: three attempts, 250 ms then 500 ms, with jitter. */
+const RETRY_TIMES = 2;
+const RETRY_BASE_DELAY_MS = 250;
+/** Every send is safe to repeat, so a transient failure gets an immediate retry; terminal and unknown stop. */
+function shouldRetrySend(error) {
+	return shouldRetryFailure({
+		classification: error.classification,
+		repeatSafe: true,
+		owner: "immediate"
+	});
+}
+function oversizedError(sized) {
+	return new OversizedMessageError({
+		messageName: sized.message.name,
+		bytes: sized.bytes,
+		limit: QUEUE_LIMITS.messageBytes
+	});
+}
+/**
+* Sends messages to the application's queues. Checks the size limits before a send, retries a
+* transient binding failure a bounded number of times, and converts the final failure to `QueueSendError`.
+*/
+var QueueClient = class {
+	options;
+	constructor(options) {
+		this.options = options;
+	}
+	/** @throws OversizedMessageError before the send. @throws QueueSendError after the retries. */
+	async send(message, options) {
+		const sized = {
+			message,
+			bytes: messageByteLength(message)
+		};
+		if (isOversized(sized)) {
+			logger$1.warn("queue_message_oversized", {
+				name: message.name,
+				type: message.type,
+				bytes: sized.bytes
+			});
+			throw oversizedError(sized);
+		}
+		const queue = this.queueFor(message);
+		logger$1.debug("sending_message", {
+			name: message.name,
+			type: message.type,
+			delaySeconds: options?.delaySeconds
+		});
+		await this.callQueue("send", async () => {
+			if (options) await queue.send(message, options);
+			else await queue.send(message);
+		});
+	}
+	/** Rejects the whole batch before any send when one message is oversized. */
+	async sendBatch(messages) {
+		const sized = sizeMessages(messages);
+		const oversized = sized.find(isOversized);
+		if (oversized) throw oversizedError(oversized);
+		await this.sendSizedBatch(sized);
+	}
+	async sendBatchPartial(messages) {
+		const sized = sizeMessages(messages);
+		await this.sendSizedBatch(sized.filter((item) => !isOversized(item)));
+		return sized.filter(isOversized).map((item) => item.message);
+	}
+	async sendToDlq(message) {
+		logger$1.debug("sending_to_dlq", { queueMessageId: message.id });
+		await this.callQueue("send_dlq", async () => {
+			await this.options.deadLetter.send(message.body);
+		});
+	}
+	/** Each lane's chunks retry on their own, so one failed chunk does not resend the others. */
+	async sendSizedBatch(sized) {
+		const byLane = /* @__PURE__ */ new Map();
+		for (const item of sized) {
+			const lane = this.options.laneOf(item.message);
+			const items = byLane.get(lane) ?? [];
+			items.push(item);
+			byLane.set(lane, items);
+		}
+		logger$1.debug("sending_batch", {
+			count: sized.length,
+			lanes: [...byLane].map(([lane, items]) => ({
+				lane,
+				count: items.length
+			}))
+		});
+		const sends = [];
+		for (const [lane, items] of byLane) {
+			const queue = this.options.queues[lane];
+			for (const group of chunkByLimits(items)) sends.push(this.callQueue("send_batch", async () => {
+				await queue.sendBatch(group.map((body) => ({ body })));
+			}));
+		}
+		await Promise.all(sends);
+	}
+	queueFor(message) {
+		return this.options.queues[this.options.laneOf(message)];
+	}
+	async callQueue(operation, call) {
+		const result = await Result.tryPromise({
+			try: call,
+			catch: (cause) => new QueueSendError({
+				operation,
+				cause
+			})
+		}, { retry: {
+			times: RETRY_TIMES,
+			delayMs: RETRY_BASE_DELAY_MS,
+			backoff: "exponential",
+			jitter: true,
+			shouldRetry: shouldRetrySend
+		} });
+		if (result.isErr()) throw result.error;
+		return result.value;
+	}
+};
+
+//#endregion
+//#region src/infrastructure/cloudflare/queue/redelivery-policy.ts
+const BASE_RETRY_DELAY_MS = 5e3;
+const MAX_RETRY_DELAY_MS = 12e4;
+const RETRY_AFTER_SPREAD_MS = 5e3;
+/** Cloudflare Queues accept a redelivery delay of at most one day. */
+const MAX_QUEUE_DELAY_SECONDS = 86400;
+/**
+* Decide whether the consumer acknowledges a failed message or asks Cloudflare to redeliver it.
+* A terminal failure acknowledges. Transient and unknown failures redeliver: after the advertised
+* wait plus a spread when the error carries one, else with exponential equal-jitter backoff.
+* An `AggregateError` from event delivery redelivers when any member does, after the longest wait.
+*/
+function decideRedelivery(cause, attempt) {
+	if (cause instanceof AggregateError && cause.errors.length > 0) {
+		const retries = cause.errors.map((member) => decideRedelivery(member, attempt)).filter((decision) => decision.action === "retry");
+		if (retries.length === 0) return {
+			action: "ack",
+			classification: "terminal"
+		};
+		return {
+			action: "retry",
+			classification: retries.some((decision) => decision.classification === "unknown") ? "unknown" : "transient",
+			delaySeconds: Math.max(...retries.map((decision) => decision.delaySeconds))
+		};
+	}
+	const classification = classifyFailure(cause);
+	if (classification === "terminal") return {
+		action: "ack",
+		classification
+	};
+	if (!shouldRetryFailure({
+		classification,
+		repeatSafe: true,
+		owner: "durable"
+	})) return {
+		action: "ack",
+		classification: "terminal"
+	};
+	const retryAfterSeconds = retryAfterSecondsOf(cause);
+	const delayMs = retryAfterSeconds === null ? exponentialEqualJitterMs(BASE_RETRY_DELAY_MS, MAX_RETRY_DELAY_MS, attempt) : retryAfterSeconds * 1e3 + spreadJitterMs(RETRY_AFTER_SPREAD_MS);
+	return {
+		action: "retry",
+		classification,
+		delaySeconds: Math.min(MAX_QUEUE_DELAY_SECONDS, Math.max(1, Math.ceil(delayMs / 1e3)))
+	};
+}
+
+//#endregion
+//#region src/infrastructure/cloudflare/queue/queue-consumer.ts
+const logger = createLogger("queue-consumer");
+/**
+* Parses and dispatches each queue message, then selects acknowledgement or retry.
+* Cloudflare owns the retry limit and sends exhausted messages to the configured dead letter.
+* The consumer logs each failure once; handlers do not.
+*/
+var QueueConsumer = class {
+	bus;
+	queueClient;
+	schema;
+	wrapDispatch;
+	/**
+	* @param bus - Where a parsed message goes.
+	* @param queueClient - Parks an unparseable body in the dead letter.
+	* @param schema - What a body may be: the application's `messages.queueSchema`.
+	* @param wrapDispatch - Wraps one dispatch in the application's context. Default: run it as is.
+	*/
+	constructor(bus, queueClient, schema, wrapDispatch = (_message, _attempt, run) => run()) {
+		this.bus = bus;
+		this.queueClient = queueClient;
+		this.schema = schema;
+		this.wrapDispatch = wrapDispatch;
+	}
+	/** Every message settles on its own. A settlement that throws rejects the batch after its siblings settle. */
+	async processBatch(batch) {
+		logger.debug("queue_batch_received", { count: batch.messages.length });
+		const rejected = (await Promise.allSettled(batch.messages.map((message) => this.processMessage(message)))).filter((result) => result.status === "rejected").map((result) => result.reason);
+		if (rejected.length > 0) throw new AggregateError(rejected, "Queue message settlement failed");
+	}
+	async processMessage(message) {
+		let parsed = null;
+		try {
+			const body = await this.parseMessage(message);
+			if (body === null) {
+				logger.error("invalid_message_format", { details: {
+					attempt: message.attempts,
+					queueMessageId: message.id
+				} });
+				await this.parkPoison(message);
+				return;
+			}
+			parsed = body;
+			await this.wrapDispatch(body, message.attempts, async () => {
+				await this.bus.handle(body);
+			});
+			message.ack();
+			logger.debug(`queue_message_processed:${body.name}`, { name: body.name });
+		} catch (cause) {
+			this.handleFailure(message, parsed, cause);
+		}
+	}
+	/** Returns null on failure; the caller owns the single log point. */
+	async parseMessage(message) {
+		const result = await this.schema.safeParseAsync(message.body);
+		return result.success ? result.data : null;
+	}
+	/** Park an unparseable message in the dead letter, then acknowledge its source delivery. */
+	async parkPoison(message) {
+		try {
+			await this.queueClient.sendToDlq(message);
+			message.ack();
+		} catch (cause) {
+			throw new DeadLetterUnavailableError(cause);
+		}
+	}
+	/**
+	* Retry declared transient and unknown failures so Cloudflare can enforce the attempt ceiling.
+	* Acknowledge only declared terminal failures.
+	*/
+	handleFailure(message, parsed, cause) {
+		if (cause instanceof MessageAlreadyProcessedError) {
+			logger.debug("duplicate_skipped", {
+				name: parsed?.name,
+				messageId: cause.messageId,
+				attempt: message.attempts
+			});
+			message.ack();
+			return;
+		}
+		const decision = decideRedelivery(cause, message.attempts);
+		if (decision.action === "ack") {
+			logger.error("message_discarded", {
+				error: cause,
+				details: {
+					name: parsed?.name,
+					messageId: parsed?.id,
+					queueMessageId: message.id,
+					attempt: message.attempts
+				}
+			});
+			message.ack();
+			return;
+		}
+		const context = {
+			name: parsed?.name,
+			messageId: parsed?.id,
+			queueMessageId: message.id,
+			attempt: message.attempts,
+			classification: decision.classification,
+			delaySeconds: decision.delaySeconds
+		};
+		if (decision.classification === "unknown" && message.attempts === 1) logger.error("queue_unknown_failure", {
+			error: cause,
+			details: context
+		});
+		else logger.debug("redelivery_requested", context);
+		message.retry({ delaySeconds: decision.delaySeconds });
+	}
+};
+
+//#endregion
+export { DeadLetterUnavailableError, OversizedMessageError, QUEUE_LIMITS, QueueClient, QueueConsumer, QueueSendError, chunkByLimits, classifyQueueError, decideRedelivery, isOversized, messageByteLength, sizeMessages };
+//# sourceMappingURL=queue.js.map

package/dist/cloudflare/queue.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"queue.js","names":["logger"],"sources":["../../src/infrastructure/cloudflare/queue/queue-limits.ts","../../src/infrastructure/cloudflare/queue/queue.errors.ts","../../src/infrastructure/cloudflare/queue/queue-client.ts","../../src/infrastructure/cloudflare/queue/redelivery-policy.ts","../../src/infrastructure/cloudflare/queue/queue-consumer.ts"],"sourcesContent":["import type { QueueMessage } from './queue-message.ts'\n\n/**\n * The Cloudflare Queues producer limits with metadata headroom, checked before each send so a\n * violation never reaches the binding. The dead letter has the same per-message limit.\n * https://developers.cloudflare.com/queues/platform/limits/\n */\nexport const QUEUE_LIMITS = {\n  messageBytes: 127_000,\n  batchBytes: 250_000,\n  batchCount: 100,\n} as const\n\n/** The size the binding measures: the JSON encoding of the body, in UTF-8 bytes. */\nexport function messageByteLength(message: QueueMessage): number {\n  return new TextEncoder().encode(JSON.stringify(message)).length\n}\n\n/** A message with its measured size. */\nexport type SizedMessage<TMessage> = { readonly message: TMessage; readonly bytes: number }\n\n/** Measure every message once. */\nexport function sizeMessages<TMessage extends QueueMessage>(\n  messages: ReadonlyArray<TMessage>,\n): SizedMessage<TMessage>[] {\n  return messages.map((message) => ({ message, bytes: messageByteLength(message) }))\n}\n\n/** Whether one message is over the per-message limit. */\nexport function isOversized(sized: SizedMessage<QueueMessage>): boolean {\n  return sized.bytes > QUEUE_LIMITS.messageBytes\n}\n\n/** Split a batch at the message-count and byte limits, keeping the order. */\nexport function chunkByLimits<TMessage>(\n  sized: ReadonlyArray<SizedMessage<TMessage>>,\n): TMessage[][] {\n  const chunks: TMessage[][] = []\n  let current: TMessage[] = []\n  let bytes = 0\n  for (const item of sized) {\n    const full =\n      current.length >= QUEUE_LIMITS.batchCount || bytes + item.bytes > QUEUE_LIMITS.batchBytes\n    if (current.length > 0 && full) {\n      chunks.push(current)\n      current = []\n      bytes = 0\n    }\n    current.push(item.message)\n    bytes += item.bytes\n  }\n  if (current.length > 0) chunks.push(current)\n  return chunks\n}\n","import { AppError, classifyBoundaryError, type FailureClassification } from '@/core'\n\n/** The Queue binding calls the client makes. Each is safe to repeat. */\nexport type QueueOperation = 'send' | 'send_batch' | 'send_dlq'\n\nconst QUEUE_OPERATION_MESSAGES = {\n  send: 'Failed to send queue message',\n  send_batch: 'Failed to send queue batch',\n  send_dlq: 'Failed to send DLQ message',\n} satisfies Readonly<Record<QueueOperation, string>>\n\n/**\n * Cloudflare Queues error codes, by whether a repeat could change the answer. The reference\n * marks only 10201 and 10250 for retry; 10251 waits for processing, 15000 is nobody's call.\n * https://developers.cloudflare.com/queues/reference/error-codes/\n */\nconst QUEUE_ERROR_CLASSIFICATIONS = new Map<number, FailureClassification>([\n  [10104, 'terminal'], // QueueNotFound\n  [10106, 'terminal'], // Unauthorized\n  [10107, 'terminal'], // QueueIDMalformed\n  [10201, 'transient'], // ClientDisconnected\n  [10202, 'terminal'], // BatchDelayInvalid\n  [10203, 'terminal'], // MessageMetadataInvalid\n  [10204, 'terminal'], // MessageSizeOutOfBounds\n  [10205, 'terminal'], // BatchSizeOutOfBounds\n  [10206, 'terminal'], // BatchCountOutOfBounds\n  [10207, 'terminal'], // JSONRequestBodyInvalid\n  [10208, 'terminal'], // JSONRequestBodyMalformed\n  [10250, 'transient'], // QueueOverloaded\n  [10251, 'transient'], // QueueStorageLimitExceeded\n  [10252, 'terminal'], // QueueDisabled\n  [10253, 'terminal'], // FreeTierLimitExceeded\n  [15000, 'unknown'], // UnknownInternalError\n])\n\nfunction extractQueueErrorCode(cause: unknown): number | undefined {\n  if (!(cause instanceof Error)) return undefined\n  const match = /(\\d{5})\\)?\\s*$/.exec(cause.message)\n  return match?.[1] === undefined ? undefined : Number(match[1])\n}\n\nfunction classifyQueueBoundaryError(cause: unknown): FailureClassification | undefined {\n  const code = extractQueueErrorCode(cause)\n  return code === undefined ? undefined : QUEUE_ERROR_CLASSIFICATIONS.get(code)\n}\n\n/** Classify a raw Queue binding failure: the code table first, then Cloudflare's signals, then transport. */\nexport function classifyQueueError(cause: unknown): FailureClassification {\n  return classifyBoundaryError({\n    cause,\n    classifyBoundary: classifyQueueBoundaryError,\n    includeCloudflare: true,\n  })\n}\n\n/** A send through a Queue binding failed. The classification says whether an immediate retry may help. */\nexport class QueueSendError extends AppError {\n  readonly _tag = 'QueueSendError'\n  readonly classification: FailureClassification\n  readonly operation: QueueOperation\n\n  constructor(args: { readonly operation: QueueOperation; readonly cause: unknown }) {\n    super(QUEUE_OPERATION_MESSAGES[args.operation], { cause: args.cause })\n    this.classification = classifyQueueError(args.cause)\n    this.operation = args.operation\n  }\n}\n\n/**\n * A message over the per-message cap can never be sent on any queue; the dead letter has the\n * same cap. The client detects it before the send, so it never comes from a platform error.\n */\nexport class OversizedMessageError extends AppError {\n  readonly _tag = 'OversizedMessageError'\n  readonly classification = 'terminal'\n  readonly messageName: string\n  readonly bytes: number\n  readonly limit: number\n\n  constructor(args: {\n    readonly messageName: string\n    readonly bytes: number\n    readonly limit: number\n  }) {\n    super(\n      `Queue message \"${args.messageName}\" is ${String(args.bytes)} bytes, over the ${String(args.limit)} limit`,\n    )\n    this.messageName = args.messageName\n    this.bytes = args.bytes\n    this.limit = args.limit\n  }\n}\n\n/**\n * The dead letter did not accept an unparseable message. Always transient, whatever the send\n * failure was, so the source delivery retries instead of acknowledging and losing the body.\n */\nexport class DeadLetterUnavailableError extends AppError {\n  readonly _tag = 'DeadLetterUnavailableError'\n  readonly classification = 'transient'\n\n  constructor(cause: unknown) {\n    super('The dead letter did not accept the message', { cause })\n  }\n}\n","import { Result } from 'better-result'\n\nimport { createLogger, shouldRetryFailure } from '@/core'\n\nimport {\n  chunkByLimits,\n  isOversized,\n  messageByteLength,\n  QUEUE_LIMITS,\n  sizeMessages,\n  type SizedMessage,\n} from './queue-limits.ts'\nimport type { QueueMessage } from './queue-message.ts'\nimport { OversizedMessageError, QueueSendError, type QueueOperation } from './queue.errors.ts'\n\n/** Cloudflare's delivery delay, in seconds. */\nexport type QueueSendOptions = { readonly delaySeconds: number }\n\n/** The two calls the client makes on a queue binding. */\nexport type QueueBinding<Body> = Pick<Queue<Body>, 'send' | 'sendBatch'>\n\n/**\n * The lanes and the dead letter of one application. A lane is a queue with its own consumer\n * settings; `laneOf` is the product's routing rule, written once at the composition root.\n */\nexport type QueueClientOptions<TMessage extends QueueMessage, Lane extends string> = {\n  readonly queues: Readonly<Record<Lane, QueueBinding<TMessage>>>\n  /** Where the consumer parks poison bodies. Cloudflare also routes exhausted retries here. */\n  readonly deadLetter: Pick<Queue, 'send'>\n  readonly laneOf: (message: TMessage) => Lane\n}\n\n/** The port an entrypoint, a relay, or a consumer sends through. */\nexport interface IQueueClient<TMessage extends QueueMessage> {\n  send(message: TMessage, options?: QueueSendOptions): Promise<void>\n  sendBatch(messages: ReadonlyArray<TMessage>): Promise<void>\n  /** Sends every message within the limits and returns the oversized ones. */\n  sendBatchPartial(messages: ReadonlyArray<TMessage>): Promise<ReadonlyArray<TMessage>>\n  /** Parks a delivered message's body as it arrived. */\n  sendToDlq(message: Message): Promise<void>\n}\n\nconst logger = createLogger('queue-client')\n\n/** Immediate retries of one binding call: three attempts, 250 ms then 500 ms, with jitter. */\nconst RETRY_TIMES = 2\nconst RETRY_BASE_DELAY_MS = 250\n\n/** Every send is safe to repeat, so a transient failure gets an immediate retry; terminal and unknown stop. */\nfunction shouldRetrySend(error: QueueSendError): boolean {\n  return shouldRetryFailure({\n    classification: error.classification,\n    repeatSafe: true,\n    owner: 'immediate',\n  })\n}\n\nfunction oversizedError(sized: SizedMessage<QueueMessage>): OversizedMessageError {\n  return new OversizedMessageError({\n    messageName: sized.message.name,\n    bytes: sized.bytes,\n    limit: QUEUE_LIMITS.messageBytes,\n  })\n}\n\n/**\n * Sends messages to the application's queues. Checks the size limits before a send, retries a\n * transient binding failure a bounded number of times, and converts the final failure to `QueueSendError`.\n */\nexport class QueueClient<\n  TMessage extends QueueMessage,\n  Lane extends string,\n> implements IQueueClient<TMessage> {\n  constructor(private readonly options: QueueClientOptions<TMessage, Lane>) {}\n\n  /** @throws OversizedMessageError before the send. @throws QueueSendError after the retries. */\n  async send(message: TMessage, options?: QueueSendOptions): Promise<void> {\n    const sized = { message, bytes: messageByteLength(message) }\n    if (isOversized(sized)) {\n      logger.warn('queue_message_oversized', {\n        name: message.name,\n        type: message.type,\n        bytes: sized.bytes,\n      })\n      throw oversizedError(sized)\n    }\n\n    const queue = this.queueFor(message)\n    logger.debug('sending_message', {\n      name: message.name,\n      type: message.type,\n      delaySeconds: options?.delaySeconds,\n    })\n\n    await this.callQueue('send', async () => {\n      if (options) {\n        await queue.send(message, options)\n      } else {\n        await queue.send(message)\n      }\n    })\n  }\n\n  /** Rejects the whole batch before any send when one message is oversized. */\n  async sendBatch(messages: ReadonlyArray<TMessage>): Promise<void> {\n    const sized = sizeMessages(messages)\n    const oversized = sized.find(isOversized)\n    if (oversized) throw oversizedError(oversized)\n    await this.sendSizedBatch(sized)\n  }\n\n  async sendBatchPartial(messages: ReadonlyArray<TMessage>): Promise<ReadonlyArray<TMessage>> {\n    const sized = sizeMessages(messages)\n    await this.sendSizedBatch(sized.filter((item) => !isOversized(item)))\n    return sized.filter(isOversized).map((item) => item.message)\n  }\n\n  async sendToDlq(message: Message): Promise<void> {\n    logger.debug('sending_to_dlq', { queueMessageId: message.id })\n    await this.callQueue('send_dlq', async () => {\n      await this.options.deadLetter.send(message.body)\n    })\n  }\n\n  /** Each lane's chunks retry on their own, so one failed chunk does not resend the others. */\n  private async sendSizedBatch(sized: ReadonlyArray<SizedMessage<TMessage>>): Promise<void> {\n    const byLane = new Map<Lane, SizedMessage<TMessage>[]>()\n    for (const item of sized) {\n      const lane = this.options.laneOf(item.message)\n      const items = byLane.get(lane) ?? []\n      items.push(item)\n      byLane.set(lane, items)\n    }\n\n    logger.debug('sending_batch', {\n      count: sized.length,\n      lanes: [...byLane].map(([lane, items]) => ({ lane, count: items.length })),\n    })\n\n    const sends: Promise<void>[] = []\n    for (const [lane, items] of byLane) {\n      const queue = this.options.queues[lane]\n      for (const group of chunkByLimits(items)) {\n        sends.push(\n          this.callQueue('send_batch', async () => {\n            await queue.sendBatch(group.map((body) => ({ body })))\n          }),\n        )\n      }\n    }\n    await Promise.all(sends)\n  }\n\n  private queueFor(message: TMessage): QueueBinding<TMessage> {\n    return this.options.queues[this.options.laneOf(message)]\n  }\n\n  private async callQueue<T>(operation: QueueOperation, call: () => Promise<T>): Promise<T> {\n    const result = await Result.tryPromise(\n      {\n        try: call,\n        catch: (cause) => new QueueSendError({ operation, cause }),\n      },\n      {\n        retry: {\n          times: RETRY_TIMES,\n          delayMs: RETRY_BASE_DELAY_MS,\n          backoff: 'exponential',\n          jitter: true,\n          shouldRetry: shouldRetrySend,\n        },\n      },\n    )\n    if (result.isErr()) throw result.error\n    return result.value\n  }\n}\n","import {\n  classifyFailure,\n  exponentialEqualJitterMs,\n  retryAfterSecondsOf,\n  shouldRetryFailure,\n  spreadJitterMs,\n  type FailureClassification,\n} from '@/core'\n\nconst BASE_RETRY_DELAY_MS = 5_000\nconst MAX_RETRY_DELAY_MS = 120_000\nconst RETRY_AFTER_SPREAD_MS = 5_000\n/** Cloudflare Queues accept a redelivery delay of at most one day. */\nconst MAX_QUEUE_DELAY_SECONDS = 24 * 60 * 60\n\n/** How the consumer settles one failed message: acknowledge it, or have Cloudflare redeliver it after a delay. */\nexport type RedeliveryDecision =\n  | { readonly action: 'ack'; readonly classification: 'terminal' }\n  | {\n      readonly action: 'retry'\n      readonly classification: Exclude<FailureClassification, 'terminal'>\n      readonly delaySeconds: number\n    }\n\n/**\n * Decide whether the consumer acknowledges a failed message or asks Cloudflare to redeliver it.\n * A terminal failure acknowledges. Transient and unknown failures redeliver: after the advertised\n * wait plus a spread when the error carries one, else with exponential equal-jitter backoff.\n * An `AggregateError` from event delivery redelivers when any member does, after the longest wait.\n */\nexport function decideRedelivery(cause: unknown, attempt: number): RedeliveryDecision {\n  if (cause instanceof AggregateError && cause.errors.length > 0) {\n    const decisions = cause.errors.map((member) => decideRedelivery(member, attempt))\n    const retries = decisions.filter((decision) => decision.action === 'retry')\n    if (retries.length === 0) return { action: 'ack', classification: 'terminal' }\n\n    // Redelivery must respect every failed subscriber's required wait.\n    return {\n      action: 'retry',\n      classification: retries.some((decision) => decision.classification === 'unknown')\n        ? 'unknown'\n        : 'transient',\n      delaySeconds: Math.max(...retries.map((decision) => decision.delaySeconds)),\n    }\n  }\n\n  const classification = classifyFailure(cause)\n  if (classification === 'terminal') return { action: 'ack', classification }\n\n  const canRetry = shouldRetryFailure({ classification, repeatSafe: true, owner: 'durable' })\n  if (!canRetry) return { action: 'ack', classification: 'terminal' }\n\n  const retryAfterSeconds = retryAfterSecondsOf(cause)\n  const delayMs =\n    retryAfterSeconds === null\n      ? exponentialEqualJitterMs(BASE_RETRY_DELAY_MS, MAX_RETRY_DELAY_MS, attempt)\n      : retryAfterSeconds * 1_000 + spreadJitterMs(RETRY_AFTER_SPREAD_MS)\n\n  return {\n    action: 'retry',\n    classification,\n    delaySeconds: Math.min(MAX_QUEUE_DELAY_SECONDS, Math.max(1, Math.ceil(delayMs / 1_000))),\n  }\n}\n","import type { z } from 'zod'\n\nimport { MessageAlreadyProcessedError } from '@/application'\nimport { createLogger } from '@/core'\n\nimport type { IQueueClient } from './queue-client.ts'\nimport type { QueueMessage } from './queue-message.ts'\nimport { DeadLetterUnavailableError } from './queue.errors.ts'\nimport { decideRedelivery } from './redelivery-policy.ts'\n\nconst logger = createLogger('queue-consumer')\n\n/** Wraps one dispatch: an error-tracking scope, an analytics context. The default runs it as is. */\nexport type DispatchWrapper<TMessage extends QueueMessage> = (\n  message: TMessage,\n  attempt: number,\n  run: () => Promise<void>,\n) => Promise<void>\n\n/** The one call the consumer makes on the bus. */\nexport type DispatchBus<TMessage extends QueueMessage> = {\n  // oxlint-disable-next-line anti-slop/no-unknown-returns -- the bus resolves to each handler's own value; the consumer discards it.\n  handle(message: TMessage): Promise<unknown>\n}\n\n/**\n * Parses and dispatches each queue message, then selects acknowledgement or retry.\n * Cloudflare owns the retry limit and sends exhausted messages to the configured dead letter.\n * The consumer logs each failure once; handlers do not.\n */\nexport class QueueConsumer<TMessage extends QueueMessage> {\n  /**\n   * @param bus - Where a parsed message goes.\n   * @param queueClient - Parks an unparseable body in the dead letter.\n   * @param schema - What a body may be: the application's `messages.queueSchema`.\n   * @param wrapDispatch - Wraps one dispatch in the application's context. Default: run it as is.\n   */\n  constructor(\n    private readonly bus: DispatchBus<TMessage>,\n    private readonly queueClient: Pick<IQueueClient<TMessage>, 'sendToDlq'>,\n    private readonly schema: z.ZodType<TMessage>,\n    private readonly wrapDispatch: DispatchWrapper<TMessage> = (_message, _attempt, run) => run(),\n  ) {}\n\n  /** Every message settles on its own. A settlement that throws rejects the batch after its siblings settle. */\n  async processBatch(batch: MessageBatch): Promise<void> {\n    logger.debug('queue_batch_received', { count: batch.messages.length })\n    const results = await Promise.allSettled(\n      batch.messages.map((message) => this.processMessage(message)),\n    )\n    const rejected = results\n      .filter((result) => result.status === 'rejected')\n      .map((result) => result.reason)\n\n    if (rejected.length > 0) {\n      throw new AggregateError(rejected, 'Queue message settlement failed')\n    }\n  }\n\n  private async processMessage(message: Message): Promise<void> {\n    let parsed: TMessage | null = null\n\n    try {\n      const body = await this.parseMessage(message)\n      if (body === null) {\n        // An unparseable body cannot succeed on retry, so park it for inspection.\n        logger.error('invalid_message_format', {\n          details: { attempt: message.attempts, queueMessageId: message.id },\n        })\n        await this.parkPoison(message)\n        return\n      }\n      parsed = body\n\n      await this.wrapDispatch(body, message.attempts, async () => {\n        await this.bus.handle(body)\n      })\n      message.ack()\n      logger.debug(`queue_message_processed:${body.name}`, { name: body.name })\n    } catch (cause) {\n      this.handleFailure(message, parsed, cause)\n    }\n  }\n\n  /** Returns null on failure; the caller owns the single log point. */\n  private async parseMessage(message: Message): Promise<TMessage | null> {\n    const result = await this.schema.safeParseAsync(message.body)\n    return result.success ? result.data : null\n  }\n\n  /** Park an unparseable message in the dead letter, then acknowledge its source delivery. */\n  private async parkPoison(message: Message): Promise<void> {\n    try {\n      await this.queueClient.sendToDlq(message)\n      message.ack()\n    } catch (cause) {\n      throw new DeadLetterUnavailableError(cause)\n    }\n  }\n\n  /**\n   * Retry declared transient and unknown failures so Cloudflare can enforce the attempt ceiling.\n   * Acknowledge only declared terminal failures.\n   */\n  private handleFailure(message: Message, parsed: TMessage | null, cause: unknown): void {\n    if (cause instanceof MessageAlreadyProcessedError) {\n      logger.debug('duplicate_skipped', {\n        name: parsed?.name,\n        messageId: cause.messageId,\n        attempt: message.attempts,\n      })\n      message.ack()\n      return\n    }\n\n    const decision = decideRedelivery(cause, message.attempts)\n    if (decision.action === 'ack') {\n      logger.error('message_discarded', {\n        error: cause,\n        details: {\n          name: parsed?.name,\n          messageId: parsed?.id,\n          queueMessageId: message.id,\n          attempt: message.attempts,\n        },\n      })\n      message.ack()\n      return\n    }\n\n    const context = {\n      name: parsed?.name,\n      messageId: parsed?.id,\n      queueMessageId: message.id,\n      attempt: message.attempts,\n      classification: decision.classification,\n      delaySeconds: decision.delaySeconds,\n    }\n    if (decision.classification === 'unknown' && message.attempts === 1) {\n      logger.error('queue_unknown_failure', { error: cause, details: context })\n    } else {\n      logger.debug('redelivery_requested', context)\n    }\n    message.retry({ delaySeconds: decision.delaySeconds })\n  }\n}\n"],"mappings":"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"}

package/dist/cloudflare/scheduled.d.ts

@@ -0,0 +1,36 @@
+import { q as MessageId } from "../index-6XMPJu7u.js";
+import { z } from "zod";
+//#region src/infrastructure/cloudflare/scheduled/scheduled-handler.d.ts
+/** The work one schedule runs. Nothing returns to the platform, so each run reports its own outcome. */
+type ScheduledRun<Deps> = (deps: Deps, at: Date) => Promise<void>;
+/** The cron expressions of a schedule map, as literal types. */
+type ScheduleExpression<Schedules extends Readonly<Record<string, string>>> = Schedules[keyof Schedules];
+/** The Cloudflare `scheduled` export, with the application's dependencies as its second argument. */
+type ScheduledHandler<Deps> = (controller: ScheduledController, deps: Deps) => Promise<void>;
+/** What `defineSchedules` returns: the map, its parser, and the handler factory. */
+type AppSchedules<Schedules extends Readonly<Record<string, string>>> = {
+  readonly schedules: Schedules;
+  /** Parses `controller.cron`, a bare string from the platform, into a known expression. */
+  readonly schema: z.ZodType<ScheduleExpression<Schedules>>;
+  /**
+   * Route each schedule to its work. One run per expression, so a schedule added without
+   * work fails to compile. An expression Wrangler fires that the map does not know is logged
+   * once and ignored. A run that throws rejects, so Cloudflare marks the invocation failed.
+   */
+  handler<Deps>(runs: Readonly<Record<ScheduleExpression<Schedules>, ScheduledRun<Deps>>>): ScheduledHandler<Deps>;
+};
+/**
+ * Define the application's schedules once: `EVERY_MINUTE: '* * * * *'`. Keys name the time,
+ * not the work, because one schedule may drive several commands. Wrangler's `triggers.crons`
+ * must hold exactly these expressions. Cron does not retry: a run that sweeps many items
+ * catches each item's failure itself.
+ */
+export declare function defineSchedules<const Schedules extends Readonly<Record<string, string>>>(schedules: Schedules): AppSchedules<Schedules>;
+/**
+ * The id of a command a schedule issues: `cron:<Name>:<scheduledTime>`. A doubled trigger for
+ * the same time is then a duplicate by construction, and the unit of work skips it.
+ */
+export declare function scheduledMessageId(name: string, at: Date): MessageId;
+//#endregion
+export type { AppSchedules, ScheduleExpression, ScheduledHandler, ScheduledRun };
+//# sourceMappingURL=scheduled.d.ts.map

package/dist/cloudflare/scheduled.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scheduled.d.ts","names":[],"sources":["../../src/infrastructure/cloudflare/scheduled/scheduled-handler.ts"],"mappings":";;;;KAOY,aAAa,SAAS,MAAM,MAAM,IAAI,SAAS;;KAG/C,mBAAmB,kBAAkB,SAAS,2BACxD,gBAAgB;;KAGN,iBAAiB,SAAS,YAAY,qBAAqB,MAAM,SAAS;;KAG1E,aAAa,kBAAkB,SAAS;WACzC,WAAW;;WAEX,QAAQ,EAAE,QAAQ,mBAAmB;;;;;;EAM9C,QAAQ,MACN,MAAM,SAAS,OAAO,mBAAmB,YAAY,aAAa,UACjE,iBAAiB;;;;;;;;wBASN,sBAAsB,kBAAkB,SAAS,yBAC/D,WAAW,YACV,aAAa;;;;;wBAoBA,mBAAmB,cAAc,IAAI,OAAO"}

package/dist/cloudflare/scheduled.js

@@ -0,0 +1,37 @@
+import { a as createLogger } from "../core-DC_4pOrI.js";
+import { z } from "zod";
+
+//#region src/infrastructure/cloudflare/scheduled/scheduled-handler.ts
+const logger = createLogger("scheduled");
+/**
+* Define the application's schedules once: `EVERY_MINUTE: '* * * * *'`. Keys name the time,
+* not the work, because one schedule may drive several commands. Wrangler's `triggers.crons`
+* must hold exactly these expressions. Cron does not retry: a run that sweeps many items
+* catches each item's failure itself.
+*/
+function defineSchedules(schedules) {
+	const schema = z.enum(schedules);
+	return {
+		schedules,
+		schema,
+		handler: (runs) => async (controller, deps) => {
+			const { cron } = controller;
+			if (!schema.validate(cron)) {
+				logger.error("scheduled_unknown_cron", { details: { cron } });
+				return;
+			}
+			await runs[cron](deps, new Date(controller.scheduledTime));
+		}
+	};
+}
+/**
+* The id of a command a schedule issues: `cron:<Name>:<scheduledTime>`. A doubled trigger for
+* the same time is then a duplicate by construction, and the unit of work skips it.
+*/
+function scheduledMessageId(name, at) {
+	return `cron:${name}:${String(at.getTime())}`;
+}
+
+//#endregion
+export { defineSchedules, scheduledMessageId };
+//# sourceMappingURL=scheduled.js.map

package/dist/cloudflare/scheduled.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"scheduled.js","names":[],"sources":["../../src/infrastructure/cloudflare/scheduled/scheduled-handler.ts"],"sourcesContent":["import { z } from 'zod'\n\nimport { createLogger, type MessageId } from '@/core'\n\nconst logger = createLogger('scheduled')\n\n/** The work one schedule runs. Nothing returns to the platform, so each run reports its own outcome. */\nexport type ScheduledRun<Deps> = (deps: Deps, at: Date) => Promise<void>\n\n/** The cron expressions of a schedule map, as literal types. */\nexport type ScheduleExpression<Schedules extends Readonly<Record<string, string>>> =\n  Schedules[keyof Schedules]\n\n/** The Cloudflare `scheduled` export, with the application's dependencies as its second argument. */\nexport type ScheduledHandler<Deps> = (controller: ScheduledController, deps: Deps) => Promise<void>\n\n/** What `defineSchedules` returns: the map, its parser, and the handler factory. */\nexport type AppSchedules<Schedules extends Readonly<Record<string, string>>> = {\n  readonly schedules: Schedules\n  /** Parses `controller.cron`, a bare string from the platform, into a known expression. */\n  readonly schema: z.ZodType<ScheduleExpression<Schedules>>\n  /**\n   * Route each schedule to its work. One run per expression, so a schedule added without\n   * work fails to compile. An expression Wrangler fires that the map does not know is logged\n   * once and ignored. A run that throws rejects, so Cloudflare marks the invocation failed.\n   */\n  handler<Deps>(\n    runs: Readonly<Record<ScheduleExpression<Schedules>, ScheduledRun<Deps>>>,\n  ): ScheduledHandler<Deps>\n}\n\n/**\n * Define the application's schedules once: `EVERY_MINUTE: '* * * * *'`. Keys name the time,\n * not the work, because one schedule may drive several commands. Wrangler's `triggers.crons`\n * must hold exactly these expressions. Cron does not retry: a run that sweeps many items\n * catches each item's failure itself.\n */\nexport function defineSchedules<const Schedules extends Readonly<Record<string, string>>>(\n  schedules: Schedules,\n): AppSchedules<Schedules> {\n  const schema = z.enum(schedules)\n  return {\n    schedules,\n    schema,\n    handler: (runs) => async (controller, deps) => {\n      const { cron } = controller\n      if (!schema.validate(cron)) {\n        logger.error('scheduled_unknown_cron', { details: { cron } })\n        return\n      }\n      await runs[cron](deps, new Date(controller.scheduledTime))\n    },\n  }\n}\n\n/**\n * The id of a command a schedule issues: `cron:<Name>:<scheduledTime>`. A doubled trigger for\n * the same time is then a duplicate by construction, and the unit of work skips it.\n */\nexport function scheduledMessageId(name: string, at: Date): MessageId {\n  return `cron:${name}:${String(at.getTime())}`\n}\n"],"mappings":";;;;AAIA,MAAM,SAAS,aAAa,WAAW;;;;;;;AAiCvC,SAAgB,gBACd,WACyB;CACzB,MAAM,SAAS,EAAE,KAAK,SAAS;CAC/B,OAAO;EACL;EACA;EACA,UAAU,SAAS,OAAO,YAAY,SAAS;GAC7C,MAAM,EAAE,SAAS;GACjB,IAAI,CAAC,OAAO,SAAS,IAAI,GAAG;IAC1B,OAAO,MAAM,0BAA0B,EAAE,SAAS,EAAE,KAAK,EAAE,CAAC;IAC5D;GACF;GACA,MAAM,KAAK,KAAK,CAAC,MAAM,IAAI,KAAK,WAAW,aAAa,CAAC;EAC3D;CACF;AACF;;;;;AAMA,SAAgB,mBAAmB,MAAc,IAAqB;CACpE,OAAO,QAAQ,KAAK,GAAG,OAAO,GAAG,QAAQ,CAAC;AAC5C"}

package/dist/cloudflare.d.ts

@@ -1,6 +1,6 @@
-import { G as DatabaseFailure, I as MessageId, N as DomainEvent, U as D1ConstraintKind, W as DatabaseError } from "./index-BStnggQO.js";
-import { s as ITransaction, v as IMessageStore } from "./index-DWIRrJMP.js";
-import { n as DrizzleSchema, t as eventCollector } from "./unit-of-work-context-CPz9rdSS.js";
+import { W as DomainEvent, et as D1ConstraintKind, nt as DatabaseFailure, q as MessageId, tt as DatabaseError } from "./index-6XMPJu7u.js";
+import { s as ITransaction, v as IMessageStore } from "./index-_Cihfq1J.js";
+import { n as DrizzleSchema, t as eventCollector } from "./unit-of-work-context-BWTJfYPW.js";
 import { BatchItem } from "drizzle-orm/batch";
 import { AnyD1Database, DrizzleD1Database } from "drizzle-orm/d1";
 //#region src/infrastructure/cloudflare/d1-database-types.d.ts

package/dist/cloudflare.js

@@ -1,6 +1,6 @@
-import { N as AppError, g as DatabaseError } from "./core-Cx5SeyKV.js";
-import { i as MessageAlreadyProcessedError } from "./application-DjsQtpgw.js";
-import { i as stageD1Statement, n as eventCollector, r as runWithUnitOfWorkContext, t as collectD1Statements } from "./unit-of-work-context-DToDpAkv.js";
+import { E as DatabaseError, U as AppError } from "./core-DC_4pOrI.js";
+import { i as MessageAlreadyProcessedError } from "./application-DYfcAy-Q.js";
+import { i as stageD1Statement, n as eventCollector, r as runWithUnitOfWorkContext, t as collectD1Statements } from "./unit-of-work-context-BFCmU92Z.js";
 import { DrizzleQueryError } from "drizzle-orm/errors";
 import { eq, sql } from "drizzle-orm";
 import { index, integer, sqliteTable, text } from "drizzle-orm/sqlite-core";