experimental-a2 0.18.1 → 0.20.0

package/docs/schedulers/01-overview.mdx

@@ -0,0 +1,112 @@
+---
+title: Overview
+description: A clock for handler retries and timers.
+---
+
+```ts server/orders.ts
+import { createServer } from 'experimental-a2/server'
+import { redis } from 'experimental-a2/store-redis'
+import { vercelQueues } from 'experimental-a2/scheduler-vercel'
+import { orders } from '@/contracts'
+
+export const scheduler = vercelQueues()
+
+export const ordersServer = createServer({
+  contract: orders,
+  store: redis({ url: process.env.REDIS_URL }),
+  scheduler,
+  handlers: {
+    /* ... */
+  },
+})
+```
+
+```ts app/api/a2/scheduler/route.ts
+import { billingServer, ordersServer, scheduler } from '@/server'
+
+export const POST = scheduler.handler(ordersServer, billingServer)
+```
+
+A scheduler wakes sessions on a clock. It retries a handler that failed or
+whose process died, and it delivers [timers](/server/timers), whose delays must
+fit the [provider's limit](/server/timers#provider-limits). Share one
+scheduler across your servers and mount its route once, with every server it
+delivers to. `scheduler.handler(...)` checks those servers when the module
+loads, so a bad route fails at startup.
+
+| Scheduler | Use it for |
+| --- | --- |
+| [Vercel Queues](/schedulers/vercel-queues) | Apps on Vercel (recommended) |
+| [QStash](/schedulers/qstash) | A stable public URL, called from separate infrastructure |
+
+## Without a scheduler
+
+If no event type has a handler and nothing calls `session.schedule`, skip it.
+Events settle as they're appended, with no queue messages. That's a complete
+production setup for history, reducers, and live sync.
+
+With handlers but no scheduler, a session only wakes on a top-level append or
+an explicit `server.drain()`. Reads never wake it, so a session nobody writes
+to stays stuck. That's fine for internal tools that can heal on the next
+write. For production, add a scheduler.
+
+## More than one scheduler
+
+Servers with different scheduler instances need separate routes, even from the
+same adapter. Give each QStash instance its own `url`, and each Vercel Queues
+instance its own `topic` and trigger.
+
+## Dispatch in a fresh invocation
+
+`append` starts handlers in the same request and uses the scheduler as a
+watchdog. `append.dispatch` stores the event and hands its handlers to the
+queue instead:
+
+```ts app/api/imports/route.ts
+import { ordersServer } from '@/server'
+
+export async function POST(request: Request) {
+  const { orderId, shopId, items } = await request.json()
+  await ordersServer.session(orderId).append.dispatch({
+    id: `created:${orderId}`,
+    type: 'created',
+    payload: { shopId, items },
+  })
+  return Response.json({ accepted: true }, { status: 202 })
+}
+```
+
+It needs a scheduler and waits for the queue to accept the message. If that
+send fails, the event may already be stored; its explicit `id` makes a retry
+safe.
+
+## Deploys and rollbacks
+
+Queued work can reach a different deployment than the one that sent it. Keep
+event schemas compatible across deployments. Each adapter's page explains
+where its tasks go: [Vercel Queues](/schedulers/vercel-queues#deployments) and
+[QStash](/schedulers/qstash#deployments).
+
+:::warning
+Don't roll back to an A2 version without timer delivery while scheduled tasks
+are outstanding. An old route can acknowledge a scheduled append without
+writing its events. Rolling back past scheduled clears fails too: an old
+Vercel Queues route keeps failing the clear until retention ends, and an old
+QStash route moves it to QStash's dead-letter queue. Roll forward, or wait for
+those tasks to deliver first.
+:::
+
+## Send errors
+
+When a provider rejects a send, both adapters keep the provider's original
+error.
+
+- **Terminal:** a definite 4xx status or error, except 408, 409, 425, and 429.
+  The Vercel adapter also treats the SDK's `BadRequestError`,
+  `UnauthorizedError`, and `ForbiddenError` as terminal.
+- **Retryable:** 408, 409, 425, 429, 5xx, network failures, and errors with no
+  recognized status.
+- Vercel Queues' duplicate-message error counts as success.
+
+A2's durable AI tools use this classification. Direct `session.schedule()`
+calls still reject with the original error.

package/docs/schedulers/02-vercel-queues.mdx

@@ -0,0 +1,87 @@
+---
+title: Vercel Queues
+description: The recommended scheduler on Vercel.
+---
+
+```ts server/orders.ts
+import { createServer } from 'experimental-a2/server'
+import { redis } from 'experimental-a2/store-redis'
+import { vercelQueues } from 'experimental-a2/scheduler-vercel'
+import { orders } from '@/contracts'
+
+export const scheduler = vercelQueues()
+
+export const ordersServer = createServer({
+  contract: orders,
+  store: redis({ url: process.env.REDIS_URL }),
+  scheduler,
+  handlers: {
+    /* ... */
+  },
+})
+```
+
+```ts app/api/a2/scheduler/route.ts
+import { ordersServer, scheduler } from '@/server'
+
+export const POST = scheduler.handler(ordersServer)
+```
+
+```json vercel.json
+{
+  "functions": {
+    "app/api/a2/scheduler/route.ts": {
+      "experimentalTriggers": [
+        {
+          "type": "queue/v2beta",
+          "topic": "a2"
+        }
+      ]
+    }
+  }
+}
+```
+
+```package-install
+npm i @vercel/queue
+```
+
+The trigger is required. It connects the route to Vercel Queues and makes the
+function private, so only the queue can call it. Don't also expose the route
+publicly or wrap it in your own authentication.
+
+Messages are kept for seven days (Vercel Queues' default is 24 hours, and
+seven days is its maximum), so timers can be scheduled up to seven days out. A
+longer delay goes out as asked, and Vercel Queues refuses it.
+
+A drain delivery is acknowledged once its session settles or a later watchdog
+for it is stored, including when the drain fails after storing that watchdog.
+A drain that fails before then stays unacknowledged, so Vercel Queues
+redelivers it.
+
+## Options
+
+| Option | Default | |
+| --- | --- | --- |
+| `topic` | `'a2'` | must match the trigger's `topic`, and `[A-Za-z0-9_-]+` |
+| `deploymentId` | `VERCEL_DEPLOYMENT_ID` | which deployment receives tasks; see below |
+| `transport`, `clock` | the `@vercel/queue` client, the system clock | test seams for custom delivery |
+
+An injected `transport` receives the topic, the task, and send options, and
+owns its own provider configuration; `deploymentId` only configures the
+built-in client.
+
+## Deployments
+
+`deploymentId` applies to every task: retries, timers, and scheduled clears.
+Leave it out to deliver to the deployment that sent the task, pass an ID to
+target one deployment, or pass `null` to let Vercel pick. Every deployment that
+sends or receives must use the same setting.
+
+- **Tasks stay with their deployment.** Promoting a new deployment doesn't move
+  them, so older deployments keep receiving their own work until it's done or
+  expires. Upgrading doesn't fix an older deployment's route.
+- **`null` doesn't mean latest.** Vercel picks any eligible deployment, so every
+  one of them must use `deploymentId: null` and handle pending tasks.
+- **Changing the setting doesn't move queued tasks.** Keep the old deployments
+  running until those tasks finish.

package/docs/schedulers/03-qstash.mdx

@@ -0,0 +1,123 @@
+---
+title: QStash
+description: Signed HTTP delivery from Upstash, to a stable public URL.
+---
+
+```ts server/orders.ts
+import { createServer } from 'experimental-a2/server'
+import { qstash } from 'experimental-a2/scheduler-qstash'
+import { redis } from 'experimental-a2/store-redis'
+import { orders } from '@/contracts'
+
+export const scheduler = qstash()
+
+export const ordersServer = createServer({
+  contract: orders,
+  store: redis({ url: process.env.REDIS_URL }),
+  scheduler,
+  handlers: {
+    /* ... */
+  },
+})
+```
+
+```ts app/api/a2/scheduler/route.ts
+import { ordersServer, scheduler } from '@/server'
+
+export const POST = scheduler.handler(ordersServer)
+```
+
+```package-install
+npm i @upstash/qstash
+```
+
+Set `QSTASH_TOKEN`, `QSTASH_CURRENT_SIGNING_KEY`, and
+`QSTASH_NEXT_SIGNING_KEY`. In development you need none of them: A2 starts
+QStash's local server on the first publish. It needs `@upstash/qstash` 2.11.0
+or newer.
+
+The route checks `Upstash-Signature` before it touches the store and answers
+unsigned requests with 401. Delivery is at least once, so handler side effects
+need idempotency keys.
+
+## Callback URL
+
+QStash calls `/api/a2/scheduler`. An explicit `url` always wins; otherwise A2
+infers it:
+
+- **Vercel production:** `https://${VERCEL_PROJECT_PRODUCTION_URL}/api/a2/scheduler`.
+- **Vercel preview:** `https://${VERCEL_BRANCH_URL}/api/a2/scheduler`.
+- **Locally:** `http://localhost:${PORT ?? 3000}/api/a2/scheduler`, against
+  QStash's development server. `PORT` must be an integer from 1 through 65535.
+
+Pass `url` for anything else: production outside Vercel, a custom path or
+host, Docker networking, or a runtime without `process.env`. With an explicit
+`url` outside production, A2 doesn't start the development server: set
+`QSTASH_DEV`, or `QSTASH_URL` and credentials, yourself. An Edge runtime infers
+the local URL but must also start the development server itself.
+
+## Options
+
+| Option | Default | |
+| --- | --- | --- |
+| `url` | inferred, see above | the callback URL |
+| `token` | `QSTASH_TOKEN` | |
+| `currentSigningKey` | `QSTASH_CURRENT_SIGNING_KEY` | |
+| `nextSigningKey` | `QSTASH_NEXT_SIGNING_KEY` | |
+| `headers` | none | static headers on every callback |
+| `client` | a lazy `@upstash/qstash` client | your own configured client |
+| `retries` | QStash's default | retries per delivery; every attempt is billed |
+| `maxBodyBytes` | `1_048_576` (1 MiB) | the largest task A2 sends or accepts |
+| `transport`, `clock` | the `@upstash/qstash` client and receiver, the system clock | test seams for custom delivery |
+
+- **`headers`** are checked and copied when `qstash()` runs. A2 asks QStash to
+  redact every value from its dashboard and API, but QStash still stores and
+  delivers them. Names are case-insensitive. `Upstash-*`, `Content-Type`, HTTP
+  framing headers, and A2's Vercel identity headers are reserved.
+- **`client`** is the `publishJSON(...)` part of a configured `Client`, for its
+  endpoint, retry policy, or telemetry. It can't be combined with `token` or
+  `transport`. It receives callback credentials unredacted and must apply each
+  publish's redaction. Put callback credentials in `headers`, not on the
+  client.
+- **`maxBodyBytes`**: A2 reserves room for a task's retry metadata before the
+  first publish, so an accepted task never outgrows the limit. Raise it for a
+  larger paid-plan limit, and keep one value on every deployment that receives
+  the URL.
+- **`transport`** implements `publish(request)` and `verify(request)`. It must
+  keep the body, deliver every header, and apply every redaction.
+
+## How delivery works
+
+- The route returns 200 once a task is done, or once its follow-up is queued,
+  so each retry gets a fresh message and retry budget. That includes a drain
+  that fails after queueing its follow-up.
+- If the store is down (`STORE_UNAVAILABLE`) or not set up yet
+  (`STORE_NOT_CONFIGURED`, such as Postgres before its tables exist) before a
+  drain queues its follow-up, or during an append or clear task, the task moves
+  to a new message: 30 seconds later, four times longer each time, up to one
+  day.
+- A signed but malformed task, or one over `maxBodyBytes`, returns 489 with
+  `Upstash-NonRetryable-Error: true`. Unknown contracts, missing
+  configuration, and other failures return an error, so QStash retries.
+- If QStash can't reach the route at all, nothing queues a follow-up: watch
+  QStash's dead-letter queue and redrive from it.
+- Delays are capped by your plan: 7 days on free plans and 1 year on
+  usage-based plans, with no fixed cap on fixed plans. Leave a second of
+  margin at the cap.
+
+## Protected previews
+
+For an inferred preview URL, each publish forwards the invocation's Vercel
+OIDC token as `x-vercel-trusted-oidc-idp-token`, redacted, so a Vercel Trusted
+Sources rule can let the first delivery through. This is best effort: a
+missing or expiring token falls back to a plain publish, and retries reuse the
+stored token, which may have expired. When every protected delivery must get
+through, pass an automation bypass in `headers` instead. Signature checks still
+apply after Vercel's.
+
+## Deployments
+
+Inferred production and preview URLs are moving aliases, so a pending task can
+reach a later deployment. Keep tasks and event schemas compatible across
+deployments, and keep the same `maxBodyBytes` on all of them: a lower value
+rejects tasks that an earlier deployment accepted.

package/docs/schedulers/meta.ts

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

package/docs/server/01-handlers.mdx

@@ -24,7 +24,7 @@ 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,
+[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.
@@ -194,7 +194,34 @@ records completion runs the handler again.
 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](/server/production#3-when-an-event-dead-letters).
+[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 }`.

package/docs/server/02-timers.mdx

@@ -34,7 +34,7 @@ export const ordersServer = createServer({
 
 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).
+[mount it once](/schedulers/overview).
 
 `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
@@ -103,7 +103,7 @@ 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).
+See [Deploys and rollbacks](/schedulers/overview#deploys-and-rollbacks).
 
 ## Stale timers
 
@@ -119,7 +119,7 @@ handler schedule the next one.
 
 | Adapter | Maximum one-shot delay |
 | --- | --- |
-| Vercel Queues | 6 days |
+| Vercel Queues | 7 days |
 | QStash free | 7 days |
 | QStash usage-based | 1 year |
 | QStash fixed | no fixed maximum |

package/docs/server/06-guarantees.mdx

@@ -71,7 +71,7 @@ up to two seconds for the watchdog send, never for handlers. A failed arm
 records `a2.append.armed = false` on the trace. Handler appends and returned
 events join the running drain and add no arm.
 
-[`append.dispatch`](/server/production#dispatch-in-a-fresh-invocation) skips
+[`append.dispatch`](/schedulers/overview#dispatch-in-a-fresh-invocation) skips
 the inline drain and hands the work to the scheduler instead.
 
 An event type without a handler settles in the append transaction. It starts
@@ -108,8 +108,11 @@ attempt takes its claim over. Ten failed attempts dead-letter the event: later
 events in its lane stay blocked, while unlaned events and other lanes continue.
 A crash costs every event it interrupts one attempt, so a session whose work
 keeps outrunning its function dead-letters: bound its fan-out, or put work that
-waits on the same resource in one lane. The event waits until you
-[retry or skip it](/server/production#3-when-an-event-dead-letters) with
+waits on the same resource in one lane. A `NonRetriableError`, or a returned
+batch the store refuses because it reuses an event id, dead-letters the event
+on that first attempt instead: a retry would fail the same way. The event
+waits until you
+[retry or skip it](/server/handlers#resolve-a-dead-letter) with
 `session.redrive()`.
 
 ## Limits

package/docs/stores/01-overview.mdx

@@ -0,0 +1,37 @@
+---
+title: Overview
+description: Where A2 keeps your session histories.
+---
+
+```ts server/orders.ts
+import { createServer } from 'experimental-a2/server'
+import { redis } from 'experimental-a2/store-redis'
+import { orders } from '@/contracts'
+
+export const ordersServer = createServer({
+  contract: orders,
+  store: redis({ url: process.env.REDIS_URL }),
+  handlers: {
+    /* ... */
+  },
+})
+```
+
+| Store | Use it for |
+| --- | --- |
+| [Redis](/stores/redis) | Production (recommended) |
+| [Redis over HTTP](/stores/redis-http) | Production, when your provider only offers a REST API |
+| [Postgres](/stores/postgres) | Production |
+| [SQLite](/stores/sqlite) | Development: the default |
+| [Memory](/stores/memory) | Tests: the default when `NODE_ENV=test` |
+
+When you omit `store`, development gets SQLite, so state survives `next dev`
+restarts, and tests get memory. Production has no default, on purpose: the
+server throws `STORE_NOT_CONFIGURED` at startup rather than write events to a
+filesystem that evaporates.
+
+A store holds A2's session histories. It doesn't connect A2 to your
+application tables; see
+[Sessions and your database](/contract/sessions#sessions-and-your-database).
+
+Servers with handlers or timers also need a [scheduler](/schedulers/overview).

package/docs/stores/02-redis.mdx

@@ -0,0 +1,49 @@
+---
+title: Redis
+description: The recommended production store. Live streams are pushed, not polled.
+---
+
+```ts server/orders.ts
+import { createServer } from 'experimental-a2/server'
+import { redis } from 'experimental-a2/store-redis'
+import { orders } from '@/contracts'
+
+export const ordersServer = createServer({
+  contract: orders,
+  store: redis({ url: process.env.REDIS_URL }),
+  handlers: {
+    /* ... */
+  },
+})
+```
+
+```package-install
+npm i ioredis
+```
+
+Works on a single Redis instance and on non-cluster providers such as Upstash,
+which is durable by default (use its TCP `rediss://` URL). There's nothing to
+set up: A2 creates its keys as it writes.
+
+## Options
+
+| Option | |
+| --- | --- |
+| `url` | creates an `ioredis` client |
+| `client` | your own `ioredis` client instead |
+| `keyPrefix` | isolates several apps on one Redis. Default `'a2'` |
+| `clock`, `ids` | test seams for timestamps and generated event ids |
+
+## How it works
+
+- Each session is a Redis Stream.
+- Every write publishes a wake-up, so live streams are push-driven, and
+  connections scale with your processes, not with your viewers.
+- A wake-up is disposable: a safety re-read recovers a lost one within ten
+  seconds.
+
+## Cost per command
+
+On providers that bill per command, such as Upstash, appending an event with a
+handler and running it takes 24 commands, and an idle live stream takes 6 a
+minute.

package/docs/stores/03-redis-http.mdx

@@ -0,0 +1,56 @@
+---
+title: Redis over HTTP
+description: The same Redis store over fetch, for providers with only a REST API.
+---
+
+```ts server/orders.ts
+import { createServer } from 'experimental-a2/server'
+import { redisHttp } from 'experimental-a2/store-redis-http'
+import { orders } from '@/contracts'
+
+const url = process.env.UPSTASH_REDIS_REST_URL
+const token = process.env.UPSTASH_REDIS_REST_TOKEN
+if (!url || !token) throw new Error('set the Upstash REST URL and token')
+
+export const ordersServer = createServer({
+  contract: orders,
+  store: redisHttp({ url, token }),
+  handlers: {
+    /* ... */
+  },
+})
+```
+
+Stores sessions exactly like [Redis](/stores/redis), with no client dependency
+and nothing to set up. Use it when your provider only offers a REST API.
+
+:::warning
+Live streams trust the messages on the store's `:notify` channels. Browsers
+never hold Redis credentials, so they can't reach those channels. The risk is a
+credential that can publish but not write, such as a token another service
+uses: it could add or hide events in live views. Grant publish access only to
+credentials that can also write the store.
+:::
+
+## Options
+
+| Option | |
+| --- | --- |
+| `url`, `token` | your provider's REST endpoint and token |
+| `keyPrefix` | isolates several apps on one Redis. Default `'a2'` |
+| `clock`, `ids` | test seams for timestamps and generated event ids |
+
+## Live updates
+
+- Live events and presence use Upstash's HTTP `SUBSCRIBE` endpoint, with the
+  same URL and token. Each active channel holds one outbound HTTP subscription
+  per store instance, shared by its viewers and closed when the last one
+  leaves.
+- Writes publish their wake-ups in the same Redis script as the append. A
+  rejected notification doesn't fail the write.
+- Idle streams re-read every ten seconds to recover a missed notification.
+  Subscriptions reconnect on their own and catch up from the event cursor.
+- After a reconnect, A2 re-reads presence and clears fields deleted during the
+  gap, so presence may repeat its latest values.
+- If `SUBSCRIBE` answers 404, 405, or 501, the store polls instead, every 25ms
+  while busy and up to every two seconds when idle. Other errors stay errors.