better-ship 0.7.0 → 0.8.0

package/src/infrastructure/cloudflare/queue/queue-client.ts

@@ -0,0 +1,177 @@
+import { Result } from 'better-result'
+
+import { createLogger, shouldRetryFailure } from '@/core'
+
+import {
+  chunkByLimits,
+  isOversized,
+  messageByteLength,
+  QUEUE_LIMITS,
+  sizeMessages,
+  type SizedMessage,
+} from './queue-limits.ts'
+import type { QueueMessage } from './queue-message.ts'
+import { OversizedMessageError, QueueSendError, type QueueOperation } from './queue.errors.ts'
+
+/** Cloudflare's delivery delay, in seconds. */
+export type QueueSendOptions = { readonly delaySeconds: number }
+
+/** The two calls the client makes on a queue binding. */
+export type QueueBinding<Body> = Pick<Queue<Body>, 'send' | 'sendBatch'>
+
+/**
+ * The lanes and the dead letter of one application. A lane is a queue with its own consumer
+ * settings; `laneOf` is the product's routing rule, written once at the composition root.
+ */
+export type QueueClientOptions<TMessage extends QueueMessage, Lane extends string> = {
+  readonly queues: Readonly<Record<Lane, QueueBinding<TMessage>>>
+  /** Where the consumer parks poison bodies. Cloudflare also routes exhausted retries here. */
+  readonly deadLetter: Pick<Queue, 'send'>
+  readonly laneOf: (message: TMessage) => Lane
+}
+
+/** The port an entrypoint, a relay, or a consumer sends through. */
+export interface IQueueClient<TMessage extends QueueMessage> {
+  send(message: TMessage, options?: QueueSendOptions): Promise<void>
+  sendBatch(messages: ReadonlyArray<TMessage>): Promise<void>
+  /** Sends every message within the limits and returns the oversized ones. */
+  sendBatchPartial(messages: ReadonlyArray<TMessage>): Promise<ReadonlyArray<TMessage>>
+  /** Parks a delivered message's body as it arrived. */
+  sendToDlq(message: Message): Promise<void>
+}
+
+const logger = 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: QueueSendError): boolean {
+  return shouldRetryFailure({
+    classification: error.classification,
+    repeatSafe: true,
+    owner: 'immediate',
+  })
+}
+
+function oversizedError(sized: SizedMessage<QueueMessage>): OversizedMessageError {
+  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`.
+ */
+export class QueueClient<
+  TMessage extends QueueMessage,
+  Lane extends string,
+> implements IQueueClient<TMessage> {
+  constructor(private readonly options: QueueClientOptions<TMessage, Lane>) {}
+
+  /** @throws OversizedMessageError before the send. @throws QueueSendError after the retries. */
+  async send(message: TMessage, options?: QueueSendOptions): Promise<void> {
+    const sized = { message, bytes: messageByteLength(message) }
+    if (isOversized(sized)) {
+      logger.warn('queue_message_oversized', {
+        name: message.name,
+        type: message.type,
+        bytes: sized.bytes,
+      })
+      throw oversizedError(sized)
+    }
+
+    const queue = this.queueFor(message)
+    logger.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: ReadonlyArray<TMessage>): Promise<void> {
+    const sized = sizeMessages(messages)
+    const oversized = sized.find(isOversized)
+    if (oversized) throw oversizedError(oversized)
+    await this.sendSizedBatch(sized)
+  }
+
+  async sendBatchPartial(messages: ReadonlyArray<TMessage>): Promise<ReadonlyArray<TMessage>> {
+    const sized = sizeMessages(messages)
+    await this.sendSizedBatch(sized.filter((item) => !isOversized(item)))
+    return sized.filter(isOversized).map((item) => item.message)
+  }
+
+  async sendToDlq(message: Message): Promise<void> {
+    logger.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. */
+  private async sendSizedBatch(sized: ReadonlyArray<SizedMessage<TMessage>>): Promise<void> {
+    const byLane = new Map<Lane, SizedMessage<TMessage>[]>()
+    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.debug('sending_batch', {
+      count: sized.length,
+      lanes: [...byLane].map(([lane, items]) => ({ lane, count: items.length })),
+    })
+
+    const sends: Promise<void>[] = []
+    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)
+  }
+
+  private queueFor(message: TMessage): QueueBinding<TMessage> {
+    return this.options.queues[this.options.laneOf(message)]
+  }
+
+  private async callQueue<T>(operation: QueueOperation, call: () => Promise<T>): Promise<T> {
+    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
+  }
+}

package/src/infrastructure/cloudflare/queue/queue-consumer.ts

@@ -0,0 +1,146 @@
+import type { z } from 'zod'
+
+import { MessageAlreadyProcessedError } from '@/application'
+import { createLogger } from '@/core'
+
+import type { IQueueClient } from './queue-client.ts'
+import type { QueueMessage } from './queue-message.ts'
+import { DeadLetterUnavailableError } from './queue.errors.ts'
+import { decideRedelivery } from './redelivery-policy.ts'
+
+const logger = createLogger('queue-consumer')
+
+/** Wraps one dispatch: an error-tracking scope, an analytics context. The default runs it as is. */
+export type DispatchWrapper<TMessage extends QueueMessage> = (
+  message: TMessage,
+  attempt: number,
+  run: () => Promise<void>,
+) => Promise<void>
+
+/** The one call the consumer makes on the bus. */
+export type DispatchBus<TMessage extends QueueMessage> = {
+  // oxlint-disable-next-line anti-slop/no-unknown-returns -- the bus resolves to each handler's own value; the consumer discards it.
+  handle(message: TMessage): Promise<unknown>
+}
+
+/**
+ * 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.
+ */
+export class QueueConsumer<TMessage extends QueueMessage> {
+  /**
+   * @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(
+    private readonly bus: DispatchBus<TMessage>,
+    private readonly queueClient: Pick<IQueueClient<TMessage>, 'sendToDlq'>,
+    private readonly schema: z.ZodType<TMessage>,
+    private readonly wrapDispatch: DispatchWrapper<TMessage> = (_message, _attempt, run) => run(),
+  ) {}
+
+  /** Every message settles on its own. A settlement that throws rejects the batch after its siblings settle. */
+  async processBatch(batch: MessageBatch): Promise<void> {
+    logger.debug('queue_batch_received', { count: batch.messages.length })
+    const results = await Promise.allSettled(
+      batch.messages.map((message) => this.processMessage(message)),
+    )
+    const rejected = results
+      .filter((result) => result.status === 'rejected')
+      .map((result) => result.reason)
+
+    if (rejected.length > 0) {
+      throw new AggregateError(rejected, 'Queue message settlement failed')
+    }
+  }
+
+  private async processMessage(message: Message): Promise<void> {
+    let parsed: TMessage | null = null
+
+    try {
+      const body = await this.parseMessage(message)
+      if (body === null) {
+        // An unparseable body cannot succeed on retry, so park it for inspection.
+        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. */
+  private async parseMessage(message: Message): Promise<TMessage | null> {
+    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. */
+  private async parkPoison(message: Message): Promise<void> {
+    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.
+   */
+  private handleFailure(message: Message, parsed: TMessage | null, cause: unknown): void {
+    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 })
+  }
+}

package/src/infrastructure/cloudflare/queue/queue-limits.ts

@@ -0,0 +1,54 @@
+import type { QueueMessage } from './queue-message.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/
+ */
+export const QUEUE_LIMITS = {
+  messageBytes: 127_000,
+  batchBytes: 250_000,
+  batchCount: 100,
+} as const
+
+/** The size the binding measures: the JSON encoding of the body, in UTF-8 bytes. */
+export function messageByteLength(message: QueueMessage): number {
+  return new TextEncoder().encode(JSON.stringify(message)).length
+}
+
+/** A message with its measured size. */
+export type SizedMessage<TMessage> = { readonly message: TMessage; readonly bytes: number }
+
+/** Measure every message once. */
+export function sizeMessages<TMessage extends QueueMessage>(
+  messages: ReadonlyArray<TMessage>,
+): SizedMessage<TMessage>[] {
+  return messages.map((message) => ({ message, bytes: messageByteLength(message) }))
+}
+
+/** Whether one message is over the per-message limit. */
+export function isOversized(sized: SizedMessage<QueueMessage>): boolean {
+  return sized.bytes > QUEUE_LIMITS.messageBytes
+}
+
+/** Split a batch at the message-count and byte limits, keeping the order. */
+export function chunkByLimits<TMessage>(
+  sized: ReadonlyArray<SizedMessage<TMessage>>,
+): TMessage[][] {
+  const chunks: TMessage[][] = []
+  let current: TMessage[] = []
+  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
+}

package/src/infrastructure/cloudflare/queue/queue-message.ts

@@ -0,0 +1,4 @@
+import type { DomainCommand, DomainEvent } from '@/core'
+
+/** A message a queue carries: a command from outside the request, or an event from the outbox. */
+export type QueueMessage = DomainCommand | DomainEvent

package/src/infrastructure/cloudflare/queue/queue.errors.ts

@@ -0,0 +1,105 @@
+import { AppError, classifyBoundaryError, type FailureClassification } from '@/core'
+
+/** The Queue binding calls the client makes. Each is safe to repeat. */
+export type QueueOperation = 'send' | 'send_batch' | 'send_dlq'
+
+const QUEUE_OPERATION_MESSAGES = {
+  send: 'Failed to send queue message',
+  send_batch: 'Failed to send queue batch',
+  send_dlq: 'Failed to send DLQ message',
+} satisfies Readonly<Record<QueueOperation, string>>
+
+/**
+ * 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 = new Map<number, FailureClassification>([
+  [10104, 'terminal'], // QueueNotFound
+  [10106, 'terminal'], // Unauthorized
+  [10107, 'terminal'], // QueueIDMalformed
+  [10201, 'transient'], // ClientDisconnected
+  [10202, 'terminal'], // BatchDelayInvalid
+  [10203, 'terminal'], // MessageMetadataInvalid
+  [10204, 'terminal'], // MessageSizeOutOfBounds
+  [10205, 'terminal'], // BatchSizeOutOfBounds
+  [10206, 'terminal'], // BatchCountOutOfBounds
+  [10207, 'terminal'], // JSONRequestBodyInvalid
+  [10208, 'terminal'], // JSONRequestBodyMalformed
+  [10250, 'transient'], // QueueOverloaded
+  [10251, 'transient'], // QueueStorageLimitExceeded
+  [10252, 'terminal'], // QueueDisabled
+  [10253, 'terminal'], // FreeTierLimitExceeded
+  [15000, 'unknown'], // UnknownInternalError
+])
+
+function extractQueueErrorCode(cause: unknown): number | undefined {
+  if (!(cause instanceof Error)) return undefined
+  const match = /(\d{5})\)?\s*$/.exec(cause.message)
+  return match?.[1] === undefined ? undefined : Number(match[1])
+}
+
+function classifyQueueBoundaryError(cause: unknown): FailureClassification | undefined {
+  const code = extractQueueErrorCode(cause)
+  return code === undefined ? undefined : QUEUE_ERROR_CLASSIFICATIONS.get(code)
+}
+
+/** Classify a raw Queue binding failure: the code table first, then Cloudflare's signals, then transport. */
+export function classifyQueueError(cause: unknown): FailureClassification {
+  return classifyBoundaryError({
+    cause,
+    classifyBoundary: classifyQueueBoundaryError,
+    includeCloudflare: true,
+  })
+}
+
+/** A send through a Queue binding failed. The classification says whether an immediate retry may help. */
+export class QueueSendError extends AppError {
+  readonly _tag = 'QueueSendError'
+  readonly classification: FailureClassification
+  readonly operation: QueueOperation
+
+  constructor(args: { readonly operation: QueueOperation; readonly cause: unknown }) {
+    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.
+ */
+export class OversizedMessageError extends AppError {
+  readonly _tag = 'OversizedMessageError'
+  readonly classification = 'terminal'
+  readonly messageName: string
+  readonly bytes: number
+  readonly limit: number
+
+  constructor(args: {
+    readonly messageName: string
+    readonly bytes: number
+    readonly limit: number
+  }) {
+    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.
+ */
+export class DeadLetterUnavailableError extends AppError {
+  readonly _tag = 'DeadLetterUnavailableError'
+  readonly classification = 'transient'
+
+  constructor(cause: unknown) {
+    super('The dead letter did not accept the message', { cause })
+  }
+}

package/src/infrastructure/cloudflare/queue/redelivery-policy.ts

@@ -0,0 +1,64 @@
+import {
+  classifyFailure,
+  exponentialEqualJitterMs,
+  retryAfterSecondsOf,
+  shouldRetryFailure,
+  spreadJitterMs,
+  type FailureClassification,
+} from '@/core'
+
+const BASE_RETRY_DELAY_MS = 5_000
+const MAX_RETRY_DELAY_MS = 120_000
+const RETRY_AFTER_SPREAD_MS = 5_000
+/** Cloudflare Queues accept a redelivery delay of at most one day. */
+const MAX_QUEUE_DELAY_SECONDS = 24 * 60 * 60
+
+/** How the consumer settles one failed message: acknowledge it, or have Cloudflare redeliver it after a delay. */
+export type RedeliveryDecision =
+  | { readonly action: 'ack'; readonly classification: 'terminal' }
+  | {
+      readonly action: 'retry'
+      readonly classification: Exclude<FailureClassification, 'terminal'>
+      readonly delaySeconds: number
+    }
+
+/**
+ * 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.
+ */
+export function decideRedelivery(cause: unknown, attempt: number): RedeliveryDecision {
+  if (cause instanceof AggregateError && cause.errors.length > 0) {
+    const decisions = cause.errors.map((member) => decideRedelivery(member, attempt))
+    const retries = decisions.filter((decision) => decision.action === 'retry')
+    if (retries.length === 0) return { action: 'ack', classification: 'terminal' }
+
+    // Redelivery must respect every failed subscriber's required wait.
+    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 }
+
+  const canRetry = shouldRetryFailure({ classification, repeatSafe: true, owner: 'durable' })
+  if (!canRetry) return { action: 'ack', classification: 'terminal' }
+
+  const retryAfterSeconds = retryAfterSecondsOf(cause)
+  const delayMs =
+    retryAfterSeconds === null
+      ? exponentialEqualJitterMs(BASE_RETRY_DELAY_MS, MAX_RETRY_DELAY_MS, attempt)
+      : retryAfterSeconds * 1_000 + spreadJitterMs(RETRY_AFTER_SPREAD_MS)
+
+  return {
+    action: 'retry',
+    classification,
+    delaySeconds: Math.min(MAX_QUEUE_DELAY_SECONDS, Math.max(1, Math.ceil(delayMs / 1_000))),
+  }
+}