feat(with-realtime-chat): serve the chat socket with upgradeWebSocket

bots/discord-bot-http/.agents/skills/neon-functions/SKILL.md

@@ -278,94 +278,108 @@ Pass the JWKS/issuer URL to the function via its `env` (see [Environment Variabl
 
 ## WebSocket Servers
 
-A WebSocket server is the canonical Functions workload: a long-running handler holds connections open in-process, with no external state store needed to keep a stream coherent. Because a function is a real Node.js process (not a lambda), the WebSocket handshake works the way it does in any Node server — the [`ws`](https://github.com/websockets/ws) library upgrades the socket, and the connection stays alive as long as bytes flow (15-minute heartbeat, see [Timeouts](#timeouts-and-runtime-limits)).
+A WebSocket server is the canonical Functions workload: a long-running handler holds connections open in-process, with no external state store needed to keep a stream coherent. The connection stays alive as long as bytes flow (15-minute heartbeat, see [Timeouts](#timeouts-and-runtime-limits)).
 
-**The return signature is the whole trick.** A function's default export is normally `{ fetch }`. To also accept WebSockets, export an `upgrade` method alongside it — the runtime routes plain HTTP to `fetch` and the WebSocket handshake to `upgrade`:
+**Upgrade from inside `fetch`.** Call `upgradeWebSocket(request)` from [`@neon/functions`](https://www.npmjs.com/package/@neon/functions) and return the response it gives you. There is one entrypoint and no WebSocket dependency to install:
 
 ```typescript
+import { upgradeWebSocket } from "@neon/functions";
+
 export default {
-  fetch(request: Request): Response | Promise<Response> { /* HTTP */ },
-  async upgrade(req: IncomingMessage, socket: Duplex, head: Buffer) { /* WS handshake */ },
+  async fetch(req: Request): Promise<Response> {
+    if (req.headers.get("upgrade")?.toLowerCase() !== "websocket") {
+      return new Response("expected a websocket upgrade", { status: 426 });
+    }
+
+    const { socket, response } = upgradeWebSocket(req);
+    socket.addEventListener("message", (event) => socket.send(event.data));
+    return response;
+  },
 };
 ```
 
-**Simple example** — raw `ws`, no framework, with auth. Browsers can't set headers on a WebSocket, so authenticate with a `?token=` query param (verify it the same way as the [agent backend](#functions-as-an-agent-backend-nextjs-and-similar-frameworks): `jwtVerify` against your JWKS) before accepting the connection:
+`socket` is a standard [`WebSocket`](https://developer.mozilla.org/en-US/docs/Web/API/WebSocket), so `addEventListener` and the `onopen`/`onmessage`/`onclose`/`onerror` properties both work. It is still `CONNECTING` when you get it — the runtime writes the `101` only once your handler returns `response`, and the socket opens then.
+
+Three rules that matter:
+
+- **Return `response` unchanged.** A `101` can't be built as a plain `Response` (the fetch spec caps constructed responses at 200–599), so the runtime hands back an object carrying the pending upgrade. `clone()`, or rebuilding it with `new Response(res.body, res)` as response-rewriting middleware does, discards the upgrade and fails the request.
+- **Refuse a handshake by returning an ordinary `Response`.** A `401`, `403` or `404` is relayed to the client as-is. That is how you gate a socket.
+- **`binaryType` defaults to `"arraybuffer"`**, not the browser's `"blob"`. `event.data` is a `string` for text frames and an `ArrayBuffer` for binary ones, so branch on `typeof`.
+
+**With auth.** Browsers can't set headers on a WebSocket, so authenticate with a `?token=` query param (verify it the same way as the [agent backend](#functions-as-an-agent-backend-nextjs-and-similar-frameworks): `jwtVerify` against your JWKS) and refuse before upgrading:
 
 ```typescript
 // src/index.ts
-import type { IncomingMessage } from "node:http";
-import type { Duplex } from "node:stream";
-import { WebSocketServer, type WebSocket } from "ws";
+import { upgradeWebSocket } from "@neon/functions";
 
 const clients = new Set<WebSocket>();
-const wss = new WebSocketServer({ noServer: true });
 
 export default {
-  // Plain HTTP (health checks, REST) is handled by fetch.
-  fetch: () => new Response("WebSocket endpoint — connect with ?token=<jwt>"),
-
-  // The runtime hands the WebSocket handshake to upgrade().
-  async upgrade(req: IncomingMessage, socket: Duplex, head: Buffer) {
-    const url = new URL(req.url ?? "/", "http://localhost");
-    const identity = await verifyToken(url.searchParams.get("token")); // reject if invalid
-    if (!identity) {
-      socket.write("HTTP/1.1 401 Unauthorized\r\n\r\n");
-      socket.destroy();
-      return;
+  async fetch(request: Request): Promise<Response> {
+    if (request.headers.get("upgrade")?.toLowerCase() !== "websocket") {
+      return new Response("WebSocket endpoint — connect with ?token=<jwt>");
     }
-    wss.handleUpgrade(req, socket, head, (ws) => {
-      clients.add(ws);
-      ws.on("close", () => clients.delete(ws));
-      ws.on("message", (data) => persist(data.toString())); // persist; fan out to every isolate — see below
+
+    const url = new URL(request.url);
+    const identity = await verifyToken(url.searchParams.get("token"));
+    if (!identity) return new Response("unauthorized", { status: 401 });
+
+    const { socket, response } = upgradeWebSocket(request);
+    clients.add(socket);
+    socket.addEventListener("close", () => clients.delete(socket));
+    socket.addEventListener("message", (event) => {
+      if (typeof event.data !== "string") return;
+      persist(identity.id, event.data); // fan out to every isolate — see below
     });
+    return response;
   },
 };
 ```
 
-**Hono variant.** If you only need Hono for the HTTP side and are happy driving `ws` yourself, just swap `fetch` in the simple example for `app.fetch` and keep the raw `upgrade` — Hono serves routing/middleware, `ws` serves the socket.
+**Subprotocols.** Pass `{ protocol }` to select one the client offered; it is echoed in `Sec-WebSocket-Protocol` and exposed as `socket.protocol`. Selecting one the client did not offer throws a `TypeError`. Omit it and no protocol is negotiated. No extensions are negotiated either — `socket.extensions` is always `""` and `permessage-deflate` is not available.
 
-To instead declare WebSocket routes _inside_ the Hono app — `app.get("/ws", upgradeWebSocket(...))` with the standard `onOpen`/`onMessage`/`onClose` lifecycle — you need an adapter that bridges Hono's `upgradeWebSocket()` helper to Neon's `upgrade(req, socket, head)`. Hono ships adapters for Cloudflare/Deno/Bun/Node, but **none for Neon**, and the Node one (`@hono/node-ws`) is deprecated and assumes it owns the HTTP server. [references/hono-websockets.md](https://neon.com/docs/ai/skills/neon-functions/references/hono-websockets.md) has a small self-contained `createNeonWebSocket(app)` adapter to copy in — it depends only on `hono` and `ws` (no deprecated package; adapted from `@hono/node-ws`, MIT) and returns a ready-to-export `{ fetch, upgrade }` handler. Usage is idiomatic Hono, and because the handshake routes through `app.request`, **auth is just normal route middleware**:
+**Hono.** Nothing special is needed: `upgradeWebSocket` takes a `Request`, so call it inside a route with `c.req.raw` and return the response. Auth and everything else is ordinary middleware.
 
 ```typescript
 // src/index.ts
 import { Hono } from "hono";
-import { createNeonWebSocket } from "./hono-ws";
+import { upgradeWebSocket } from "@neon/functions";
 
 const app = new Hono();
-const { upgradeWebSocket, handler } = createNeonWebSocket(app);
 
-app.get(
-  "/ws",
-  async (c, next) => {
-    if (!(await verifyToken(c.req.query("token")))) return c.text("Unauthorized", 401);
-    await next();
-  },
-  upgradeWebSocket(() => ({
-    onOpen: (_evt, ws) => ws.send("welcome"),
-    onMessage: (evt, ws) => ws.send(`echo: ${evt.data}`),
-    onClose: () => console.log("disconnected"),
-  })),
-);
-
-export default handler; // Neon's { fetch, upgrade } contract
-```
+app.get("/", (c) => c.text("ok"));
+
+app.get("/ws", async (c) => {
+  const identity = await verifyToken(c.req.query("token"));
+  if (!identity) return c.text("Unauthorized", 401);
 
-> Don't put header-modifying middleware (e.g. CORS) on an `upgradeWebSocket` route — the helper rewrites headers internally and will throw. The [sync](#keeping-clients-in-sync-across-isolates-do-not-skip-this) and [reconnect](#client-must-reconnect) guidance below applies unchanged.
+  const { socket, response } = upgradeWebSocket(c.req.raw);
+  socket.addEventListener("open", () => socket.send("welcome"));
+  socket.addEventListener("message", (event) => socket.send(`echo: ${event.data}`));
+  return response;
+});
+
+export default { fetch: (request: Request) => app.fetch(request) };
+```
 
 ### Heartbeat (keep the socket alive)
 
-A connection stays open **only while bytes flow**: Neon evicts a silent stream after 15 minutes ([Timeouts and Runtime Limits](#timeouts-and-runtime-limits)), and intermediary proxies / load balancers are usually far stricter (often tens of seconds). Don't rely on the app being chatty enough — send a periodic ping from the server so the socket never goes quiet. `ws.ping()` sends a WebSocket ping frame and the browser answers with a pong automatically, so there's no client code to write:
+A connection stays open **only while bytes flow**: Neon evicts a silent stream after 15 minutes ([Timeouts and Runtime Limits](#timeouts-and-runtime-limits)), and intermediary proxies / load balancers are usually far stricter (often tens of seconds). Don't rely on the app being chatty enough — send a periodic keepalive from the server so the socket never goes quiet.
+
+The standard `WebSocket` interface has no `ping()`, so send an application-level message the client ignores:
 
 ```typescript
 const HEARTBEAT_MS = 25_000; // comfortably under proxy idle timeouts
 
 const beat = setInterval(() => {
-  for (const ws of clients) if (ws.readyState === ws.OPEN) ws.ping();
+  for (const socket of clients) {
+    if (socket.readyState === socket.OPEN) socket.send('{"type":"ping"}');
+  }
 }, HEARTBEAT_MS);
 beat.unref?.();
 ```
 
-(With the Hono `upgradeWebSocket` helper you don't hold the raw socket, so send an application-level keepalive instead — e.g. `ws.send("ping")` on the same interval, ignored by the client.)
+The client should skip these when handling messages. The server does answer a client-sent ping frame with a pong automatically, so a browser client can drive the heartbeat instead if you'd rather not filter messages.
 
 ### Keeping clients in sync across isolates (do not skip this)
 
@@ -385,7 +399,9 @@ const poller = setInterval(async () => {
   );
   for (const { id, payload } of rows) {
     lastId = id;
-    for (const ws of clients) if (ws.readyState === ws.OPEN) ws.send(payload);
+    for (const socket of clients) {
+      if (socket.readyState === socket.OPEN) socket.send(payload);
+    }
   }
 }, 1000);
 poller.unref?.();
@@ -409,7 +425,9 @@ const listener = new Client({ connectionString: process.env.DATABASE_URL_UNPOOLE
 listener.connect().then(() => listener.query(`LISTEN ${CHANNEL}`));
 listener.on("notification", (msg) => {
   if (!msg.payload) return;
-  for (const ws of clients) if (ws.readyState === ws.OPEN) ws.send(msg.payload);
+  for (const socket of clients) {
+    if (socket.readyState === socket.OPEN) socket.send(msg.payload);
+  }
 });
 
 // Broadcast by NOTIFYing through the pool — every isolate's listener fires.
@@ -443,11 +461,11 @@ async function connect() {
 connect();
 ```
 
-Together — Hono `fetch` + `ws` `upgrade`, JWT auth over `?token=`, cross-isolate fan-out, and client backoff — these compose into a complete realtime chat backend on a single function.
+Together — `upgradeWebSocket` inside `fetch`, JWT auth over `?token=`, cross-isolate fan-out, and client backoff — these compose into a complete realtime chat backend on a single function.
 
 ## Server-Sent Events (SSE)
 
-When you only need **server → client** streaming (live counters, notifications, progress, token streams), SSE is simpler than a WebSocket and needs no `upgrade` method or extra library: a plain `fetch` handler returns a `Response` whose body is a `ReadableStream` with `Content-Type: text/event-stream`, and the runtime holds it open as long as bytes flow. The browser consumes it with `EventSource`, which **reconnects on its own** — so there's no client backoff to write.
+When you only need **server → client** streaming (live counters, notifications, progress, token streams), SSE is simpler than a WebSocket and needs no upgrade at all: a plain `fetch` handler returns a `Response` whose body is a `ReadableStream` with `Content-Type: text/event-stream`, and the runtime holds it open as long as bytes flow. The browser consumes it with `EventSource`, which **reconnects on its own** — so there's no client backoff to write.
 
 ```typescript
 // src/index.ts — minimal SSE endpoint