better-ship 0.7.0 → 0.10.0

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))),
+  }
+}

package/src/infrastructure/cloudflare/scheduled/index.ts

@@ -0,0 +1,8 @@
+export {
+  defineSchedules,
+  scheduledMessageId,
+  type AppSchedules,
+  type ScheduledHandler,
+  type ScheduledRun,
+  type ScheduleExpression,
+} from './scheduled-handler.ts'

package/src/infrastructure/cloudflare/scheduled/scheduled-handler.ts

@@ -0,0 +1,62 @@
+import { z } from 'zod'
+
+import { createLogger, type MessageId } from '@/core'
+
+const logger = createLogger('scheduled')
+
+/** The work one schedule runs. Nothing returns to the platform, so each run reports its own outcome. */
+export type ScheduledRun<Deps> = (deps: Deps, at: Date) => Promise<void>
+
+/** The cron expressions of a schedule map, as literal types. */
+export type ScheduleExpression<Schedules extends Readonly<Record<string, string>>> =
+  Schedules[keyof Schedules]
+
+/** The Cloudflare `scheduled` export, with the application's dependencies as its second argument. */
+export type ScheduledHandler<Deps> = (controller: ScheduledController, deps: Deps) => Promise<void>
+
+/** What `defineSchedules` returns: the map, its parser, and the handler factory. */
+export 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 function defineSchedules<const Schedules extends Readonly<Record<string, string>>>(
+  schedules: Schedules,
+): AppSchedules<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.
+ */
+export function scheduledMessageId(name: string, at: Date): MessageId {
+  return `cron:${name}:${String(at.getTime())}`
+}

package/src/infrastructure/tanstack/auth.middleware.ts

@@ -1,9 +1,11 @@
-import { createMiddleware, type Register, type RequestServerOptions } from '@tanstack/react-start'
+import { createMiddleware } from '@tanstack/react-start'
 import { getRequestHeaders } from '@tanstack/react-start/server'
 import { getSessionCookie } from 'better-auth/cookies'
 
 import { AuthenticationError, StaleSessionError, createLogger } from '@/core'
 
+import type { RequestContext } from './request-context.ts'
+
 const logger = createLogger('auth-middleware')
 
 /** The fields middleware reads; generic callers retain every additional session and user field. */
@@ -28,7 +30,7 @@ export type AuthContext<Session extends AuthSession> =
 
 /** Select the current request's Better Auth instance from TanStack's registered context. */
 export type AuthMiddlewareOptions<Session extends AuthSession> = {
-  readonly getAuth: (context: RequestServerOptions<Register, undefined>['context']) => {
+  readonly getAuth: (context: RequestContext) => {
     readonly api: {
       readonly getSession: (options: { headers: Headers }) => Promise<Session | null>
     }
@@ -60,7 +62,7 @@ export function createAuthMiddleware<Session extends AuthSession>(
   )
 
   async function resolveRequiredSession(
-    context: RequestServerOptions<Register, undefined>['context'],
+    context: RequestContext,
     headers: Headers,
   ): Promise<Session> {
     const resolved = await options.getAuth(context).api.getSession({ headers })

package/src/infrastructure/tanstack/error.middleware.ts

@@ -1,15 +1,14 @@
-import { isNotFound, isRedirect, type AnyRedirect } from '@tanstack/react-router'
-import { createMiddleware, type Register, type RequestServerOptions } from '@tanstack/react-start'
+import { isNotFound, isRedirect, redirect } from '@tanstack/react-router'
+import { createMiddleware } from '@tanstack/react-start'
 import type { BetterAuthCookies } from 'better-auth'
 
 import { StaleSessionError, type ErrorTable } from '@/core'
 
 import { createHttpErrorResponseConverter } from './http-error-response.ts'
+import type { RequestContext } from './request-context.ts'
 import { clearStaleSessionCookies } from './session-cookies.ts'
 import { createErrorPayloadConverter } from './to-error-payload.ts'
 
-type RequestContext = RequestServerOptions<Register, undefined>['context']
-
 /** The part of a Better Auth instance the boundary reads: its computed cookie definitions. */
 export type AuthCookieSource = {
   readonly $context: Promise<{ readonly authCookies: BetterAuthCookies }>
@@ -18,8 +17,8 @@ export type AuthCookieSource = {
 /** The application's error table, its stale-session redirect, and its Better Auth instance. */
 export type ErrorMiddlewareOptions<Entries> = {
   readonly errors: ErrorTable<Entries>
-  /** Build the redirect a server function throws for a stale session. */
-  readonly signIn: () => AnyRedirect
+  /** The path a server function redirects to for a stale session, with any search string. */
+  readonly signIn: string
   /** Select the request's Better Auth instance; its cookie definitions say what to clear. */
   readonly getAuth: (context: RequestContext) => AuthCookieSource
 }
@@ -43,7 +42,7 @@ export function createErrorMiddleware<Entries>(options: ErrorMiddlewareOptions<E
     if (cause instanceof StaleSessionError) {
       await clearSession(context)
       // oxlint-disable-next-line typescript/only-throw-error -- Router redirects by throwing this.
-      throw options.signIn()
+      throw redirect({ href: options.signIn })
     }
     // oxlint-disable-next-line typescript/only-throw-error -- The client rejects with this and reads its tag.
     throw toErrorPayload(cause)

package/src/infrastructure/tanstack/request-context.ts

@@ -0,0 +1,11 @@
+import type { Register } from '@tanstack/react-start'
+
+/**
+ * The request context an application registers as `Register.server.requestContext`.
+ * TanStack's own request context type also reads `Register.config`, which lists the middleware
+ * whose options carry this type, so using it here would make every application's types circular.
+ * Without a registration TanStack passes no context, so the fallback is `undefined`.
+ */
+export type RequestContext = Register extends { server: { requestContext: infer Context } }
+  ? Context
+  : undefined