experimental-a2 0.8.0 → 0.9.0

package/docs/actors/01-introduction.mdx

@@ -0,0 +1,189 @@
+---
+title: Introduction
+description: "A durable object built on the log: one named instance, typed state, and handlers that process one message at a time."
+---
+
+## The model
+
+An actor is state behind a mailbox. You address an instance by id, send
+it typed events, and its handlers process them one at a time: read
+state, decide, mutate, return. Each handler ends in one atomic commit.
+Between messages the instance is rows in your store, not a process:
+nothing to keep alive, no locks to take, no lost updates to debug.
+
+Every instance is an ordinary A2 session underneath, so everything the
+log gives a session (durability, retries, history, devtools) holds for
+actors too. The module is three entry points: `experimental-a2/actor`
+on the server, `experimental-a2/actor/client` anywhere, and
+`experimental-a2/actor/react` for the hook.
+
+## Define one
+
+A protocol declares the state shape and the events with their inputs.
+Types, not schemas: handlers are trusted server code, and the compiler
+holds them to the protocol. Pass it explicitly.
+
+```ts vault.ts
+import { NonRetriableError } from 'experimental-a2'
+import { actor } from 'experimental-a2/actor'
+
+interface Vault {
+  state: { balance: number }
+  events: {
+    deposit: { amount: number }
+    withdraw: { amount: number }
+  }
+}
+
+export const vault = actor<Vault>({
+  name: 'vault',
+  state: { balance: 0 },
+  handlers: {
+    deposit: (ctx, input) => {
+      ctx.state.balance += input.amount
+    },
+    withdraw: (ctx, input) => {
+      if (ctx.state.balance < input.amount) {
+        throw new NonRetriableError('insufficient funds')
+      }
+      ctx.state.balance -= input.amount
+    },
+  },
+})
+```
+
+The `handlers` record must cover every declared event: a missing
+handler, an extra one, or a wrong input shape fails to compile. Inputs
+arrive typed; `ctx.state` is a mutable draft of the instance's state,
+committed atomically when the handler returns. `name` is identity (it
+prefixes storage keys), and `state` seeds new instances.
+
+Types are compile-time claims. When an event can arrive from the wire,
+guard its input in the handler's first lines and throw
+`NonRetriableError` on bad shapes (bring a schema library and `.parse`
+if you prefer; it is userland either way).
+
+`actor` also accepts the `store`, `scheduler`, and `telemetry` options
+`createServer` takes. Without a store it uses the same development
+default; see [Going to production](/guides/production). A protocol can
+declare one more vocabulary, `presence`, for live audience state; see
+[Presence](/actors/routes#presence).
+
+## Call it
+
+`call` sends the event and awaits its answer: the state after the
+handler ran, and the log index of that commit.
+
+```ts
+// anywhere on the server:
+import { vault } from '@/vault'
+
+const savings = vault.actor('savings')
+
+const { state, index } = await savings.call.deposit({ amount: 100 })
+// state reflects this deposit, and every message before it
+```
+
+`vault.actor(id)` is a handle, not a resource; nothing exists until the
+first message. Concurrent calls from any number of serverless
+invocations serialize on the instance's lane, and each answer reflects
+its own message. That serialization is the feature:
+[Concurrency](/actors/concurrency) is the full story.
+
+### Refusals
+
+A handler says no by throwing `NonRetriableError`. That refusal is an
+answer, not a failure: nothing commits, nothing retries, and the caller
+gets the message.
+
+```ts
+// anywhere on the server:
+import { ActorRefusedError } from 'experimental-a2/actor'
+import { vault } from '@/vault'
+
+try {
+  await vault.actor('savings').call.withdraw({ amount: 1_000_000 })
+} catch (error) {
+  if (error instanceof ActorRefusedError) {
+    // the answer was no: state unchanged, message settled
+  }
+}
+```
+
+Three kinds of failure, three behaviors:
+
+- **`NonRetriableError`** is a refusal, and a refusal is all or
+  nothing: no state change, no buffered sends. The message is settled,
+  and the caller receives `ActorRefusedError`.
+- **Any other throw** is an infrastructure failure. A2 retries the
+  message with the usual budget and backoff; the instance's lane waits,
+  which is deliberate (correctness over liveness). See
+  [Errors](/reference/errors).
+- **A crash** re-runs the handler from the pre-message state. `ctx.id`
+  is the message id, stable across re-runs: use it as the idempotency
+  key for external I/O.
+
+## Send, don't wait
+
+`send` validates, appends the event durably, and returns without
+waiting for the handler.
+
+```ts
+// anywhere on the server:
+import { vault } from '@/vault'
+
+const { id } = await vault.actor('savings').send.deposit({ amount: 25 })
+// durably queued; the handler runs on the instance's lane
+```
+
+Same mailbox, same ordering; the only difference is that nobody waits
+for the answer. Pass `{ id }` in the options to make a retried send
+idempotent.
+
+## Read without queueing
+
+```ts
+// anywhere on the server:
+import { vault } from '@/vault'
+
+const { state } = await vault.actor('savings').state()
+```
+
+A snapshot read. It never queues behind pending messages, and a new
+instance reads as its seed state.
+
+## State is remembered, not recomputed
+
+Every commit appends a state event to the instance's log, and reads
+fold those by last write wins. History is never reinterpreted: you can
+rewrite a handler freely without changing what any past commit means.
+(This is the opposite trade from [reducers](/concepts/state), which
+recompute views from events; actor state is the recorded decision
+itself.)
+
+Because state lives in the log, it holds to the same floor as any
+payload: plain JSON trees. A `Date`, a `Map`, or `NaN` fails the commit
+loudly instead of being silently coerced.
+
+Two consequences worth designing for:
+
+- **Old instances meet new code.** After a deploy, state written by the
+  previous version flows into the new handlers. Default new fields
+  defensively (`ctx.state.pending ??= {}` as a first line) instead of
+  assuming the latest shape.
+- **The seed applies to new instances only.** Changing `state` in the
+  definition does not migrate existing instances; they keep their
+  remembered state.
+
+## The log is still there
+
+An actor is a layer over an ordinary A2 session, not a wall around
+one. `handle.session` is that session (history, streams, scheduling),
+the definition
+exposes its assembled `contract`, `server`, and `reducer`, and the full
+mailbox is visible in devtools. Event names starting with `a2.` are
+reserved for the actor's own bookkeeping.
+
+Next: [Concurrency](/actors/concurrency) for the execution
+model, [Deadlines and timers](/actors/timers) for scheduled events, and
+[Routes, clients, and React](/actors/routes) for the wire.

package/docs/actors/02-concurrency.mdx

@@ -0,0 +1,154 @@
+---
+title: Concurrency
+description: "Each instance processes one message at a time. Slow work goes in concurrent handlers: they run in parallel and report back by sending events."
+---
+
+## One message at a time
+
+Every message an instance receives runs on its
+[lane](/concepts/handlers#lanes): a serial queue, one handler at a
+time, in arrival order. This is what makes handlers easy to trust. A
+handler always sees the state every previous message produced, its
+checks cannot be raced by another message, and its changes commit
+before the next message runs.
+
+The lane is per instance. A thousand vaults process in parallel; each
+vault processes in order. If a single instance receives more traffic
+than one queue can absorb, split the identity and give the work more
+instances (per user, per order, per document) instead of trying to
+make one instance concurrent.
+
+## The problem with slow work
+
+A serial handler holds the lane while it runs. If `withdraw` awaits a
+two-second bank API, every deposit waits behind it. The instance stays
+correct, but it stops responding.
+
+The fix is not to weaken the lane. It is to split the work: serial
+handlers make the decisions, concurrent handlers do the slow parts,
+and the results come back as events.
+
+## Concurrent handlers
+
+Wrap a handler in `concurrent(...)` and it leaves the lane: it runs in
+parallel with serial handlers and with other concurrent handlers. Two
+things change inside it:
+
+- There is no `ctx.state` draft to mutate. Reading state becomes a
+  function call, `ctx.state()`, and the snapshot it returns can go
+  stale while the handler keeps running.
+- State changes happen by sending events. Their serial handlers run on
+  the lane and decide against current state.
+
+## Reserve, transfer, settle
+
+A withdrawal that talks to a slow bank, without ever blocking the
+vault: reserve the money, run the transfer, then settle or refund.
+
+```ts vault.ts
+import { NonRetriableError } from 'experimental-a2'
+import { actor, concurrent } from 'experimental-a2/actor'
+
+interface Vault {
+  state: {
+    balance: number
+    /** In-flight transfers: ref to reserved amount. */
+    pending: Record<string, number>
+  }
+  events: {
+    deposit: { amount: number }
+    withdraw: { amount: number }
+    transfer: { ref: string; amount: number }
+    settle: { ref: string }
+    refund: { ref: string }
+  }
+}
+
+export const vault = actor<Vault>({
+  name: 'vault',
+  state: { balance: 0, pending: {} },
+  handlers: {
+    deposit: (ctx, input) => {
+      ctx.state.balance += input.amount
+    },
+
+    // the reserve: serial, so the guard sees fresh state
+    withdraw: (ctx, input) => {
+      if (ctx.state.balance < input.amount) {
+        throw new NonRetriableError('insufficient funds')
+      }
+      ctx.state.balance -= input.amount
+      ctx.state.pending[ctx.id] = input.amount
+      ctx.send.transfer({ ref: ctx.id, amount: input.amount })
+    },
+
+    // the slow part: off the lane, in parallel
+    transfer: concurrent(async (ctx, input) => {
+      // your slow call; ctx.id makes retried attempts idempotent:
+      // const ok = await bank.transfer(input.amount, { idempotencyKey: ctx.id })
+      const ok: boolean = true
+      if (!ok) {
+        ctx.send.refund({ ref: input.ref })
+        return
+      }
+      ctx.send.settle({ ref: input.ref })
+    }),
+
+    // finalizers: serial again, idempotent by the pending guard
+    settle: (ctx, input) => {
+      if (ctx.state.pending[input.ref] === undefined) return
+      delete ctx.state.pending[input.ref]
+    },
+    refund: (ctx, input) => {
+      const amount = ctx.state.pending[input.ref]
+      if (amount === undefined) return
+      delete ctx.state.pending[input.ref]
+      ctx.state.balance += amount
+    },
+  },
+})
+```
+
+Step by step:
+
+1. **`withdraw` reserves.** It runs on the lane, so the balance check
+   cannot be raced by another withdrawal. The balance drops, `pending`
+   records the reserved amount, and the `transfer` event commits
+   atomically with both. The withdrawal cannot half-start.
+2. **`transfer` does the slow part.** It runs off the lane, so
+   deposits keep flowing meanwhile. It finishes by sending an event:
+   `settle` on success, `refund` when the bank says no. It never
+   changes state itself, and it reports failure by sending, not by
+   throwing.
+3. **`settle` and `refund` finish the job.** Both check `pending[ref]`
+   first and return when the entry is gone, so a duplicate or late
+   message does nothing. The refund amount comes from state, not from
+   recomputing it.
+
+A crash at any step re-runs that one message from the state it started
+with. Wherever the process dies, the vault lands in a named state:
+reserved, settled, or refunded. Money is never half-transferred.
+
+## Buffered sends
+
+`ctx.send` does not append immediately. Everything a handler sends is
+buffered and commits when the handler completes: for a serial handler,
+in the same commit as its state change; for a concurrent handler, when
+it finishes. A refusal discards the buffer along with the state
+changes, so a refused message leaves no trace. Re-runs produce the
+same message ids, so a retried handler does not append its sends
+twice.
+
+## When handlers fail
+
+- A **serial** handler that throws `NonRetriableError` refuses the
+  message: nothing commits, and the caller gets the answer (see
+  [Introduction](/actors/introduction#refusals)).
+- A **serial** handler that throws anything else is retried on the
+  lane, and the instance waits. This is deliberate: state never
+  advances past a failure.
+- A **concurrent** handler that throws is retried off the lane;
+  nothing else waits for it.
+- `call` works on serial events only. A concurrent handler produces no
+  answer to wait for, so calling one is rejected: `send` those events
+  instead.

package/docs/actors/03-timers.mdx

@@ -0,0 +1,120 @@
+---
+title: Deadlines and timers
+description: "Schedule a typed event back to the same instance. Deadlines survive deploys and land on the lane like any other message."
+---
+
+## A deadline is a message, delivered later
+
+`ctx.schedule` mirrors `ctx.send`, one method per declared event, with
+a timing argument: exactly one of `{ delay: '1h' }` or `{ at: date }`.
+It hands the event to the configured scheduler, and delivery lands on
+the instance's lane like any other message.
+
+```ts escrow.ts
+import { actor } from 'experimental-a2/actor'
+import { vercelQueues } from 'experimental-a2/scheduler-vercel'
+
+interface Escrow {
+  state: { held: Record<string, number> }
+  events: {
+    hold: { offerId: string; amount: number }
+    accept: { offerId: string }
+    release: { offerId: string }
+  }
+}
+
+export const escrow = actor<Escrow>({
+  name: 'escrow',
+  state: { held: {} },
+  scheduler: vercelQueues(),
+  handlers: {
+    hold: async (ctx, input) => {
+      ctx.state.held[input.offerId] = input.amount
+      await ctx.schedule.release({ offerId: input.offerId }, { delay: '1h' })
+    },
+    accept: (ctx, input) => {
+      if (ctx.state.held[input.offerId] === undefined) return
+      delete ctx.state.held[input.offerId]
+      // your payout; ctx.id is the idempotency key
+    },
+    release: (ctx, input) => {
+      if (ctx.state.held[input.offerId] === undefined) return
+      delete ctx.state.held[input.offerId]
+      // your refund; ctx.id is the idempotency key
+    },
+  },
+})
+```
+
+Held funds now have two futures, and both are handled: someone accepts
+the offer, or the hour passes and the funds release themselves. The
+deadline is durable: it outlives the invocation that armed it and any
+deploys in between.
+
+Scheduling requires the `scheduler` option. Adapters, delay limits, and
+delivery semantics are the session timers underneath; see
+[Timers and delays](/guides/timers).
+
+## Stale timers are no-ops
+
+When `accept` wins the race, the release timer still fires an hour
+later. It meets the same first-line guard the finalizer pattern already
+uses (`held[offerId] === undefined`) and does nothing. When the timer
+wins, a late `accept` meets that guard instead.
+
+There is no cancellation API, and the log records that the timer fired.
+Guarded delivery is the pattern: let the event land, read the state,
+return when it no longer applies. The guard that makes finalizers
+idempotent is the same guard that makes deadlines safe.
+
+## Identity and retries
+
+A timer's name defaults to the target event's name, scoped to the
+triggering message. A re-run of a crashed handler therefore addresses
+the same timer rather than arming a second one, and provider
+deduplication plus stable event ids fold duplicate deliveries into one
+append. Relative delays anchor to the triggering message's durable
+`createdAt`, so re-runs resolve the same due time.
+
+One handler run gets one timer per target event. To arm several toward
+the same event, name them apart:
+
+```ts
+// inside a handler:
+await ctx.schedule.release(
+  { offerId: 'offer-42' },
+  { delay: '30m', name: 'first-nudge' },
+)
+```
+
+## Scheduling is immediate
+
+:::warning
+Unlike `ctx.send`, `ctx.schedule` is not buffered. A timer lives at the
+provider, not in the log, so it cannot ride the handler's atomic
+commit: the call awaits provider acceptance right where it happens. A
+handler that schedules and then refuses has still armed the timer.
+Guarded delivery makes that safe (the stale timer fires into a no-op),
+but order handlers accordingly: guards and refusals first, `ctx.schedule`
+last.
+:::
+
+## From outside a handler
+
+The typed surface lives on handler contexts. To schedule from ordinary
+server code, use the instance's underlying session, which takes an
+explicit name, timing, and event:
+
+```ts
+// anywhere on the server:
+import { escrow } from '@/escrow'
+
+await escrow.actor('offer-42').session.schedule(
+  'expire-offer',
+  { at: new Date('2030-01-01T00:00:00Z') },
+  { type: 'release', payload: { offerId: 'offer-42' } },
+)
+```
+
+Root scheduling semantics apply (`{ at }` for retry-stable targets);
+see [Timers and delays](/guides/timers#schedule-from-ordinary-server-code).