experimental-a2 0.0.0 → 0.2.0

package/docs/concepts/02-handlers.mdx

@@ -1,6 +1,6 @@
 ---
 title: Handlers
-description: Stateless async functions that react to one event, and usually append the next one.
+description: Concurrent reactions with atomic returned events and explicit serial lanes.
 ---
 
 ```ts server/orders.ts
@@ -10,137 +10,271 @@ import { orders } from '@/contracts'
 export const ordersServer = createServer({
   contract: orders,
   handlers: {
-    created: async ({ event, append }) => {
+    created: async ({ event }) => {
       // your side effect, e.g. email the shop, idempotent via event.id:
       // await sendEmailToShop(event.payload, { idempotencyKey: event.id })
-      await append({ type: 'shop.notified', payload: {} })
+      return { type: 'shop.notified', payload: {} }
     },
   },
 })
 ```
 
-That's a handler: it runs when its event lands, does its work, and appends
-what happens next. Handlers live in the server's construction, not on
-sessions. One table of reactions serves every session: `order-1`,
-`order-2`, all of them. Because the table is complete at construction, a
-handler can never be silently missing just because the module that
-defined it wasn't imported.
+A handler runs when its event lands. It is a plain async function: call a
+database, hit an API, stream a model response. A2 durably claims the event,
+renews that claim while the function runs, and retries after a crash.
 
-They're also plain async functions. No determinism requirements, no replay,
-no wrappers around side effects. Call your database, hit an API, use
-`Math.random()`, stream a model response for a minute. A2 heartbeats the
-session's lease while your handler runs, so a slow handler never loses its
-exclusivity to a concurrent retry. The one thing you don't do in a handler
-is wait for the future. For that, [append an event later](/guides/timers).
+Handlers live in the server's construction, not on sessions. One complete
+table serves every session. A handler cannot be silently missing because the
+module that registered it was never imported.
+
+## Events without handlers
+
+Handlers are optional per event type. An event without one still gets its full
+place in the log. You can read it with `history()`, fold it into state, and
+stream it to a live client. A2 settles it in the append transaction, with no
+dispatch claim or recovery message.
+
+```ts server/order-log.ts
+import { createServer } from 'experimental-a2/server'
+import { postgres } from 'experimental-a2/log-postgres'
+import { orders } from '@/contracts'
+
+export const orderLog = createServer({
+  contract: orders,
+  log: postgres({ connectionString: process.env.DATABASE_URL }),
+})
+```
+
+A contract can mix handled and unhandled event types. Adding a handler later
+does not replay events that were already settled. Model replay as a new event
+or run an explicit migration when that is the behavior you want.
 
 ## The context
 
 Every handler receives one argument:
 
-| 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.append(...e)`   | Append what happens next to this session's log. Typed against the contract's schemas.          |
-| `ctx.history()`      | Every past event in this session, oldest first. Always the raw log.                            |
-| `ctx.signal`         | An `AbortSignal`, active only with `abortOn`. See [Cancellation](/guides/cancellation).         |
+| 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`, `history`, `state`, and `stream`. |
+| `ctx.signal`  | An `AbortSignal`, active only with `abortOn`. See [Cancellation](/guides/cancellation). |
 
 `ctx.attempt` starts at `1` and increments on every durable claim. It may skip
 when a process dies between the claim and handler entry.
 
-Use `history()` when a handler needs more than the triggering event: "has
-this order already been notified twice?". For a cheap computed view of a
-long session, use a [reducer](/concepts/state) instead.
+`ctx.session.id` is the same value as `ctx.event.sessionId`. Use
+`ctx.session.history()` when a handler needs raw facts. Use
+[`state()`](/concepts/state) for a cached computed view of a long session.
 
-## Chaining
+## Return what happens after success
 
-The core pattern: handlers append the event that should happen next.
+Return an event when it depends on successful handler completion:
 
-```ts
-// server/orders.ts, the next link in the chain:
+```ts server/return-one.ts
 import { createServer } from 'experimental-a2/server'
 import { orders } from '@/contracts'
 
-export const ordersServer = createServer({
+export const assignments = createServer({
+  contract: orders,
+  handlers: {
+    'shop.started': async () => {
+      return { type: 'driver.notified', payload: { driverId: 'driver-7' } }
+    },
+  },
+})
+```
+
+A handler can return one event or an array:
+
+```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' } },
+      )
+    },
+  },
+})
+```
+
+`contract.batch(...)` keeps each event's literal type when an async handler
+returns different event types. It is a type helper; validation still happens
+when A2 commits the returned events.
+
+A2 marks the triggering event processed and appends the returned batch in one
+atomic storage operation. The batch is all-or-nothing and occupies consecutive
+log positions. If the handler throws or the process dies first, none of the
+returned events exist.
+
+Returned events receive deterministic ids. If A2 commits the operation but
+loses its acknowledgement, the retry recognizes the exact returned batch and
+does not duplicate it.
+
+## Append what should happen now
+
+`ctx.session.append()` has different timing. It commits immediately, so the appended
+event can start while its parent handler is still running:
+
+```ts server/append-now.ts
+import { createServer } from 'experimental-a2/server'
+import { orders } from '@/contracts'
+
+export const immediate = createServer({
   contract: orders,
   handlers: {
-    'shop.started': async ({ append }) => {
-      // const driverId = await acquireDriver(), however your app finds one
-      const driverId = 'driver-7'
-      await append({ type: 'driver.notified', payload: { driverId } })
+    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 () => {},
   },
 })
 ```
 
-This is how a lifecycle moves in A2. It is not a workflow definition, but a
-chain of facts, each one triggering the next reaction. Afterward, the full
-story of the order is sitting in its log, readable top to bottom.
+Use it for streaming progress, independent fan-out, or any fact that remains
+true even if the current handler later fails. A multi-event
+`ctx.session.append()` is atomic per call.
+
+The first argument names this immediate append within the triggering event.
+It is the handler-local idempotency key for events whose `id` is omitted. Keep
+it stable across retries:
+
+```ts
+// inside a handler:
+await session.append(
+  'publish-build',
+  { type: 'artifact.created', payload: artifact },
+  { type: 'build.completed', payload: result },
+)
+```
+
+A2 combines the triggering event id, this name, and each unnamed event's
+position to derive deterministic child ids. Parallel branches can finish in
+any order without changing their identities. Reusing a name with the same
+generated-id batch returns the existing events. Changing that batch conflicts
+with the rows already stored under those ids. An explicit event `id` wins over
+the generated id, which is useful when different triggering events must
+converge on one fact. Top-level `server.session(id).append(...events)` takes no
+name because it is not scoped to a handler.
+
+The distinction is small and important:
+
+| Syntax | The event becomes durable |
+| ------ | ------------------------- |
+| `return event` | Atomically when the handler completes successfully |
+| `return [a, b]` | Both atomically when the handler completes successfully |
+| `await session.append(name, event)` | Immediately, before the handler completes |
+
+## Concurrent by default
+
+Every eligible event has its own durable claim. Independent handlers in the
+same session start without waiting for earlier handlers:
+
+```ts
+// anywhere on the server:
+await ordersServer.session('order-42').append(
+  { type: 'created', payload: { shopId: 'shop-7', items: [] } },
+  { type: 'shop.started', payload: {} },
+)
+```
+
+The log order remains stable, but handler start and completion order do not.
+A failure retries that event without holding up unlaned events or other lanes.
+
+## Lanes
+
+Use a lane when events share a resource and must not overlap:
+
+```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 () => {},
+    },
+  },
+})
+```
 
-`append` takes one or more events. A multi-event append is atomic:
-all-or-nothing, consecutive log positions, one transaction.
+Within one session, events with the same lane run one at a time in log order.
+Different lanes and unlaned events remain concurrent. A constant lane like
+`'order-work'` recreates a serial queue for the event types that use it.
 
-## Ordering
+A lane can also be derived from the validated event:
 
-Within a session, handlers run serially, in log order. The handler for
-event 5 doesn't start until events 1 through 4 have finished, even when
-retries and queue deliveries arrive shuffled. Across sessions there's no
-coordination; two orders never wait on each other.
+```ts server/drivers.ts
+import { createServer } from 'experimental-a2/server'
+import { orders } from '@/contracts'
 
-Chained handlers run inline for as long as the current invocation lives. A2
-does not predict whether the next handler fits in the remaining function
-time. If the platform stops the invocation, completed events stay processed
-and the event that was still running stays pending. Recovery retries that same
-event under a fresh lease.
+export const drivers = createServer({
+  contract: orders,
+  handlers: {
+    'driver.notified': {
+      lane: ({ event }) => `driver:${event.payload.driverId}`,
+      handler: async ({ event }) => {
+        // your work for this driver, using event.payload.driverId
+      },
+    },
+  },
+})
+```
 
-Each individual handler must still fit inside a fresh invocation. A2 can
-recover a chain whose total duration crosses the function limit, but it cannot
-split one handler while it is running. If a handler always exceeds the
-platform's function duration, every recovery attempt reaches the same limit.
-Break that work into a chain of smaller events, or give the function enough
-time for one handler to finish.
+The resolved lane is stored with the event when it is appended. Recovery uses
+that stored value, so a deployment cannot reinterpret pending work. Lane keys
+are scoped to one session. They are not distributed locks across sessions.
 
-If a handler fails, the session stalls at that event. Later events keep
-accumulating in the log (appends never fail because a handler is failing),
-but their handlers wait. Skipping ahead would let a handler observe a
-history whose earlier handlers never ran; stalling is the honest behavior.
-The retry story is in [Durability](/concepts/durability).
+If a lane's first unfinished event fails, later events in that lane wait.
+Other lanes continue. After ten caught failures the event dead-letters and
+keeps blocking its lane until manual resolution.
 
 ## Handlers can run twice
 
 Handlers are at-least-once. A crash after your side effect but before A2
-marks the event processed means the handler runs again. Two rules make this
-a non-issue:
+commits completion means the handler can run again.
 
 1. **External side effects take an idempotency key.** `event.id` is stable
-   across re-runs. Pass it to your email provider, your payment API,
-   anything that shouldn't happen twice.
-
-2. **`ctx.append` is deduplicated for you.** Each append call inside a
-   handler gets a deterministic id derived from the triggering event and the
-   call's position. A re-run produces the same ids, hits the log's unique
-   index, and gets the existing rows back. The straight-line case needs no
-   thought.
-
-:::note
-How? Without an explicit `id`, `ctx.append` derives one deterministically:
-a hash of the triggering event's id plus the call's position ("the second
-append this handler made"). A re-run reproduces the same ids, hits the
-log's unique index, and gets the original rows back. It's the same
-[idempotency machinery](/concepts/durability#what-append-never-throws-for)
-that dedupes every append. No special case, no checkpoint state.
-:::
-
-One caveat on rule 2: a handler that appends in a data-dependent order
-(looping over results from an external API, say) should pass explicit `id`s,
-because "the same call position" isn't stable when the loop changes.
+   across attempts. Pass it to anything that should not happen twice.
+
+2. **Immediate handler appends are deduplicated.**
+   `ctx.session.append(name, ...events)` derives ids from the triggering event,
+   the stable handler-local name, and each event's position. A retry gets the
+   existing rows back. A changed generated-id batch conflicts with those
+   existing rows.
+
+3. **Returned events commit with completion.** They either all exist with the
+   processed marker or none exist.
+
+A handler should give every independent immediate append a stable name. The
+name removes any dependence on the order in which concurrent branches call
+`append`. Use explicit event ids when several different triggering events must
+converge on one shared fact.
 
 ## When handlers throw
 
-Throwing means "retry me". A2 records the failure and retries with backoff
-until the handler succeeds, or, after ten caught failures, dead-letters the event
-and stalls the session for [manual resolution](/concepts/durability#when-a-handler-keeps-failing).
+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 for [manual resolution](/concepts/durability#when-a-handler-keeps-failing).
 
-The flip side: a handler interrupted by a user (via `ctx.signal`) should
-catch and return normally. "Retry me" is exactly the wrong response to
-someone pressing stop. See [Cancellation](/guides/cancellation).
+An interrupted handler should catch and return normally. Throwing is the
+wrong response to someone pressing stop. See
+[Cancellation](/guides/cancellation).