better-ship 0.7.0 → 0.10.0

package/dist/{unit-of-work-context-DToDpAkv.js → unit-of-work-context-BFCmU92Z.js}

@@ -1,4 +1,4 @@
-import { t as UnitOfWorkAlreadyActiveError } from "./application-DjsQtpgw.js";
+import { t as UnitOfWorkAlreadyActiveError } from "./application-DYfcAy-Q.js";
 import { panic } from "better-result";
 import { AsyncLocalStorage } from "node:async_hooks";
 
@@ -45,4 +45,4 @@ function currentContext() {
 
 //#endregion
 export { stageD1Statement as i, eventCollector as n, runWithUnitOfWorkContext as r, collectD1Statements as t };
-//# sourceMappingURL=unit-of-work-context-DToDpAkv.js.map
+//# sourceMappingURL=unit-of-work-context-BFCmU92Z.js.map

package/dist/{unit-of-work-context-DToDpAkv.js.map → unit-of-work-context-BFCmU92Z.js.map}

@@ -1 +1 @@
-{"version":3,"file":"unit-of-work-context-DToDpAkv.js","names":[],"sources":["../src/infrastructure/unit-of-work-context.ts"],"sourcesContent":["import { AsyncLocalStorage } from 'node:async_hooks'\n\nimport { panic } from 'better-result'\nimport type { BatchItem } from 'drizzle-orm/batch'\n\nimport { UnitOfWorkAlreadyActiveError, type IEventCollector } from '@/application'\nimport type { DomainEvent } from '@/core'\n\ntype UnitOfWorkContext = { readonly events: DomainEvent[] } & (\n  | { readonly database: 'd1'; readonly statements: BatchItem<'sqlite'>[] }\n  | { readonly database: 'postgres' }\n)\n\n// One async scope isolates events and D1 statements and rejects nesting across both adapters.\nconst storage = new AsyncLocalStorage<UnitOfWorkContext>()\n\n/** Reject nested transactions before database work starts; preserve independent concurrent execution. */\nexport async function runWithUnitOfWorkContext<T>(\n  database: UnitOfWorkContext['database'],\n  work: () => Promise<T>,\n): Promise<T> {\n  if (storage.getStore() !== undefined) throw new UnitOfWorkAlreadyActiveError()\n  const context: UnitOfWorkContext =\n    database === 'd1' ? { database, events: [], statements: [] } : { database, events: [] }\n  return storage.run(context, work)\n}\n\n/** Inject this shared scope into the unit of work and expose its emitter to application handlers. */\nexport const eventCollector: IEventCollector = {\n  emit(event) {\n    currentContext().events.push(event)\n  },\n  collect() {\n    return [...currentContext().events]\n  },\n}\n\n/** Queue one native D1 statement for the active batch; other contexts cannot accept D1 writes. */\nexport function stageD1Statement(statement: BatchItem<'sqlite'>): void {\n  d1Context().statements.push(statement)\n}\n\n/** Read the active D1 batch in staging order for commit. */\nexport function collectD1Statements(): ReadonlyArray<BatchItem<'sqlite'>> {\n  return [...d1Context().statements]\n}\n\nfunction d1Context(): Extract<UnitOfWorkContext, { database: 'd1' }> {\n  const context = currentContext()\n  if (context.database !== 'd1') return panic('D1 statements require a D1 unit of work')\n  return context\n}\n\nfunction currentContext(): UnitOfWorkContext {\n  return storage.getStore() ?? panic('operation requires an active unit of work')\n}\n"],"mappings":";;;;;AAcA,MAAM,UAAU,IAAI,kBAAqC;;AAGzD,eAAsB,yBACpB,UACA,MACY;CACZ,IAAI,QAAQ,SAAS,MAAM,QAAW,MAAM,IAAI,6BAA6B;CAC7E,MAAM,UACJ,aAAa,OAAO;EAAE;EAAU,QAAQ,CAAC;EAAG,YAAY,CAAC;CAAE,IAAI;EAAE;EAAU,QAAQ,CAAC;CAAE;CACxF,OAAO,QAAQ,IAAI,SAAS,IAAI;AAClC;;AAGA,MAAa,iBAAkC;CAC7C,KAAK,OAAO;EACV,eAAe,CAAC,CAAC,OAAO,KAAK,KAAK;CACpC;CACA,UAAU;EACR,OAAO,CAAC,GAAG,eAAe,CAAC,CAAC,MAAM;CACpC;AACF;;AAGA,SAAgB,iBAAiB,WAAsC;CACrE,UAAU,CAAC,CAAC,WAAW,KAAK,SAAS;AACvC;;AAGA,SAAgB,sBAA0D;CACxE,OAAO,CAAC,GAAG,UAAU,CAAC,CAAC,UAAU;AACnC;AAEA,SAAS,YAA4D;CACnE,MAAM,UAAU,eAAe;CAC/B,IAAI,QAAQ,aAAa,MAAM,OAAO,MAAM,yCAAyC;CACrF,OAAO;AACT;AAEA,SAAS,iBAAoC;CAC3C,OAAO,QAAQ,SAAS,KAAK,MAAM,2CAA2C;AAChF"}
+{"version":3,"file":"unit-of-work-context-BFCmU92Z.js","names":[],"sources":["../src/infrastructure/unit-of-work-context.ts"],"sourcesContent":["import { AsyncLocalStorage } from 'node:async_hooks'\n\nimport { panic } from 'better-result'\nimport type { BatchItem } from 'drizzle-orm/batch'\n\nimport { UnitOfWorkAlreadyActiveError, type IEventCollector } from '@/application'\nimport type { DomainEvent } from '@/core'\n\ntype UnitOfWorkContext = { readonly events: DomainEvent[] } & (\n  | { readonly database: 'd1'; readonly statements: BatchItem<'sqlite'>[] }\n  | { readonly database: 'postgres' }\n)\n\n// One async scope isolates events and D1 statements and rejects nesting across both adapters.\nconst storage = new AsyncLocalStorage<UnitOfWorkContext>()\n\n/** Reject nested transactions before database work starts; preserve independent concurrent execution. */\nexport async function runWithUnitOfWorkContext<T>(\n  database: UnitOfWorkContext['database'],\n  work: () => Promise<T>,\n): Promise<T> {\n  if (storage.getStore() !== undefined) throw new UnitOfWorkAlreadyActiveError()\n  const context: UnitOfWorkContext =\n    database === 'd1' ? { database, events: [], statements: [] } : { database, events: [] }\n  return storage.run(context, work)\n}\n\n/** Inject this shared scope into the unit of work and expose its emitter to application handlers. */\nexport const eventCollector: IEventCollector = {\n  emit(event) {\n    currentContext().events.push(event)\n  },\n  collect() {\n    return [...currentContext().events]\n  },\n}\n\n/** Queue one native D1 statement for the active batch; other contexts cannot accept D1 writes. */\nexport function stageD1Statement(statement: BatchItem<'sqlite'>): void {\n  d1Context().statements.push(statement)\n}\n\n/** Read the active D1 batch in staging order for commit. */\nexport function collectD1Statements(): ReadonlyArray<BatchItem<'sqlite'>> {\n  return [...d1Context().statements]\n}\n\nfunction d1Context(): Extract<UnitOfWorkContext, { database: 'd1' }> {\n  const context = currentContext()\n  if (context.database !== 'd1') return panic('D1 statements require a D1 unit of work')\n  return context\n}\n\nfunction currentContext(): UnitOfWorkContext {\n  return storage.getStore() ?? panic('operation requires an active unit of work')\n}\n"],"mappings":";;;;;AAcA,MAAM,UAAU,IAAI,kBAAqC;;AAGzD,eAAsB,yBACpB,UACA,MACY;CACZ,IAAI,QAAQ,SAAS,MAAM,QAAW,MAAM,IAAI,6BAA6B;CAC7E,MAAM,UACJ,aAAa,OAAO;EAAE;EAAU,QAAQ,CAAC;EAAG,YAAY,CAAC;CAAE,IAAI;EAAE;EAAU,QAAQ,CAAC;CAAE;CACxF,OAAO,QAAQ,IAAI,SAAS,IAAI;AAClC;;AAGA,MAAa,iBAAkC;CAC7C,KAAK,OAAO;EACV,eAAe,CAAC,CAAC,OAAO,KAAK,KAAK;CACpC;CACA,UAAU;EACR,OAAO,CAAC,GAAG,eAAe,CAAC,CAAC,MAAM;CACpC;AACF;;AAGA,SAAgB,iBAAiB,WAAsC;CACrE,UAAU,CAAC,CAAC,WAAW,KAAK,SAAS;AACvC;;AAGA,SAAgB,sBAA0D;CACxE,OAAO,CAAC,GAAG,UAAU,CAAC,CAAC,UAAU;AACnC;AAEA,SAAS,YAA4D;CACnE,MAAM,UAAU,eAAe;CAC/B,IAAI,QAAQ,aAAa,MAAM,OAAO,MAAM,yCAAyC;CACrF,OAAO;AACT;AAEA,SAAS,iBAAoC;CAC3C,OAAO,QAAQ,SAAS,KAAK,MAAM,2CAA2C;AAChF"}

package/dist/{unit-of-work-context-CPz9rdSS.d.ts → unit-of-work-context-BWTJfYPW.d.ts}

@@ -1,5 +1,5 @@
-import "./index-BStnggQO.js";
-import { o as IEventCollector } from "./index-DWIRrJMP.js";
+import "./index-6XMPJu7u.js";
+import { o as IEventCollector } from "./index-_Cihfq1J.js";
 import { BatchItem } from "drizzle-orm/batch";
 //#region src/infrastructure/drizzle-schema.d.ts
 /**
@@ -13,4 +13,4 @@ type DrizzleSchema = Record<string, unknown>;
 declare const eventCollector: IEventCollector;
 //#endregion
 export { DrizzleSchema as n, eventCollector as t };
-//# sourceMappingURL=unit-of-work-context-CPz9rdSS.d.ts.map
+//# sourceMappingURL=unit-of-work-context-BWTJfYPW.d.ts.map

package/dist/{unit-of-work-context-CPz9rdSS.d.ts.map → unit-of-work-context-BWTJfYPW.d.ts.map}

@@ -1 +1 @@
-{"version":3,"file":"unit-of-work-context-CPz9rdSS.d.ts","names":[],"sources":["../src/infrastructure/drizzle-schema.ts","../src/infrastructure/unit-of-work-context.ts"],"mappings":";;;;;;;;KAKY,gBAAgB;;;;cCuBf,gBAAgB"}
+{"version":3,"file":"unit-of-work-context-BWTJfYPW.d.ts","names":[],"sources":["../src/infrastructure/drizzle-schema.ts","../src/infrastructure/unit-of-work-context.ts"],"mappings":";;;;;;;;KAKY,gBAAgB;;;;cCuBf,gBAAgB"}

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://www.schemastore.org/package.json",
   "name": "better-ship",
-  "version": "0.7.0",
+  "version": "0.10.0",
   "description": "Foundation for applications on Cloudflare Workers: logger, errors, message bus, infrastructure adapters, and UI primitives",
   "license": "Apache-2.0",
   "repository": {
@@ -24,6 +24,8 @@
     "./better-auth/stripe": "./dist/better-auth/stripe.js",
     "./cloudflare": "./dist/cloudflare.js",
     "./cloudflare/auth-secondary-storage": "./dist/cloudflare/auth-secondary-storage.js",
+    "./cloudflare/queue": "./dist/cloudflare/queue.js",
+    "./cloudflare/scheduled": "./dist/cloudflare/scheduled.js",
     "./core": "./dist/core.js",
     "./postgres": "./dist/postgres.js",
     "./tanstack": "./dist/tanstack.js",
@@ -52,7 +54,6 @@
     "better-auth": "^1.7.4",
     "drizzle-kit": "^0.31.10",
     "drizzle-orm": "^0.45.2",
-    "jose": "^6.2.12",
     "postgres": "^3.4.9",
     "stripe": "^22.6.2",
     "tsdown": "^0.23.0",
@@ -66,7 +67,6 @@
     "@tanstack/react-start": "^1.168.52",
     "better-auth": "^1.7.4",
     "drizzle-orm": "^0.45.2",
-    "jose": "^6.2.12",
     "stripe": "^22.6.2"
   },
   "peerDependenciesMeta": {
@@ -76,9 +76,6 @@
     "stripe": {
       "optional": true
     },
-    "jose": {
-      "optional": true
-    },
     "better-auth": {
       "optional": true
     },

package/src/core/backoff.ts

@@ -0,0 +1,29 @@
+import { panic } from 'better-result'
+
+/** Uniform jitter within one fixed window. */
+export function spreadJitterMs(spreadMs: number): number {
+  if (!Number.isFinite(spreadMs) || spreadMs < 0) {
+    return panic('spreadMs must be a non-negative number')
+  }
+  return Math.floor(Math.random() * spreadMs)
+}
+
+/**
+ * Half the capped exponential delay, plus jitter over the other half. Decorrelates concurrent
+ * repeats like full jitter, but keeps a floor: use it when few attempts remain before work is dropped.
+ */
+export function exponentialEqualJitterMs(
+  baseDelayMs: number,
+  maxDelayMs: number,
+  attempt: number,
+): number {
+  const halfCapMs = exponentialDelayCapMs(baseDelayMs, maxDelayMs, attempt) / 2
+  return Math.floor(halfCapMs) + spreadJitterMs(halfCapMs)
+}
+
+function exponentialDelayCapMs(baseDelayMs: number, maxDelayMs: number, attempt: number): number {
+  if (!Number.isSafeInteger(attempt) || attempt < 1) {
+    return panic('attempt must be a positive integer')
+  }
+  return Math.min(baseDelayMs * 2 ** (attempt - 1), maxDelayMs)
+}

package/src/core/classify-failure.ts

@@ -0,0 +1,60 @@
+import { z } from 'zod'
+
+import { AppError } from './app-error.ts'
+import {
+  isCloudflareOverloadedError,
+  isCloudflareRetryableError,
+  isTransientCloudflareRuntimeError,
+} from './cloudflare-classification.ts'
+import type { FailureClassification } from './failure-classification.ts'
+import { isAbortError, isTransientTransportError } from './transport-classification.ts'
+
+/** A boundary's own rule for its raw errors. `undefined` means the boundary has no opinion. */
+export type BoundaryErrorClassifier = (cause: unknown) => FailureClassification | undefined
+
+/**
+ * Classify one raw external error: the boundary's own rule first, then Cloudflare's signals,
+ * then the transport patterns. Cancellation is terminal even when Cloudflare marks it retryable.
+ */
+export function classifyBoundaryError(args: {
+  readonly cause: unknown
+  readonly classifyBoundary: BoundaryErrorClassifier
+  readonly includeCloudflare: boolean
+}): FailureClassification {
+  const boundary = args.classifyBoundary(args.cause)
+  if (boundary !== undefined) return boundary
+
+  if (isAbortError(args.cause)) return 'terminal'
+
+  if (
+    args.includeCloudflare &&
+    (isCloudflareOverloadedError(args.cause) ||
+      isCloudflareRetryableError(args.cause) ||
+      isTransientCloudflareRuntimeError(args.cause))
+  ) {
+    return 'transient'
+  }
+
+  if (isTransientTransportError(args.cause)) return 'transient'
+
+  return 'unknown'
+}
+
+/**
+ * Judge a final failure for its durable retry owner. An `AppError` carries its own answer.
+ * A raw throw nobody judged is unknown, so an immediate owner stops and a durable one may repeat.
+ */
+export function classifyFailure(cause: unknown): FailureClassification {
+  if (cause instanceof AppError) return cause.classification
+  if (isAbortError(cause)) return 'terminal'
+  if (isTransientCloudflareRuntimeError(cause)) return 'transient'
+  return 'unknown'
+}
+
+const RetryAfterSchema = z.object({ retryAfter: z.number().positive() })
+
+/** Read a positive server-advertised retry delay in seconds, such as `RateLimitError.retryAfter`. */
+export function retryAfterSecondsOf(cause: unknown): number | null {
+  const result = RetryAfterSchema.safeParse(cause)
+  return result.success ? result.data.retryAfter : null
+}

package/src/core/cloudflare-classification.ts

@@ -0,0 +1,45 @@
+import { z } from 'zod'
+
+/** Stable Cloudflare messages that mean the runtime failed, not our code, and a repeat may pass. */
+export const CLOUDFLARE_TRANSIENT_ERROR_PATTERNS = {
+  networkConnectionLost: /network connection lost/,
+  objectReset: /caused object to be reset/,
+  codeUpdateReset: /reset because its code was updated/,
+  objectMoved: /object has moved to a different machine/,
+  internalWorkflows: /internal workflows error/,
+} as const
+
+const TRANSIENT_PLATFORM_PATTERNS = [
+  CLOUDFLARE_TRANSIENT_ERROR_PATTERNS.objectReset,
+  CLOUDFLARE_TRANSIENT_ERROR_PATTERNS.codeUpdateReset,
+  CLOUDFLARE_TRANSIENT_ERROR_PATTERNS.objectMoved,
+  CLOUDFLARE_TRANSIENT_ERROR_PATTERNS.internalWorkflows,
+]
+
+// workerd stamps these flags as own properties on the error it throws across a binding.
+const RetryableFlagSchema = z.object({ retryable: z.literal(true) })
+const OverloadedFlagSchema = z.object({ overloaded: z.literal(true) })
+const ObjectResetFlagSchema = z.object({ durableObjectReset: z.literal(true) })
+
+/** workerd stamps `retryable` on a failure it judged safe to repeat. */
+export function isCloudflareRetryableError(cause: unknown): boolean {
+  return RetryableFlagSchema.validate(cause)
+}
+
+/** workerd stamps `overloaded` when the target could not take the call. */
+export function isCloudflareOverloadedError(cause: unknown): boolean {
+  return OverloadedFlagSchema.validate(cause)
+}
+
+/** workerd stamps `durableObjectReset` when the object restarted during the call. */
+export function isCloudflareObjectResetError(cause: unknown): boolean {
+  return ObjectResetFlagSchema.validate(cause)
+}
+
+/** Match transient Cloudflare runtime evidence without the general transport patterns. */
+export function isTransientCloudflareRuntimeError(cause: unknown): boolean {
+  if (isCloudflareObjectResetError(cause)) return true
+  if (!(cause instanceof Error)) return false
+  const message = cause.message.toLowerCase()
+  return TRANSIENT_PLATFORM_PATTERNS.some((pattern) => pattern.test(message))
+}

package/src/core/index.ts

@@ -57,6 +57,20 @@ export {
   type RetryOwner,
 } from './failure-classification.ts'
 export { isAbortError, isTransientTransportError } from './transport-classification.ts'
+export {
+  CLOUDFLARE_TRANSIENT_ERROR_PATTERNS,
+  isCloudflareObjectResetError,
+  isCloudflareOverloadedError,
+  isCloudflareRetryableError,
+  isTransientCloudflareRuntimeError,
+} from './cloudflare-classification.ts'
+export {
+  classifyBoundaryError,
+  classifyFailure,
+  retryAfterSecondsOf,
+  type BoundaryErrorClassifier,
+} from './classify-failure.ts'
+export { exponentialEqualJitterMs, spreadJitterMs } from './backoff.ts'
 export {
   configureLogger,
   consoleSink,

package/src/infrastructure/better-auth/apple-client-secret.ts

@@ -1,12 +1,21 @@
-import { importPKCS8, SignJWT } from 'jose'
+import { Buffer } from 'node:buffer'
+import { createPrivateKey, sign } from 'node:crypto'
 
 import { AppError, createLogger } from '@/core'
 
 const logger = createLogger('auth')
 // Typist reports an invalid key once per isolate because session checks repeatedly construct auth options.
 let appleKeyFailureLogged = false
+/**
+ * Apple caps `exp` at 15,777,000 seconds after `iat`; 180 days stays under it. Source:
+ * https://developer.apple.com/documentation/accountorganizationaldatasharing/creating-a-client-secret
+ */
+const SECRET_LIFETIME_SECONDS = 180 * 24 * 60 * 60
 
-/** Apple sends its OAuth callback from this origin. Include it in trustedOrigins when enabling Apple. */
+/**
+ * Apple's issuer and OAuth callback origin, and the `aud` claim of the client secret. Include it in
+ * trustedOrigins when enabling Apple. Source: the same Apple page as `SECRET_LIFETIME_SECONDS`.
+ */
 export const APPLE_ORIGIN = 'https://appleid.apple.com'
 
 /** Apple credentials used to sign a client secret. Ported from Porte's apple-client-secret.ts. */
@@ -27,11 +36,23 @@ export class AppleClientSecretError extends AppError {
   }
 }
 
-/** Sign Apple's six-month client secret. Invalid private keys return an empty secret and log once per isolate, as in Typist. */
-export async function generateAppleClientSecret(config: AppleKeyConfig): Promise<string> {
-  let key: Awaited<ReturnType<typeof importPKCS8>>
+/** One JWS segment before encoding: the protected header or the claims. */
+type JwsSegment = Readonly<Record<string, string | number>>
+
+function base64UrlJson(segment: JwsSegment): string {
+  return Buffer.from(JSON.stringify(segment)).toString('base64url')
+}
+
+/**
+ * Sign Apple's six-month client secret synchronously, so Better Auth options can be built without awaiting it.
+ * Signing uses `node:crypto` as Typist does, so the Worker needs the `nodejs_compat` flag.
+ * Invalid private keys return an empty secret and log once per isolate, as in Typist.
+ */
+export function generateAppleClientSecret(config: AppleKeyConfig): string {
+  const key = config.applePrivateKey.replace(/\\n/g, '\n')
+  // Validation only: workerd's sign() takes the PEM string, not the KeyObject.
   try {
-    key = await importPKCS8(config.applePrivateKey.replace(/\\n/g, '\n'), 'ES256')
+    createPrivateKey(key)
   } catch (error) {
     if (!appleKeyFailureLogged) {
       appleKeyFailureLogged = true
@@ -39,15 +60,21 @@ export async function generateAppleClientSecret(config: AppleKeyConfig): Promise
     }
     return ''
   }
+  const issuedAt = Math.floor(Date.now() / 1000)
+  const header = base64UrlJson({ alg: 'ES256', kid: config.appleKeyId })
+  const claims = base64UrlJson({
+    iss: config.appleTeamId,
+    sub: config.appleClientId,
+    aud: APPLE_ORIGIN,
+    iat: issuedAt,
+    exp: issuedAt + SECRET_LIFETIME_SECONDS,
+  })
+  const input = `${header}.${claims}`
   try {
-    return await new SignJWT({})
-      .setProtectedHeader({ alg: 'ES256', kid: config.appleKeyId })
-      .setIssuer(config.appleTeamId)
-      .setSubject(config.appleClientId)
-      .setAudience(APPLE_ORIGIN)
-      .setIssuedAt()
-      .setExpirationTime('180d')
-      .sign(key)
+    // A JWS carries the raw r||s signature; OpenSSL emits DER unless told otherwise.
+    const signature = sign('sha256', Buffer.from(input), { key, dsaEncoding: 'ieee-p1363' })
+    // TypeScript 7 types the returned buffer without an encoding parameter on toString.
+    return `${input}.${Buffer.from(signature).toString('base64url')}`
   } catch (cause) {
     throw new AppleClientSecretError(cause)
   }

package/src/infrastructure/better-auth/rate-limit.ts

@@ -1,7 +1,13 @@
-import type { BetterAuthRateLimitStorage } from 'better-auth'
+import type { BetterAuthOptions, BetterAuthRateLimitStorage } from 'better-auth'
 
 import { AppError, createLogger } from '@/core'
 
+/** A rule Better Auth passes to storage: a window in seconds and the requests it allows. */
+export type AuthRateLimitRule = {
+  readonly window: number
+  readonly max: number
+}
+
 /** Each rule must match its binding's deployed limit and period. Cloudflare accepts only 10 or 60 seconds. */
 export type AuthRateLimitBinding = {
   readonly binding: Pick<RateLimit, 'limit'>
@@ -9,6 +15,43 @@ export type AuthRateLimitBinding = {
   readonly max: number
 }
 
+/**
+ * Better Auth's built-in rules, which it does not export. Sign-in, sign-up, change-password, and
+ * change-email paths get 3 requests per 10 seconds. Password reset, verification email, forget-password,
+ * and email OTP send paths get 3 per 60 seconds. A package test pins both against the installed version.
+ * Source: `getDefaultSpecialRules` in
+ * https://github.com/better-auth/better-auth/blob/v1.7.4/packages/better-auth/src/api/rate-limiter/index.ts
+ */
+export const BUILT_IN_AUTH_RATE_LIMIT_RULES: readonly AuthRateLimitRule[] = [
+  { window: 10, max: 3 },
+  { window: 60, max: 3 },
+]
+
+/**
+ * Every rule the configured instance can pass to storage, deduplicated: the general rule, the built-in
+ * rules, each plugin's rules, and static custom rules. Function-valued custom rules decide per request
+ * and are not listed. Disabled rate limiting returns no rules.
+ */
+export function authRateLimitRules(
+  options: Pick<BetterAuthOptions, 'rateLimit' | 'plugins'>,
+): readonly AuthRateLimitRule[] {
+  const rateLimit = options.rateLimit
+  if (rateLimit?.enabled === false) return []
+  // Better Auth's own defaults when the general rule is not set: window 10, max 100. Source:
+  // https://github.com/better-auth/better-auth/blob/v1.7.4/packages/better-auth/src/context/create-context.ts
+  const rules: AuthRateLimitRule[] = [
+    { window: rateLimit?.window ?? 10, max: rateLimit?.max ?? 100 },
+    ...BUILT_IN_AUTH_RATE_LIMIT_RULES,
+  ]
+  for (const plugin of options.plugins ?? [])
+    for (const rule of plugin.rateLimit ?? []) rules.push({ window: rule.window, max: rule.max })
+  for (const rule of Object.values(rateLimit?.customRules ?? {}))
+    if (rule !== false && !(rule instanceof Function))
+      rules.push({ window: rule.window, max: rule.max })
+  const unique = new Map(rules.map((rule) => [`${rule.window}:${rule.max}`, rule]))
+  return [...unique.values()]
+}
+
 /** A binding failure with no known retry classification. The cause preserves the original failure. */
 export class AuthRateLimitError extends AppError {
   readonly _tag = 'AuthRateLimitError'

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

@@ -0,0 +1,25 @@
+export {
+  QueueClient,
+  type IQueueClient,
+  type QueueBinding,
+  type QueueClientOptions,
+  type QueueSendOptions,
+} from './queue-client.ts'
+export type { QueueMessage } from './queue-message.ts'
+export { QueueConsumer, type DispatchBus, type DispatchWrapper } from './queue-consumer.ts'
+export {
+  chunkByLimits,
+  isOversized,
+  messageByteLength,
+  QUEUE_LIMITS,
+  sizeMessages,
+  type SizedMessage,
+} from './queue-limits.ts'
+export {
+  classifyQueueError,
+  DeadLetterUnavailableError,
+  OversizedMessageError,
+  QueueSendError,
+  type QueueOperation,
+} from './queue.errors.ts'
+export { decideRedelivery, type RedeliveryDecision } from './redelivery-policy.ts'

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