experimental-a2 0.3.0 → 0.5.0

package/src/scheduler-task.ts

@@ -0,0 +1,106 @@
+/** One event carried by a delayed append task. */
+export type ScheduledEvent = {
+  id: string
+  type: string
+  payload: unknown
+}
+
+/** A durable wake-up for pending handler work. */
+export type SchedulerDrainTask = {
+  version: 1
+  kind: 'drain'
+  contract: string
+  sessionId: string
+  /** Earliest useful delivery as epoch milliseconds. */
+  dueAt: number
+}
+
+/** A durable delayed append. */
+export type SchedulerAppendTask = {
+  version: 1
+  kind: 'append'
+  /** Stable identity for provider-level deduplication. */
+  id: string
+  contract: string
+  sessionId: string
+  /** Earliest useful delivery as epoch milliseconds. */
+  dueAt: number
+  events: readonly ScheduledEvent[]
+}
+
+/** The versioned message protocol shared by scheduler adapters. */
+export type SchedulerTask = SchedulerDrainTask | SchedulerAppendTask
+
+const recordOf = (value: unknown): Record<string, unknown> | null =>
+  value !== null && typeof value === 'object' && !Array.isArray(value)
+    ? (value as Record<string, unknown>)
+    : null
+
+const validName = (value: unknown): value is string =>
+  typeof value === 'string' && value.length > 0
+
+const validDueAt = (value: unknown): value is number =>
+  typeof value === 'number' && Number.isInteger(value) && value % 1_000 === 0
+
+const baseTask = (
+  record: Record<string, unknown>,
+): { contract: string; sessionId: string } | null =>
+  Object.hasOwn(record, 'contract') &&
+  Object.hasOwn(record, 'sessionId') &&
+  validName(record['contract']) &&
+  validName(record['sessionId'])
+    ? { contract: record['contract'], sessionId: record['sessionId'] }
+    : null
+
+/**
+ * Validate one delivered task.
+ * Adapters call this only after their transport authentication has succeeded.
+ */
+export function normalizeSchedulerTask(value: unknown): SchedulerTask | null {
+  const record = recordOf(value)
+  if (!record) return null
+  const base = baseTask(record)
+  if (!base) return null
+
+  if (record['version'] !== 1) return null
+  if (record['kind'] === 'drain') {
+    const dueAt = record['dueAt']
+    if (!validDueAt(dueAt)) return null
+    return { version: 1, kind: 'drain', ...base, dueAt }
+  }
+  if (record['kind'] !== 'append') return null
+
+  const { dueAt, events, id } = record
+  if (!validName(id) || !validDueAt(dueAt)) return null
+  if (!Array.isArray(events) || events.length === 0) return null
+  const parsedEvents: ScheduledEvent[] = []
+  for (const event of events) {
+    const item = recordOf(event)
+    if (
+      !item ||
+      typeof item['id'] !== 'string' ||
+      typeof item['type'] !== 'string' ||
+      !Object.hasOwn(item, 'payload')
+    ) {
+      return null
+    }
+    parsedEvents.push({
+      id: item['id'],
+      type: item['type'],
+      payload: item['payload'],
+    })
+  }
+  if (
+    new Set(parsedEvents.map((event) => event.id)).size !== parsedEvents.length
+  ) {
+    return null
+  }
+  return {
+    version: 1,
+    kind: 'append',
+    id,
+    ...base,
+    dueAt,
+    events: parsedEvents,
+  }
+}

package/src/scheduler-vercel.ts

@@ -0,0 +1,437 @@
+/**
+ * experimental-a2/scheduler-vercel — queue-backed scheduler over Vercel Queues.
+ *
+ * `vercelQueues()` returns an `A2Scheduler` (a2-implementation.md §9):
+ *
+ * - drain tasks round the requested watchdog time up to a one-second slot.
+ *   One message per `(topic, contract, session, dueAt)` coalesces appends,
+ *   claim renewals and racing callbacks. `DuplicateMessageError` is
+ *   success because that due-time slot is already durable.
+ * - append tasks hash their stable task id with the topic for provider
+ *   deduplication. Their six-day maximum delay leaves a full day for
+ *   delivery and retries inside the provider's seven-day retention.
+ *   They target the publishing deployment unless explicitly configured
+ *   as deploymentless. Drain tasks always remain deployment-scoped.
+ * - `handler(...servers)` is the delivery route: look up the server for
+ *   the contract named in the message and drain it. Settled drains ack;
+ *   contention arms a later watchdog before acking; handler failure keeps
+ *   the current message and redelivers with backoff.
+ *
+ * `@vercel/queue` is an optional peer dependency, imported lazily. The
+ * `transport` option is the injection seam — tests run a real little
+ * in-memory queue through the same interface.
+ */
+
+import { createHash } from 'node:crypto'
+import { SYSTEM_CLOCK, type Clock } from './store.ts'
+import {
+  assertSchedulerTargets,
+  classifySchedulerSendFailure,
+  DRAIN_TIMINGS,
+  serverInternals,
+} from './internal.ts'
+import { retryableLazy } from './retryable-lazy.ts'
+import {
+  normalizeSchedulerTask,
+  type SchedulerDrainTask,
+  type SchedulerTask,
+} from './scheduler-task.ts'
+import {
+  deliverSchedulerAppend,
+  type A2Scheduler,
+  type DrainableServer,
+} from './server.ts'
+
+/**
+ * The "not settled yet" signal for a stalled handler — an expected state,
+ * not a transport failure. The default transport classifies it in
+ * `@vercel/queue`'s `retry` option and reschedules the delivery quietly
+ * (`{ afterSeconds }` → visibility change → 200 response, no error log)
+ * instead of letting it surface as a thrown 500. Busy deliveries use a
+ * fresh watchdog instead. Custom transports should treat this class the
+ * same way when their protocol has a polite reschedule.
+ */
+export class DrainUnsettled extends Error {}
+
+export type QueueDeliveryMetadata = {
+  messageId: string
+  deliveryCount: number
+}
+
+type VercelQueueMessage = SchedulerTask & {
+  /** Provider-private state used to address callback lease operations. */
+  _a2Vercel?: {
+    version: 1
+    deployment: 'deployment' | 'deploymentless'
+  }
+}
+
+/** What this module needs from a Vercel Queues-compatible transport. */
+export type QueueTransport = {
+  send(
+    topic: string,
+    message: SchedulerTask,
+    options?: {
+      delaySeconds?: number
+      idempotencyKey?: string
+      retentionSeconds?: number
+    },
+    /** Resolved A2 affinity. Custom transports own its provider mapping. */
+    routing?: {
+      deployment: 'deployment' | 'deploymentless'
+    },
+  ): Promise<unknown>
+  /**
+   * Wrap the delivery handler into a route. The handler throws
+   * `DrainUnsettled` when the session needs redelivery — transports
+   * with a polite reschedule (visibility change) should use it there
+   * instead of surfacing an error; anything else thrown is a genuine
+   * failure and should stay loud.
+   */
+  handleCallback(
+    handler: (
+      message: unknown,
+      metadata: QueueDeliveryMetadata,
+    ) => Promise<void>,
+  ): (req: Request) => Promise<Response>
+  /** Is this send error the idempotency-key collision? (= success) */
+  isDuplicate(error: unknown): boolean
+}
+
+export type VercelQueuesOptions = {
+  /** Queue topic matching `[A-Za-z0-9_-]+`. Default `'a2'`. */
+  topic?: string
+  /**
+   * Deployment affinity for scheduled append tasks. Recovery drain tasks
+   * always target the publishing deployment. Default `'deployment'`.
+   */
+  scheduledAppends?: 'deployment' | 'deploymentless'
+  /** Injectable transport (tests). Default: `@vercel/queue`. */
+  transport?: QueueTransport
+  /** Injectable clock for due-time calculations (tests). */
+  clock?: Clock
+}
+
+/** Vercel Queues rejects shorter visibility changes. */
+const MIN_VISIBILITY_SECONDS = 30
+
+/** Vercel Queues' maximum message retention and delivery delay. */
+const MAX_RETENTION_SECONDS = 7 * 24 * 60 * 60
+
+/** Leave the final retention day for delivery and retries. */
+const MAX_DELAY_SECONDS = 6 * 24 * 60 * 60
+
+const TOPIC_PATTERN = /^[A-Za-z0-9_-]+$/
+const RETRYABLE_HTTP_CLIENT_STATUSES = new Set([408, 409, 425, 429])
+/** The SDK's send path maps these statuses to name-only error instances. */
+const TERMINAL_VERCEL_SEND_ERROR_NAMES = new Set([
+  'BadRequestError',
+  'UnauthorizedError',
+  'ForbiddenError',
+])
+
+const recordOf = (value: unknown): Record<string, unknown> | null =>
+  value !== null && typeof value === 'object' && !Array.isArray(value)
+    ? (value as Record<string, unknown>)
+    : null
+
+const httpStatusOf = (error: unknown): number | undefined => {
+  try {
+    const record = recordOf(error)
+    if (!record) return undefined
+    const response = recordOf(record['response'])
+    const statuses = [
+      record['status'],
+      record['statusCode'],
+      response?.['status'],
+    ].filter(
+      (value): value is number =>
+        typeof value === 'number' &&
+        Number.isInteger(value) &&
+        value >= 100 &&
+        value <= 599,
+    )
+    const [status] = statuses
+    if (status === undefined) return undefined
+    return statuses.every((candidate) => candidate === status)
+      ? status
+      : undefined
+  } catch {
+    return undefined
+  }
+}
+
+const errorNameOf = (error: unknown): string | undefined => {
+  try {
+    const name = recordOf(error)?.['name']
+    return typeof name === 'string' ? name : undefined
+  } catch {
+    return undefined
+  }
+}
+
+const classifyVercelSendFailure = (error: unknown): unknown => {
+  const status = httpStatusOf(error)
+  const terminal =
+    status === undefined
+      ? TERMINAL_VERCEL_SEND_ERROR_NAMES.has(errorNameOf(error) ?? '')
+      : status >= 400 &&
+        status < 500 &&
+        !RETRYABLE_HTTP_CLIENT_STATUSES.has(status)
+  return classifySchedulerSendFailure(
+    error,
+    terminal ? 'terminal' : 'retryable',
+  )
+}
+
+const digestId = (parts: readonly string[]): string =>
+  `a2_${createHash('sha256').update(JSON.stringify(parts)).digest('hex')}`
+
+/** Base of the unsettled redelivery backoff, doubled per delivery. */
+const UNSETTLED_BACKOFF_BASE_SECONDS = 5
+
+/** Redelivery backoff for retry states: base, 2×, 4×… bounded. */
+const unsettledBackoffSeconds = (deliveryCount: number): number =>
+  Math.min(
+    Math.max(
+      UNSETTLED_BACKOFF_BASE_SECONDS * 2 ** Math.max(deliveryCount - 1, 0),
+      MIN_VISIBILITY_SECONDS,
+    ),
+    60,
+  )
+
+const vercelQueueTransport = async (): Promise<QueueTransport> => {
+  const queue = await import('@vercel/queue').catch(() => {
+    throw classifySchedulerSendFailure(
+      new Error(
+        "experimental-a2/scheduler-vercel needs the '@vercel/queue' package (optional peer dependency) — install it, or inject a transport",
+      ),
+      'terminal',
+    )
+  })
+  const deploymentClient = new queue.QueueClient()
+  const deploymentlessClient = new queue.QueueClient({ deploymentId: null })
+  return {
+    send: (topic, message, options, routing) => {
+      const deployment = routing?.deployment ?? 'deployment'
+      const body: VercelQueueMessage = {
+        ...message,
+        _a2Vercel: { version: 1, deployment },
+      }
+      return (
+        deployment === 'deploymentless'
+          ? deploymentlessClient
+          : deploymentClient
+      ).send(topic, body, options)
+    },
+    handleCallback: (handler) => {
+      const callbackOptions = {
+        // A hard-killed callback normally has a fresh claim watchdog. If
+        // its successor send also failed, make the old unacked delivery's
+        // fallback as prompt as Vercel Queues permits.
+        visibilityTimeoutSeconds: MIN_VISIBILITY_SECONDS,
+        // Not-settled-yet is an expected state: reschedule the (still
+        // unacked) delivery via a visibility change — 200, no error
+        // log. Everything else returns undefined → the SDK's default
+        // throw path, which is loud on purpose.
+        retry: (error: unknown, metadata: QueueDeliveryMetadata) =>
+          error instanceof DrainUnsettled
+            ? {
+                afterSeconds: unsettledBackoffSeconds(metadata.deliveryCount),
+              }
+            : undefined,
+      }
+      const deploymentHandler = deploymentClient.handleCallback(
+        handler,
+        callbackOptions,
+      ) as (req: Request) => Promise<Response>
+      const deploymentlessHandler = deploymentlessClient.handleCallback(
+        handler,
+        callbackOptions,
+      ) as (req: Request) => Promise<Response>
+      return async (req: Request): Promise<Response> => {
+        let delivered: unknown
+        try {
+          delivered = await req.clone().json()
+        } catch {
+          return deploymentlessHandler(req)
+        }
+        const metadata = recordOf(recordOf(delivered)?.['_a2Vercel'])
+        const routing =
+          metadata?.['version'] === 1 ? metadata['deployment'] : undefined
+        return routing === 'deployment'
+          ? deploymentHandler(req)
+          : deploymentlessHandler(req)
+      }
+    },
+    isDuplicate: (error) => error instanceof queue.DuplicateMessageError,
+  }
+}
+
+export function vercelQueues(options: VercelQueuesOptions = {}): A2Scheduler {
+  const topic = options.topic ?? 'a2'
+  if (typeof topic !== 'string' || !TOPIC_PATTERN.test(topic)) {
+    throw new TypeError('vercelQueues() topic must match [A-Za-z0-9_-]+')
+  }
+  const scheduledAppends = options.scheduledAppends ?? 'deployment'
+  if (
+    scheduledAppends !== 'deployment' &&
+    scheduledAppends !== 'deploymentless'
+  ) {
+    throw new TypeError(
+      "vercelQueues() scheduledAppends must be 'deployment' or 'deploymentless'",
+    )
+  }
+  const clock = options.clock ?? SYSTEM_CLOCK
+
+  // Lazy: constructing the scheduler value does no I/O and works without
+  // the peer dep until the first task or delivery.
+  const transport = retryableLazy(() =>
+    options.transport
+      ? Promise.resolve(options.transport)
+      : vercelQueueTransport(),
+  ).get
+
+  const sendTask = async (task: SchedulerTask): Promise<void> => {
+    const nowMs = clock.now().getTime()
+    const requestedDueAt = task.dueAt
+    if (!Number.isFinite(requestedDueAt)) {
+      throw classifySchedulerSendFailure(
+        new TypeError('vercel scheduler dueAt must be a finite number'),
+        'terminal',
+      )
+    }
+    const dueAt =
+      requestedDueAt <= nowMs
+        ? Math.floor(nowMs / 1_000) * 1_000
+        : Math.ceil(requestedDueAt / 1_000) * 1_000
+    const deliveryTargetAt = task.kind === 'append' ? requestedDueAt : dueAt
+    const deliveryDelaySeconds = Math.max(
+      0,
+      Math.ceil((deliveryTargetAt - nowMs) / 1_000),
+    )
+    if (deliveryDelaySeconds > MAX_DELAY_SECONDS) {
+      throw classifySchedulerSendFailure(
+        new RangeError(
+          'vercelQueues() tasks cannot be delayed more than 6 days',
+        ),
+        'terminal',
+      )
+    }
+    const deployment = task.kind === 'append' ? scheduledAppends : 'deployment'
+    const message: SchedulerTask = { ...task, dueAt }
+    const idempotencyKey =
+      task.kind === 'drain'
+        ? digestId([
+            'a2:scheduler-vercel:drain:v1',
+            topic,
+            task.contract,
+            task.sessionId,
+            String(dueAt),
+          ])
+        : digestId(['a2:scheduler-vercel:append:v1', topic, task.id])
+    const t = await transport()
+    try {
+      await t.send(
+        topic,
+        message,
+        {
+          delaySeconds: deliveryDelaySeconds,
+          idempotencyKey,
+          retentionSeconds: MAX_RETENTION_SECONDS,
+        },
+        { deployment },
+      )
+    } catch (err) {
+      if (t.isDuplicate(err)) return
+      throw classifyVercelSendFailure(err)
+    }
+  }
+
+  const successorDueAt = (message: SchedulerDrainTask): number => {
+    const minimumDueAt =
+      clock.now().getTime() +
+      DRAIN_TIMINGS.claimTtlMs +
+      DRAIN_TIMINGS.watchdogGraceMs
+    const beats = Math.max(
+      1,
+      Math.ceil(
+        (minimumDueAt - message.dueAt) / DRAIN_TIMINGS.claimHeartbeatMs,
+      ),
+    )
+    return message.dueAt + beats * DRAIN_TIMINGS.claimHeartbeatMs
+  }
+
+  return {
+    async schedule(task) {
+      await sendTask(task)
+    },
+
+    handler(...servers: DrainableServer[]) {
+      assertSchedulerTargets(servers, { allowStructural: true })
+      const byContract = new Map<string, DrainableServer>()
+      for (const server of servers) {
+        byContract.set(server.contract.name, server)
+      }
+      return async (req: Request): Promise<Response> => {
+        const t = await transport()
+        return t.handleCallback(async (delivered) => {
+          const task = normalizeSchedulerTask(delivered)
+          if (!task) {
+            throw new TypeError('a2 scheduler received an invalid task')
+          }
+          const server = byContract.get(task.contract)
+          if (!server) {
+            // A message for a contract this route doesn't serve is a
+            // wiring bug — throw so it redelivers and stays visible in
+            // queue observability instead of vanishing on an ack.
+            throw new Error(
+              `a2 scheduler: no server for contract '${task.contract}' — pass it to schedulerHandler(...)`,
+            )
+          }
+          const internals = serverInternals.get(server)
+          if (task.kind === 'append') {
+            await deliverSchedulerAppend(server, task)
+            return
+          }
+
+          const nextDueAt = successorDueAt(task)
+          const result = internals
+            ? await internals.schedulerDrain(task.sessionId, {
+                watchdogDueAt: nextDueAt,
+              })
+            : {
+                ...(await server.drain(task.sessionId)),
+                outcome: 'unknown' as const,
+              }
+          if (result.settled) return
+
+          if (result.outcome === 'busy') {
+            // The live owner normally arms its own claim windows.
+            // Ensure a later slot here as well before relinquishing this
+            // durable delivery. If the queue is down, the throw leaves the
+            // current message unacked for visibility-timeout redelivery.
+            if (result.schedulerArm) await result.schedulerArm
+            else {
+              await sendTask({
+                version: 1,
+                kind: 'drain',
+                contract: task.contract,
+                sessionId: task.sessionId,
+                dueAt: nextDueAt,
+              })
+            }
+            return
+          }
+
+          // Handler failure keeps the current durable message and uses the
+          // transport retry path. Dead-lettered sessions count as settled
+          // above, so retries stop there.
+          throw new DrainUnsettled(
+            `a2 scheduler: session '${task.sessionId}' of '${task.contract}' not settled yet (${result.outcome}) — rescheduled for redelivery`,
+          )
+        })(req)
+      }
+    },
+  }
+}

package/src/server.browser.ts

@@ -0,0 +1,12 @@
+/**
+ * The browser build of experimental-a2/server. There isn't one — on purpose.
+ * Contracts and reducers (from `experimental-a2`) and the session client (from
+ * `experimental-a2/client` / `experimental-a2/react`) are the isomorphic surface; the server is
+ * where handlers and storage live. This module existing in a client
+ * bundle means a `'use client'` file (or something it imports)
+ * value-imported your server module.
+ */
+throw new Error(
+  'experimental-a2/server is server-only — a client bundle imported it. Import the contract (a2) or the session client (experimental-a2/client, experimental-a2/react) in browser code instead.',
+)
+export {}