experimental-a2 0.17.0 → 0.18.1

package/docs/reference/02-errors.mdx

@@ -1,150 +0,0 @@
----
-title: Errors
-description: Stable server and client error codes, transport details, and append guarantees.
----
-
-## `A2Error`
-
-A2 failures carry an `A2Error` with a stable `code`. The session client exposes
-`A2ClientError`, which extends `A2Error`, for both server failures and failures
-observed locally. Existing `instanceof A2Error` checks also match client errors.
-
-```ts
-// e.g. in a route handler:
-import { A2Error } from 'experimental-a2'
-
-export async function POST(req: Request) {
-  const { orderId, payload } = await req.json()
-  try {
-    const events = await ordersServer
-      .session(orderId)
-      .append({ type: 'created', payload })
-    return Response.json(events)
-  } catch (err) {
-    if (err instanceof A2Error && err.code === 'INVALID_PAYLOAD') {
-      // err.details carries the schema issues, in Standard Schema format
-      return Response.json({ issues: err.details }, { status: 400 })
-    }
-    throw err
-  }
-}
-```
-
-## The codes
-
-| Code                      | Thrown when                                                        | Retryable |
-| ------------------------- | ------------------------------------------------------------------ | --------- |
-| `INVALID_PAYLOAD`         | a payload fails its schema; nothing was written, and `details` carries the issues ([Standard Schema](https://standardschema.dev) format) | no        |
-| `FORBIDDEN`               | `server.fetch` authorization denies a parsed stream, history read, push, or presence update | no |
-| `UNKNOWN_EVENT_TYPE`      | an event type isn't in the contract's `events` map                  | no        |
-| `UNKNOWN_PRESENCE_FIELD`  | a presence field isn't in the contract's `presence` map             | no        |
-| `PRESENCE_NOT_SUPPORTED`  | the contract declares `presence` but the configured store has no presence capability (thrown at construction; for environment-resolved stores, deferred to the first store use) | no |
-| `PARTIAL_DUPLICATE_BATCH` | a batch mixed already-appended and fresh events                     | no        |
-| `SUPERSEDED_ATTEMPT`      | a handler append or clear from an attempt that a recovery claim or a session clear has replaced; nothing was written. Also the abort reason on that handler's `ctx.signal` | no        |
-| `SESSION_CLEARED`         | a state read reached below the latest clear, a handler read state past a clear of its event, or an actor call was cleared before it received its answer | no |
-| `CLAIM_EXPIRED`           | never thrown; only the `ctx.signal` abort reason when the attempt's lease lapsed without renewal (assumed loss, decided locally, not proof) | no        |
-| `STORE_UNAVAILABLE`       | the store backend failed; nothing was written, original error as `cause` | **yes**   |
-| `STORE_NOT_CONFIGURED`    | production boot with no `store` configured (during `next build` page collection, deferred to first use) | no |
-
-Of these server codes, only `STORE_UNAVAILABLE` is automatically retried by
-client pushes. Reconnection has its own caller-configurable policy.
-
-## `A2ClientError`
-
-Import `A2ClientError` from `experimental-a2/client`. Connection failures,
-push failures, history read failures, and local A2 validation failures use
-this class. Server failures keep their `code`, `message`, and `details`.
-Unexpected thrown values are retained as `cause`. Invalid API arguments can
-still throw native `TypeError` or `RangeError` exceptions.
-
-| Client code | Meaning |
-| --- | --- |
-| `TIMEOUT` | A2 detected a stream stall or an unconfirmed subscription. `phase` is `stream` or `subscribe`; `timeoutMs` is the expired deadline. |
-| `HTTP_ERROR` | An unsuccessful HTTP response without a recognized A2 error body. `status` carries the HTTP status. |
-| `CONNECTION_FAILED` | The transport could not establish or retain a connection. WebSocket close events preserve `closeCode` and `closeReason` when available. |
-| `UNKNOWN` | An unexpected client failure. The original value is available as `cause`. |
-
-HTTP failures retain `status` even when they carry a recognized server code.
-A browser WebSocket handshake rejection has no readable HTTP status or body;
-it remains `CONNECTION_FAILED`. A2 does not infer an authorization failure or
-a timeout from an opaque socket error.
-
-The stream watchdog detects 35 seconds of silence after connection. A
-multiplexed subscription also has 35 seconds to receive confirmation. There
-is no A2-owned initial connection deadline for HTTP or single-session
-WebSockets. Clean stream termination has no error: the reconnection callback
-and connection snapshot carry `null`.
-
-Pushes retain their three-attempt budget for `STORE_UNAVAILABLE` and client
-transport failures. The reconnection callback controls only the live stream.
-Pausing that stream preserves the writer; it does not guarantee that a push
-can succeed while its WebSocket is unavailable.
-
-On `PARTIAL_DUPLICATE_BATCH`: retrying an *identical* batch is not an
-error. It's an idempotent success, and you get the previously appended
-events back. Mixing already-sent events with fresh ones in a single batch
-is always a caller bug, so A2 refuses it rather than quietly reinterpret
-what "atomic" meant. The same code covers two adjacent bugs: a batch that
-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
-
-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
-  and, if persistent, [dead-letter the event](/concepts/durability#when-a-handler-keeps-failing).
-  `append` never fails because a downstream handler is failing.
-- **A duplicate of an identical batch.** That's a lost ack, not a bug.
-
-## Over the wire
-
-The push route serializes an `A2Error` as:
-
-```json
-{ "error": { "code": "INVALID_PAYLOAD", "message": "...", "details": [] } }
-```
-
-with a mapped status: `INVALID_PAYLOAD`, `UNKNOWN_EVENT_TYPE`, and
-`PARTIAL_DUPLICATE_BATCH` are 400; `FORBIDDEN` is 403;
-`SUPERSEDED_ATTEMPT` is 409; `STORE_UNAVAILABLE` is 503.
-
-The session client deserializes the body into an `A2ClientError`, so client
-and server code branch on identical server codes. `server.fetch` owns HTTP
-serialization. Multiplexed WebSocket subscription failures carry the same
-error envelope in their `unsubscribed` frame, alongside the legacy `reason`
-string. Older reason-only frames remain readable as `CONNECTION_FAILED`.
-Unknown server exceptions become `STORE_UNAVAILABLE`; their private causes
-are not sent to clients.