experimental-a2 0.8.1 → 0.10.0

package/docs/actors/04-routes.mdx

@@ -0,0 +1,352 @@
+---
+title: Routes, clients, and React
+description: "One route serves an instance: GET streams live state, POST answers calls. Authorize per operation, project per mount, and mount it in React with one hook."
+---
+
+## The actor for this page
+
+A vault with one internal field, so the projection section below has
+something to hide:
+
+```ts vault.ts
+import { NonRetriableError } from 'experimental-a2'
+import { actor } from 'experimental-a2/actor'
+
+interface Vault {
+  state: {
+    balance: number
+    /** Internal bookkeeping; not for subscribers. */
+    audit: string[]
+  }
+  events: {
+    deposit: { amount: number }
+    withdraw: { amount: number }
+  }
+}
+
+export type VaultState = Vault['state']
+
+export const vault = actor<Vault>({
+  name: 'vault',
+  state: { balance: 0, audit: [] },
+  handlers: {
+    deposit: (ctx, input) => {
+      ctx.state.balance += input.amount
+      ctx.state.audit.push(`deposit ${input.amount}`)
+    },
+    withdraw: (ctx, input) => {
+      if (ctx.state.balance < input.amount) {
+        throw new NonRetriableError('insufficient funds')
+      }
+      ctx.state.balance -= input.amount
+      ctx.state.audit.push(`withdraw ${input.amount}`)
+    },
+  },
+})
+```
+
+## The route
+
+`handle.fetch` serves one instance over HTTP. Your route authenticates
+and picks the instance; the library serves the rest.
+
+```ts app/vault/[vaultId]/route.ts
+import { vault } from '@/vault'
+
+async function respond(
+  request: Request,
+  context: { params: Promise<{ vaultId: string }> },
+): Promise<Response> {
+  const { vaultId } = await context.params
+  // here's where you'd do auth, or any other checks
+  return vault.actor(vaultId).fetch(request)
+}
+
+export const GET = respond
+export const POST = respond
+```
+
+`GET` is the live stream: a server-sent events response of the
+instance's state commits, resumed after the `index` query parameter,
+with heartbeats. The stream carries state and nothing else: subscribers
+see what the actor is, never other callers' inputs, and a refusal
+answers only its caller. The full mailbox stays server-side.
+
+`POST` is the call lane. The body names a declared event:
+
+```json
+{ "event": "deposit", "input": { "amount": 100 }, "messageId": "m-1" }
+```
+
+The response is the answer: `{ state, index }` on success, `409` with
+the refusal's message when the handler says no, `400` for an undeclared
+event. `messageId` is optional; send one to make retrying the request
+idempotent.
+
+## Authorize
+
+`authorize` is per-operation policy, checked before any write or
+subscription. Authentication (who is asking) stays in your route;
+`authorize` decides whether this operation is allowed.
+
+```ts
+// app/vault/[vaultId]/route.ts, now with per-operation policy:
+import { vault } from '@/vault'
+
+export async function POST(
+  request: Request,
+  context: { params: Promise<{ vaultId: string }> },
+): Promise<Response> {
+  const { vaultId } = await context.params
+  return vault.actor(vaultId).fetch(request, {
+    authorize: (operation) =>
+      operation.type === 'call' && operation.event !== 'withdraw',
+  })
+}
+```
+
+The operation is a discriminated union: `{ type: 'stream', id,
+startAfter }` for subscriptions, `{ type: 'call', id, event, input,
+messageId? }` for calls. Returning `false` answers `403`.
+
+## Views: what each mount shows
+
+State can be mixed-audience: internal bookkeeping next to public
+fields. The definition stays audience-blind; audiences are a route
+concern, like auth. A `view` is a request-time projection applied to
+everything that mount serves: every state frame on the stream and
+every call answer (the two must agree, or the call lane would leak
+what the stream hides).
+
+```ts
+// app/vault/[vaultId]/public/route.ts, a projected mount of the same actor:
+import { vault } from '@/vault'
+
+export async function GET(
+  request: Request,
+  context: { params: Promise<{ vaultId: string }> },
+): Promise<Response> {
+  const { vaultId } = await context.params
+  return vault.actor(vaultId).fetch(request, {
+    view: (state) => ({ balance: state.balance }),
+  })
+}
+```
+
+Different routes project the same actor differently: an admin mount
+with no view sees everything, the public mount above hides `audit`.
+Per-viewer views need no extra machinery, because the route already
+holds the identity; a closure does it
+(`view: (state) => ({ ...visible, mine: state.perUser[user.id] })`).
+View output holds to the same plain-JSON floor as state itself.
+
+Views are for internal-but-not-secret fields. Secrets do not belong in
+state at all: state commits are log rows, and the log is forever. Keep
+secrets outside, pass references, resolve them inside handlers.
+
+## Any client
+
+`createActorClient` is the typed call surface over that route's `POST`
+lane. It works anywhere: browsers, other frameworks, other servers.
+
+```ts
+// in the browser, or any client at all:
+import {
+  ActorRefusedError,
+  createActorClient,
+} from 'experimental-a2/actor/client'
+import type { vault } from '@/vault'
+
+const savings = createActorClient<typeof vault>({ api: '/vault/savings' })
+
+try {
+  const { state } = await savings.call.deposit({ amount: 100 })
+  // state is the answer: the fold after this deposit
+} catch (error) {
+  if (error instanceof ActorRefusedError) {
+    // the server's refusal, revived with its message
+  }
+}
+```
+
+The import of `vault` is type-only, so it is erased at build time: the
+server module never enters a client bundle. On a view-projected mount,
+pass the projected shape as the second type argument
+(`createActorClient<typeof vault, PublicVault>`) so answers carry it.
+
+## React
+
+One hook. The server component hands down the first fold, the hook
+keeps it live and exposes the same typed calls.
+
+```tsx app/vault/[vaultId]/page.tsx
+import { vault } from '@/vault'
+import { VaultClient } from './vault-client'
+
+export default async function VaultPage({
+  params,
+}: {
+  params: Promise<{ vaultId: string }>
+}) {
+  const { vaultId } = await params
+  const initial = await vault.actor(vaultId).state()
+  return <VaultClient vaultId={vaultId} initial={initial} />
+}
+```
+
+```tsx app/vault/[vaultId]/vault-client.tsx
+'use client'
+import { useActor } from 'experimental-a2/actor/react'
+import type { ActorSnapshot } from 'experimental-a2/actor/react'
+import type { vault, VaultState } from '@/vault'
+
+export function VaultClient({
+  vaultId,
+  initial,
+}: {
+  vaultId: string
+  initial: ActorSnapshot<VaultState>
+}) {
+  const { state, call, connection } = useActor<typeof vault>({
+    api: `/vault/${vaultId}`,
+    id: vaultId,
+    initial,
+  })
+
+  return (
+    <div>
+      <p>
+        Balance: {state.balance}
+        {connection.status === 'live' ? '' : ' (reconnecting)'}
+      </p>
+      <button onClick={() => void call.deposit({ amount: 25 })}>
+        Deposit $25
+      </button>
+    </div>
+  )
+}
+```
+
+What the hook gives you:
+
+- **`state`**: the live view. Every commit streams in and replaces it;
+  the fold is library code, so no reducers, schemas, or contracts
+  appear in browser code.
+- **`call`**: the same typed surface as `createActorClient`, because it
+  is one; `useActor` is a thin React wrapper over the client primitive
+  and the stream.
+- **`index`**: the stream frontier, and **`events`**: the state-commit
+  feed this browser has observed, for activity-feed UI.
+- **`connection`**: the same discriminated union as
+  [`useSession`](/guides/react#the-client-component), heartbeat
+  watchdog included.
+
+Live, not optimistic. Handlers are server code deciding against
+serialized fresh state, so there is nothing correct for the browser to
+apply early; a local guess would be wrong exactly when the actor
+matters. If a control needs pending UI, `await call.deposit(...)` is a
+promise like any other.
+
+On a view-projected mount, pass the projected shape as the second type
+argument (`useActor<typeof vault, PublicVault>`); `initial`, `state`,
+and the call answers all carry it.
+
+## Presence
+
+Who is here, live: cursors, names, viewer counts. Presence is
+ephemeral audience state. It replicates to the instance's subscribers
+and expires; it never enters the log, and handlers cannot see it (an
+actor decides from its log, never from who is watching).
+
+Declare the vocabulary in the protocol as types, and arm the wire with
+`presence: true`:
+
+```ts board.ts
+import { actor } from 'experimental-a2/actor'
+
+interface Board {
+  state: { strokes: number }
+  events: { draw: { path: string } }
+  presence: { cursor: { x: number; y: number }; name: string }
+}
+
+export const board = actor<Board>({
+  name: 'board',
+  state: { strokes: 0 },
+  presence: true,
+  handlers: {
+    draw: (ctx) => {
+      ctx.state.strokes += 1
+    },
+  },
+})
+```
+
+The route does not change: the same `GET` stream interleaves presence
+updates between state commits, and the same `POST` lane accepts
+presence announcements. In React, pass a `participant` identity and
+use the map:
+
+```tsx app/board/[boardId]/board-client.tsx
+'use client'
+import { useActor } from 'experimental-a2/actor/react'
+import type { ActorSnapshot } from 'experimental-a2/actor/react'
+import type { board } from '@/board'
+
+export function BoardClient({
+  boardId,
+  initial,
+  user,
+}: {
+  boardId: string
+  initial: ActorSnapshot<{ strokes: number }>
+  user: string
+}) {
+  const { presence, setPresence } = useActor<typeof board>({
+    api: `/board/${boardId}`,
+    id: boardId,
+    initial,
+    participant: user,
+  })
+
+  return (
+    <div
+      onPointerMove={(event) =>
+        setPresence({ cursor: { x: event.clientX, y: event.clientY } })
+      }
+    >
+      {Object.keys(presence).length} here
+    </div>
+  )
+}
+```
+
+`setPresence` is fire-and-forget: throttled on the way out, resent
+after a reconnect, `null` clears a field. The map holds each
+participant's latest fields with their stamps; how long a value stays
+painted is render logic, decided against `at`.
+
+Three guards stand where presence enters, and none of them is a
+schema:
+
+- **Types**: the protocol types `setPresence` and the map, so honest
+  clients cannot send the wrong shape.
+- **The floor**: the library rejects values that are not plain JSON
+  trees, values over 8 KB, and object-plumbing field names.
+- **`authorize`**: every announcement arrives as
+  `{ type: 'presence', id, participant, values }` before it is
+  accepted. Clamp, verify the participant matches the authenticated
+  user, or rate-limit here.
+
+What no guard does is make peer values trustworthy. Presence is
+authored by whoever holds a connection: render it like user input.
+
+## The session wire underneath
+
+`handle.fetch` serves the actor's two lanes and nothing else. When you
+want the raw session protocol instead (the full event feed, pushes,
+presence, the `ws` transport), the definition exposes the underlying
+server: mount `def.server.fetch` and use the core
+[client](/guides/react) against it. That wire shows the whole mailbox
+to its subscribers, inputs included, so reserve it for trusted
+audiences.

package/docs/actors/meta.ts

@@ -0,0 +1 @@
+export default { order: 4 }

package/docs/concepts/meta.ts

@@ -0,0 +1 @@
+export default { order: 2 }

package/docs/guides/10-transports.mdx

@@ -13,20 +13,33 @@ it:
 ```ts
 // in a 'use client' session module:
 api: '/api/order-events'
+api: (sessionId) => `/api/orders/${encodeURIComponent(sessionId)}/events`
 api: { type: 'http', push: '/api/order-push', stream: '/api/order-stream' }
 api: { type: 'ws', url: '/api/order-events' }
 ```
 
-- **The string** is the default and the recommendation: one route
-  serving GET (SSE stream and history) and POST (push).
+- **One route** is the default and the recommendation. Pass a fixed URL or a
+  session URL function. It serves GET (SSE stream and history) and POST (push).
 - **`http` split** serves the two verbs from separate routes. Use it
   when platform duration limits differ per verb.
-- **`ws`** rides streams, pushes, and presence over one multiplexed
-  WebSocket. One socket carries every session of the client.
+- **`ws`** rides streams, pushes, and presence over WebSocket. It opens
+  one socket per session. Set `multiplex: true` on the client and
+  `multiplexWebSocket: true` on the route to share one socket across the
+  client's sessions.
 
 A split socket is unrepresentable on purpose. The socket is one
 connection in both directions.
 
+Every session-scoped URL may instead be a `(sessionId) => string` function.
+A2 resolves it for each request or reconnect, then adds its standard query
+parameters. This supports paths scoped to a session. Encode the ID when placing
+it in a path segment. The function chooses a route, not authority: if a path or
+connection token is scoped to one session, `authorize` must compare that scope
+to `operation.sessionId`. Bind URL tokens to the same session and keep them
+short-lived because URLs can appear in infrastructure logs. Multiplexed
+WebSockets take one plain URL because the connection carries more than one
+session.
+
 One wire is missing from `ws` by design: the history lane.
 [`loadHistory`](/guides/react#the-client-component) is a bounded cold
 read and rides plain HTTP. On a `ws` API it throws a `TypeError`.
@@ -103,22 +116,58 @@ export function GET(request: Request): Promise<Response> {
 }
 ```
 
-The socket is multiplexed. Subscribe frames open per-session lanes,
-each resuming from its own frontier. Every down frame carries its
-`sessionId`; pushes and presence route by it. One heartbeat and one
-connection serve all of the client's sessions.
+The socket is bound to the `sessionId` in its upgrade URL. The route
+authorizes that session before upgrading, and frames cannot select a
+different session afterward. Each connected session has its own socket.
+
+Authenticate the physical upgrade before calling `server.fetch`. For browser
+sockets authenticated by cookies, validate the request's `Origin` too. A
+WebSocket handshake does not use a CORS preflight.
+Then pass `authorize` to check the session stream and every push or
+presence frame. There is no separate upgrade operation: request policy
+belongs to the route, while A2 operation policy belongs to `authorize`.
+
+To multiplex, opt in on both sides:
+
+```ts app/api/multiplexed-order-events/route.ts
+import { experimental_upgradeWebSocket } from '@vercel/functions'
+import { ordersServer } from '@/server/orders'
+
+export function GET(request: Request): Promise<Response> {
+  return ordersServer.fetch(request, {
+    multiplexWebSocket: true,
+    upgradeWebSocket: (attach) =>
+      experimental_upgradeWebSocket(attach, {
+        maxPayload: 4 * 1024 * 1024,
+      }),
+  })
+}
+```
+
+```ts app/orders/multiplexed-session.ts
+'use client'
+import { createClient } from 'experimental-a2/client'
+import { ordersReducer } from '@/reducer'
+
+export const ordersClient = createClient({
+  reducer: ordersReducer,
+  api: {
+    type: 'ws',
+    url: '/api/multiplexed-order-events',
+    multiplex: true,
+  },
+})
+```
 
-Authenticate the physical upgrade before calling `server.fetch`.
-Then pass `authorize` to check every session subscribe and every push
-or presence frame. There is no separate upgrade operation: request
-policy belongs to the route, while A2 operation policy belongs to
-`authorize`.
+Only enable multiplexing when the request's authentication context may
+open more than one session and `authorize` checks each supplied session
+ID. Subscribe frames open the lanes after the physical upgrade.
 
-A denied subscribe receives an `unsubscribed` notice and leaves other
-sessions connected. A denied event push receives a non-retryable
-`FORBIDDEN` ack. Denied presence is silently dropped because presence
-is fire-and-forget and repaints on the next update. Failed presence
-authorization is dropped the same way and leaves the socket connected.
+On a multiplexed socket, a denied subscribe receives an `unsubscribed`
+notice and leaves other sessions connected. On either socket shape, a
+denied event push receives a non-retryable `FORBIDDEN` ack. Denied
+presence is silently dropped because presence is fire-and-forget and
+repaints on the next update.
 
 A2 reads the platform's ambient invocation deadline and closes the
 socket cleanly before it. `waitUntil` and deadline discovery remain
@@ -148,10 +197,11 @@ shared above the wire seam.
 
 ## Lifecycle
 
-When a socket closes, the client reconnects with backoff, re-subscribes
-every session at its own frontier, receives fresh presence snapshots,
-and re-sends its own latest presence values. Event pushes keep their
-client-generated ids, so retry remains idempotent.
+When a socket closes, the client reconnects with backoff at the current
+frontier, receives a fresh presence snapshot, and re-sends its own latest
+presence values. A multiplexed socket re-subscribes every active session
+at its own frontier. Event pushes keep their client-generated ids, so
+retry remains idempotent.
 
 SSE and WebSocket are transport choices, not different consistency
 models. Both resume from the durable event frontier and treat presence

package/docs/guides/meta.ts

@@ -0,0 +1 @@
+export default { order: 3 }

package/docs/index.mdx

@@ -281,6 +281,9 @@ public package entry points. See [Complete examples](/guides/examples).
   <Card title="A2 and your database" href="/guides/application-data" icon="database">
     Decide what belongs in a session and what belongs in ordinary tables.
   </Card>
+  <Card title="Actors" href="/actors/introduction" icon="boxes">
+    Durable objects on the log: typed state, one message at a time.
+  </Card>
   <Card title="Complete examples" href="/guides/examples" icon="code">
     Read or copy the standalone Next.js playground included with the package.
   </Card>

package/docs/reference/01-api.mdx

@@ -199,6 +199,7 @@ server.fetch(
     upgradeWebSocket?: (
       attach: (socket: A2Socket) => void,
     ) => Response | Promise<Response>
+    multiplexWebSocket?: boolean
   },
 ): Promise<Response>
 
@@ -307,13 +308,20 @@ export function GET(request: Request): Promise<Response> {
 }
 ```
 
-Authenticate the physical WebSocket GET before calling `server.fetch`. Then
-use `authorize` for each session subscribe and each event or presence push.
-There is no WebSocket-upgrade operation in `A2Operation`. A denied subscribe
-receives `unsubscribed` and does not affect other sessions. A denied event push
-receives a `FORBIDDEN` ack. Denied presence is silently dropped because it is
-fire-and-forget. Failed presence authorization is dropped the same way and does
-not disconnect unrelated sessions on the multiplexed socket.
+By default, the `sessionId` and `index` query parameters bind one session to the
+socket. A2 authorizes the stream before upgrading. Frames on that socket cannot
+select another session.
+
+Set `multiplexWebSocket: true` here and `multiplex: true` in the client's `ws`
+API to share one socket.
+Authenticate the physical WebSocket GET before calling `server.fetch`. Validate
+`Origin` too when browser cookies authenticate it; WebSocket handshakes do not
+use a CORS preflight. Use `authorize` for each session subscribe and each event
+or presence push. Only enable multiplexing when that request context may access
+every session accepted by `authorize`. A denied subscribe receives
+`unsubscribed` and does not affect other sessions. A denied event push receives
+a `FORBIDDEN` ack. Denied presence is silently dropped because it is
+fire-and-forget.
 
 SSE and WebSocket lifetimes use the platform's ambient invocation deadline.
 A2 also uses the platform's ambient `waitUntil` capability for background work.
@@ -674,8 +682,8 @@ session.stream(options: {
 
 A live feed of the session's events. `startAfter` is a non-negative safe integer;
 `startAfter: 20` begins with event 21.
-Server-side only; `server.fetch` exposes it over SSE, and over the multiplexed
-socket when `upgrade` is set. Subscribing never dispatches handlers.
+Server-side only; `server.fetch` exposes it over SSE and WebSocket. Subscribing
+never dispatches handlers.
 
 With `presence: true`, the feed yields one `PresenceSnapshot` first:
 `{ snapshot }`, the current pruned map with each field's own `value`,
@@ -1201,11 +1209,21 @@ createClient(options: {
 }): A2Client
 
 type ClientApi =
-  | string // one route: GET SSE stream + POST push
-  | { type: 'http'; push: string; stream: string } // split routes
-  | { type: 'ws'; url: string } // one socket, both directions
+  | SessionUrl // one route: GET SSE stream + POST push
+  | { type: 'http'; push: SessionUrl; stream: SessionUrl }
+  | { type: 'ws'; url: SessionUrl; multiplex?: false }
+  | { type: 'ws'; url: string; multiplex: true }
+
+type SessionUrl = string | ((sessionId: string) => string)
 ```
 
+A `SessionUrl` function runs for each HTTP request or WebSocket connection.
+Use it for session-specific paths. A2 still adds its `sessionId` and read-bound
+query parameters. The function does not authorize that ID. Bind any path scope
+or URL token to `operation.sessionId` in `authorize`; keep URL tokens short-lived
+because URLs can appear in infrastructure logs. A multiplexed WebSocket URL is
+a string because its connection carries more than one session.
+
 The framework-agnostic session client `experimental-a2/react` is built on: the SSE
 subscription with frontier resume and reconnection, the optimistic push
 queue with ack/rollback, and the local fold. `client.session(id, {

package/docs/reference/02-errors.mdx

@@ -58,6 +58,39 @@ contains the same id twice, and an id that was already used in a
 *different* session (event ids are globally unique). In every case,
 nothing is written.
 
+## NonRetriableError
+
+The second exported error class. Throw it (or a subclass, matched by
+`instanceof`) from a handler when the failure is deterministic: the
+event dead-letters immediately instead of consuming the ten-failure
+retry budget, because a guard that refuses this attempt will refuse
+every retry identically. Any other thrown error keeps the ordinary
+retry contract.
+
+```ts
+import { z } from 'zod'
+import * as a2 from 'experimental-a2'
+import { NonRetriableError } from 'experimental-a2'
+import { createServer } from 'experimental-a2/server'
+
+const orders = a2.contract({
+  name: 'orders',
+  events: { created: z.object({ chargeable: z.boolean() }) },
+})
+
+export const ordersServer = createServer({
+  contract: orders,
+  handlers: {
+    created: async ({ event }) => {
+      if (!event.payload.chargeable) {
+        throw new NonRetriableError('this order cannot be charged')
+      }
+      // transient failures below retry as usual
+    },
+  },
+})
+```
+
 ## What append never throws for
 
 - **A failing handler.** Appends always land; handler failures are retried

package/docs/reference/meta.ts

@@ -0,0 +1 @@
+export default { order: 5 }

package/examples/playground/app/page.tsx

@@ -6,7 +6,7 @@ export default function HomePage(): ReactNode {
     <article>
       <h1>A durable event log, live in your browser</h1>
       <p className="lede">
-        Seven small demos, one model: append an event, let a handler react, fold
+        Eight small demos, one model: append an event, let a handler react, fold
         the log into a view — on the server for the first paint, in the browser
         for every moment after.
       </p>
@@ -64,6 +64,15 @@ export default function HomePage(): ReactNode {
             under a fresh claim.
           </p>
         </Link>
+        <Link className="card" href="/vault">
+          <h2>Vault (actor)</h2>
+          <p>
+            A durable actor: send messages to one vault's mailbox, watch it
+            process them one at a time against its state — serialized
+            read-modify-write, refusals as answers, and the whole transcript in
+            the log. Built on <code>experimental-a2/actor</code>.
+          </p>
+        </Link>
         <Link className="card" href="/counter">
           <h2>Counter</h2>
           <p>

package/examples/playground/app/vault/[vaultId]/route.ts

@@ -0,0 +1,19 @@
+/**
+ * The vault's ingress — the actor mirror of `server.fetch`: your route
+ * authenticates and picks the instance, `handle.fetch` serves the rest
+ * (GET → the state-plane SSE, POST → the call lane).
+ */
+import { vault } from '../server'
+
+async function respond(
+  request: Request,
+  context: { params: Promise<{ vaultId: string }> },
+): Promise<Response> {
+  const { vaultId } = await context.params
+  // here's where you'd authenticate; per-operation policy goes in
+  // fetch's { authorize } option
+  return vault.actor(vaultId).fetch(request)
+}
+
+export const GET = respond
+export const POST = respond

package/examples/playground/app/vault/page.tsx

@@ -0,0 +1,12 @@
+import type { ReactNode } from 'react'
+import { vault } from './server'
+import { VaultClient } from './vault-client'
+
+export const dynamic = 'force-dynamic'
+
+const VAULT_ID = 'shared'
+
+export default async function VaultPage(): Promise<ReactNode> {
+  const initial = await vault.actor(VAULT_ID).state()
+  return <VaultClient vaultId={VAULT_ID} initial={initial} />
+}