experimental-a2 0.6.0 → 0.7.0

package/docs/guides/10-transports.mdx

@@ -7,8 +7,8 @@ description: "One client, three wires: a single HTTP route, split routes for per
 
 Everything the client does is transport-agnostic: optimistic pushes
 with ack and `confirmed`, frontier-resumed live reads, reconnection
-with backoff, the presence throttle and re-send. `api` picks the wire
-underneath it:
+with backoff, and presence throttling. `api` picks the wire underneath
+it:
 
 ```ts
 // in a 'use client' session module:
@@ -18,73 +18,111 @@ api: { type: 'ws', url: '/api/order-events' }
 ```
 
 - **The string** is the default and the recommendation: one route
-  serving GET (SSE stream) and POST (push), one file, one auth surface.
-  Everything else in these docs uses it.
-- **`http` split** serves the two verbs from two routes. Use it when
-  platform duration limits differ per verb: the stream is a long-lived
-  read that wants a high `maxDuration`, the push is a short write that
-  doesn't.
-- **`ws`** rides everything over one WebSocket: streams come down it,
-  pushes and presence go up it. One socket carries every session of
-  the client; a page showing ten sessions holds one connection, not
-  ten. Use it when latency or per-message cost matters; at a presence
-  cadence of fifteen sends a second, each send is a socket frame
-  instead of a route invocation.
+  serving 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.
 
 A split socket is unrepresentable on purpose. The socket is one
-connection in both directions; there is nothing left to split.
+connection in both directions.
 
 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`.
+read and rides plain HTTP. On a `ws` API it throws a `TypeError`.
+
+## The HTTP route
+
+`server.fetch` is bound, so an unprotected route is two exports:
+
+```ts app/api/public-order-events/route.ts
+import { ordersServer } from '@/server/orders'
+
+export const GET = ordersServer.fetch
+export const POST = ordersServer.fetch
+```
+
+A plain GET streams one session over SSE. A GET with `gte` and `lte`
+returns a history slice. POST parses the push envelope and appends its
+events. If the contract declares presence, the same route streams and
+accepts presence automatically.
+
+Wrap the call when the route needs authentication or authorization:
+
+```ts app/api/protected-order-events/route.ts
+import { ordersServer } from '@/server/orders'
+
+async function fetchOrders(request: Request): Promise<Response> {
+  // your authentication:
+  const user = { id: 'user-1' }
+  if (!user) return new Response(null, { status: 401 })
+
+  return ordersServer.fetch(request, {
+    authorize(operation) {
+      // your per-session and per-operation authorization:
+      // return canAccess(user, operation)
+      return true
+    },
+  })
+}
+
+export const GET = fetchOrders
+export const POST = fetchOrders
+```
+
+`authorize` runs after A2 parses the operation and before schema
+validation or durable I/O. It receives `stream`, `history`, and `push`
+operations. Push operations include parsed event names and payloads,
+plus the complete presence patch when present. Return `false` to deny.
+A2 answers `FORBIDDEN` with status 403. If the hook throws, A2 treats
+that as an infrastructure failure and answers `STORE_UNAVAILABLE`.
+
+The hook is per `fetch` call. Authentication stays in the route, where
+request headers, cookies, and framework context are available. The
+captured user can then authorize strongly typed A2 operations without
+repeating request parsing.
 
 ## The WebSocket route
 
-The same `handle` route serves both transports. Pass `options.upgrade`
-and a GET carrying an upgrade header becomes the socket; plain GETs
-stay SSE, POST keeps working next to it. A `ws` client never calls
-POST, an `http` client never upgrades; the transports are additive.
+Pass the platform's upgrade capability on GET. POST can stay a direct
+export for HTTP clients:
 
-```ts app/api/order-events/route.ts
+```ts app/api/socket-order-events/route.ts
 import { experimental_upgradeWebSocket } from '@vercel/functions'
-import { handle } from 'experimental-a2/http'
 import { ordersServer } from '@/server/orders'
 
-export const { GET, POST } = handle(ordersServer, {
-  before({ request, intent }) {
-    // here's where you'd do auth, or any other checks: the upgrade
-    // itself, every subscribe, and every push arrive here as intents
-  },
-  upgrade: (attach) =>
-    experimental_upgradeWebSocket(attach, {
-      // ws defaults to 100 MiB per frame; POST bodies cap at about
-      // 4.5 MB on the platform. Keep the two ingress paths at parity.
-      maxPayload: 4 * 1024 * 1024,
-    }),
-})
+export const POST = ordersServer.fetch
+
+export function GET(request: Request): Promise<Response> {
+  return ordersServer.fetch(request, {
+    upgradeWebSocket: (attach) =>
+      experimental_upgradeWebSocket(attach, {
+        maxPayload: 4 * 1024 * 1024,
+      }),
+  })
+}
 ```
 
-The socket is multiplexed: `subscribe` frames open per-session lanes,
-each resuming from its own frontier; every down frame carries the
-`sessionId` it belongs to; pushes and presence route by it. One
-heartbeat, one connection, all of the client's sessions.
-
-Auth has two moments. `before` runs for the upgrade itself
-(`intent.type === 'ws-upgrade'`), while the request is still a request;
-return a Response to refuse and no socket ever opens. It then runs
-again for every subscribe and push frame: each subscribe arrives as a
-`stream` intent, each push as a `push` intent, with `request` always
-the original upgrade Request. A Response cannot cross a socket, so a
-denial answers in the wire's own vocabulary: a denied subscribe gets an
-`unsubscribed` notice (every other session on the socket streams on), a
-denied push a non-retryable error ack. Socket presence frames are
-fire-and-forget and never become intents; the presence plane's policy
-seam on every wire is `validatePush`.
-
-Two more options ride along: `presence: true` interleaves presence with
-events on every lane, the same opt-in as `stream()`, and `deadline`
-(epoch milliseconds) closes the socket cleanly ahead of a known
-platform deadline, so clients reconnect on your schedule.
+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.
+
+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`.
+
+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.
+
+A2 reads the platform's ambient invocation deadline and closes the
+socket cleanly before it. `waitUntil` and deadline discovery remain
+platform capabilities used internally, not options on `server.fetch`.
 
 ## The client
 
@@ -104,37 +142,17 @@ export const { SessionProvider, useSession } = createReact({
 ```
 
 Nothing else changes. `useSession` is identical, `push` returns the
-same ack and `confirmed`, presence coalesces on the same cadence. The
-connection status, the stall watchdog (two missed heartbeats), and
-reconnection with backoff all behave as they do over SSE, because they
-are the same machinery above the wire seam.
+same ack and `confirmed`, and presence coalesces on the same cadence.
+The connection status, stall watchdog, and reconnection behavior are
+shared above the wire seam.
 
 ## Lifecycle
 
-A socket closes when the platform ends the function invocation, or
-when the server closes it deliberately ahead of a known deadline. The
-client treats every close the same way it treats a dropped SSE stream:
-reconnect with backoff, re-subscribe every session at its own frontier,
-receive fresh presence snapshots, re-send its own presence fields set
-since the disconnect. A push whose socket died before the ack rejects as
-retryable: nothing was acknowledged, and if the append had already
-committed, the client-generated event ids make the retry an idempotent
-replay (you get the original events back). Push retries wait for the
-restored socket rather than a fixed clock, capped by the reconnect
-backoff, so a push caught in a routine blip resolves the way it would
-have over HTTP, where pushes never depended on the stream.
-
-On Vercel, WebSocket connections pin to one function instance and new
-connections may land anywhere. A2 never relies on instance affinity:
-the log is the shared state, so two clients on two instances converge
-through it, exactly as they do over HTTP.
-
-## Choosing
-
-SSE plus POST is the right default: simplest route, ordinary HTTP
-semantics, and one auth surface. Reach for `ws` when the send rate
-makes per-request overhead visible (live cursors, drag ghosts) or when
-round-trip latency is the product. Reach for the `http` split only when
-per-route duration configuration forces it. The protocol underneath is
-the same in every case: the log replays, presence repaints, and the
-wire is an implementation detail.
+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.
+
+SSE and WebSocket are transport choices, not different consistency
+models. Both resume from the durable event frontier and treat presence
+as ephemeral repaintable state.