better-ship 0.11.0 → 0.13.0

package/src/application/outbox-retention.ts

@@ -0,0 +1,61 @@
+import type { IOutboxRetentionRepository } from './outbox-repository.ts'
+
+/** Typist's retention defaults; receipt retention must cover the application's supported replay period. */
+export type OutboxRetentionOptions = {
+  readonly publishedRetentionMs?: number
+  readonly failedRetentionMs?: number
+  readonly receiptRetentionMs?: number
+  readonly batchSize?: number
+  readonly maxBatches?: number
+}
+
+/** Deleted records per category during one bounded sweep. */
+export type OutboxRetentionResult = {
+  readonly published: number
+  readonly failed: number
+  readonly receipts: number
+}
+
+/** Bounded cleanup ported from Typist's message retention handler. The application schedules each sweep. */
+export class OutboxRetention {
+  private readonly options: Required<OutboxRetentionOptions>
+
+  constructor(
+    private readonly repository: IOutboxRetentionRepository,
+    options: OutboxRetentionOptions = {},
+  ) {
+    this.options = {
+      publishedRetentionMs: options.publishedRetentionMs ?? 86_400_000,
+      failedRetentionMs: options.failedRetentionMs ?? 30 * 86_400_000,
+      receiptRetentionMs: options.receiptRetentionMs ?? 7 * 86_400_000,
+      batchSize: options.batchSize ?? 1_000,
+      maxBatches: options.maxBatches ?? 10,
+    }
+  }
+
+  /** Calculate all cutoffs from one supplied time; propagate repository failures to the calling boundary. */
+  async sweep(at: Date): Promise<OutboxRetentionResult> {
+    const { publishedRetentionMs, failedRetentionMs, receiptRetentionMs } = this.options
+    const published = await this.deleteBatches((size) =>
+      this.repository.deletePublishedBefore(new Date(at.getTime() - publishedRetentionMs), size),
+    )
+    const failed = await this.deleteBatches((size) =>
+      this.repository.deleteFailedBefore(new Date(at.getTime() - failedRetentionMs), size),
+    )
+    const receipts = await this.deleteBatches((size) =>
+      this.repository.deleteReceiptsBefore(new Date(at.getTime() - receiptRetentionMs), size),
+    )
+    return { published, failed, receipts }
+  }
+
+  private async deleteBatches(deleteBatch: (size: number) => Promise<number>): Promise<number> {
+    let total = 0
+    for (let batch = 0; batch < this.options.maxBatches; batch += 1) {
+      // oxlint-disable-next-line no-await-in-loop -- The delete count decides whether another batch is needed.
+      const deleted = await deleteBatch(this.options.batchSize)
+      total += deleted
+      if (deleted < this.options.batchSize) break
+    }
+    return total
+  }
+}

package/src/core/backoff.ts

@@ -21,7 +21,12 @@ export function exponentialEqualJitterMs(
   return Math.floor(halfCapMs) + spreadJitterMs(halfCapMs)
 }
 
-function exponentialDelayCapMs(baseDelayMs: number, maxDelayMs: number, attempt: number): number {
+/** Capped exponential delay for a durable retry recorded in storage. */
+export function exponentialDelayCapMs(
+  baseDelayMs: number,
+  maxDelayMs: number,
+  attempt: number,
+): number {
   if (!Number.isSafeInteger(attempt) || attempt < 1) {
     return panic('attempt must be a positive integer')
   }

package/src/core/index.ts

@@ -88,7 +88,7 @@ export {
   retryAfterSecondsOf,
   type BoundaryErrorClassifier,
 } from './classify-failure.ts'
-export { exponentialEqualJitterMs, spreadJitterMs } from './backoff.ts'
+export { exponentialDelayCapMs, exponentialEqualJitterMs, spreadJitterMs } from './backoff.ts'
 export {
   configureLogger,
   consoleSink,

package/src/infrastructure/cloudflare/d1-outbox-repository.ts

@@ -0,0 +1,224 @@
+import { and, asc, eq, inArray, isNull, lt, lte, or, sql } from 'drizzle-orm'
+
+import type { DeadLetterReason, IOutboxRepository, OutboxClaim, OutboxMessage } from '@/application'
+import { exponentialDelayCapMs } from '@/core'
+
+import type { DrizzleSchema } from '../drizzle-schema.ts'
+import {
+  OUTBOX_REPOSITORY_DEFAULTS,
+  type OutboxRepositoryOptions,
+} from '../outbox-repository-options.ts'
+import { executeDatabase } from './d1-database-execution.ts'
+import type { D1Db } from './d1-database-types.ts'
+import { messageOutbox, processedMessages } from './d1-schema.ts'
+
+/**
+ * Typist's atomic D1 claims on a plain connection, outside a unit of work.
+ * Every write runs once; lease expiry and the scheduled sweep recover interrupted operations.
+ */
+export class D1OutboxRepository<Schema extends DrizzleSchema> implements IOutboxRepository {
+  private readonly options: Required<OutboxRepositoryOptions>
+
+  constructor(
+    private readonly db: D1Db<Schema>,
+    options: OutboxRepositoryOptions = {},
+    private readonly now: () => Date = () => new Date(),
+  ) {
+    this.options = { ...OUTBOX_REPOSITORY_DEFAULTS, ...options }
+  }
+
+  /** Lease due rows in one statement; increment attempts even when reclaiming an expired lease. */
+  async claimPending(batchSize: number): Promise<OutboxClaim> {
+    const token = crypto.randomUUID()
+    const now = this.now()
+    const rows = await executeDatabase('claim pending outbox messages', () =>
+      this.db
+        .update(messageOutbox)
+        .set({
+          claimToken: token,
+          claimExpiresAt: deadline(now.getTime() + this.options.leaseMs),
+          attempts: sql`${messageOutbox.attempts} + 1`,
+        })
+        .where(
+          inArray(
+            messageOutbox.id,
+            this.db
+              .select({ id: messageOutbox.id })
+              .from(messageOutbox)
+              .where(
+                and(
+                  isNull(messageOutbox.publishedAt),
+                  isNull(messageOutbox.failedAt),
+                  lte(messageOutbox.availableAt, now),
+                  or(isNull(messageOutbox.claimExpiresAt), lte(messageOutbox.claimExpiresAt, now)),
+                ),
+              )
+              .orderBy(
+                asc(messageOutbox.availableAt),
+                asc(messageOutbox.createdAt),
+                asc(messageOutbox.id),
+              )
+              .limit(batchSize),
+          ),
+        )
+        .returning({
+          payload: messageOutbox.payload,
+          attempts: messageOutbox.attempts,
+          availableAt: messageOutbox.availableAt,
+          createdAt: messageOutbox.createdAt,
+        }),
+    )
+    // UPDATE RETURNING does not preserve the selection order.
+    rows.sort(
+      (a, b) =>
+        a.availableAt.getTime() - b.availableAt.getTime() ||
+        a.createdAt.getTime() - b.createdAt.getTime() ||
+        a.payload.id.localeCompare(b.payload.id),
+    )
+    return { token, messages: rows.map(({ payload, attempts }) => ({ payload, attempts })) }
+  }
+
+  /** Mark only supplied rows that still hold this token as published. */
+  async markPublished(claim: OutboxClaim, messages: ReadonlyArray<OutboxMessage>): Promise<void> {
+    if (messages.length === 0) return
+    await executeDatabase('mark outbox messages published', () =>
+      this.db
+        .update(messageOutbox)
+        .set({ publishedAt: this.now(), claimToken: null, claimExpiresAt: null })
+        .where(
+          and(
+            inArray(messageOutbox.id, outboxIds(messages)),
+            eq(messageOutbox.claimToken, claim.token),
+          ),
+        ),
+    )
+  }
+
+  /** Release supplied rows with per-row backoff; a stale token cannot change a newer claim. */
+  async releaseClaim(claim: OutboxClaim, messages: ReadonlyArray<OutboxMessage>): Promise<void> {
+    const now = this.now()
+    for (const attempts of new Set(messages.map((row) => row.attempts))) {
+      const rows = messages.filter((row) => row.attempts === attempts)
+      const delay = exponentialDelayCapMs(
+        this.options.retryBaseDelayMs,
+        this.options.retryMaxDelayMs,
+        attempts,
+      )
+      // oxlint-disable-next-line no-await-in-loop -- Stop releasing rows on the first database failure.
+      await executeDatabase('release outbox claim', () =>
+        this.db
+          .update(messageOutbox)
+          .set({
+            availableAt: deadline(now.getTime() + delay),
+            claimToken: null,
+            claimExpiresAt: null,
+          })
+          .where(
+            and(
+              inArray(messageOutbox.id, outboxIds(rows)),
+              eq(messageOutbox.claimToken, claim.token),
+            ),
+          ),
+      )
+    }
+  }
+
+  /** Retain the full payload and record a closed reason with a readable error message. */
+  async deadLetter(
+    claim: OutboxClaim,
+    messages: ReadonlyArray<OutboxMessage>,
+    reason: DeadLetterReason,
+    errorMessage: string,
+  ): Promise<void> {
+    if (messages.length === 0) return
+    await executeDatabase('dead-letter outbox messages', () =>
+      this.db
+        .update(messageOutbox)
+        .set({
+          failedAt: this.now(),
+          lastError: `${reason}: ${errorMessage}`,
+          claimToken: null,
+          claimExpiresAt: null,
+        })
+        .where(
+          and(
+            inArray(messageOutbox.id, outboxIds(messages)),
+            eq(messageOutbox.claimToken, claim.token),
+          ),
+        ),
+    )
+  }
+
+  /** Delete at most batchSize published rows, strictly before the cutoff. */
+  async deletePublishedBefore(cutoff: Date, batchSize: number): Promise<number> {
+    const rows = await executeDatabase('delete published outbox messages', () =>
+      this.db
+        .delete(messageOutbox)
+        .where(
+          inArray(
+            messageOutbox.id,
+            this.db
+              .select({ id: messageOutbox.id })
+              .from(messageOutbox)
+              .where(lt(messageOutbox.publishedAt, cutoff))
+              .orderBy(asc(messageOutbox.publishedAt), asc(messageOutbox.id))
+              .limit(batchSize),
+          ),
+        )
+        .returning({ id: messageOutbox.id }),
+    )
+    return rows.length
+  }
+
+  /** Delete at most batchSize failed rows; pending and published rows remain untouched. */
+  async deleteFailedBefore(cutoff: Date, batchSize: number): Promise<number> {
+    const rows = await executeDatabase('delete failed outbox messages', () =>
+      this.db
+        .delete(messageOutbox)
+        .where(
+          inArray(
+            messageOutbox.id,
+            this.db
+              .select({ id: messageOutbox.id })
+              .from(messageOutbox)
+              .where(and(isNull(messageOutbox.publishedAt), lt(messageOutbox.failedAt, cutoff)))
+              .orderBy(asc(messageOutbox.failedAt), asc(messageOutbox.id))
+              .limit(batchSize),
+          ),
+        )
+        .returning({ id: messageOutbox.id }),
+    )
+    return rows.length
+  }
+
+  /** Delete at most batchSize receipts, strictly before the cutoff. */
+  async deleteReceiptsBefore(cutoff: Date, batchSize: number): Promise<number> {
+    const rows = await executeDatabase('delete message receipts', () =>
+      this.db
+        .delete(processedMessages)
+        .where(
+          inArray(
+            processedMessages.messageId,
+            this.db
+              .select({ messageId: processedMessages.messageId })
+              .from(processedMessages)
+              .where(lt(processedMessages.processedAt, cutoff))
+              .orderBy(asc(processedMessages.processedAt), asc(processedMessages.messageId))
+              .limit(batchSize),
+          ),
+        )
+        .returning({ messageId: processedMessages.messageId }),
+    )
+    return rows.length
+  }
+}
+
+// One JSON parameter keeps large claims below D1's 100-parameter limit.
+function outboxIds(messages: ReadonlyArray<OutboxMessage>) {
+  return sql`(select value from json_each(${JSON.stringify(messages.map((row) => row.payload.id))}))`
+}
+
+// D1 timestamps repository seconds; round future deadlines up so a lease or delay never ends early.
+function deadline(ms: number): Date {
+  return new Date(Math.ceil(ms / 1_000) * 1_000)
+}

package/src/infrastructure/cloudflare/index.ts

@@ -7,3 +7,5 @@ export type { D1Connection, D1Db, D1ReadDb, D1Tx } from './d1-database-types.ts'
 export { DatabaseError, type DatabaseFailure, type D1ConstraintKind } from '@/core'
 export { executeDatabase } from './d1-database-execution.ts'
 export { eventCollector } from '../unit-of-work-context.ts'
+export { D1OutboxRepository } from './d1-outbox-repository.ts'
+export type { OutboxRepositoryOptions } from '../outbox-repository-options.ts'

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

@@ -23,3 +23,4 @@ export {
   type QueueOperation,
 } from './queue.errors.ts'
 export { decideRedelivery, type RedeliveryDecision } from './redelivery-policy.ts'
+export { waitUntilWake } from './wait-until-wake.ts'

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

@@ -35,7 +35,9 @@ 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>>
+  sendBatchPartial<Sent extends TMessage>(
+    messages: ReadonlyArray<Sent>,
+  ): Promise<ReadonlyArray<Sent>>
   /** Parks a delivered message's body as it arrived. */
   sendToDlq(message: Message): Promise<void>
 }
@@ -109,7 +111,9 @@ export class QueueClient<
     await this.sendSizedBatch(sized)
   }
 
-  async sendBatchPartial(messages: ReadonlyArray<TMessage>): Promise<ReadonlyArray<TMessage>> {
+  async sendBatchPartial<Sent extends TMessage>(
+    messages: ReadonlyArray<Sent>,
+  ): Promise<ReadonlyArray<Sent>> {
     const sized = sizeMessages(messages)
     await this.sendSizedBatch(sized.filter((item) => !isOversized(item)))
     return sized.filter(isOversized).map((item) => item.message)

package/src/infrastructure/cloudflare/queue/wait-until-wake.ts

@@ -0,0 +1,19 @@
+import type { IOutboxRelay, OutboxRelay } from '@/application'
+import { createLogger } from '@/core'
+
+const logger = createLogger('outbox-wake')
+
+/** Register delivery after commit; log a failed drain once and leave recovery to the scheduled sweep. */
+export function waitUntilWake(
+  context: Pick<ExecutionContext, 'waitUntil'>,
+  relay: Pick<OutboxRelay, 'drain'>,
+): IOutboxRelay {
+  return {
+    wake: () =>
+      context.waitUntil(
+        relay.drain().catch((cause: unknown) => {
+          logger.error('outbox_wake_failed', { error: cause })
+        }),
+      ),
+  }
+}

package/src/infrastructure/outbox-repository-options.ts

@@ -0,0 +1,9 @@
+/** Shared lease and delay defaults for both database adapters. */
+export const OUTBOX_REPOSITORY_DEFAULTS = {
+  leaseMs: 60_000,
+  retryBaseDelayMs: 1_000,
+  retryMaxDelayMs: 60_000,
+}
+
+/** Override lease and delay limits at the composition root. */
+export type OutboxRepositoryOptions = Readonly<Partial<typeof OUTBOX_REPOSITORY_DEFAULTS>>

package/src/infrastructure/postgres/index.ts

@@ -13,3 +13,5 @@ export { DatabaseError, type DatabaseFailure } from '@/core'
 export { executeDatabase } from './postgres-database-execution.ts'
 export { classifyPostgresError } from './classify-postgres-error.ts'
 export { eventCollector } from '../unit-of-work-context.ts'
+export { PostgresOutboxRepository } from './postgres-outbox-repository.ts'
+export type { OutboxRepositoryOptions } from '../outbox-repository-options.ts'

package/src/infrastructure/postgres/postgres-outbox-repository.ts

@@ -0,0 +1,216 @@
+import { and, asc, eq, inArray, isNull, lt, lte, or, sql } from 'drizzle-orm'
+
+import type { DeadLetterReason, IOutboxRepository, OutboxClaim, OutboxMessage } from '@/application'
+import { exponentialDelayCapMs } from '@/core'
+
+import type { DrizzleSchema } from '../drizzle-schema.ts'
+import {
+  OUTBOX_REPOSITORY_DEFAULTS,
+  type OutboxRepositoryOptions,
+} from '../outbox-repository-options.ts'
+import { executeDatabase } from './postgres-database-execution.ts'
+import type { PostgresDb } from './postgres-database-types.ts'
+import { messageOutbox, processedMessages } from './postgres-schema.ts'
+
+/**
+ * Typist's lease protocol with riposte's SKIP LOCKED selection on a plain connection, outside a unit of work.
+ * Every write runs once; lease expiry and the scheduled sweep recover interrupted operations.
+ */
+export class PostgresOutboxRepository implements IOutboxRepository {
+  private readonly options: Required<OutboxRepositoryOptions>
+
+  constructor(
+    private readonly db: PostgresDb<DrizzleSchema>,
+    options: OutboxRepositoryOptions = {},
+    private readonly now: () => Date = () => new Date(),
+  ) {
+    this.options = { ...OUTBOX_REPOSITORY_DEFAULTS, ...options }
+  }
+
+  /** Lease due rows in one statement; increment attempts even when reclaiming an expired lease. */
+  async claimPending(batchSize: number): Promise<OutboxClaim> {
+    const token = crypto.randomUUID()
+    const now = this.now()
+    const rows = await executeDatabase('claim pending outbox messages', () =>
+      this.db
+        .update(messageOutbox)
+        .set({
+          claimToken: token,
+          claimExpiresAt: new Date(now.getTime() + this.options.leaseMs),
+          attempts: sql`${messageOutbox.attempts} + 1`,
+        })
+        .where(
+          inArray(
+            messageOutbox.id,
+            this.db
+              .select({ id: messageOutbox.id })
+              .from(messageOutbox)
+              .where(
+                and(
+                  isNull(messageOutbox.publishedAt),
+                  isNull(messageOutbox.failedAt),
+                  lte(messageOutbox.availableAt, now),
+                  or(isNull(messageOutbox.claimExpiresAt), lte(messageOutbox.claimExpiresAt, now)),
+                ),
+              )
+              .orderBy(
+                asc(messageOutbox.availableAt),
+                asc(messageOutbox.createdAt),
+                asc(messageOutbox.id),
+              )
+              .limit(batchSize)
+              .for('update', { skipLocked: true }),
+          ),
+        )
+        .returning({
+          payload: messageOutbox.payload,
+          attempts: messageOutbox.attempts,
+          availableAt: messageOutbox.availableAt,
+          createdAt: messageOutbox.createdAt,
+        }),
+    )
+    // UPDATE RETURNING does not preserve the selection order.
+    rows.sort(
+      (a, b) =>
+        a.availableAt.getTime() - b.availableAt.getTime() ||
+        a.createdAt.getTime() - b.createdAt.getTime() ||
+        a.payload.id.localeCompare(b.payload.id),
+    )
+    return { token, messages: rows.map(({ payload, attempts }) => ({ payload, attempts })) }
+  }
+
+  /** Mark only supplied rows that still hold this token as published. */
+  async markPublished(claim: OutboxClaim, messages: ReadonlyArray<OutboxMessage>): Promise<void> {
+    if (messages.length === 0) return
+    await executeDatabase('mark outbox messages published', () =>
+      this.db
+        .update(messageOutbox)
+        .set({ publishedAt: this.now(), claimToken: null, claimExpiresAt: null })
+        .where(
+          and(
+            inArray(
+              messageOutbox.id,
+              messages.map((row) => row.payload.id),
+            ),
+            eq(messageOutbox.claimToken, claim.token),
+          ),
+        ),
+    )
+  }
+
+  /** Release supplied rows with per-row backoff; a stale token cannot change a newer claim. */
+  async releaseClaim(claim: OutboxClaim, messages: ReadonlyArray<OutboxMessage>): Promise<void> {
+    const now = this.now()
+    for (const attempts of new Set(messages.map((row) => row.attempts))) {
+      const ids = messages.filter((row) => row.attempts === attempts).map((row) => row.payload.id)
+      const delay = exponentialDelayCapMs(
+        this.options.retryBaseDelayMs,
+        this.options.retryMaxDelayMs,
+        attempts,
+      )
+      // oxlint-disable-next-line no-await-in-loop -- Stop releasing rows on the first database failure.
+      await executeDatabase('release outbox claim', () =>
+        this.db
+          .update(messageOutbox)
+          .set({
+            availableAt: new Date(now.getTime() + delay),
+            claimToken: null,
+            claimExpiresAt: null,
+          })
+          .where(and(inArray(messageOutbox.id, ids), eq(messageOutbox.claimToken, claim.token))),
+      )
+    }
+  }
+
+  /** Retain the full payload and record a closed reason with a readable error message. */
+  async deadLetter(
+    claim: OutboxClaim,
+    messages: ReadonlyArray<OutboxMessage>,
+    reason: DeadLetterReason,
+    errorMessage: string,
+  ): Promise<void> {
+    if (messages.length === 0) return
+    await executeDatabase('dead-letter outbox messages', () =>
+      this.db
+        .update(messageOutbox)
+        .set({
+          failedAt: this.now(),
+          lastError: `${reason}: ${errorMessage}`,
+          claimToken: null,
+          claimExpiresAt: null,
+        })
+        .where(
+          and(
+            inArray(
+              messageOutbox.id,
+              messages.map((row) => row.payload.id),
+            ),
+            eq(messageOutbox.claimToken, claim.token),
+          ),
+        ),
+    )
+  }
+
+  /** Delete at most batchSize published rows, strictly before the cutoff. */
+  async deletePublishedBefore(cutoff: Date, batchSize: number): Promise<number> {
+    const rows = await executeDatabase('delete published outbox messages', () =>
+      this.db
+        .delete(messageOutbox)
+        .where(
+          inArray(
+            messageOutbox.id,
+            this.db
+              .select({ id: messageOutbox.id })
+              .from(messageOutbox)
+              .where(lt(messageOutbox.publishedAt, cutoff))
+              .orderBy(asc(messageOutbox.publishedAt), asc(messageOutbox.id))
+              .limit(batchSize),
+          ),
+        )
+        .returning({ id: messageOutbox.id }),
+    )
+    return rows.length
+  }
+
+  /** Delete at most batchSize failed rows; pending and published rows remain untouched. */
+  async deleteFailedBefore(cutoff: Date, batchSize: number): Promise<number> {
+    const rows = await executeDatabase('delete failed outbox messages', () =>
+      this.db
+        .delete(messageOutbox)
+        .where(
+          inArray(
+            messageOutbox.id,
+            this.db
+              .select({ id: messageOutbox.id })
+              .from(messageOutbox)
+              .where(and(isNull(messageOutbox.publishedAt), lt(messageOutbox.failedAt, cutoff)))
+              .orderBy(asc(messageOutbox.failedAt), asc(messageOutbox.id))
+              .limit(batchSize),
+          ),
+        )
+        .returning({ id: messageOutbox.id }),
+    )
+    return rows.length
+  }
+
+  /** Delete at most batchSize receipts, strictly before the cutoff. */
+  async deleteReceiptsBefore(cutoff: Date, batchSize: number): Promise<number> {
+    const rows = await executeDatabase('delete message receipts', () =>
+      this.db
+        .delete(processedMessages)
+        .where(
+          inArray(
+            processedMessages.messageId,
+            this.db
+              .select({ messageId: processedMessages.messageId })
+              .from(processedMessages)
+              .where(lt(processedMessages.processedAt, cutoff))
+              .orderBy(asc(processedMessages.processedAt), asc(processedMessages.messageId))
+              .limit(batchSize),
+          ),
+        )
+        .returning({ messageId: processedMessages.messageId }),
+    )
+    return rows.length
+  }
+}

package/src/infrastructure/resend/resend-email-service.ts

@@ -99,7 +99,7 @@ export class ResendEmailService implements IEmailService {
     }
     const client = await this.client
     const payload: CreateEmailOptions = {
-      from: this.fromAddress,
+      from: email.from ?? this.fromAddress,
       to: [email.to].flat(),
       subject: email.subject,
       html: email.html,