@alxia/react-router 0.18.0 → 0.20.0

package/docs/guide/lists.md

@@ -0,0 +1,111 @@
+# Lists whose state is the URL
+
+A list screen of a BFF keeps its state in the address bar: `?q=ana&status=open`
+for a search and filters, `?after=<cursor>` for the page. The loader reads it;
+the screen changes it. `@alxia/react-router/lists` holds the three hooks every
+such screen needs. `react` and `react-router` are its only imports, so it adds
+no peer beyond those, and every hook renders on the server.
+
+```tsx
+import {
+	usePagedRows,
+	useSameRouteLoading,
+	useSearchChange,
+} from '@alxia/react-router/lists';
+```
+
+## The loader
+
+One loader serves the first page and the next ones. It reads the cursor and
+answers `{ items, next }`, `next` being `null` on the last page:
+
+```ts
+export async function loader({ request }: Route.LoaderArgs) {
+	const url = new URL(request.url);
+	return {
+		page: await listUsers({
+			q: url.searchParams.get('q') ?? '',
+			after: url.searchParams.get('after'),
+		}),
+	};
+}
+```
+
+## `useSearchChange`
+
+```tsx
+const change = useSearchChange(); // resetKeys: ['after']
+
+<input onChange={(event) => change({ q: event.target.value || null })} />;
+<Select onChange={(status) => change({ status })} />;
+```
+
+`change(changes)` sets each parameter given a string, deletes each given
+`null` or `undefined` (an empty string is a value, so it is kept as `?q=`),
+and deletes `resetKeys` in the same step: a new search makes the old cursor
+meaningless. It navigates with `replace: true` and `preventScrollReset: true`,
+so typing does not fill the history nor jump the page. Pass
+`{ resetKeys: ['after', 'page'] }` to drop more.
+
+## `useSameRouteLoading`
+
+```tsx
+const reloading = useSameRouteLoading();
+return reloading ? <Skeleton /> : <Table rows={rows} />;
+```
+
+`true` while a navigation is loading **and** its pathname is the page's own: a
+new search of this list. A click on a link to another page stays `false`, so
+the list does not flash a skeleton on the way out.
+
+## `usePagedRows`
+
+```tsx
+const { rows, next, loading, error, loadMore } = usePagedRows(
+	loaderData.page,
+	(page) => page.items,
+);
+
+<Button disabled={!next || loading} onClick={loadMore}>
+	{error ? 'Retry' : 'Load more'}
+</Button>;
+```
+
+| option | default | |
+| --- | --- | --- |
+| `cursorParam` | `'after'` | the search parameter carrying the cursor |
+| `nextOf` | `page.next` | the cursor after a page, `null` at the end |
+
+- `loadMore()` asks the **same route** for `?<cursorParam>=<next>`, keeping the
+  rest of the search, through `useFetcher`: the address bar and the page's
+  data do not change. It does nothing at the end or while a page is on its way.
+- `rows` is the first page's rows followed by every page loaded after it.
+- **It starts over** when `firstPage` is another object, which is what the
+  loader gives after a new search or a revalidation. The new first page's rows
+  are the ones rendered, with no frame of stale rows, and a page still on its
+  way for the old search is dropped.
+- **A failure keeps the rows.** When the route answers something that is not a
+  page (`null`, or `data({ message }, { status: 503 })`), `error` is `true` and
+  `next` is unchanged, so the same button retries. The next `loadMore` clears
+  it. Fetcher data that is not a page (no rows, or a `next` that is neither a string nor `null`) sets `error`, like a failed page.
+
+### Another cursor parameter
+
+```ts
+// the loader answers { items, cursor } for ?q=&page=<cursor>
+const { rows, next, loadMore } = usePagedRows(
+	loaderData.page,
+	(page) => page.items,
+	{ cursorParam: 'page', nextOf: (page) => page.cursor },
+);
+const change = useSearchChange({ resetKeys: ['page'] });
+```
+
+`cursorParam` and `useSearchChange`'s `resetKeys` must name the same
+parameter: with the defaults both are `after` (`DEFAULT_CURSOR_PARAM`), and
+with another one a search that keeps the old cursor shows the wrong page.
+
+A loader that **throws** on a cursor request is not an `error` here: React
+Router sends a fetcher's thrown error to the route's `ErrorBoundary`. To offer
+a retry instead, catch in the loader for a request that has the cursor and
+answer a value that is not a page.

package/docs/guide/subscriptions.md

@@ -0,0 +1,126 @@
+# Subscriptions for a BFF
+
+This page is for a React Router app that is the backend of its own pages (a
+BFF) and wants to show a GraphQL subscription in the browser: a room's
+events, a chat, a live counter. The browser must not hold the API's token and
+must not be able to send the API a document of its own, so the app exposes
+**one resource route** that checks the user's session, looks the operation up
+in a list the server holds, and relays the API's server-sent events.
+
+`@alxia/react-router/subscription` is that route. It imports nothing (web APIs only), so it adds no peer.
+
+## Expose a subscription
+
+`allow` maps each operation name to the **document the server sends for it**.
+Build the map from your codegen's documents, so the text is the one your
+client was generated from:
+
+```ts
+// app/routes/events.ts: a resource route, served at /events
+import { createSubscriptionProxy } from '@alxia/react-router/subscription';
+import { print } from 'graphql';
+import { ChatMessagesDocument, RoomEventsDocument } from '../generated/graphql';
+import { cookies } from '../session.server';
+
+const events = createSubscriptionProxy({
+	endpoint: 'https://api.example.com/graphql',
+	allow: {
+		RoomEvents: print(RoomEventsDocument), // a TypedDocumentNode
+		ChatMessages: print(ChatMessagesDocument),
+		// or the document string codegen exports, or a literal
+	},
+	getToken: (request) => cookies.token(request),
+	headers: (request) => ({
+		'x-client-name': 'my-bff',
+		'x-proxy-secret': process.env.PROXY_SECRET,
+		'x-forwarded-for': request.headers.get('x-forwarded-for'),
+		'accept-language': request.headers.get('accept-language'),
+	}),
+});
+
+export const loader = events.loader; // GET: operationName and variables in the query string
+export const action = events.action; // POST: the same in a JSON body
+```
+
+```ts
+// app/routes.ts
+import { route, type RouteConfig } from '@react-router/dev/routes';
+
+export default [route('events', 'routes/events.ts')] satisfies RouteConfig;
+```
+
+The browser talks to `/events` with a client that speaks GraphQL over SSE in
+its distinct connections mode, such as `graphql-sse`. It names the operation
+and sends its variables; the `query` it sends, as `graphql-sse` always does,
+is **ignored**:
+
+```ts
+import { createClient } from 'graphql-sse';
+
+const client = createClient({ url: '/events', singleConnection: false });
+
+const dispose = client.subscribe(
+	{
+		query: 'subscription RoomEvents($id: ID!) { roomEvents(id: $id) { id kind } }',
+		operationName: 'RoomEvents',
+		variables: { id: roomId },
+	},
+	{ next: show, error: report, complete: () => {} },
+);
+```
+
+`graphql-sse` sends a POST by default and a GET for `method: 'GET'`; both
+work, each through the matching export.
+
+## What the proxy does
+
+| Step | Rule |
+| --- | --- |
+| Same site | Both methods run the rule of `jsonActions`: an `Origin` that is not the app's own, or a `Sec-Fetch-Site` other than `same-origin` or `none`, is a **403** (`origin` sets the app's origin; the request's own by default). It reads headers only. A POST must be `application/json`, else **415**. |
+| Session | `getToken(request)` gives the token, read on the server from the HttpOnly cookie. Empty, `null`, `undefined` or a token holding a line break is a **401**; nothing goes upstream. |
+| Request | The client's `operationName` and `variables` are read. A body that cannot be read (the client left) is a **400**; a body past 64 KiB (`Content-Length` first, then the bytes read), a query string past 16 KiB or `variables` past 16 KiB is a **400**, as is malformed input. Its `query` and `extensions` are ignored. |
+| Allow-list | Each document of `allow` must define `subscription <key>` and no other operation (fragments are fine), or `createSubscriptionProxy` throws a `TypeError` when it is created. `operationName` must be a key of `allow`, else **403**. The proxy sends **its own document** for it, with the client's variables: no document, fragment, extension or persisted id of the client's reaches the API. |
+| Upstream request | A `POST` to `endpoint` with `Accept: text/event-stream`, `Authorization: Bearer <token>` and your `headers`. The browser's own headers and cookies are never forwarded. A header name or value no header can hold (a line break) is a worded **500**. |
+| Relay | Whole events are relayed in order, as the client takes them: a slow client holds the upstream back instead of growing a buffer, and a heartbeat is skipped while one is waiting. A heartbeat comment (`:`) goes out every `heartbeatMs` (15000 by default, `0` turns it off), never inside an event. An event of more than 1 MiB with no end cuts the stream with an `UPSTREAM_ERROR`. |
+| End | The upstream's `complete`, or the end of its stream, closes the client's stream. A stream that breaks sends a `next` with an `UPSTREAM_ERROR` and a `complete`. |
+| Abort | When the browser closes the request, the upstream request is aborted: no subscription is left running. A request that is already aborted never starts one. |
+| Rate limit | An upstream **429** is passed through with `Retry-After` and `retryAfter` in the body (`{ "retryAfter": 12, "errors": [{ "extensions": { "code": "RATE_LIMITED", "retryAfter": 12 } }] }`), read from the upstream's header or body. The proxy never retries. |
+| Other failures | An upstream 5xx, an unreachable API or an answer that is not an event stream is a **502** (`UPSTREAM_ERROR`); an upstream 4xx such as a 401 passes through. |
+
+The stream is answered with `Content-Type: text/event-stream`,
+`Cache-Control: no-store, no-transform` and `X-Accel-Buffering: no`, so no
+adapter or reverse proxy needs to buffer it.
+
+## Options
+
+| Option | |
+| --- | --- |
+| `endpoint` | the API's GraphQL URL (required) |
+| `allow` | operation name to the document sent upstream (required); each document must define `subscription <name>`, that operation alone, checked when the proxy is created |
+| `getToken(request)` | the session's token, sync or async (required) |
+| `headers` | a record, `Headers`, or `(request) => record`; a `null` or `undefined` value is left out |
+| `origin` | the app's origin for the same-site check, a string or a getter; the request's own by default |
+| `heartbeatMs` | 15000 |
+| `fetch` | the `fetch` used upstream (the global one); useful in specs |
+
+## Keep the stream alive
+
+Bun closes an idle connection after `idleTimeout` seconds (10 by default).
+The heartbeat covers it as long as `heartbeatMs` is shorter, and so is a proxy's
+read timeout. Behind nginx, keep `proxy_buffering off` for the route (the
+`X-Accel-Buffering: no` header does it per response).
+
+## Cross-site requests
+
+Both methods refuse a request from another site (the rule above), and the
+session cookie should stay `SameSite=Lax` (`sessionCookies` does it). The
+allow-list is what the browser may start; because the documents are the
+server's, it cannot start anything else, a mutation included. The route does
+not stop a signed-in user from starting an allowed subscription as often as
+they like: rate-limit it (`@alxia/rate-limit`) if the API does not.
+
+## Testing
+
+Give the proxy a fake API through `fetch`, or start a `Bun.serve` that
+answers with an event stream, and call `events.action({ request })`; the
+answer is a plain `Response`.

package/docs/roadmap.md

@@ -14,6 +14,21 @@ number on it. Every release, with each change it made, is in
   so an app stops carrying its own copies. See the
   [session guide](guide/session.md#the-pages-hooks).
 
+- **`@alxia/react-router/subscription`: GraphQL subscriptions for the
+  browser of a BFF.** `createSubscriptionProxy` gives a resource route's
+  `loader` and `action` that relay a subscription over SSE: the server holds
+  each allowed document, the bearer comes from the session, the route refuses
+  cross-site requests, keeps the stream alive with a heartbeat, aborts the
+  upstream with the client and passes a 429 on with `retryAfter`. See the
+  [subscriptions guide](guide/subscriptions.md).
+
+- **`@alxia/react-router/lists`: hooks for lists whose state is the URL.**
+  `useSearchChange` (set or delete search parameters and drop the cursor),
+  `useSameRouteLoading` (another search of the same page is loading) and
+  `usePagedRows` (append the pages a load-more asks of the same loader, start
+  over on a new first page, keep the rows when a page fails). See the
+  [lists guide](guide/lists.md).
+
 ## Next
 
 Nothing planned.

package/docs/troubleshooting.md

@@ -533,6 +533,28 @@ them.
 inside a folder is served by that folder's `static` route, whatever its
 name.
 
+### A "load more" lands on the route's `ErrorBoundary`
+
+**When:** the loader throws (or throws a `Response`) for a request that has the cursor, and the page used `usePagedRows`: the whole route is replaced by its `ErrorBoundary` instead of showing the rows with a retry button.
+
+**Why:** React Router sends the error of a fetcher's load to the route's boundary. `usePagedRows` only sees what the fetcher answers, so its `error` is `true` for an answer that is not a page, not for a throw.
+
+**Fix:** catch in the loader for a request that has the cursor and answer a value that is not a page:
+
+```ts
+export async function loader({ request }: Route.LoaderArgs) {
+	const url = new URL(request.url);
+	try {
+		return await listUsers(url.searchParams);
+	} catch (error) {
+		if (url.searchParams.has('after')) return { message: 'unavailable' };
+		throw error;
+	}
+}
+```
+
+The rows stay, `error` is `true`, and `loadMore` retries.
+
 ### `Refused to execute inline script because it violates the following Content Security Policy directive: "default-src 'none'"`
 
 The browser's console prints it; the page renders on the server, then
@@ -2714,3 +2736,112 @@ import { TOKEN_PAGE_HEADERS } from '@alxia/react-router/session';
 
 export const headers = () => TOKEN_PAGE_HEADERS;
 ```
+
+### A subscription answers 401
+
+`{"errors":[{"message":"Sign in to continue.","extensions":{"code":"UNAUTHENTICATED"}}]}`
+
+**Why:** `getToken(request)` returned `null`, `undefined`, `''` or a token with a
+line break: the browser sent no session cookie (signed out, expired, or a
+cross-site request with a `SameSite=Lax` cookie), or `getToken` reads another
+cookie than the one the sign-in wrote.
+
+**Fix:** return the token the loaders use, and send the cookie with the request
+(`credentials: 'include'` for a cross-origin client):
+
+```ts
+getToken: (request) => cookies.token(request),
+```
+
+### A subscription answers 403 `This operation is not allowed.`
+
+**Why:** `operationName` is not a key of `allow`. The proxy runs only the
+documents the server holds; a `query` the client sends is ignored.
+
+**Fix:** list the name with its document, and send that name:
+
+```ts
+createSubscriptionProxy({ endpoint, allow: { RoomEvents: document }, getToken });
+```
+
+### A subscription answers 403 `Cross-site request refused.`
+
+**Why:** the request's `Origin` is not the app's own, or its `Sec-Fetch-Site` is
+`cross-site`, or `same-site` (another subdomain of the same site: only `same-origin` and `none` pass). Behind a TLS-terminating proxy
+the request's own origin can read `http://`.
+
+**Fix:** call the route from the app's own pages, or give the proxy the public
+origin:
+
+```ts
+createSubscriptionProxy({ endpoint, allow, getToken, origin: 'https://app.example.com' });
+```
+
+### A subscription answers 415 `Send the request as application/json.`
+
+**Why:** a POST with another `Content-Type`, or none.
+
+**Fix:** send `Content-Type: application/json` (`graphql-sse` does), or use GET.
+
+### A subscription answers 400 `The request is too large.`
+
+**Why:** the body is over 64 KiB, the query string over 16 KiB, or `variables`
+over 16 KiB.
+
+**Fix:** send less in `variables`; a document does not belong in the request,
+the server holds it.
+
+### A subscription answers 400 `The request is not valid JSON.`
+
+**Why:** the POST body, or the `variables` parameter of a GET, is not JSON.
+
+**Fix:** send `JSON.stringify({ operationName, variables })`, and `variables`
+JSON-encoded in a GET.
+
+### A subscription answers 400 `The request must be a JSON object.`, `Send an "operationName".`, `"operationName" must be a string.` or `"variables" must be an object.`
+
+**Why:** the body is an array or a scalar, `operationName` is missing or not a
+string, or `variables` is not an object.
+
+**Fix:** send `{ "operationName": "RoomEvents", "variables": { … } }`.
+
+### A subscription answers 500 `The proxy's upstream headers are not valid …`
+
+**Why:** a value of `headers` (a forwarded `Accept-Language`, a secret from the
+environment) holds a line break, or a name is not a header name.
+
+**Fix:** trim or validate the value before it goes in `headers`.
+
+### A subscription answers 429 with `retryAfter`
+
+The API's rate limit answered. The proxy passes it on and never retries.
+
+**Fix:** have the client wait `Retry-After` seconds (also `retryAfter` in the
+body) before it subscribes again.
+
+### A subscription answers 502
+
+**Why:** the API is unreachable, answered 5xx, or answered something that is
+not `text/event-stream` (a proxy in front of it, or a wrong `endpoint`).
+
+**Fix:** post the document to the `endpoint` by hand with the same headers; it
+must answer with `Content-Type: text/event-stream`.
+
+### The stream ends with `The API stream failed.`
+
+**Why:** the upstream stream broke, or sent an event of more than 1 MiB with
+no blank line ending it.
+
+**Fix:** read the API's logs; a subscription's events are small and end with a
+blank line.
+
+### Events arrive in bursts, or the stream closes after a few seconds
+
+**Why:** a proxy or CDN between the app and the browser buffers the response,
+or closes an idle connection (Bun's `idleTimeout`, a load balancer's timeout)
+because `heartbeatMs` is longer than it.
+
+**Fix:** keep `heartbeatMs` shorter than the shortest idle timeout on the
+path, turn response buffering off for the route (nginx `proxy_buffering off`;
+the route already sends `X-Accel-Buffering: no`), and do not compress the
+route's responses.

package/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "@alxia/react-router",
-	"version": "0.18.0",
-	"description": "alxia as the server of a React Router framework app: server rendering behind the app's hooks, loaders reading its typed context, the client's assets served; the code with no UI an installable app shares (`/pwa`), its hooks (`/pwa/react`), `noCache` for the worker's script (`/pwa/server`), the service worker on Workbox (`/pwa/worker`) and its build (`/pwa/build`), an API's refusals worded for the page (`/errors`), the BFF session: cookies, sign-in, step-up and mail links (`/session`), its page hooks (`/session/react`) and what it shares with the page (`/session/model`), the page's CSP nonce and inline boot scripts (`/document`) and a streaming `entry.server` (`/entry`)",
+	"version": "0.20.0",
+	"description": "alxia as the server of a React Router framework app: server rendering behind the app's hooks, loaders reading its typed context, the client's assets served; the code with no UI an installable app shares (`/pwa`), its hooks (`/pwa/react`), `noCache` for the worker's script (`/pwa/server`), the service worker on Workbox (`/pwa/worker`) and its build (`/pwa/build`), an API's refusals worded for the page (`/errors`), the BFF session: cookies, sign-in, step-up and mail links (`/session`), its page hooks (`/session/react`) and what it shares with the page (`/session/model`), a GraphQL subscription relayed to the browser over SSE (`/subscription`), the page's CSP nonce and inline boot scripts (`/document`) and a streaming `entry.server` (`/entry`)",
 	"license": "MIT",
 	"type": "module",
 	"main": "./dist/index.js",
@@ -82,6 +82,16 @@
 			"import": "./dist/session/model/index.js",
 			"default": "./dist/session/model/index.js"
 		},
+		"./lists": {
+			"types": "./dist/lists/index.d.ts",
+			"import": "./dist/lists/index.js",
+			"default": "./dist/lists/index.js"
+		},
+		"./subscription": {
+			"types": "./dist/subscription/index.d.ts",
+			"import": "./dist/subscription/index.js",
+			"default": "./dist/subscription/index.js"
+		},
 		"./package.json": "./package.json"
 	},
 	"repository": {
@@ -109,6 +119,8 @@
 			"src/session/model/index.ts",
 			"src/session/index.ts",
 			"src/session/react/index.ts",
+			"src/subscription/index.ts",
+			"src/lists/index.ts",
 			"src/document/index.ts",
 			"src/entry/index.ts",
 			"src/pwa/worker/index.ts",
@@ -123,7 +135,7 @@
 		"@nxgt/graphql-client": "^0.4.0",
 		"@nxgt/janus": "^0.29.0",
 		"@react-router/dev": "^8.5.0",
-		"@types/bun": "^1.4.2",
+		"@types/bun": "^1.4.4",
 		"@types/react": "^19.3.0",
 		"@types/react-dom": "^19.3.0",
 		"graphql": "^17.0.2",