@luckystack/server 0.1.0

package/docs/http-routes.md

@@ -0,0 +1,309 @@
+# HTTP Routes
+
+> Deep specs. Bron: `packages/server/src/httpHandler.ts`, `packages/server/src/httpRoutes/*.ts`, `packages/server/src/customRoutesRegistry.ts`. Bijgewerkt: 2026-05-20.
+
+## Overview
+
+`@luckystack/server` ships every HTTP route the framework needs: liveness / readiness / health probes, CSRF token issue + middleware, the destructive test-reset endpoint, favicon, uploads, OAuth (`/auth/api` + `/auth/callback`), the dispatcher to `/api/*` and `/sync/*`, custom routes, and a static-file SPA fallback. The orchestrator in `httpHandler.ts` runs them as two ordered tables (PRE_PARAMS and POST_PARAMS). Each handler matches its own route path and returns `boolean`. First handler to return `true` (or end the response) terminates dispatch.
+
+Pre-params handlers (no body parse) run first so probes, favicon, and CSRF stay cheap:
+
+1. `handleCsrfRoute` — `/auth/csrf`
+2. `handleFaviconRoute` — `/favicon.ico`
+3. `handleLivezRoute` — `projectConfig.http.liveEndpoint` (default `/livez`)
+4. `handleReadyzRoute` — `projectConfig.http.readyEndpoint` (default `/readyz`)
+5. `handleHealthRoute` — `projectConfig.http.healthEndpoint` (default `/_health`)
+6. `handleTestResetRoute` — `projectConfig.http.testResetEndpoint` (default `/_test/reset`)
+
+Post-params handlers (after body parsing) run next:
+
+1. `handleUploadsRoute` — `/uploads/*`
+2. `handleAuthApiRoute` — `/auth/api/*`
+3. `handleAuthCallbackRoute` — `/auth/callback/*`
+4. `handleApiRoute` — `/api/*` (delegates to `@luckystack/api`)
+5. `handleSyncRoute` — `/sync/*` (delegates to `@luckystack/sync`)
+6. `handleCustomRoutes` — every handler from `registerCustomRoute(...)` + `options.customRoutes`
+7. `handleStaticAndSpaFallback` — `/assets/*`, known extensions, SPA `index.html`
+
+A custom-route registry sits in front of the static fallback. Both the legacy `customRoutes` option on `CreateLuckyStackServerOptions` and the global `registerCustomRoute(...)` registry are honored. Errors in custom handlers are caught and reported as `500 server.customRouteFailed`; the request loop is never crashed by a misbehaving handler.
+
+## Framework route reference
+
+| Route | Method(s) | Handler | Response (success) | Response (failure) |
+| --- | --- | --- | --- | --- |
+| `/auth/csrf` | GET | `handleCsrfRoute` | `200 { status: 'success', csrfToken }` | `401 auth.unauthenticated` |
+| `/favicon.ico` | GET | `handleFaviconRoute` | Whatever `options.serveFavicon(res)` writes | `404` empty when no handler supplied |
+| `/livez` | GET | `handleLivezRoute` | `200 { status: 'live' }` | Always 200 when reachable |
+| `/readyz` | GET | `handleReadyzRoute` | `200 { status: 'ready', checks: {...} }` | `503 { status: 'not-ready', checks: {...} }` |
+| `/_health` | GET | `handleHealthRoute` | `200 { status: 'ok', bootUuid, envKey, synchronizedHashes }` | `503 { status: 'degraded', ... }` when boot UUID is missing |
+| `/_test/reset` | POST | `handleTestResetRoute` | `200 { status: 'success', cleared: string[] }` | `404 notFound` or `403 auth.forbidden` — see `security-defaults.md` |
+| `/uploads/*` | GET | `handleUploadsRoute` | Avatar bytes via `@luckystack/core` `serveAvatar` | `404` from `serveAvatar` when missing |
+| `/auth/api/*` | POST | `handleAuthApiRoute` | OAuth redirect (`302`) or credentials login envelope | Rate-limited envelope, `200` envelope with `status:false, reason` |
+| `/auth/callback/*` | GET | `handleAuthCallbackRoute` | `302` to `redirectUrl` with session cookie or token | `401 'Login failed'` plain text |
+| `/api/*` | GET / POST / PUT / DELETE | `handleApiRoute` | JSON envelope from `@luckystack/api` `handleHttpApiRequest`, or SSE stream | `400 api.invalidName`, `500 api.invalidRequestFormat` |
+| `/sync/*` | POST | `handleSyncRoute` | JSON envelope from `@luckystack/sync` `handleHttpSyncRequest`, or SSE stream | `405 sync.methodNotAllowed`, `400 sync.invalidName`, `500 sync.invalidRequestFormat` |
+| `/assets/*`, `*.{png,jpg,jpeg,gif,svg,html,css,js}` | GET | `handleStaticAndSpaFallback` | Whatever `options.serveFile` writes (URL temporarily rewritten) | `404` when no `serveFile` is wired |
+| Any other extension-less path | GET | `handleStaticAndSpaFallback` | SPA fallback (rewrite URL to `/`, call `serveFile`) | `404` when no `serveFile` |
+
+> The CSRF header name clients must send (for the `/auth/csrf` route above) is configurable: it comes from `getCsrfConfig().headerName` (default `x-csrf-token`), renamable via `registerCsrfConfig({ headerName })` from `@luckystack/core`.
+
+## API Reference — handlers
+
+All handlers conform to:
+
+```typescript
+type HttpRouteHandler = (ctx: HttpRouteContext) => Promise<boolean>;
+
+interface HttpRouteContext {
+  req: IncomingMessage;
+  res: ServerResponse;
+  options: CreateLuckyStackServerOptions;
+  routePath: string;
+  queryString: string | undefined;
+  method: 'GET' | 'POST' | 'PUT' | 'DELETE';
+  token: string | null;
+  requestId: string;
+  sessionCookieOptions: string;
+  params: object;
+}
+```
+
+A handler returns `true` (or simply ends `res`) to short-circuit dispatch; returning `false` falls through to the next handler.
+
+### `handleLivezRoute(ctx)`
+
+**Behavior:**
+
+- Matches when `routePath === projectConfig.http.liveEndpoint` (default `/livez`).
+- Always emits `200 application/json { status: 'live' }`.
+
+**Edge cases:** no downstream dependencies; succeeds as long as the Node event loop is responsive.
+
+### `handleReadyzRoute(ctx)`
+
+**Behavior:**
+
+- Matches when `routePath === projectConfig.http.readyEndpoint` (default `/readyz`).
+- Sequentially checks: `readBootUuid()` (Redis), `redis.ping()`, and a Prisma probe.
+- Prisma probe is provider-agnostic: tries `$queryRaw\`SELECT 1\`` first, then `$runCommandRaw({ ping: 1 })`. Detecting the active provider via private fields drifts between Prisma majors, so the handler probes by capability.
+- Returns `200 { status: 'ready', checks }` only when all three pass; `503 { status: 'not-ready', checks: { bootUuid, redis, prisma } }` otherwise.
+
+**Edge cases:**
+
+- `redis.ping()` errors are swallowed and surface as `redis: false`.
+- A Prisma client with neither raw method available results in `prismaOk = false`.
+
+### `handleHealthRoute(ctx)`
+
+**Behavior:**
+
+- Matches when `routePath === projectConfig.http.healthEndpoint` (default `/_health`).
+- Reads `bootUuid`, `resolveEnvKey()`, and `computeSynchronizedEnvHashes()` from `@luckystack/core`.
+- Returns `200 { status: 'ok', bootUuid, envKey, synchronizedHashes }` when boot UUID is present, otherwise `503 { status: 'degraded', ... }`.
+- Consumed by `@luckystack/router` to verify shared-Redis topology after a rolling restart.
+
+### `handleCsrfRoute(ctx)`
+
+**Behavior:**
+
+- Matches `routePath === '/auth/csrf'`.
+- Requires a session token (cookie or `Authorization`). Returns `401 auth.unauthenticated` when missing or when `getSession(token)` does not resolve a valid session.
+- On success returns `200 { status: 'success', csrfToken }`.
+
+**Note:** the matching middleware is `enforceCsrfOnStateChangingRequest` (see `request-pipeline.md`). This route only issues tokens.
+
+### `handleFaviconRoute(ctx)`
+
+**Behavior:**
+
+- Matches `routePath === '/favicon.ico'`.
+- Delegates to `options.serveFavicon(res)`. Without that option, returns an empty `404`.
+
+### `handleUploadsRoute(ctx)`
+
+**Behavior:**
+
+- Matches every path starting with `/uploads/`.
+- Delegates to `serveAvatar({ routePath, res })` from `@luckystack/core`. Response (and `404` on miss) is owned by `serveAvatar`.
+
+### `handleAuthApiRoute(ctx)`
+
+**Behavior:**
+
+- Matches `routePath` starting with `/auth/api`.
+- Looks up the provider via `getOAuthProviders().find((p) => p.name === routePath.split('/')[3])`.
+- For full OAuth providers (`isFullOAuthProvider(provider)`):
+  - `createOAuthState(provider.name)` produces a CSRF state token; failure returns `500 login.oauthStateInitFailed`.
+  - Builds the provider's authorization URL with `client_id`, `redirect_uri`, `scope`, `response_type=code`, `prompt=select_account`, `state`, and emits a `302`.
+- For credentials provider:
+  - Applies an IP-keyed rate limit (`key: ip:<remote>:auth:credentials`) using `projectConfig.rateLimiting.defaultApiLimit` + `windowMs`. On hit, dispatches `rateLimitExceeded` hook and returns `{ status: false, reason: 'api.rateLimitExceeded', errorParams: [{ key: 'seconds', value: resetIn }] }`.
+  - Calls `loginWithCredentials(params)`. On success: delete existing session, choose cookie-based vs header-based token via `x-session-based-token` header (overrides `projectConfig.session.basedToken`), then emit `Set-Cookie` or `X-Session-Token`.
+  - Final envelope: `{ status, reason, session, authenticated }`.
+
+**Errors:** unknown provider -> `{ status: false, reason: 'login.providerNotFound' }`; thrown errors bubble to the outer `httpHandler` error path.
+
+### `handleAuthCallbackRoute(ctx)`
+
+**Behavior:**
+
+- Matches `routePath` starting with `/auth/callback`.
+- Computes `baseLocation = process.env.DNS || projectConfig.app.publicUrl || '/'` (the `||` is intentional — empty `DNS` falls through; `??` would shadow `app.publicUrl`).
+- Delegates to `loginCallback(routePath, req, res, { defaultRedirectUrl })` from `@luckystack/login`.
+- On failure: `401 'Login failed'`.
+- On success: delete existing session, then redirect (`302`). With `projectConfig.session.basedToken: true` the token rides as `?token=...` in the query; otherwise it's emitted as a session cookie.
+
+### `handleApiRoute(ctx)`
+
+**Behavior:**
+
+- Matches every path starting with `/api/`.
+- Detects SSE intent via `shouldUseHttpStream({ acceptHeader, queryString })`: returns true if `Accept` contains `text/event-stream` or `?<projectConfig.http.stream.queryParam>=<enabledValue>` (or `=1`). When true, initializes an SSE response header and tracks client disconnect via `req.on('close', ...)`.
+- Strips `/api/` prefix; empty name -> `400 api.invalidName` (or SSE `final` event with same payload).
+- Calls `handleHttpApiRequest({ name, data, token, requesterIp, xLanguageHeader, acceptLanguageHeader, method, stream? })` from `@luckystack/api`. The `stream` callback emits `event: stream` SSE frames during long-running calls.
+- Emits the result (`event: final` for SSE, or `JSON.stringify(result)` + `res.writeHead(result.httpStatus)` for non-SSE).
+
+**Errors:** any thrown error is logged + captured to Sentry, `apiError` hook dispatched, and the envelope `500 api.invalidRequestFormat` is returned (over SSE or JSON).
+
+### `handleSyncRoute(ctx)`
+
+**Behavior:**
+
+- Matches every path starting with `/sync/`.
+- Only `POST` is allowed; other methods return `405 sync.methodNotAllowed`.
+- Normalizes params into `{ data, receiver, ignoreSelf?, cb? }`. Empty `receiver` is allowed (`''`).
+- Calls `handleHttpSyncRequest({ name: 'sync/<rest>', cb, data, receiver, ignoreSelf, token, requesterIp, xLanguageHeader, acceptLanguageHeader, stream? })` from `@luckystack/sync`.
+- SSE handling mirrors `handleApiRoute`.
+
+**Errors:** mirrors `handleApiRoute` — logs, Sentry, `syncError` hook, returns `500 sync.invalidRequestFormat`.
+
+### `handleCustomRoutes(ctx)`
+
+**Behavior:**
+
+- Iterates every handler registered via `registerCustomRoute(...)` in registration order; first one to return `true` or end the response wins.
+- If none handled, falls back to the inline `options.customRoutes` if provided.
+- Each handler is wrapped in `tryCatch` — on throw it logs via `getLogger().error`, calls `captureException`, and emits `500 server.customRouteFailed` (returning `true` so dispatch stops).
+
+### `handleStaticAndSpaFallback(ctx)`
+
+**Behavior:**
+
+- `/assets/*` paths: slice from the first `/assets/` occurrence, temporarily rewrite `req.url` to the asset path, call `options.serveFile`, restore `req.url`. Without `serveFile`, returns `404 Not Found`.
+- Paths matching `KNOWN_STATIC_FILE_REGEX` (`/^\/(assets\/[a-zA-Z0-9_\-/]+|[a-zA-Z0-9_\-]+)\.(png|jpg|jpeg|gif|svg|html|css|js)$/`): call `serveFile` directly without URL rewrite.
+- Other paths that have an extension `path.extname(routePath)`: `404 Not Found` (text/plain).
+- Extensionless paths (SPA routes): rewrite `req.url` to `/`, call `serveFile`. Without `serveFile`, returns `404 Not Found`.
+
+**Why the rewrite around `serveFile`:** consumers (Vite, custom static middleware) read `req.url`. We swap then restore so downstream loggers / metrics see the original URL.
+
+## Custom-route registry
+
+```typescript
+export const registerCustomRoute: (handler: CustomRouteHandler) => void;
+export const getCustomRoutes: () => readonly CustomRouteHandler[];
+export const clearCustomRoutes: () => void;
+```
+
+- `registerCustomRoute(handler)` — appends to an in-memory array. Called by overlay packages (`@luckystack/docs-ui` mounts `/_docs` this way).
+- `getCustomRoutes()` — read snapshot; iterated by `handleCustomRoutes`.
+- `clearCustomRoutes()` — empty the array; used by `@luckystack/test-runner`'s reset flow.
+
+The handler signature:
+
+```typescript
+type CustomRouteHandler = (
+  req: IncomingMessage,
+  res: ServerResponse,
+  ctx: RouteContext,
+) => Promise<boolean> | boolean;
+
+interface RouteContext {
+  routePath: string;
+  method: string;
+  queryString: string | undefined;
+  token: string | null;
+}
+```
+
+Return `true` (or end the response) when handled. Throws are caught and emit `500 server.customRouteFailed`.
+
+**Example — webhook receiver:**
+
+```typescript
+import { registerCustomRoute } from '@luckystack/server';
+
+registerCustomRoute(async (req, res, ctx) => {
+  if (ctx.routePath !== '/webhooks/stripe') return false;
+  if (ctx.method !== 'POST') {
+    res.writeHead(405);
+    res.end();
+    return true;
+  }
+  // verify signature, process body ...
+  res.writeHead(200);
+  res.end('ok');
+  return true;
+});
+```
+
+**Example — health alias for an external monitor:**
+
+```typescript
+registerCustomRoute(async (_req, res, ctx) => {
+  if (ctx.routePath !== '/healthz') return false;
+  res.statusCode = 200;
+  res.end('ok');
+  return true;
+});
+```
+
+## SSE streaming
+
+`/api/*` and `/sync/*` both support Server-Sent Events when the client opts in. Helpers live in `packages/server/src/sse.ts`:
+
+| Helper | Behavior |
+| --- | --- |
+| `shouldUseHttpStream({ acceptHeader, queryString })` | Returns `true` if `Accept` includes `text/event-stream` OR the query string contains `<projectConfig.http.stream.queryParam>=<enabledValue>` (or `=1`). |
+| `initSseResponse(res)` | Writes `200` with `Content-Type: text/event-stream`, `Cache-Control: no-cache, no-transform`, `Connection: keep-alive`, `X-Accel-Buffering: no`. Emits `projectConfig.http.stream.connectedComment` as a keepalive comment if configured. |
+| `sendSseEvent({ res, event, data })` | Writes `event: <event>\ndata: <json>\n\n`. No-op once `res.writableEnded`. |
+
+Lifecycle in `handleApiRoute` / `handleSyncRoute`:
+
+1. Decide SSE vs JSON via `shouldUseHttpStream`.
+2. If SSE, call `initSseResponse(res)` and `req.on('close', () => { streamClosed = true; })`.
+3. Pass a `stream` callback to `handleHttpApiRequest` / `handleHttpSyncRequest` that emits `event: stream` frames while the request is processing.
+4. On completion, emit `event: final` with the result envelope and call `res.end()`.
+5. On error, emit `event: error` with the `500 *.invalidRequestFormat` envelope.
+
+## Hooks dispatched
+
+| Hook | Payload | When |
+| --- | --- | --- |
+| `rateLimitExceeded` | `{ scope, key, limit, windowMs, count, route, ip }` | `handleAuthApiRoute` credentials path when IP limit is exceeded. |
+| `apiError` | `{ route, method, requestId, error }` | `handleApiRoute` outer error path. |
+| `syncError` | `{ route, method, requestId, error }` | `handleSyncRoute` outer error path. |
+| `csrfMismatch` | `{ route, method, requestId, userId, providedToken }` | `enforceCsrfOnStateChangingRequest` (see `request-pipeline.md`). |
+| `preHttpRequest` | `{ method, url, requestId, origin, headers }` | Every incoming request before dispatch (see `request-pipeline.md`). |
+
+## Config keys consumed
+
+| Source | Key | Effect |
+| --- | --- | --- |
+| config | `projectConfig.http.healthEndpoint` | Default `/_health`. |
+| config | `projectConfig.http.liveEndpoint` | Default `/livez`. |
+| config | `projectConfig.http.readyEndpoint` | Default `/readyz`. |
+| config | `projectConfig.http.testResetEndpoint` | Default `/_test/reset`. |
+| config | `projectConfig.http.stream.queryParam` / `enabledValue` / `connectedComment` | SSE opt-in query parameter + initial keepalive comment. |
+| config | `projectConfig.http.sessionCookieName` | Cookie name written by `/auth/api` / `/auth/callback`. |
+| config | `projectConfig.session.basedToken` | Cookie vs header token transport. |
+| config | `projectConfig.rateLimiting.defaultApiLimit` / `windowMs` | Credentials login rate limit. |
+| env | `DNS` | Legacy public origin override for callback redirect. |
+| env | `TEST_RESET_TOKEN` | Consumed by `/_test/reset` — see `security-defaults.md`. |
+
+## Related
+
+- Function INDEX: `packages/server/CLAUDE.md`
+- Request pipeline: `packages/server/docs/request-pipeline.md`
+- Security defaults: `packages/server/docs/security-defaults.md`
+- API delegate: `docs/ARCHITECTURE_API.md`
+- Sync delegate: `docs/ARCHITECTURE_SYNC.md`
+- README: `packages/server/README.md`

package/docs/request-pipeline.md

@@ -0,0 +1,198 @@
+# Request Pipeline
+
+> Deep specs. Bron: `packages/server/src/httpHandler.ts`, `packages/server/src/loadSocket.ts`, `packages/server/src/sse.ts`. Bijgewerkt: 2026-05-20.
+
+## Overview
+
+`handleHttpRequest` is the orchestrator that every HTTP request flows through. Its job is fixed and intentionally narrow: enforce origin policy, set headers, parse session + CSRF, run pre-request hook, decide method validity, parse params, then walk two ordered handler tables. Each handler in those tables (see `http-routes.md`) is single-purpose and returns `boolean`.
+
+Top-level flow:
+
+1. Build session-cookie option string (`HttpOnly; SameSite; Path; Max-Age; Secure?`).
+2. `enforceOriginPolicy(req, res)` — origin/referer gate. Read-only methods without origin pass; state-changing methods without origin are 403.
+3. `setSecurityHeaders(req, res, origin)` — framework defaults + consumer builder (see `security-defaults.md`).
+4. Resolve `requestId` from `x-request-id` (echoed back) or `randomUUID()`. Set `X-Request-Id` response header.
+5. Dispatch `preHttpRequest` hook with a sanitized header subset. A `HookStopSignal` returns `JSON.stringify({ status: 'error', errorCode })` at `signal.httpStatus ?? 403`.
+6. `OPTIONS` -> `204` and return.
+7. Method allowlist: `GET / POST / PUT / DELETE`. Anything else -> `404` plain text.
+8. Extract session token via `extractTokenFromRequest`. Sliding-cookie refresh when the cookie + session both exist.
+9. `enforceCsrfOnStateChangingRequest(...)` — see `security-defaults.md`.
+10. Dispatch `PRE_PARAMS_ROUTES` (`csrf`, `favicon`, `livez`, `readyz`, `_health`, `_test/reset`) — fast paths that should not consume the body.
+11. `parseRequestParams(...)` — `await getParams({ method, req, res, queryString })`. Streams the body when applicable; bails out if `res.writableEnded`.
+12. Dispatch `POST_PARAMS_ROUTES` (`uploads`, `auth/api`, `auth/callback`, `api`, `sync`, `customRoutes`, `staticAndSpaFallback`).
+
+Socket.io runs on a parallel lifecycle — attached to the same `http.Server` via `loadSocket(httpServer, { maxHttpBufferSize })` but with its own event-driven dispatch.
+
+## API Reference
+
+### `handleHttpRequest(req, res, options): Promise<void>`
+
+**Signature:**
+
+```typescript
+export const handleHttpRequest = async (
+  req: IncomingMessage,
+  res: ServerResponse,
+  options: CreateLuckyStackServerOptions,
+): Promise<void>;
+```
+
+**Parameters:**
+
+| Field | Type | Purpose |
+| --- | --- | --- |
+| `req` | `IncomingMessage` | Raw Node request. |
+| `res` | `ServerResponse` | Raw Node response. |
+| `options` | `CreateLuckyStackServerOptions` | Forwarded to the route handler context (used by `staticAndSpaFallback` / `customRoutes`). |
+
+**Returns:** `Promise<void>`. The handler resolves once it has ended the response (or short-circuited).
+
+**Behavior (execution order):**
+
+- Read `projectConfig` once and snapshot `shouldLogDev`, `sessionCookieName`, `sessionCookieOptions`.
+- `enforceOriginPolicy`: state-changing requests without `Origin` / `Referer` are rejected with `403 'Forbidden'`. A present-but-disallowed origin is also `403`. Read-only methods without origin pass to keep health probes and asset fetches working.
+- `setSecurityHeaders`: see `security-defaults.md`. Consumer builder runs after defaults; errors fall through to defaults.
+- Compute `requestId`. Honor `x-request-id` (idempotent for retrying proxies); otherwise mint a `randomUUID()`. Echo as `X-Request-Id` response header.
+- Build a sanitized `safeHeaders` map (drops `authorization`, `cookie`, `set-cookie`, `x-csrf-token`).
+- Dispatch `preHttpRequest` hook. On `result.stopped`: respond with `signal.httpStatus ?? 403` and `application/json { status: 'error', errorCode: signal.errorCode }`.
+- `OPTIONS` -> `writeHead(204)` + `end()`.
+- Reject methods outside `GET / POST / PUT / DELETE` with `404 text/plain`.
+- Split `req.url` into `[routePath, queryString]`.
+- `extractTokenFromRequest(req)` — pulls token from cookie or `Authorization`.
+- `refreshSessionCookieIfPresent` — sliding expiration in cookie mode. Re-emits `Set-Cookie` with refreshed `Max-Age` when the session exists.
+- `enforceCsrfOnStateChangingRequest` — returns `true` when it has ended the response; the request loop bails.
+- `dispatchRoutes(PRE_PARAMS_ROUTES, { ...baseCtx, params: {} })` — first handler to return `true` (or end `res`) wins; otherwise the chain falls through.
+- `parseRequestParams` — pulls body when method needs one. If `res.writableEnded` (because the body parser ended with an error), bail out.
+- `dispatchRoutes(POST_PARAMS_ROUTES, { ...baseCtx, params })`.
+
+**Errors / Edge cases:**
+
+- The orchestrator itself never wraps the table in `tryCatch`. Per-route handlers wrap their work; `customRoutes` handlers are caught and reported as `500 server.customRouteFailed`.
+- Handler order is fixed; mutating it requires editing `PRE_PARAMS_ROUTES` / `POST_PARAMS_ROUTES`.
+- A handler that ends `res` but returns `false` still terminates dispatch — `dispatchRoutes` checks `res.writableEnded` after each call.
+
+---
+
+### `dispatchRoutes(handlers, ctx): Promise<boolean>`
+
+**Signature:**
+
+```typescript
+const dispatchRoutes = async (
+  handlers: HttpRouteHandler[],
+  ctx: HttpRouteContext,
+): Promise<boolean>;
+```
+
+**Behavior:**
+
+- Iterates `handlers` in array order.
+- After each call, if `handled === true` OR `ctx.res.writableEnded` -> return `true` (stop).
+- Otherwise continue. Return `false` if none handled.
+
+**Edge case:** a handler that writes a partial response without ending (`res.write(...)`) without setting `writableEnded` still falls through unless it returns `true`. Always end the response or return `true`.
+
+---
+
+### `loadSocket(httpServer, options?): SocketIOServer`
+
+**Signature:**
+
+```typescript
+export interface LoadSocketOptions {
+  maxHttpBufferSize?: number;
+}
+
+export const loadSocket = (
+  httpServer: HttpServer,
+  options: LoadSocketOptions = {},
+): SocketIOServer;
+```
+
+**Parameters:**
+
+| Field | Type | Default | Purpose |
+| --- | --- | --- | --- |
+| `httpServer` | `http.Server` | required | The HTTP server returned by `createLuckyStackServer`. Socket.io upgrades on it. |
+| `options.maxHttpBufferSize` | `number` | `projectConfig.socket.maxHttpBufferSize` | Forwarded to Socket.io. |
+
+**Returns:** the `SocketIOServer` instance. Also registered globally via `setIoInstance(io)` so framework code (presence, broadcast helpers) can reach it without a parameter.
+
+**Behavior:**
+
+- Construct `SocketIOServer` with:
+  - CORS: methods `GET / POST / PUT / DELETE / OPTIONS`, origin callback delegates to `allowedOrigin`, `credentials: true`. Empty origin is allowed (Socket.io polling without an origin header).
+  - `maxHttpBufferSize`, `pingTimeout`, `pingInterval` from `projectConfig.socket`.
+- `setIoInstance(io)` and `attachSocketRedisAdapter(io)` — required for room broadcasts to fan out across instances.
+- `io.on('connect', ...)` per-socket lifecycle:
+  - Extract token, cache `activityBroadcasterEnabled` + `locationProviderEnabled` flags + `preferredLocale`.
+  - When token present: `socketConnected({ token, io })` (presence).
+  - Dispatch `onSocketConnect` hook with `{ socketId, token, ip }`.
+  - Wire event handlers (delegates):
+    - `apiRequest` -> `handleApiRequest({ msg, socket, token })` from `@luckystack/api`.
+    - `sync` -> `handleSyncRequest({ msg, socket, token })` from `@luckystack/sync`.
+    - `joinRoom` -> validate, `getSession(token)`, dispatch `preRoomJoin` (may stop), `socket.join(group)`, persist `roomCodes` via `saveSession`, emit `buildJoinRoomResponseEventName(responseIndex)`, dispatch `postRoomJoin`. Serialized per-token via `withSessionLock`.
+    - `leaveRoom` -> symmetric to `joinRoom`. Dispatches `preRoomLeave` / `postRoomLeave`.
+    - `getJoinedRooms` -> emits visible rooms (filters out `socket.id` and the token room).
+    - `disconnect` -> dispatch `onSocketDisconnect`, then either `socketDisconnecting` (if presence is enabled) or a dev log line.
+    - `updateLocation` -> when location provider is enabled, mutate session location, dispatch `onLocationUpdate`. Coordinates with `socketLeaveRoom` from presence.
+  - When `activityBroadcasterEnabled && token`: `initActivityBroadcaster({ socket, token })`.
+  - When token present: `socket.join(token)` — every authenticated socket joins its own token room so server-side code can target a user by token.
+
+**Errors / Edge cases:**
+
+- `withSessionLock(token, fn)` serializes per-token mutations to prevent read-modify-write races on `session.roomCodes`. The lock's `then(fn, fn)` ensures a failed prior call doesn't block the next caller.
+- Legacy session shapes that still carry `code` / `codes` are stripped on save via `sanitizeSessionRoomKeys`.
+- Room validation: empty / non-string `group` -> emit `room.invalid` error frame.
+- `responseIndex` is required for join/leave/getJoinedRooms; non-number values silently no-op (the client never gets a response — Socket.io's response indexing is purely opt-in).
+
+## SSE streaming inside the pipeline
+
+`/api/*` and `/sync/*` opt into SSE via `shouldUseHttpStream({ acceptHeader, queryString })`. When enabled:
+
+- `initSseResponse(res)` writes `200 text/event-stream` + `Cache-Control: no-cache, no-transform` + `Connection: keep-alive` + `X-Accel-Buffering: no`. Optional `projectConfig.http.stream.connectedComment` is sent as the initial keepalive comment.
+- The route handler passes a `stream` callback to its delegate. The delegate emits per-event payloads; the handler forwards each as `event: stream\ndata: <json>\n\n`.
+- On completion, emit `event: final` with the result envelope. On error, `event: error`. Then `res.end()`.
+- `req.on('close', ...)` flips a `streamClosed` flag so post-disconnect writes are suppressed.
+
+## Hooks dispatched
+
+| Hook | Payload | When |
+| --- | --- | --- |
+| `preHttpRequest` | `{ method, url, requestId, origin, headers }` | Before route dispatch. May stop with `HookStopSignal` to short-circuit. `headers` omits sensitive entries. |
+| `csrfMismatch` | `{ route, method, requestId, userId, providedToken: boolean }` | Cookie-mode CSRF check rejects a write. Token VALUE is never in payload. |
+| `apiError` / `syncError` | `{ route, method, requestId, error }` | Outer error path of `/api/*` / `/sync/*` handlers (see `http-routes.md`). |
+| `rateLimitExceeded` | `{ scope, key, limit, windowMs, count, route, ip }` | Credentials login. |
+| `onSocketConnect` / `onSocketDisconnect` | `OnSocketConnectPayload` / `OnSocketDisconnectPayload` | Socket lifecycle (see `create-server.md`). |
+| `preRoomJoin` / `postRoomJoin` | `PreRoomJoinPayload` / `PostRoomJoinPayload` | Room-join lifecycle inside `loadSocket`. `pre*` may stop. |
+| `preRoomLeave` / `postRoomLeave` | `PreRoomLeavePayload` / `PostRoomLeavePayload` | Room-leave lifecycle inside `loadSocket`. `pre*` may stop. |
+| `onLocationUpdate` | `OnLocationUpdatePayload` | When the presence layer reports a path change. |
+
+## Config keys consumed
+
+| Source | Key | Effect |
+| --- | --- | --- |
+| env | `SECURE` | `'true'` -> session cookies get the `Secure;` flag. |
+| config | `projectConfig.logging.devLogs` | Gates per-request debug logs (sanitized params + method/route). |
+| config | `projectConfig.http.cors.*` / `securityHeaders.*` | Response headers (see `security-defaults.md`). |
+| config | `projectConfig.http.sessionCookieName` / `sessionCookiePath` / `sessionCookieSameSite` | Session cookie shape. |
+| config | `projectConfig.session.expiryDays` / `basedToken` | Cookie `Max-Age` + CSRF middleware activation predicate. |
+| config | `projectConfig.http.stream.queryParam` / `enabledValue` / `connectedComment` | SSE opt-in + keepalive. |
+| config | `projectConfig.socket.maxHttpBufferSize` / `pingTimeout` / `pingInterval` | Socket.io transport options. |
+| config | `projectConfig.socketActivityBroadcaster` / `locationProviderEnabled` | Gate presence-related socket handlers. |
+
+## Error fall-through
+
+- The outer `handleHttpRequest` does NOT wrap the table in a global `tryCatch`. Each handler is responsible for its own errors.
+- `handleApiRoute` / `handleSyncRoute` wrap their body and emit `500 *.invalidRequestFormat` after dispatching `apiError` / `syncError`.
+- `handleCustomRoutes` wraps each handler and emits `500 server.customRouteFailed` on throw.
+- Throws from inside a `dispatchHook` handler propagate per `@luckystack/core`'s `dispatchHook` semantics — generally they are caught and logged inside the hook system.
+
+## Related
+
+- Function INDEX: `packages/server/CLAUDE.md`
+- HTTP routes: `packages/server/docs/http-routes.md`
+- Security defaults: `packages/server/docs/security-defaults.md`
+- Create server: `packages/server/docs/create-server.md`
+- Architecture: `docs/ARCHITECTURE_API.md`, `docs/ARCHITECTURE_SOCKET.md`, `docs/ARCHITECTURE_SYNC.md`, `docs/ARCHITECTURE_SESSION.md`
+- README: `packages/server/README.md`