experimental-a2 0.16.1 → 0.17.0

package/src/scheduler-task.ts

@@ -26,10 +26,27 @@ export type SchedulerAppendTask = {
   /** Earliest useful delivery as epoch milliseconds. */
   dueAt: number
   events: readonly ScheduledEvent[]
+  /** The scheduling handler's event; delivery skips once it is cleared. */
+  originIndex?: number
+}
+
+/** A durable conditional clear. */
+export type SchedulerClearTask = {
+  version: 1
+  kind: 'clear'
+  /** Stable identity for provider-level deduplication. */
+  id: string
+  contract: string
+  sessionId: string
+  /** Earliest useful delivery as epoch milliseconds. */
+  dueAt: number
+  /** Clear only while this is still the head. */
+  ifLastIndex: number
 }
 
 /** The versioned message protocol shared by scheduler adapters. */
-export type SchedulerTask = SchedulerDrainTask | SchedulerAppendTask
+export type SchedulerTask =
+  SchedulerDrainTask | SchedulerAppendTask | SchedulerClearTask
 
 const recordOf = (value: unknown): Record<string, unknown> | null =>
   value !== null && typeof value === 'object' && !Array.isArray(value)
@@ -42,6 +59,9 @@ const validName = (value: unknown): value is string =>
 const validDueAt = (value: unknown): value is number =>
   typeof value === 'number' && Number.isInteger(value) && value % 1_000 === 0
 
+const validIndex = (value: unknown): value is number =>
+  typeof value === 'number' && Number.isSafeInteger(value) && value >= 0
+
 const baseTask = (
   record: Record<string, unknown>,
 ): { contract: string; sessionId: string } | null =>
@@ -68,10 +88,21 @@ export function normalizeSchedulerTask(value: unknown): SchedulerTask | null {
     if (!validDueAt(dueAt)) return null
     return { version: 1, kind: 'drain', ...base, dueAt }
   }
+  if (record['kind'] === 'clear') {
+    const { dueAt, id, ifLastIndex } = record
+    if (!validName(id) || !validDueAt(dueAt) || !validIndex(ifLastIndex))
+      return null
+    return { version: 1, kind: 'clear', id, ...base, dueAt, ifLastIndex }
+  }
   if (record['kind'] !== 'append') return null
 
-  const { dueAt, events, id } = record
+  const { dueAt, events, id, originIndex } = record
   if (!validName(id) || !validDueAt(dueAt)) return null
+  if (
+    originIndex !== undefined &&
+    (!validIndex(originIndex) || originIndex === 0)
+  )
+    return null
   if (!Array.isArray(events) || events.length === 0) return null
   const parsedEvents: ScheduledEvent[] = []
   for (const event of events) {
@@ -102,5 +133,6 @@ export function normalizeSchedulerTask(value: unknown): SchedulerTask | null {
     ...base,
     dueAt,
     events: parsedEvents,
+    ...(originIndex === undefined ? {} : { originIndex }),
   }
 }

package/src/scheduler-vercel.ts

@@ -10,8 +10,8 @@
  * - 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.
+ *   Clear tasks follow the same identity and delay rules. All tasks use
+ *   the configured deployment scope for sending and receiving.
  * - `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
@@ -38,6 +38,7 @@ import {
 } from './scheduler-task.ts'
 import {
   deliverSchedulerAppend,
+  deliverSchedulerClear,
   type A2Scheduler,
   type DrainableServer,
 } from './server.ts'
@@ -58,14 +59,6 @@ export type QueueDeliveryMetadata = {
   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(
@@ -76,10 +69,6 @@ export type QueueTransport = {
       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
@@ -101,11 +90,8 @@ export type QueueTransport = {
 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'
+  /** Queue SDK deployment scope for all tasks. Default: VERCEL_DEPLOYMENT_ID; null opts out. */
+  deploymentId?: string | null
   /** Injectable transport (tests). Default: `@vercel/queue`. */
   transport?: QueueTransport
   /** Injectable clock for due-time calculations (tests). */
@@ -200,7 +186,9 @@ const unsettledBackoffSeconds = (deliveryCount: number): number =>
     60,
   )
 
-const vercelQueueTransport = async (): Promise<QueueTransport> => {
+const vercelQueueTransport = async (
+  clientOptions: Pick<VercelQueuesOptions, 'deploymentId'>,
+): Promise<QueueTransport> => {
   const queue = await import('@vercel/queue').catch(() => {
     throw classifySchedulerSendFailure(
       new Error(
@@ -209,23 +197,11 @@ const vercelQueueTransport = async (): Promise<QueueTransport> => {
       'terminal',
     )
   })
-  const deploymentClient = new queue.QueueClient()
-  const deploymentlessClient = new queue.QueueClient({ deploymentId: null })
+  const client = new queue.QueueClient(clientOptions)
   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 = {
+    send: (topic, message, options) => client.send(topic, message, options),
+    handleCallback: (handler) =>
+      client.handleCallback(handler, {
         // 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.
@@ -234,36 +210,13 @@ const vercelQueueTransport = async (): Promise<QueueTransport> => {
         // 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) =>
+        retry: (error, metadata) =>
           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)
-      }
-    },
+      }) as (req: Request) => Promise<Response>,
     isDuplicate: (error) => error instanceof queue.DuplicateMessageError,
   }
 }
@@ -273,23 +226,18 @@ export function vercelQueues(options: VercelQueuesOptions = {}): A2Scheduler {
   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
+  const clientOptions =
+    options.deploymentId === undefined
+      ? {}
+      : { deploymentId: options.deploymentId }
 
   // 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(),
+      : vercelQueueTransport(clientOptions),
   ).get
 
   const sendTask = async (task: SchedulerTask): Promise<void> => {
@@ -305,7 +253,7 @@ export function vercelQueues(options: VercelQueuesOptions = {}): A2Scheduler {
       requestedDueAt <= nowMs
         ? Math.floor(nowMs / 1_000) * 1_000
         : Math.ceil(requestedDueAt / 1_000) * 1_000
-    const deliveryTargetAt = task.kind === 'append' ? requestedDueAt : dueAt
+    const deliveryTargetAt = task.kind === 'drain' ? dueAt : requestedDueAt
     const deliveryDelaySeconds = Math.max(
       0,
       Math.ceil((deliveryTargetAt - nowMs) / 1_000),
@@ -318,7 +266,6 @@ export function vercelQueues(options: VercelQueuesOptions = {}): A2Scheduler {
         'terminal',
       )
     }
-    const deployment = task.kind === 'append' ? scheduledAppends : 'deployment'
     const message: SchedulerTask = { ...task, dueAt }
     const idempotencyKey =
       task.kind === 'drain'
@@ -329,19 +276,16 @@ export function vercelQueues(options: VercelQueuesOptions = {}): A2Scheduler {
             task.sessionId,
             String(dueAt),
           ])
-        : digestId(['a2:scheduler-vercel:append:v1', topic, task.id])
+        : task.kind === 'append'
+          ? digestId(['a2:scheduler-vercel:append:v1', topic, task.id])
+          : digestId(['a2:scheduler-vercel:clear:v1', topic, task.id])
     const t = await transport()
     try {
-      await t.send(
-        topic,
-        message,
-        {
-          delaySeconds: deliveryDelaySeconds,
-          idempotencyKey,
-          retentionSeconds: MAX_RETENTION_SECONDS,
-        },
-        { deployment },
-      )
+      await t.send(topic, message, {
+        delaySeconds: deliveryDelaySeconds,
+        idempotencyKey,
+        retentionSeconds: MAX_RETENTION_SECONDS,
+      })
     } catch (err) {
       if (t.isDuplicate(err)) return
       throw classifyVercelSendFailure(err)
@@ -394,6 +338,10 @@ export function vercelQueues(options: VercelQueuesOptions = {}): A2Scheduler {
             await deliverSchedulerAppend(server, task)
             return
           }
+          if (task.kind === 'clear') {
+            await deliverSchedulerClear(server, task)
+            return
+          }
 
           const nextDueAt = successorDueAt(task)
           const result = internals

package/src/server-fetch.ts

@@ -1,3 +1,4 @@
+import { encodeState } from './reducer-runtime.ts'
 import type {
   AppendInput,
   ContractEvent,
@@ -12,7 +13,7 @@ import {
   type ParsedPushEvent,
   type ParsedPushPresence,
 } from './push-envelope.ts'
-import type { A2Server } from './server.ts'
+import type { A2Server, Session, SessionAppend } from './server.ts'
 import {
   sessionSocket,
   sessionsSocket,
@@ -20,7 +21,16 @@ import {
   type SocketSession,
 } from './session-socket.ts'
 import { sseResponse } from './sse.ts'
-import { asA2Error, errorStatus, errorToWire, eventToWire } from './wire.ts'
+import { bootstrapStream } from './bootstrap-stream.ts'
+import type { Reducer } from './reducer.ts'
+import type { SubscriptionStart, WireVersion } from './wire.ts'
+import {
+  asA2Error,
+  errorStatus,
+  errorToWire,
+  eventToWire,
+  wireVersion,
+} from './wire.ts'
 
 type SuggestedEventType<D extends EventDefs> =
   (keyof D & string) | (string & Record<never, never>)
@@ -50,6 +60,7 @@ export type A2Operation<
       readonly type: 'stream'
       readonly sessionId: string
       readonly startAfter: number
+      readonly bootstrap?: true
       readonly transport: 'http' | 'websocket'
     }
   | {
@@ -100,10 +111,15 @@ export function setServerFetchHooks<
   serverFetchHooks.set(server.fetch, hooks)
 }
 
-type FetchServer<D extends EventDefs, P extends PresenceDefs> = Pick<
-  A2Server<D, P>,
-  'contract' | 'session'
->
+type FetchServer<D extends EventDefs, P extends PresenceDefs> = {
+  contract: A2Server<D, P>['contract']
+  session(id: string): Session<D, SessionAppend<D>, P>
+  /** Public history plus the latest clear marker when the range includes it. */
+  historyPage(
+    sessionId: string,
+    bounds: { gte: number; lte: number },
+  ): Promise<{ events: ContractEvent<D>[]; clearIndex?: number }>
+}
 
 type ServerFetch<D extends EventDefs, P extends PresenceDefs> = {
   (request: Request): Promise<Response>
@@ -150,6 +166,25 @@ const parseResumeIndex = (raw: string | null): number => {
   return index
 }
 
+const parseSubscription = (params: URLSearchParams): SubscriptionStart => {
+  const reducer = params.get('reducer')
+  const bootstrap = params.get('bootstrap')
+  const index = params.get('index')
+  if (reducer === '') throw new A2Error('INVALID_PAYLOAD', 'empty reducer name')
+  if (bootstrap !== null) {
+    if (bootstrap !== '1' || index !== null || reducer === null)
+      throw new A2Error(
+        'INVALID_PAYLOAD',
+        'bootstrap requires a reducer and no index',
+      )
+    return { bootstrap: true, reducer }
+  }
+  return {
+    index: parseResumeIndex(index),
+    ...(reducer === null ? {} : { reducer }),
+  }
+}
+
 const errorResponse = (error: unknown): Response => {
   const a2error = asA2Error(error)
   return Response.json(errorToWire(a2error), {
@@ -235,29 +270,82 @@ export function createServerFetch<
       }
     }
 
-    const attachMultiplexed = (socket: A2Socket): void => {
-      const deadline = invocationDeadlineMs()
-      sessionsSocket<D>(
-        async (sessionId, startAfter) => {
-          const operation: A2Operation<D, P> = {
-            type: 'stream',
-            sessionId,
-            startAfter,
-            transport: 'websocket',
-          }
-          return (await authorized(operation))
-            ? server.session(sessionId)
-            : null
-        },
-        socket,
-        {
-          presence,
-          ...(deadline === null ? {} : { deadline }),
-          gatePush: gateSocketPush,
-        },
+    const selectedSession = (
+      sessionId: string,
+      selection: SubscriptionStart,
+    ): SocketSession => {
+      const reducer = server.contract.reducer
+      if (
+        selection.reducer !== undefined &&
+        reducer !== undefined &&
+        reducer.name !== selection.reducer
       )
+        throw new A2Error(
+          'INVALID_PAYLOAD',
+          'client reducer does not match the public contract reducer',
+        )
+      const target = server.session(sessionId)
+      const streamTarget = target as unknown as SocketSession
+      if (!selection.bootstrap) return streamTarget
+      if (!reducer)
+        throw new A2Error('INVALID_PAYLOAD', 'contract has no public reducer')
+      return {
+        ...streamTarget,
+        stream: (streamOptions) =>
+          bootstrapStream({
+            snapshot: async () => {
+              const initial = await target.state(
+                reducer as unknown as Reducer<D, unknown>,
+              )
+              return {
+                kind: 'snapshot',
+                sessionId,
+                name: reducer.name,
+                index: initial.index,
+                state: encodeState({ reducer, state: initial.state }),
+                ...(initial.clearIndex === undefined
+                  ? {}
+                  : { clearIndex: initial.clearIndex }),
+              }
+            },
+            stream: (index) => {
+              const bounds = {
+                startAfter: index,
+                presence: streamOptions.presence === true,
+              }
+              return target.stream(bounds)
+            },
+          }),
+      }
     }
 
+    const attachMultiplexed =
+      (wire: WireVersion) =>
+      (socket: A2Socket): void => {
+        const deadline = invocationDeadlineMs()
+        sessionsSocket<D>(
+          async (sessionId, startAfter, selection = { index: startAfter }) => {
+            const operation: A2Operation<D, P> = {
+              type: 'stream',
+              sessionId,
+              startAfter,
+              ...(selection.bootstrap ? { bootstrap: true as const } : {}),
+              transport: 'websocket',
+            }
+            return (await authorized(operation))
+              ? selectedSession(sessionId, selection)
+              : null
+          },
+          socket,
+          {
+            presence,
+            wire,
+            ...(deadline === null ? {} : { deadline }),
+            gatePush: gateSocketPush,
+          },
+        )
+      }
+
     try {
       if (request.method === 'GET') {
         if (request.headers.get('upgrade')?.toLowerCase() === 'websocket') {
@@ -267,28 +355,32 @@ export function createServerFetch<
               { status: 426 },
             )
           }
+          const { searchParams } = new URL(request.url)
+          const wire = wireVersion(searchParams.get('wire'))
           if (options.multiplexWebSocket === true) {
-            return await options.upgradeWebSocket(attachMultiplexed)
+            return await options.upgradeWebSocket(attachMultiplexed(wire))
           }
 
-          const { searchParams } = new URL(request.url)
           const sessionId = searchParams.get('sessionId')
           if (sessionId === null || sessionId.length === 0) {
             throw new A2Error('INVALID_PAYLOAD', 'missing sessionId')
           }
-          const startAfter = parseResumeIndex(searchParams.get('index'))
+          const selection = parseSubscription(searchParams)
+          const startAfter = selection.index ?? 0
           await authorize({
             type: 'stream',
             sessionId,
             startAfter,
+            ...(selection.bootstrap ? { bootstrap: true as const } : {}),
             transport: 'websocket',
           })
-          const target = server.session(sessionId)
+          const target = selectedSession(sessionId, selection)
           const attach = (socket: A2Socket): void => {
             const deadline = invocationDeadlineMs()
             sessionSocket(sessionId, target, socket, {
               startAfter,
               presence,
+              wire,
               ...(deadline === null ? {} : { deadline }),
               gatePush: gateSocketPush,
             })
@@ -311,25 +403,37 @@ export function createServerFetch<
             ...bounds,
             transport: 'http',
           })
-          const events = await server.session(sessionId).history(bounds)
-          const covered = events.length === bounds.lte - bounds.gte + 1
+          const { events, clearIndex } = await server.historyPage(
+            sessionId,
+            bounds,
+          )
+          const first = Math.max(bounds.gte, (clearIndex ?? 0) + 1)
+          const covered = events.length === Math.max(0, bounds.lte - first + 1)
           return Response.json(events.map(eventToWire), {
-            headers: { 'a2-history-covered': String(covered) },
+            headers: {
+              'a2-history-covered': String(covered),
+              ...(clearIndex === undefined
+                ? {}
+                : { 'a2-clear-index': String(clearIndex) }),
+            },
           })
         }
 
-        const startAfter = parseResumeIndex(searchParams.get('index'))
+        const selection = parseSubscription(searchParams)
+        const startAfter = selection.index ?? 0
         await authorize({
           type: 'stream',
           sessionId,
           startAfter,
+          ...(selection.bootstrap ? { bootstrap: true as const } : {}),
           transport: 'http',
         })
-        const target = server.session(sessionId) as unknown as SocketSession
+        const target = selectedSession(sessionId, selection)
         return sseResponse(
           presence
             ? target.stream({ startAfter, presence: true })
             : target.stream({ startAfter }),
+          { wire: wireVersion(searchParams.get('wire')) },
         )
       }