experimental-a2 0.20.0 → 0.22.0

package/docs/server/01-handlers.mdx

@@ -1,227 +0,0 @@
----
-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](/stores/overview) 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 failed attempts it
-dead-letters and keeps blocking its lane until
-[you retry or skip it](#resolve-a-dead-letter).
-
-When someone presses stop, catch the abort and return normally instead. See
-[Cancellation](/server/cancellation).
-
-## Resolve a dead letter
-
-A [dead-lettered](/server/guarantees#when-a-handler-keeps-failing) event waits
-for you. List a session's dead letters, then retry or skip each one:
-
-```ts
-// anywhere on the server, behind your own operator checks:
-import { ordersServer } from '@/server'
-
-const order = ordersServer.session(orderId)
-const [dead] = await order.deadLetters()
-if (dead) {
-  // dead.lastError says why (null if every attempt timed out or crashed);
-  // deploy the handler fix first, then:
-  await order.redrive(dead.index, { action: 'retry' })
-}
-```
-
-- **Retry.** `{ action: 'retry' }` runs the handler again with a fresh
-  ten-failure budget. Once it completes, its lane continues.
-- **Skip.** `{ action: 'skip' }` marks the event processed without running it,
-  accepting that its effects never happen. The next event in its lane runs.
-
-Each redrive is one atomic store operation, and it wakes the session like an
-append, so the lane resumes without another write. An event that isn't
-dead-lettered anymore is left alone: `redrive` reports `{ redriven: false }`.