experimental-a2 0.9.0 → 0.10.0

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/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/examples/playground/package.json

@@ -22,7 +22,7 @@
     "@vercel/sandbox": "^3.0.0",
     "ai": "^7.0.58",
     "codemirror": "^6.0.2",
-    "experimental-a2": "0.9.0",
+    "experimental-a2": "0.10.0",
     "ioredis": "^5.9.0",
     "next": "^16.3.0",
     "pg": "^8.16.0",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "experimental-a2",
-  "version": "0.9.0",
+  "version": "0.10.0",
   "description": "Durable sync and reactions for things with a lifecycle: one event log, derived state, and live client per session.",
   "license": "MIT",
   "type": "module",