experimental-a2 0.16.1 → 0.18.0

package/docs/server/01-handlers.mdx

@@ -0,0 +1,200 @@
+---
+title: Handlers
+description: Plain async functions that react to events. Concurrent by default, serialized by lanes, retried after failures.
+---
+
+```ts server/orders.ts
+import { createServer } from 'experimental-a2/server'
+import { orders } from '@/contracts'
+
+export const ordersServer = createServer({
+  contract: orders,
+  handlers: {
+    created: async ({ event }) => {
+      // your side effect, e.g. email the shop, idempotent via event.id:
+      // await sendEmailToShop(event.payload, { idempotencyKey: event.id })
+      return { type: 'shop.notified', payload: {} }
+    },
+  },
+})
+```
+
+A handler runs when its event lands: a plain async function that can call a
+database, hit an API, or stream a model response. A2 claims the event while it
+runs and retries it after a crash.
+
+`createServer` from `experimental-a2/server` binds the contract to a
+[store](/server/production#1-choose-a-store) and one complete handler table,
+so a handler can't go missing because its module was never imported. Compose
+the table across files by spreading objects into `handlers`. It is the only
+entry point that touches a store, and it fails loudly in a browser bundle.
+
+## Events without handlers
+
+```ts server/order-history.ts
+import { createServer } from 'experimental-a2/server'
+import { postgres } from 'experimental-a2/store-postgres'
+import { orders } from '@/contracts'
+
+export const orderHistory = createServer({
+  contract: orders,
+  store: postgres({ connectionString: process.env.DATABASE_URL }),
+})
+```
+
+Handlers are optional per event type. An event without one is still logged,
+folded into state, and streamed; it settles in its append transaction, with no
+claim or scheduler message. Adding a handler later doesn't replay settled
+events. Append a new event or run a migration when you want that.
+
+## The context
+
+| Property      | What it is |
+| ------------- | ---------- |
+| `ctx.event`   | The triggering event: `{ id, type, payload, index, sessionId, createdAt }`. |
+| `ctx.attempt` | The durable 1-based dispatch claim for this event. |
+| `ctx.session` | This session's handle: `id`, `append`, `schedule`, `clear`, `history`, `state`, `stream`, and `setPresence` (presence contracts only). |
+| `ctx.signal`  | An `AbortSignal`. Fires on matching `abortOn` events and when the attempt loses its claim (`CLAIM_EXPIRED`, `SUPERSEDED_ATTEMPT`). See [Cancellation](/server/cancellation). |
+
+`ctx.attempt` increments on every durable claim. It can skip a number when a
+process dies between the claim and handler entry.
+
+[`ctx.session.state(reducer)`](/contract/state) folds through
+`ctx.event.index`, so later concurrent appends don't change what this event
+sees. Pass `{ through: 'latest' }` to read the current committed frontier
+instead.
+
+## Return what happens after success
+
+```ts server/return-many.ts
+import { createServer } from 'experimental-a2/server'
+import { orders } from '@/contracts'
+
+export const fanout = createServer({
+  contract: orders,
+  handlers: {
+    'shop.started': async () => {
+      return orders.batch(
+        { type: 'shop.notified', payload: {} },
+        { type: 'driver.notified', payload: { driverId: 'driver-7' } },
+      )
+    },
+  },
+})
+```
+
+Return one event or an array when it should exist only if the handler
+succeeds. A2 marks the trigger processed and appends the batch in one atomic
+operation, at consecutive positions. If the handler throws or the process dies
+first, none of it exists. Returned events get deterministic ids, so a retry
+after a lost acknowledgement doesn't duplicate them.
+
+`contract.batch(...)` is a type helper that keeps each event's literal type;
+A2 still validates at commit.
+
+## Append what should happen now
+
+```ts server/append-now.ts
+import { createServer } from 'experimental-a2/server'
+import { orders } from '@/contracts'
+
+export const immediate = createServer({
+  contract: orders,
+  handlers: {
+    created: async ({ session }) => {
+      await session.append('notify-shop', {
+        type: 'shop.notified',
+        payload: {},
+      })
+
+      // The shop.notified handler may already be running here.
+      // await continueCurrentWork()
+    },
+    'shop.notified': async () => {},
+  },
+})
+```
+
+`ctx.session.append()` commits immediately, so the appended event can start
+while its parent is still running. Use it for streaming progress, independent
+fan-out, or any fact that stays true even if the handler later fails. Each
+call is atomic.
+
+The first argument names the append within the triggering event. A2 derives
+the ids of events without an `id` from the trigger, the name, and each
+event's position, so a retry gets the existing events back, whatever order
+parallel branches finish in. Keep the name stable; reusing it with a different
+batch conflicts. An explicit `id` wins, so different triggers can converge on
+one fact. Top-level `server.session(id).append(...events)` takes no name.
+
+## Concurrent by default
+
+```ts
+// anywhere on the server:
+await ordersServer.session('order-42').append(
+  { type: 'created', payload: { shopId: 'shop-7', items: [] } },
+  { type: 'shop.started', payload: {} },
+)
+```
+
+Every eligible event has its own claim, so both handlers start without
+waiting for each other. Log order stays stable; handler order doesn't. A
+failure retries that event without holding up unlaned events or other lanes.
+
+## Lanes
+
+```ts server/serial-orders.ts
+import { createServer } from 'experimental-a2/server'
+import { orders } from '@/contracts'
+
+export const serialOrders = createServer({
+  contract: orders,
+  handlers: {
+    created: {
+      lane: 'order-work',
+      handler: async () => {},
+    },
+    'shop.started': {
+      lane: 'order-work',
+      handler: async () => {},
+    },
+    'driver.notified': {
+      lane: ({ event }) => `driver:${event.payload.driverId}`,
+      handler: async ({ event }) => {
+        // your work for this driver, using event.payload.driverId
+      },
+    },
+  },
+})
+```
+
+Use a lane when events share a resource and must not overlap. Within one
+session, same-lane events run one at a time in log order; different lanes and
+unlaned events stay concurrent. A lane is a constant (a serial queue) or a
+function of the validated event.
+
+A2 stores the resolved lane at append, so a deployment can't reinterpret
+pending work. Lanes are per session, not distributed locks across sessions. If
+a lane's first unfinished event fails, later events in that lane wait; other
+lanes continue.
+
+## Handlers can run twice
+
+Handlers are at-least-once. A crash after your side effect but before A2
+records completion runs the handler again.
+
+- **External side effects take an idempotency key.** `event.id` is stable
+  across attempts.
+- **Named appends are deduplicated.** A retry gets the existing events back.
+- **Returned events commit with completion.** They all exist with the
+  processed marker, or none do.
+
+## When handlers throw
+
+Throwing means "retry me." A2 records the failure and retries with backoff.
+The failed event blocks only its lane. After ten caught failures it
+dead-letters and keeps blocking its lane until
+[you retry or skip it](/server/production#3-when-an-event-dead-letters).
+
+When someone presses stop, catch the abort and return normally instead. See
+[Cancellation](/server/cancellation).

package/docs/server/02-timers.mdx

@@ -0,0 +1,130 @@
+---
+title: Timers
+description: Schedule a typed session event for later, through the same scheduler that handles recovery.
+---
+
+## Schedule from a handler
+
+```ts server/orders.ts
+import { createServer } from 'experimental-a2/server'
+import { vercelQueues } from 'experimental-a2/scheduler-vercel'
+import { orders } from '@/contracts'
+
+export const scheduler = vercelQueues()
+
+export const ordersServer = createServer({
+  contract: orders,
+  scheduler,
+  handlers: {
+    created: async ({ session }) => {
+      await session.schedule(
+        'expire-order',
+        { delay: '5d' },
+        { type: 'expired', payload: {} },
+      )
+    },
+    expired: async ({ session }) => {
+      const events = await session.history()
+      if (events.some((event) => event.type === 'shop.started')) return
+      // your expiry side effect goes here
+    },
+  },
+})
+```
+
+Configure a scheduler, then call `session.schedule(name, timing, ...events)`.
+The scheduler route that handles recovery delivers timers too;
+[mount it once](/server/production#2-add-a-scheduler-for-handlers-and-timers).
+
+`timing` is `{ delay }` (units `ms`, `s`, `m`, `h`, `d`, checked by the type)
+or `{ at: Date }`. A delay must be a finite, unsigned base-10 decimal above
+zero with no leading zeros; A2 rejects `0s`, signs, exponent notation,
+malformed strings, and invalid dates.
+
+The call resolves once the provider accepts the task; nothing enters the log
+until delivery. The target is the earliest delivery time, not a deadline:
+adapters round to whole seconds, and an already-due target sends immediately.
+
+## Schedule from ordinary server code
+
+```ts app/api/trials/route.ts
+import { z } from 'zod'
+import { ordersServer } from '@/server/orders'
+
+const scheduleTrial = z.object({
+  orderId: z.string(),
+  expiresAt: z.iso.datetime().transform((value) => new Date(value)),
+})
+
+export async function POST(request: Request) {
+  const body = scheduleTrial.parse(await request.json())
+  await ordersServer.session(body.orderId).schedule(
+    'expire-order',
+    { at: body.expiresAt },
+    { type: 'expired', payload: {} },
+  )
+  return Response.json({ scheduled: true }, { status: 202 })
+}
+```
+
+Root sessions have the same method. A root `{ delay: '30s' }` counts from that
+call's clock, so a retry 10 seconds later delivers 10 seconds later too. Use
+`{ at }` when a caller may retry. Inside a handler, a delay counts from the
+triggering event's durable `createdAt`, so retries keep the same target.
+
+## Identity and retries
+
+`name` identifies one schedule: per contract and session at the root, plus the
+triggering event id in a handler. Different events can share a name like
+`expire-order`, while retries of one event converge.
+
+Keep the same name, timing, and events on every retry. Omitted event ids are
+derived and stable, so duplicate deliveries append once per session lifetime,
+even after the provider's deduplication window. A
+[clear](/contract/sessions#clearing-a-session) frees those ids, so a root task
+redelivered after one appends again. Changed input under the same name
+conflicts at delivery when it produces a different validated event.
+
+## What arrives later
+
+Payloads travel in the provider message as plain JSON: encode a `Date` as an
+ISO string and a class as plain data. A2 rejects `undefined`, functions,
+symbols, bigints, cycles, accessors, and non-plain prototypes, and shared
+references arrive as copies. At delivery, an ordinary top-level append with
+fixed ids validates the original input, so a schema transform runs on that
+input, not on an earlier output.
+
+Scheduled events enter the log only when delivered, with `cause: null`. From
+there they behave like any server append: handlers, lanes, reducers, streams,
+and live clients see them normally, and their stable ids absorb at-least-once
+delivery.
+
+If the receiving deployment changed or removed the event's schema, delivery
+can fail validation and then keeps retrying as a scheduler error. The Vercel
+adapter pins timers to their publishing deployment by default; with
+`deploymentId: null` or a stable URL like QStash's, keep schemas compatible.
+See [Deploy safely](/server/production#4-deploy-safely).
+
+## Stale timers
+
+The order shipped on day two; its expiry still arrives on day five. Use the
+guard from the first example: let the event land, read the session, and return
+when it no longer applies. The log still records that the timer fired.
+
+A2 has no cancellation, reschedule, cron, or timer-listing API. `name` is an
+idempotency key, not a handle. For repeating work, have each occurrence's
+handler schedule the next one.
+
+## Provider limits
+
+| Adapter | Maximum one-shot delay |
+| --- | --- |
+| Vercel Queues | 6 days |
+| QStash free | 7 days |
+| QStash usage-based | 1 year |
+| QStash fixed | no fixed maximum |
+
+A2 does not split a longer delay into several tasks. Vercel Queues keeps
+messages for seven days, and A2 reserves the final day for delivery and
+retries. At a QStash maximum, leave at least one second of margin: its
+`notBefore` uses whole Unix seconds.

package/docs/server/03-cancellation.mdx

@@ -0,0 +1,141 @@
+---
+title: Cancellation
+description: There is no abort() API. Cancelling is appending, and the running handler finds out through a signal.
+---
+
+## Cancelling is appending
+
+```ts
+// in the browser: push from useSession
+push({ type: 'cancelled', payload: { lastSeenIndex: index } })
+```
+
+A user presses stop on a streaming AI response. That's an event: same route,
+same auth, same log as every other event. Two things then happen, at two
+speeds.
+
+## The running handler stops
+
+```ts server/chat.ts
+import { createServer } from 'experimental-a2/server'
+import { chat } from '@/contracts'
+
+export const chatServer = createServer({
+  contract: chat,
+  handlers: {
+    generate: {
+      abortOn: ['cancelled'],
+      handler: async (ctx) => {
+        // your abortable work; hand it ctx.signal:
+        // await streamText({ signal: ctx.signal, ... })
+      },
+    },
+  },
+})
+```
+
+`abortOn` names the events that interrupt the handler. When a `cancelled`
+event lands, or had already landed before the handler started, `ctx.signal`
+fires. Handlers without `abortOn` hold no subscription.
+
+When one session runs several generations over its lifetime, match the
+instance with a predicate:
+
+```ts
+// server/chat.ts, the generate entry, targeted by instance:
+generate: {
+  abortOn: {
+    // only the cancel that names this run fires the signal
+    cancelled: (event, trigger) => event.payload.of === trigger.id,
+  },
+  handler: async (ctx) => {
+    // ...
+  },
+}
+```
+
+The pushing side already knows the id it's cancelling: it's in the hook's
+`events` feed.
+
+## When a run loses its claim
+
+Every handler's signal, with or without `abortOn`, also fires when the run
+loses its claim: `CLAIM_EXPIRED` when the lease lapses without renewal
+(decided locally, so it works while the store is unreachable), or
+`SUPERSEDED_ATTEMPT` when a recovery run has claimed the event. Either way, a
+successor is taking over: stop external work. A superseded run can no longer
+write to the log or complete; passing `ctx.signal` to your external calls is
+what stops it racing its successor outside A2.
+
+Pass `ctx.signal` to your I/O and let the abort propagate. That handles every
+case:
+
+- **A propagated lease abort** surrenders the attempt: no completion, no
+  failure budget spent, normal recovery.
+- **A user cancellation** (`abortOn`) is the one to catch and return normally
+  from. The stop is the outcome, so the completion counts.
+- **Return normally after a lease abort** only when the work is done. A lapsed
+  run that finishes before any successor claims the event still completes.
+- **Any other throw** is a real failure and spends the retry budget.
+
+## Clean up after the handler
+
+A `cancelled` handler can run while the interrupted one is still unwinding:
+the signal is the preemption channel, the event is the durable record. When
+cleanup must wait, put both event types in one lane. The event still fires the
+signal on append, but its own handler waits for earlier work in the lane:
+
+```ts server/chat-with-cleanup.ts
+import { createServer } from 'experimental-a2/server'
+import { chat } from '@/contracts'
+
+export const chatServer = createServer({
+  contract: chat,
+  handlers: {
+    generate: {
+      lane: 'generation',
+      abortOn: ['cancelled'],
+      handler: async (ctx) => {
+        // your abortable work; hand it ctx.signal:
+        // await streamText({ signal: ctx.signal, ... })
+      },
+    },
+    cancelled: {
+      lane: 'generation',
+      handler: async () => {
+        // your cleanup, after generate has returned
+      },
+    },
+  },
+})
+```
+
+## The view cuts
+
+```ts reducer.ts
+case 'chunk':
+  return state.cancelled
+    ? state
+    : { ...state, chunks: [...state.chunks, { index: event.index, delta: event.payload.delta }] }
+case 'cancelled':
+  return {
+    ...state,
+    cancelled: true,
+    chunks: state.chunks.filter((c) => c.index <= event.payload.lastSeenIndex),
+  }
+```
+
+Chunks in flight during the cancel round trip still land after `cancelled`.
+They're true history; keeping them out of the view is the reducer's job.
+
+`lastSeenIndex` is the client's stream frontier, which it already tracks. The
+cut is exact and clock-free: chunks the user never saw are removed, so the
+optimistic view and the authoritative refold agree. Because the client pushes
+`cancelled` [optimistically](/client/react#events-and-history), its own fold
+cuts instantly, and stragglers hit `state.cancelled` and vanish.
+
+:::tip
+Keep chunks at per-chunk granularity in state until the session reaches a
+terminal event, then compact them into one string. That's reducer design,
+fully yours.
+:::