experimental-a2 0.19.0 → 0.21.1

package/docs/server/05-production.mdx

@@ -1,323 +0,0 @@
----
-title: Production
-description: Choose a durable store, add a scheduler for recovery and timers, and know what to do when an event dead-letters.
----
-
-## 1. Choose a store
-
-```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: {
-    /* ... */
-  },
-})
-```
-
-| Entry point | Backend | Use it for |
-| --- | --- | --- |
-| `experimental-a2/store-redis` | Redis | Production (recommended) |
-| `experimental-a2/store-redis-http` | Redis over a REST API | Production |
-| `experimental-a2/store-postgres` | Postgres | Production |
-| `experimental-a2/store-sqlite` | SQLite | Development: the default, at `.a2/dev.db` |
-| `experimental-a2/store-memory` | In-memory | Tests: the default when `NODE_ENV=test` |
-
-When you omit `store`, development gets SQLite (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.
-
-The store holds A2's session histories. It does not connect A2 to your
-application tables; see [Sessions and your database](/contract/sessions#sessions-and-your-database).
-
-### Redis (recommended)
-
-`redis({ url })` from `experimental-a2/store-redis` stores each session as a
-Redis Stream and streams push-natively, so connections scale with your
-processes, not your audience. `ioredis` is an optional peer dependency; pass
-`url` or inject a client. It works on single instances and non-cluster
-providers such as Upstash, where durability is on by default.
-
-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. See
-[`experimental-a2/store-redis`](/reference/adapters#experimental-a2store-redis)
-for how live streams recover a lost wake-up.
-
-When only a REST API is available, `redisHttp({ url, token })` from
-`experimental-a2/store-redis-http` speaks the same storage over `fetch`, with
-no client dependency or extra setup. Live events and presence use Upstash's
-HTTP `SUBSCRIBE` endpoint with the same URL and token. If that endpoint answers
-404, 405, or 501, the store polls instead; other errors stay errors. See
-[`experimental-a2/store-redis-http`](/reference/adapters#experimental-a2store-redis-http)
-for its subscriptions, reconnects, and fallback.
-
-:::warning
-`redisHttp` 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 Redis 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.
-:::
-
-### Postgres
-
-Any Postgres works: Neon, Supabase, RDS, or your own box, including
-transaction-mode poolers. `pg` is an optional peer dependency. Pass
-`connectionString`, or inject your own pool as `client`; an injected pool's
-platform lifecycle is yours to manage.
-
-Live streams poll by default, backing off when a session goes quiet. For
-native notifications, also pass `listenConnectionString`: a direct connection
-to the same database. It installs notification triggers on A2's event and
-presence tables, which stay installed and also cover writes from instances
-without the option. Stores in one runtime share a listener, but every
-serverless instance opens its own direct connection, so leave connection
-headroom. See
-[`experimental-a2/store-postgres`](/reference/adapters#experimental-a2store-postgres)
-for live-stream latency and recovery.
-
-## 2. Add a scheduler for handlers and timers
-
-The scheduler puts a clock on recovery and on [timers](/server/timers).
-Vercel Queues is the recommended default on Vercel. QStash delivers over HTTP
-from separate infrastructure. Either adapter carries recovery and
-`session.schedule` tasks through one route. Scheduled delays must fit the
-[provider's limit](/server/timers#provider-limits).
-
-### Vercel Queues (recommended)
-
-```ts
-// server/orders.ts, now with a scheduler:
-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: {
-    /* ... */
-  },
-})
-```
-
-`@vercel/queue` is a peer dependency. Share one scheduler instance across
-servers, and mount its handler once with every server it may deliver to:
-
-```ts app/api/a2/scheduler/route.ts
-import { billingServer, ordersServer, scheduler } from '@/server'
-
-export const POST = scheduler.handler(ordersServer, billingServer)
-```
-
-`scheduler.handler(...)` checks its servers when the module loads: at least
-one drainable server, with unique contract names. A bad route fails at
-startup, or in a build that evaluates route modules.
-
-```json vercel.json
-{
-  "functions": {
-    "app/api/a2/scheduler/route.ts": {
-      "experimentalTriggers": [
-        {
-          "type": "queue/v2beta",
-          "topic": "a2"
-        }
-      ]
-    }
-  }
-}
-```
-
-The trigger is required. It connects the route to Vercel Queues and makes the
-function private, so only queue infrastructure can invoke it. Don't expose the
-callback as a public route or wrap it in a second authentication scheme.
-
-The adapter keeps messages for 7 days (Vercel Queues' default is 24 hours), so
-scheduled appends and clears can be up to 7 days out.
-
-### QStash
-
-```ts
-// server/orders.ts, with QStash instead:
-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: {
-    /* ... */
-  },
-})
-```
-
-`@upstash/qstash` 2.11.0 or newer is a peer dependency. Mount
-`scheduler.handler(...)` in the same `app/api/a2/scheduler/route.ts`, and set
-`QSTASH_TOKEN`, `QSTASH_CURRENT_SIGNING_KEY`, and `QSTASH_NEXT_SIGNING_KEY`.
-
-- **Callback URL:** inferred from `PORT` locally, and from
-  `VERCEL_PROJECT_PRODUCTION_URL` or `VERCEL_BRANCH_URL` on Vercel. Pass `url`
-  anywhere else.
-- **Local development:** A2 starts QStash's development server on the first
-  publish or verification, with no QStash variables needed.
-- **Security:** the route verifies `Upstash-Signature` before touching the
-  store and answers unsigned traffic with 401. Behind Deployment Protection,
-  pass an automation bypass as a callback header.
-- **Outages:** delivery is at least once and A2 keeps recovery going, but when
-  QStash can't reach the route at all, redrive its DLQ.
-
-The [adapter reference](/reference/adapters#experimental-a2scheduler-qstash)
-covers the options, protected previews, Edge runtimes, and body limits.
-
-### More than one scheduler
-
-Servers with different scheduler instances need separate routes, even from the
-same adapter. Each extra QStash instance passes its own `url`. Each Vercel
-Queues instance needs its own `topic` and a matching `experimentalTriggers`
-entry.
-
-### Dispatch in a fresh invocation
-
-Ordinary `append` starts handlers inline and uses the scheduler as a watchdog.
-`append.dispatch` persists the input and hands the pending work straight 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 requires a scheduler. The call awaits the queue send and starts no inline
-drain. If the send fails, the event may already be durable; its explicit id
-makes the retry idempotent. Dispatch controls the wakeup, not which worker
-claims the event.
-
-### Running without a scheduler
-
-If no event type has a handler and nothing calls `session.schedule`, skip
-`scheduler`. Events settle in their append transaction, with no drains, claims,
-or queue messages. That's a complete production configuration: a durable event
-log for history, reducers, and live sync.
-
-With handlers, skipping it means the only wakeups are a top-level append or an
-explicit `server.drain()`. Reads never wake a session, so one nobody wakes
-stays stuck. That's fine for internal tools where "heals on the next write" is
-acceptable. For production, configure a scheduler.
-
-## 3. When an event dead-letters
-
-A [dead-lettered](/server/guarantees#when-a-handler-keeps-failing) event waits
-for you. List a session's dead letters, then resolve 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' })
-}
-```
-
-- **Fix and 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 the way an
-append does, so the lane resumes without another write. An event that isn't
-dead-lettered anymore is left alone: `redrive` reports `{ redriven: false }`.
-
-## 4. Deploy safely
-
-The Vercel adapter's `deploymentId` applies to every task: recovery, scheduled
-appends, and scheduled clears. Omit it to use the publishing deployment, pass
-a deployment ID to target one, or pass `null` for deploymentless delivery.
-Publishing and consuming clients must use the same scope.
-
-- **Pinned tasks stay put.** Promoting a new deployment doesn't move them;
-  older deployments keep receiving their own work until it is acknowledged or
-  expires. Upgrading doesn't repair an older deployment's callback handler.
-- **Deploymentless doesn't mean latest.** Vercel picks an eligible consumer,
-  not the latest production deployment. Every eligible consumer must use
-  `deploymentId: null` and stay compatible with pending tasks and session work.
-- **Changing the setting doesn't move queued tasks.** Keep consumers for the
-  original scope until those tasks finish.
-
-QStash's inferred production and branch URLs are moving aliases, so pending
-tasks can reach a later deployment. Keep task envelopes and event schemas
-compatible across deployments, and keep the same `maxBodyBytes` on every
-deployment that can receive the callback: lowering it mid-rollout can reject
-tasks the previous deployment accepted.
-
-:::warning
-Don't roll back to an A2 version without timer delivery while scheduled tasks
-are outstanding.
-An old route can acknowledge a new append task as a recovery message without
-writing its events. Rolling back past scheduled clears fails too: an old
-Vercel Queues route keeps failing a clear task until retention ends, and an
-old QStash route rejects it as non-retryable, moving it to QStash's
-dead-letter queue. Roll forward, or wait for those tasks to deliver or remove
-them through the provider first.
-:::
-
-## Watch it in traces
-
-```ts
-// server/orders.ts, with telemetry:
-import { createServer } from 'experimental-a2/server'
-import { otel } from 'experimental-a2/otel'
-import { orders } from '@/contracts'
-
-export const ordersServer = createServer({
-  contract: orders,
-  // ...store, scheduler, and handlers as above
-  telemetry: otel(),
-})
-```
-
-`telemetry` takes an instrumentation hook; `experimental-a2/otel` implements
-it over OpenTelemetry (`@opentelemetry/api` is a peer dependency). With any
-OTel setup registered (on Vercel, `@vercel/otel`), one trace shows the request,
-`a2.append`, the inline `a2.drain`, an `a2.event` span per handler, and the
-appends those handlers make. Failures mark their `a2.event` span,
-`a2.event.attempt` reports `ctx.attempt`, and `a2.event.outcome =
-dead_lettered` is the attribute to alert on. Agent servers add `a2.ai.*`
-spans. See the [span catalogue](/reference/adapters#the-span-catalogue).
-
-## Checklist
-
-| Piece               | Done when                                                            |
-| ------------------- | -------------------------------------------------------------------- |
-| Store               | `store: redis(...)` (or `postgres(...)`) on every server              |
-| Scheduler           | for servers with handlers or timers: one shared adapter, route, and provider config |
-| Idempotent handlers | external side effects take `event.id` as an idempotency key           |
-| Client split        | contracts/reducers isomorphic; only `experimental-a2/server` touches backends      |