Event: {$notifications.event}
\r\nData: {JSON.stringify($notifications.data)}
\r\n{/if}\r\n```\r\n\r\n### Step 4: Publish from the server\r\n\r\n**src/routes/api/notify/+server.js**\r\n```js\r\nexport async function POST({ request, platform }) {\r\n const data = await request.json();\r\n\r\n // This sends to ALL clients subscribed to 'notifications'\r\n platform.publish('notifications', 'new-message', data);\r\n\r\n return new Response('OK');\r\n}\r\n```\r\n\r\n**Build and run:**\r\n```bash\r\nnpm run build\r\nnode build\r\n```\r\n\r\n---\r\n\r\n## Quick start: WSS (secure WebSocket)\r\n\r\nWSS works automatically when you enable TLS. WebSocket connections upgrade over the same HTTPS port.\r\n\r\n**svelte.config.js**\r\n```js\r\nimport adapter from 'svelte-adapter-uws';\r\n\r\nexport default {\r\n kit: {\r\n adapter: adapter({\r\n websocket: true\r\n })\r\n }\r\n};\r\n```\r\n\r\n```bash\r\nnpm run build\r\nSSL_CERT=/path/to/cert.pem SSL_KEY=/path/to/key.pem node build\r\n```\r\n\r\nThe client store automatically uses `wss://` when the page is served over HTTPS - no configuration needed on the client side.\r\n\r\n---\r\n\r\n## Development, Preview & Production\r\n\r\n### `npm run dev` - works (with the Vite plugin)\r\n\r\nThe Vite plugin is required for WebSocket support in both dev and production (see [Step 2](#step-2-add-the-vite-plugin-required)). It spins up a `ws` WebSocket server alongside Vite's dev server, so your client store and `event.platform` work identically to production.\r\n\r\nChanges to your `hooks.ws` file are picked up automatically - the plugin reloads the handler on save and closes existing connections so they reconnect with the new code. No dev server restart needed.\r\n\r\n**Note:** The dev plugin enforces `allowedOrigins` on WebSocket upgrades the same way the production handler does. For local dev scenarios that need to accept arbitrary origins (e.g. WSS from a staging client during integration), pass `devSkipOriginCheck: true` to the plugin: `uws({ devSkipOriginCheck: true })`.\r\n\r\n**vite.config.js**\r\n```js\r\nimport { sveltekit } from '@sveltejs/kit/vite';\r\nimport uws from 'svelte-adapter-uws/vite';\r\n\r\nexport default {\r\n plugins: [sveltekit(), uws()]\r\n};\r\n```\r\n\r\n### `npm run preview` - WebSockets don't work\r\n\r\nSvelteKit's preview server is Vite's built-in HTTP server. It doesn't know about uWebSockets.js or WebSocket upgrades. Your HTTP routes and SSR will work, but **WebSocket connections will fail**.\r\n\r\nUse `node build` instead of preview for testing WebSocket features.\r\n\r\n### `node build` - production, everything works\r\n\r\nThis is the real deal. uWebSockets.js handles everything:\r\n\r\n```bash\r\nnpm run build\r\nnode build\r\n```\r\n\r\nOr with environment variables:\r\n```bash\r\nPORT=8080 HOST=0.0.0.0 node build\r\n```\r\n\r\nOr with TLS:\r\n```bash\r\nSSL_CERT=./cert.pem SSL_KEY=./key.pem PORT=443 node build\r\n```\r\n\r\n---\r\n\r\n**Configuration**\r\n\r\n## Adapter options\r\n\r\n```js\r\nadapter({\r\n // Output directory for the build\r\n out: 'build', // default: 'build'\r\n\r\n // Precompress static assets with brotli and gzip\r\n precompress: true, // default: true\r\n\r\n // Prefix for environment variables (e.g. 'MY_APP_' -> MY_APP_PORT)\r\n envPrefix: '', // default: ''\r\n\r\n // Health check endpoint (set to false to disable)\r\n healthCheckPath: '/healthz', // default: '/healthz'\r\n\r\n // WebSocket configuration\r\n websocket: true // or false, or an options object (see below)\r\n})\r\n```\r\n\r\n### WebSocket options\r\n\r\n```js\r\nadapter({\r\n websocket: {\r\n // Path for WebSocket connections\r\n path: '/ws', // default: '/ws'\r\n\r\n // Path to your custom handler module (auto-discovers src/hooks.ws.js if omitted)\r\n handler: './src/lib/server/websocket.js', // default: auto-discover\r\n\r\n // Max message size in bytes (connections sending larger messages are closed)\r\n maxPayloadLength: 1024 * 1024, // default: 1 MB\r\n\r\n // Seconds of inactivity before the connection is closed\r\n idleTimeout: 120, // default: 120\r\n\r\n // Max bytes of backpressure per connection before messages are dropped.\r\n // uWS defaults to 64 KB; this adapter uses 1 MB to handle pub/sub spikes.\r\n // Lower this if you expect many slow consumers.\r\n maxBackpressure: 1024 * 1024, // default: 1 MB\r\n\r\n // Enable per-message deflate compression\r\n compression: false, // default: false\r\n\r\n // Automatically send pings to keep the connection alive\r\n sendPingsAutomatically: true, // default: true\r\n\r\n // Seconds before an async upgrade handler is rejected with 504 (0 to disable)\r\n upgradeTimeout: 10, // default: 10\r\n\r\n // Sliding-window rate limit: max WebSocket upgrade requests per IP per window.\r\n // Prevents connection flood attacks. Uses a sliding window so a client cannot\r\n // double the effective rate by placing requests at a fixed-window boundary.\r\n // Set to 0 to disable.\r\n upgradeRateLimit: 10, // default: 10\r\n upgradeRateLimitWindow: 10, // window size in seconds, default: 10\r\n\r\n // Allowed origins for WebSocket connections\r\n // 'same-origin' - only accept where Origin matches Host and scheme (default)\r\n // '*' - accept from any origin\r\n // ['https://example.com'] - whitelist specific origins\r\n // Requests without an Origin header (non-browser clients) are rejected\r\n // unless an upgrade handler is configured to authenticate them.\r\n allowedOrigins: 'same-origin' // default: 'same-origin'\r\n }\r\n})\r\n```\r\n\r\n### Backpressure and connection limits\r\n\r\nThese options control how the server handles misbehaving or slow clients at the WebSocket level:\r\n\r\n**`maxPayloadLength`** (default: 1 MB) - the maximum size of a single incoming WebSocket message. If a client sends a message larger than this, uWS closes the connection immediately (not just the message - the entire connection is dropped). Set this based on the largest message your application expects to receive. uWS's own default is 16 KB, which the adapter previously matched; the 1 MB default ships now to handle typical app payloads in a single frame without forcing chunked-upload frameworks into ~12 KB chunks (which the previous 16 KB cap did). For a stricter cap, pin an explicit value (e.g. `16 * 1024` for the uWS-matching 16 KB).\r\n\r\n**`maxBackpressure`** (default: 1 MB) - the per-connection outbound send buffer, AND the threshold above which `publish` / `send` / `publishBatched` silently skip a subscriber. When a specific subscriber's buffer is over this size, uWS drops that frame *for that subscriber only* while continuing to deliver to every non-backpressured subscriber. This makes `publish` / `send` / `publishBatched` volatile-by-default for slow consumers (the right behavior for cursor positions, typing indicators, presence pings - see \"Volatile / fire-and-forget delivery\" below). The `drain` hook fires per-connection when the buffer empties again. Lower this if you want subscribers shed sooner; raise it if you prefer to keep the connection queued and absorb temporary slowness. uWS's own default is 64 KB; this adapter sets 1 MB to favor keeping the connection alive under pub/sub spikes.\r\n\r\n**`upgradeRateLimit`** (default: 10 per 10s window) - sliding-window rate limit on WebSocket upgrade requests per client IP. Clients exceeding the limit get a `429 Too Many Requests` response. The IP rate map is capped at 10,000 entries with LRU eviction by activity score, so sustained connection floods from many IPs don't cause unbounded memory growth.\r\n\r\n**`upgradeAdmission`** (default: disabled) - two-layer admission control on the upgrade path, both opt-in:\r\n\r\n- `maxConcurrent` caps how many upgrades may be in flight at once. Crossed requests get a fast `503 Service Unavailable` before any per-request work, so a connection storm can be shed without spending CPU on TLS, header parsing, or cookie decoding. Set this just above your steady-state in-flight count to act as a circuit breaker.\r\n- `perTickBudget` caps how many actual `res.upgrade()` calls run per Node.js event-loop tick. Once the budget is spent, subsequent calls are deferred via `setImmediate` so the loop is not starved by 10K synchronous handshakes from one I/O batch. Pre-upgrade work (rate limit, origin check, hook dispatch) still runs in the original tick; only the hand-off to the C++ upgrade path is paced. Start with `64` and adjust based on your peak burst envelope.\r\n\r\n```js\r\nadapter({\r\n websocket: {\r\n upgradeAdmission: { maxConcurrent: 1000, perTickBudget: 64 }\r\n }\r\n});\r\n```\r\n\r\nThe two layers are independent: each works without the other. Both default to `0` (disabled) so the upgrade path stays unchanged unless you opt in.\r\n\r\n#### Layered admission: upgrade-path + message-path\r\n\r\n`upgradeAdmission` operates at the WebSocket handshake. It sheds connection attempts before TLS work and before any per-request CPU is spent. That is the right primitive when the threat is \"too many clients are trying to connect\" - a connection flood, a thundering herd after a deploy, a runaway client retry loop.\r\n\r\nIt is NOT the right primitive when the threat is \"established connections are sending too many RPCs\" - a chatty client, an abusive presence ping loop, a misbehaving game tick. Those calls have already passed the handshake; the connection is open; you want to shed at the message dispatch layer instead.\r\n\r\nFor that second layer, [`svelte-adapter-uws-extensions`](https://github.com/lanteanio/svelte-adapter-uws-extensions) ships `createAdmissionControl`, an opt-in message-path admission wrapper that runs against already-accepted connections. The two stack naturally:\r\n\r\n```js\r\n// Production wiring sketch\r\nimport { createAdmissionControl } from 'svelte-adapter-uws-extensions';\r\n\r\nconst messageAdmission = createAdmissionControl({ /* RPC concurrency, per-key buckets, ... */ });\r\n\r\n// In hooks.ws.js\r\nexport function message(ws, ctx) {\r\n messageAdmission.run(ws, ctx, async () => {\r\n // ... your message handler ...\r\n });\r\n}\r\n\r\n// In svelte.config.js\r\nadapter({\r\n websocket: {\r\n upgradeAdmission: { maxConcurrent: 1000, perTickBudget: 64 } // handshake layer\r\n }\r\n});\r\n```\r\n\r\nThe two layers do not share state, configuration, or call sites. They cannot drift apart because the WebSocket lifecycle enforces the ordering: a connection that fails `upgradeAdmission` never reaches the message handler at all, so `createAdmissionControl` only ever sees connections that were already admitted at the handshake. The layering is a structural property, not a runtime one.\r\n\r\n### Security configuration\r\n\r\nDefense-in-depth opt-ins layered on top of `allowedOrigins`. All default to safe values; flip them only after the documented audit step.\r\n\r\n- **`websocket.authPathRequireOrigin`** (default `true`) - the `/__ws/auth` POST endpoint requires `x-requested-with: XMLHttpRequest`, `Sec-Fetch-Site: same-origin`, or an `Origin` matching `allowedOrigins`. The adapter client always stamps `x-requested-with` so the browser path is unaffected. Set `false` to accept native (non-browser) clients without those headers.\r\n- **`websocket.compressCredentialedResponses`** (default `false`) - requests carrying `Cookie` or `Authorization` skip dynamic brotli/gzip compression to defend against the [BREACH](https://en.wikipedia.org/wiki/BREACH) attack (compressed length leaks attacker-influenced reflected input alongside a secret). Set `true` only after auditing the page surface for BREACH defenses (random per-response masking, prefix randomization, no secrets reflected with attacker input). Build-time precompressed static files are unaffected.\r\n- **`websocket.unsafeSameOriginWithoutHostPin`** (default `false`) - when `allowedOrigins: 'same-origin'` is paired with no fronting trust (no `ORIGIN` env, no `HOST_HEADER` env, no native TLS, no `upgrade()` hook), the runtime throws at startup because the same-origin check then compares two attacker-controlled headers (Origin vs Host). Set `true` to restore the previous warn-only behavior. Pin the deployment shape first (`ORIGIN`, `HOST_HEADER`, native TLS, or an `upgrade()` hook).\r\n\r\n`websocket.allowSystemTopicSubscribe` (default `false`) and `websocket.allowNonAsciiTopics` (default `false`) are documented in [Topic validation](#topic-validation). The Vite plugin mirrors all of these flags; `devSkipOriginCheck` (default `false`) on the plugin disables the dev-mode `allowedOrigins` enforcement for local-only scenarios.\r\n\r\n### Capacity model\r\n\r\nEvery internal `Map` / `Set` that grows with client behaviour or topic cardinality has an explicit upper bound and a defined behaviour at saturation. The defaults are deliberately generous (1,000,000 across the board) - far above any healthy single-connection use, even at uWS's million-connection scale - so the cap catches obvious bugs and runaway clients without ever biting real apps. Aggregate memory at extreme scale is bounded separately by `upgradeAdmission.maxConcurrent`; per-connection caps are not the right place to defend against a 1M-connection DoS.\r\n\r\n| Site | Default cap | Behaviour at saturation | Override |\r\n|------|-------------|-------------------------|----------|\r\n| Subscriptions per connection | 1,000,000 | `subscribe-denied` with reason `'RATE_LIMITED'` | not exposed |\r\n| Pending `platform.request` calls per connection | 1,000,000 | promise rejects with \"pending requests exceeded\" | not exposed |\r\n| `sendCoalesced` keys per connection | 1,000,000 | drop oldest insertion-order entry on insert | not exposed |\r\n| Topic seq registry (`topicSeqs`) | 1,000,000 | one structured `console.warn` with topN publishers; publish continues | not exposed (resume protocol depends on persistence) |\r\n| Runaway-publisher warn dedup | 1,000,000 | FIFO-evict oldest entry on insert | not exposed |\r\n| `envelopePrefixCache` | 256 | FIFO half-evict | not exposed |\r\n| `decodeCache` | 256 | FIFO half-evict | not exposed |\r\n| SSR dedup in-flight | 500 | new request bypasses dedup | not exposed |\r\n| SSR dedup body buffer per request | 512 KB | response replays without dedup | not exposed |\r\n| Upgrade rate-limit IP map | 10,000 | LRU on 60s sweep | not exposed |\r\n| Aggregate live connections | unbounded by default | reject upgrade with 503 once `maxConcurrent` set | `upgradeAdmission.maxConcurrent` |\r\n| Outbound buffer per connection | 1 MB | uWS drops the frame for that subscriber only | `wsOptions.maxBackpressure` |\r\n\r\n**Plugin caps** all default to 1,000,000 with the same idiot-proof bias:\r\n\r\n| Plugin | Cap | Behaviour at saturation | Override |\r\n|--------|-----|-------------------------|----------|\r\n| `replay` | `maxTopics: 100`, ring `size: 1000` | LRU evict / ring overwrite | per-topic options |\r\n| `presence` | `maxConnections: 1_000_000`, `maxTopics: 1_000_000` | drop oldest insertion-order entry | constructor options |\r\n| `cursor` | `maxConnections: 1_000_000`, `maxTopics: 1_000_000` | drop oldest insertion-order entry; pending throttle timers cleared | constructor options |\r\n| `throttle` / `debounce` | `maxTopics: 1_000_000` | flush pending then drop oldest topic | second arg to `throttle(interval, options)` / `debounce(...)` |\r\n| `lock` | `maxKeys: 1_000_000` | new-key `withLock` rejects with \"active key count exceeded\" | constructor options |\r\n| `ratelimit` | `maxBuckets: 1_000_000` | drop oldest insertion-order bucket on insert | constructor options |\r\n| `queue` | `maxSize: 1_000_000` per key | `push` rejects, `onDrop` callback fires | constructor options (pass `Infinity` to opt out) |\r\n| `dedup` | `maxEntries: 10_000` | soft + hard cap, oldest insertion-order evicted | constructor options |\r\n| `session` | `maxEntries: 10_000` | soft + hard cap, oldest insertion-order evicted | constructor options |\r\n| `groups` | `maxMembers` (per group, required) | `join` returns `false`, `onFull` callback fires | required option |\r\n\r\nTwo policy notes:\r\n\r\n- **Per-conn cap math at uWS scale.** `1,000,000 subscriptions × 1,000,000 connections` is more than any realistic process can handle. The per-conn caps catch single-connection bugs (a `for (i=0; iCannot subscribe to {$denials.topic}: {$denials.reason}
\r\n{/if}\r\n```\r\n\r\nThe server's `subscribe` hook controls denial reasons:\r\n\r\n```js\r\nexport function subscribe(ws, topic, { platform }) {\r\n const { userId, role } = ws.getUserData();\r\n if (!userId) return 'UNAUTHENTICATED'; // -> subscribe-denied\r\n if (topic.startsWith('admin') && role !== 'admin') {\r\n return 'FORBIDDEN';\r\n }\r\n // omit / return undefined / return true -> subscribed\r\n}\r\n```\r\n\r\nOld clients that send `subscribe` without a `ref` get no ack frame (silent allow / silent deny, as before). Old servers that ignore `ref` don't break new clients - they just don't emit acks; the client sees no entry in `denials` and treats the subscription as active.\r\n\r\n`subscribe-batch` works the same way: one ack frame per topic in the batch, all sharing the batch's single `ref`.\r\n\r\nFor batch subscribes (typically the resubscribe-on-reconnect path) you can opt into a single-call `subscribeBatch` hook instead of paying N `subscribe` calls. The framework calls it once with all pre-validated topics and applies the returned per-topic decisions:\r\n\r\n```js\r\nexport async function subscribeBatch(ws, topics, { platform }) {\r\n const { userId } = ws.getUserData();\r\n // One DB query for all topics instead of N\r\n const allowed = await db.allowedTopics(userId, topics);\r\n const allowedSet = new Set(allowed);\r\n const denials = {};\r\n for (const topic of topics) {\r\n if (!allowedSet.has(topic)) denials[topic] = 'FORBIDDEN';\r\n }\r\n return denials; // omit a topic -> allow; false -> FORBIDDEN; string -> that reason\r\n}\r\n```\r\n\r\nIf you only export `subscribe`, the framework still loops it per topic for batch-subscribes (no behaviour change). Export `subscribeBatch` only when you need the single-query optimization. The hook is sync in this version; for async lookups, pre-cache user grants on `userData` during `upgrade`.\r\n\r\n### Message protocol\r\n\r\nThe adapter uses a JSON envelope format for all pub/sub messages: `{ topic, event, data, seq? }`. Control messages from the client store (`subscribe`, `unsubscribe`, `subscribe-batch`, `resume`) use `{ type, topic, ref? }`, `{ type, topics, ref? }`, or `{ type, sessionId, lastSeenSeqs }`. The server emits `{\"type\":\"welcome\",\"sessionId\":\"...\"}` on open, `{\"type\":\"resumed\"}` after a resume frame, and `{\"type\":\"subscribed\",...}` / `{\"type\":\"subscribe-denied\",...}` per topic when the client supplied a `ref`.\r\n\r\nTo avoid JSON-parsing every incoming message, the handler uses a byte-prefix discriminator: control messages start with `{\"type\"` (byte 3 is `y`), while user envelopes start with `{\"topic\"` (byte 3 is `o`). A single byte comparison skips `JSON.parse` entirely for user messages. Messages over 8 KB are also skipped (generous ceiling for `subscribe-batch` with many topics, well above any realistic control message).\r\n\r\n### Topic validation\r\n\r\nTopics submitted by clients are validated before being accepted:\r\n\r\n- Must be between 1 and 256 characters\r\n- Default accept set is printable ASCII (0x20-0x7E) excluding `\"` and `\\`. Control bytes, line separators (U+2028/U+2029), bidirectional overrides (U+202E), the byte-order mark, and other non-ASCII runes are rejected at the wire boundary so log dashboards and admin UIs see a clean, greppable topic name. Apps that legitimately accept non-ASCII topic names from clients can opt in via `websocket.allowNonAsciiTopics: true` (always-illegal `\"` and `\\` remain rejected).\r\n- `subscribe-batch` accepts at most 256 topics per message (the client only sends what it was subscribed to before a reconnect)\r\n\r\nTopics prefixed with `__` are reserved for framework-internal channels (presence uses `__presence:*`, replay uses `__replay:*`, plus `__signal:*`, `__group:*`, `__rpc`, etc.). Wire-level subscribes to `__`-prefixed topics are rejected with `INVALID_TOPIC`, so a client cannot intercept signals routed to other users or plugin broadcasts. Server-side `platform.subscribe(ws, '__signal:userId')` (the legitimate pattern that `enableSignals` uses) still works because the block is on the wire layer only. Advanced apps that intentionally route public topics through the `__` prefix can opt out via `websocket.allowSystemTopicSubscribe: true`.\r\n\r\n### Explicit handler path\r\n\r\nIf your handler is somewhere other than `src/hooks.ws.js`:\r\n\r\n```js\r\nadapter({\r\n websocket: {\r\n handler: './src/lib/server/websocket.js'\r\n }\r\n})\r\n```\r\n\r\n### What the handler gets\r\n\r\nThe `upgrade` function receives an `UpgradeContext`:\r\n\r\n```js\r\n{\r\n headers: { 'cookie': '...', 'host': 'localhost:3000', ... }, // all lowercase\r\n cookies: { session_id: 'abc123', theme: 'dark' }, // parsed from Cookie header\r\n url: '/ws?token=abc', // request path + query string\r\n remoteAddress: '127.0.0.1' // client IP\r\n}\r\n```\r\n\r\nThe `subscribe` function receives `(ws, topic)` and can return `false` to deny a client's subscription request. Omit it to allow all subscriptions.\r\n\r\nThe `ws` object in `open`, `message`, `close`, and `drain` is a [uWebSockets.js WebSocket](https://github.com/uNetworking/uWebSockets.js). Key methods:\r\n\r\n- `ws.getUserData()` - returns whatever `upgrade` returned\r\n- `ws.subscribe(topic)` - subscribe to a topic for `app.publish()`\r\n- `ws.unsubscribe(topic)` - unsubscribe from a topic\r\n- `ws.send(data)` - send a message to this connection\r\n- `ws.close()` - close the connection\r\n\r\n---\r\n\r\n## Authentication\r\n\r\nWebSocket authentication uses the exact same cookies as your SvelteKit app. When the browser opens a WebSocket connection, it sends all cookies for the domain - including session cookies set by SvelteKit's `cookies.set()`. No tokens, no query parameters, no extra client-side code.\r\n\r\nHere's the full flow from login to authenticated WebSocket:\r\n\r\n### Step 1: Login sets a cookie (standard SvelteKit)\r\n\r\n**src/routes/login/+page.server.js**\r\n```js\r\nimport { authenticate, createSession } from '$lib/server/auth.js';\r\n\r\nexport const actions = {\r\n default: async ({ request, cookies }) => {\r\n const form = await request.formData();\r\n const email = form.get('email');\r\n const password = form.get('password');\r\n\r\n const user = await authenticate(email, password);\r\n if (!user) return { error: 'Invalid credentials' };\r\n\r\n const sessionId = await createSession(user.id);\r\n\r\n // This cookie is automatically sent on WebSocket upgrade requests\r\n cookies.set('session', sessionId, {\r\n path: '/',\r\n httpOnly: true,\r\n sameSite: 'strict',\r\n secure: true,\r\n maxAge: 60 * 60 * 24 * 7 // 1 week\r\n });\r\n\r\n return { success: true };\r\n }\r\n};\r\n```\r\n\r\n### Step 2: WebSocket handler reads the same cookie\r\n\r\n**src/hooks.ws.js**\r\n```js\r\nimport { getSession } from '$lib/server/auth.js';\r\n\r\nexport async function upgrade({ cookies }) {\r\n // Same cookie that SvelteKit set during login\r\n const sessionId = cookies.session;\r\n if (!sessionId) return false; // -> 401, connection rejected\r\n\r\n const user = await getSession(sessionId);\r\n if (!user) return false; // -> 401, expired or invalid session\r\n\r\n // Attach user data to the socket - available via ws.getUserData()\r\n // To refresh the session cookie on connect, use the `authenticate` hook\r\n // (see \"Refreshing session cookies on WebSocket connect\" below).\r\n // `upgradeResponse()` with custom non-cookie headers is also supported:\r\n // return upgradeResponse({ userId: user.id }, { 'x-session-version': '2' });\r\n return { userId: user.id, name: user.name, role: user.role };\r\n}\r\n\r\nexport function open(ws, { platform }) {\r\n const { userId, role } = ws.getUserData();\r\n console.log(`${userId} connected (${role})`);\r\n\r\n // Subscribe to user-specific and role-based topics\r\n ws.subscribe(`user:${userId}`);\r\n if (role === 'admin') ws.subscribe('admin');\r\n}\r\n\r\nexport function close(ws, { platform }) {\r\n const { userId } = ws.getUserData();\r\n console.log(`${userId} disconnected`);\r\n}\r\n```\r\n\r\n### Step 3: Client - nothing special needed\r\n\r\n**src/routes/dashboard/+page.svelte**\r\n```svelte\r\n\r\n\r\n{#if $status === 'open'}\r\n Authenticated & connected\r\n{:else if $status === 'connecting'}\r\n Connecting...\r\n{:else}\r\n Disconnected (not logged in?)\r\n{/if}\r\n```\r\n\r\n### Step 4: Send messages to specific users from anywhere\r\n\r\n**src/routes/api/notify/+server.js**\r\n```js\r\nimport { json } from '@sveltejs/kit';\r\n\r\nexport async function POST({ request, platform }) {\r\n const { userId, message } = await request.json();\r\n\r\n // Only that user receives this (they subscribed in open())\r\n platform.publish(`user:${userId}`, 'notification', { message });\r\n\r\n return json({ sent: true });\r\n}\r\n```\r\n\r\n### Why this works\r\n\r\nThe WebSocket upgrade is an HTTP request. The browser treats it like any other request to your domain - it includes all cookies, follows the same-origin policy, and respects `httpOnly`/`secure`/`sameSite` flags. There's no difference between how cookies reach a `+page.server.js` load function and how they reach the `upgrade` handler.\r\n\r\n| What | Where | Same cookies? |\r\n|---|---|---|\r\n| Page load | `+page.server.js` `load()` | Yes |\r\n| Form action | `+page.server.js` `actions` | Yes |\r\n| API route | `+server.js` | Yes |\r\n| Server hook | `hooks.server.js` `handle()` | Yes |\r\n| **WebSocket upgrade** | **`hooks.ws.js` `upgrade()`** | **Yes** |\r\n\r\n### Refreshing session cookies on WebSocket connect\r\n\r\nFor short-lived sessions you often want to rotate the session cookie every time a client connects. The obvious approach - attaching `Set-Cookie` to the 101 Switching Protocols response via `upgradeResponse()` - is RFC-compliant but **is silently rejected by Cloudflare Tunnel, Cloudflare's proxy, and some other strict edge proxies**. The symptom is that the WebSocket `open` handler fires server-side, then the connection closes with code 1006 (`Received TCP FIN before WebSocket close frame`) before any frames are exchanged. The adapter emits a build-time warning when it detects this pattern.\r\n\r\nThe adapter ships a first-class solution: the optional `authenticate` hook runs as a normal HTTP POST **before** the WebSocket upgrade. `Set-Cookie` rides on a standard 2xx response, which every proxy handles correctly; the browser then attaches the refreshed cookie to the upgrade request that follows.\r\n\r\n**Step 1: add an `authenticate` export to `hooks.ws.js`**\r\n\r\n```js\r\n// src/hooks.ws.js\r\nimport { getSession, renewSession } from '$lib/server/auth.js';\r\n\r\n// Runs as POST /__ws/auth, before the WebSocket upgrade.\r\n// cookies.set() becomes Set-Cookie on a standard 204 response.\r\nexport async function authenticate({ cookies }) {\r\n const session = await getSession(cookies.get('session'));\r\n if (!session) return false; // -> 401, client does not open the WebSocket\r\n\r\n const renewed = await renewSession(session);\r\n cookies.set('session', renewed.token, {\r\n path: '/',\r\n httpOnly: true,\r\n secure: true,\r\n sameSite: 'lax',\r\n maxAge: 60 * 60 * 24 * 7\r\n });\r\n}\r\n\r\n// Your existing upgrade() hook stays unchanged - it reads the now-fresh cookie.\r\nexport async function upgrade({ cookies }) {\r\n const session = await getSession(cookies.session);\r\n if (!session) return false;\r\n return { userId: session.userId, role: session.role };\r\n}\r\n```\r\n\r\nThe `authenticate` event exposes the SvelteKit event shape you already know: `{ request, headers, cookies, url, remoteAddress, getClientAddress, platform }`. Return values:\r\n\r\n- `undefined` / nothing - success, responds `204 No Content` with any `Set-Cookie` headers from `cookies.set()` (recommended).\r\n- `false` - responds `401 Unauthorized`. The client does not open the WebSocket.\r\n- A full `Response` - used as-is; any `cookies.set()` calls are merged in.\r\n\r\n**Step 2: opt in from the client**\r\n\r\n```js\r\nimport { connect } from 'svelte-adapter-uws/client';\r\n\r\n// Hit /__ws/auth before every WebSocket connect (including reconnects)\r\nconnect({ auth: true });\r\n\r\n// Or point at a custom path (e.g. behind a Cloudflare Access rule)\r\nconnect({ auth: '/api/ws-auth' });\r\n```\r\n\r\nWith `auth: true` the client stores runs `fetch('/__ws/auth', { method: 'POST', credentials: 'include' })` before every `new WebSocket(...)` call, including after automatic reconnects. Concurrent connect attempts share a single in-flight preflight. A `4xx` response is treated as terminal (the user is not authenticated); `5xx` and network errors fall back to the normal reconnect backoff.\r\n\r\n**Configuration**\r\n\r\n- The default auth path is `/__ws/auth`. Override with `adapter({ websocket: { authPath: '/api/ws-auth' } })`.\r\n- The hook is only mounted when `authenticate` is exported from `hooks.ws` - no runtime cost when unused.\r\n- Dev mode (Vite plugin) mirrors the production route on the same path.\r\n- The endpoint requires `x-requested-with: XMLHttpRequest`, `Sec-Fetch-Site: same-origin`, or an `Origin` matching `allowedOrigins` (CSRF defense). The adapter client always stamps `x-requested-with`. Native (non-browser) clients that need to reach this endpoint without those headers can opt out via `websocket.authPathRequireOrigin: false`. See [Security configuration](#security-configuration).\r\n\r\n**Why not put `Set-Cookie` on the 101?**\r\n\r\nCloudflare's HTTP/2 WebSocket bridging rewrites 101 responses, and `Set-Cookie` on the 101 trips the edge into tearing the connection down. This is undocumented Cloudflare behavior, but reproducible on every tunnel and proxy connector. The `authenticate` hook sidesteps it entirely by using a standard HTTP response.\r\n\r\n---\r\n\r\n## Platform API (`event.platform`)\r\n\r\nAvailable in server hooks, load functions, form actions, API routes, and WebSocket hooks (`hooks.ws`).\r\n\r\n### `platform.publish(topic, event, data, options?)`\r\n\r\nSend a message to all WebSocket clients subscribed to a topic.\r\n\r\nTopic and event names are validated before being written into the JSON envelope - quotes, backslashes, and control characters will throw. This prevents JSON injection when names are built from dynamic values like user IDs (`platform.publish(\\`user:\\${id}\\`, ...)`). The validation is a single-pass char scan and adds no measurable overhead.\r\n\r\nIn cluster mode, the message is automatically relayed to all other workers. Pass `{ relay: false }` to skip the relay when the message originates from an external pub/sub source (Redis, Postgres LISTEN/NOTIFY, etc.) that already delivers to every process:\r\n\r\n```js\r\n// Redis subscriber running on every worker - relay would cause duplicates\r\nsub.on('message', (channel, payload) => {\r\n platform.publish(channel, 'update', JSON.parse(payload), { relay: false });\r\n});\r\n```\r\n\r\nEvery published frame is also stamped with a monotonic per-topic `seq` field in the envelope (first publish to a topic is `seq: 1`, then 2, 3, ...). Reconnecting clients can use this to detect dropped frames and resume from where they left off. Pass `{ seq: false }` to skip stamping for ephemeral or high-cardinality topics where the counter map would grow unbounded:\r\n\r\n```js\r\n// Skip seq for per-user cursor topics: counter map would grow with users\r\nplatform.publish(`cursor:${userId}`, 'move', pos, { seq: false });\r\n```\r\n\r\n```js\r\n// src/routes/todos/+page.server.js\r\nexport const actions = {\r\n create: async ({ request, platform }) => {\r\n const formData = await request.formData();\r\n const todo = await db.createTodo(formData.get('text'));\r\n\r\n // Every client subscribed to 'todos' receives this\r\n platform.publish('todos', 'created', todo);\r\n\r\n return { success: true };\r\n }\r\n};\r\n```\r\n\r\n### `platform.send(ws, topic, event, data)`\r\n\r\nSend a message to a single WebSocket connection. Wraps in the same `{ topic, event, data }` envelope as `publish()`.\r\n\r\nThis is useful when you store WebSocket references (e.g. in a `Map`) and need to message specific connections from SvelteKit handlers:\r\n\r\n```js\r\n// src/hooks.ws.js - store connections by user ID\r\nconst userSockets = new Map();\r\n\r\nexport function open(ws, { platform }) {\r\n const { userId } = ws.getUserData();\r\n userSockets.set(userId, ws);\r\n}\r\n\r\nexport function close(ws, { platform }) {\r\n const { userId } = ws.getUserData();\r\n userSockets.delete(userId);\r\n}\r\n\r\n// Export the map so SvelteKit handlers can access it\r\nexport { userSockets };\r\n```\r\n\r\n```js\r\n// src/routes/api/dm/+server.js - send to a specific user\r\nimport { userSockets } from '../../hooks.ws.js';\r\n\r\nexport async function POST({ request, platform }) {\r\n const { targetUserId, message } = await request.json();\r\n const ws = userSockets.get(targetUserId);\r\n if (ws) {\r\n platform.send(ws, 'dm', 'new-message', { message });\r\n }\r\n return new Response('OK');\r\n}\r\n```\r\n\r\nYou can also reply directly from inside `hooks.ws.js` using `platform.send()` or `ws.send()` with the envelope format:\r\n\r\n```js\r\n// src/hooks.ws.js\r\nexport function message(ws, { data, platform }) {\r\n const msg = JSON.parse(Buffer.from(data).toString());\r\n // Using platform.send (recommended):\r\n platform.send(ws, 'echo', 'reply', { got: msg });\r\n // Or using ws.send with manual envelope:\r\n ws.send(JSON.stringify({ topic: 'echo', event: 'reply', data: { got: msg } }));\r\n}\r\n```\r\n\r\n### `platform.sendCoalesced(ws, { key, topic, event, data })`\r\n\r\nSend a message to a single connection with **coalesce-by-key** semantics. Each `(connection, key)` pair holds at most one pending message; if a newer call for the same `key` arrives before the previous frame drains to the wire, the older value is replaced in place.\r\n\r\nUse this for latest-value streams where intermediate values are noise - price ticks, cursor positions, presence state, typing indicators, scroll position. Under load, this is the difference between the client lagging by a thousand stale frames and the client always seeing the most recent value.\r\n\r\nIf you want a backpressured subscriber to keep eventually receiving the latest value (the queue-and-drain shape), `sendCoalesced` is the right primitive. If you want backpressured subscribers skipped entirely so the wire stays current for everyone else, use `platform.publish` / `platform.send` instead - those drop on backpressure (see the \"Volatile / fire-and-forget delivery\" section below). `sendCoalesced` is explicitly drop-the-middle, keep-the-latest; `publish` / `send` are explicitly drop-the-laggard, keep-everyone-else-current.\r\n\r\n```js\r\n// src/hooks.ws.js - cursor positions during a collaborative edit\r\nexport function message(ws, { data, platform }) {\r\n const msg = JSON.parse(Buffer.from(data).toString());\r\n if (msg.event === 'cursor') {\r\n const { docId, userId } = ws.getUserData();\r\n // Coalesce per (connection, user) - one pending cursor frame per peer.\r\n // High-frequency mousemove updates collapse cleanly under backpressure.\r\n for (const peer of getPeersOf(docId)) {\r\n platform.sendCoalesced(peer, {\r\n key: 'cursor:' + userId,\r\n topic: 'doc:' + docId,\r\n event: 'cursor',\r\n data: { userId, x: msg.data.x, y: msg.data.y }\r\n });\r\n }\r\n }\r\n}\r\n```\r\n\r\nThree properties worth knowing:\r\n\r\n- **Latest value wins.** `set` on an existing key replaces the value but keeps the original slot, so coalescing one key never reorders the rest of the queue.\r\n- **Lazy serialization.** `data` is held as-is in the per-connection buffer and only `JSON.stringify`'d at flush time. A stream that overwrites the same key 1000 times before a single drain pays one serialization, not 1000.\r\n- **Auto-resume on drain.** When `maxBackpressure` is hit, pumping stops and resumes on the next uWS drain event automatically. No manual flow control.\r\n\r\n### `platform.sendTo(filter, topic, event, data)`\r\n\r\nSend a message to all connections whose `userData` matches a filter function. Returns the number of connections the message was sent to.\r\n\r\nThis is simpler than manually maintaining a `Map` of connections - no `hooks.ws.js` needed:\r\n\r\n```js\r\n// src/routes/api/dm/+server.js - send to a specific user\r\nexport async function POST({ request, platform }) {\r\n const { targetUserId, message } = await request.json();\r\n const count = platform.sendTo(\r\n (userData) => userData.userId === targetUserId,\r\n 'dm', 'new-message', { message }\r\n );\r\n return new Response(count > 0 ? 'Sent' : 'User offline');\r\n}\r\n```\r\n\r\n```js\r\n// Send to all admins\r\nplatform.sendTo(\r\n (userData) => userData.role === 'admin',\r\n 'alerts', 'warning', { message: 'Server load high' }\r\n);\r\n```\r\n\r\n> **Performance:** `sendTo` iterates every open connection and runs your filter function against each one. It's fine for low-frequency operations like sending a DM or notifying admins, but don't use it in a hot loop. If you're broadcasting to a known group of users, subscribe them to a shared topic and use `platform.publish()` instead - topic-based pub/sub is handled natively by uWS in C++ and doesn't touch the JS event loop.\r\n\r\n### `platform.connections`\r\n\r\nNumber of active WebSocket connections:\r\n\r\n```js\r\n// src/routes/api/stats/+server.js\r\nimport { json } from '@sveltejs/kit';\r\n\r\nexport async function GET({ platform }) {\r\n return json({ online: platform.connections });\r\n}\r\n```\r\n\r\n### `platform.subscribers(topic)`\r\n\r\nNumber of clients subscribed to a specific topic:\r\n\r\n```js\r\nexport async function GET({ platform, params }) {\r\n return json({\r\n viewers: platform.subscribers(`page:${params.id}`)\r\n });\r\n}\r\n```\r\n\r\n### `platform.assertions`\r\n\r\nPer-category counter of framework invariant violations. The adapter ships internal hard-asserts at ~30 invariant sites (envelope build, WebSocket lifecycle, subscription bookkeeping, cross-worker IPC payloads, server-initiated request entry shape, sendCoalesced state). When one fires, the counter for that category increments and a structured `[adapter-uws/assert]` line is logged.\r\n\r\nMost apps will never see a non-empty entry here. A non-zero counter indicates a regression in the framework or a third-party plugin and should be reported as a GitHub issue with the category string and accompanying log context.\r\n\r\n```js\r\nexport async function GET({ platform }) {\r\n // Surface the counters in your /healthz or ops dashboard\r\n const assertions = {};\r\n for (const [category, count] of platform.assertions) {\r\n assertions[category] = count;\r\n }\r\n return json({ healthy: Object.keys(assertions).length === 0, assertions });\r\n}\r\n```\r\n\r\nThe returned `Map` is the live module-level instance - read-only, do not mutate. In test mode (`process.env.VITEST` set, or `NODE_ENV === 'test'`) the assert helper additionally throws so test runners surface the failure; in production it logs and counts but does not throw, so a violation inside a uWS callback frame cannot crash the worker.\r\n\r\n### `platform.closedWsAborts`\r\n\r\nPer-worker count of best-effort uWS operations that aborted because the underlying WebSocket had already closed. Bumped every time `platform.subscribe`, `platform.unsubscribe`, `platform.send`, `platform.sendCoalesced`, `platform.sendTo`, or `platform.request` is called on a `ws` whose native handle has been freed - typically because the caller `await`-ed something (auth, loader, subscribe hook) and the client closed during the wait.\r\n\r\nThese methods are *closed-WS safe* by contract: they swallow uWS's `Invalid access of closed uWS.WebSocket` exception, return a success-shaped no-op sentinel (`null` for subscribe, `false` for unsubscribe, `2` for send, etc.), and bump this counter. Callers can fire-and-forget without a per-site try/catch.\r\n\r\n```js\r\nexport async function GET({ platform }) {\r\n return json({ closedWsAborts: platform.closedWsAborts });\r\n}\r\n```\r\n\r\nA non-zero value is normal under client churn (tab close, network blips, mass reconnect waves). A rapidly-growing value under steady load indicates either pathological client behaviour or that the server's async setup path is too long for its connect rate. In clustered mode, sum across workers for cluster-wide visibility.\r\n\r\nMonotonic, per-worker, reset only on process restart.\r\n\r\n### `platform.pressure` and `platform.onPressure(cb)`\r\n\r\nWorker-local backpressure signal. The adapter samples once per second (configurable) and reports the most urgent active stress as a single `reason` enum, so user code can degrade with intent instead of generic panic.\r\n\r\n```js\r\nplatform.pressure\r\n// {\r\n// active: false,\r\n// subscriberRatio: 12.4, // total subscriptions / connections, on this worker\r\n// publishRate: 240, // platform.publish() calls/sec, last sample\r\n// memoryMB: 128, // process.memoryUsage().rss in MB\r\n// reason: 'NONE' // 'NONE' | 'PUBLISH_RATE' | 'SUBSCRIBERS' | 'MEMORY'\r\n// }\r\n```\r\n\r\nReading `platform.pressure` is a property access - safe in hot paths, no I/O. Use it for synchronous shed decisions in request handlers:\r\n\r\n```js\r\n// src/routes/api/heavy-write/+server.js\r\nexport async function POST({ platform, request }) {\r\n if (platform.pressure.reason === 'MEMORY') {\r\n return new Response('Try again shortly', { status: 503 });\r\n }\r\n // ... normal write path\r\n}\r\n```\r\n\r\n`platform.onPressure(cb)` fires only on **transitions** (when `reason` changes between samples), not on every tick. Returns an unsubscribe function:\r\n\r\n```js\r\n// src/hooks.ws.js - notify the connected client when pressure state changes\r\nexport function open(ws, { platform }) {\r\n const off = platform.onPressure(({ reason, active }) => {\r\n platform.send(ws, '__pressure', reason, { active });\r\n });\r\n ws.getUserData().__offPressure = off;\r\n}\r\n\r\nexport function close(ws) {\r\n ws.getUserData().__offPressure?.();\r\n}\r\n```\r\n\r\n**Reason precedence is fixed:** `MEMORY > PUBLISH_RATE > SUBSCRIBERS`. A worker under multiple stresses reports the most urgent one. Memory wins because the worker is approaching OOM and nothing else matters; publish rate is next because CPU saturation cascades fastest; subscriber ratio is last because heavy fan-out degrades gracefully.\r\n\r\n**Thresholds are configurable per-deployment.** Defaults are conservative - a healthy small app should never trip them in steady state. Override via `WebSocketOptions.pressure`:\r\n\r\n```js\r\n// svelte.config.js\r\nimport adapter from 'svelte-adapter-uws';\r\n\r\nexport default {\r\n kit: {\r\n adapter: adapter({\r\n websocket: {\r\n pressure: {\r\n memoryHeapUsedRatio: 0.9, // default 0.85\r\n publishRatePerSec: 50000, // default 10000 (aggregate)\r\n subscriberRatio: false, // disable this signal\r\n sampleIntervalMs: 500, // default 1000; clamped to >=100\r\n topicPublishRatePerSec: 10000, // default 5000 (per topic)\r\n topicPublishBytesPerSec: 5_000_000 // default 10485760 (10 MB/s per topic)\r\n }\r\n }\r\n })\r\n }\r\n};\r\n```\r\n\r\nSet any individual threshold to `false` to disable that signal. `sampleIntervalMs` is clamped to a minimum of 100 ms.\r\n\r\n> **Clustering:** `platform.pressure` is per-worker. Each worker samples its own counters and reports its own snapshot. There is no aggregate \"cluster pressure\" - a hot worker should shed its own load without waiting for the rest of the cluster.\r\n\r\n#### Per-topic publish-rate detection\r\n\r\nBeyond the aggregate `publishRatePerSec` signal, the sampler also tracks **per-topic** publish rates and surfaces the top 5 each tick:\r\n\r\n```js\r\nplatform.pressure.topPublishers\r\n// [\r\n// { topic: 'cursor:room-42', messagesPerSec: 8500, bytesPerSec: 1234567 },\r\n// { topic: 'audit:org-1', messagesPerSec: 1200, bytesPerSec: 234567 },\r\n// ...\r\n// ]\r\n```\r\n\r\nWhen a topic crosses `topicPublishRatePerSec` or `topicPublishBytesPerSec` in a sample window, the adapter flags it as a runaway publisher. By default this prints a throttled `console.warn` (one per topic per minute). For programmatic handling, register `platform.onPublishRate(cb)` - doing so suppresses the default warning so you own the surface:\r\n\r\n```js\r\nplatform.onPublishRate((events) => {\r\n for (const e of events) {\r\n metrics.record('runaway_publisher', {\r\n topic: e.topic,\r\n msgRate: e.messagesPerSec,\r\n byteRate: e.bytesPerSec\r\n });\r\n }\r\n});\r\n```\r\n\r\nThe bookkeeping is cheap: the per-topic counter mutates two integer fields in place per `platform.publish()` call (one entry allocated the first time a topic is published to, then zero allocations forever after). Set `topicPublishRatePerSec: false` and `topicPublishBytesPerSec: false` to disable per-topic tracking entirely if you do not want it.\r\n\r\n### `platform.topic(name)` - scoped helper\r\n\r\nReduces repetition when publishing multiple events to the same topic:\r\n\r\n```js\r\n// src/routes/todos/+page.server.js\r\nexport const actions = {\r\n create: async ({ request, platform }) => {\r\n const todos = platform.topic('todos');\r\n const todo = await db.create(await request.formData());\r\n todos.created(todo); // shorthand for platform.publish('todos', 'created', todo)\r\n },\r\n\r\n update: async ({ request, platform }) => {\r\n const to","readmeFilename":"README.md"}