vybekiit 0.7.4 → 0.7.7

package/dist/global-skills/neon-functions/references/hono-websockets.md

@@ -1,145 +0,0 @@
-# Hono WebSocket helper on Neon Functions
-
-Neon Functions accept WebSockets via a `{ fetch, upgrade }` default export, where `upgrade(req, socket, head)` is the raw Node handshake (see the [WebSocket servers](../SKILL.md#websocket-servers) section). That works directly with the `ws` library. If you'd rather declare WebSocket routes _inside_ a Hono app — `app.get("/ws", upgradeWebSocket(...))` with the standard `onOpen`/`onMessage`/`onClose` lifecycle — you need an adapter.
-
-## Why an adapter (and why not `@hono/node-ws`)
-
-Hono's `upgradeWebSocket()` is runtime-agnostic at the route layer, but the actual handshake is done by a per-runtime adapter (`hono/cloudflare-workers`, `hono/deno`, `hono/bun`, `@hono/node-server`). **There is no adapter for Neon.** The Node one, `@hono/node-ws`, is **deprecated** and its replacement assumes it owns the HTTP server (`serve({ websocket })`) — which Neon's runtime does instead.
-
-So vendor the small adapter below. It depends only on `hono` and `ws` (no deprecated package), and is adapted from `@hono/node-ws` (MIT). Instead of attaching to an `http.Server`'s `'upgrade'` event, it returns a ready-to-export `{ fetch, upgrade }` handler that matches Neon's contract.
-
-## The adapter
-
-```typescript
-// src/hono-ws.ts — bridges Hono's upgradeWebSocket() to Neon's { fetch, upgrade }.
-import { STATUS_CODES, type IncomingMessage } from "node:http";
-import type { Duplex } from "node:stream";
-import type { Hono } from "hono";
-import { WSContext, defineWebSocketHelper } from "hono/ws";
-import { WebSocketServer, type WebSocket } from "ws";
-
-type Wire = (ws: WebSocket) => void;
-
-export function createNeonWebSocket(app: Hono, baseUrl = "http://localhost") {
-  const wss = new WebSocketServer({ noServer: true });
-  // Correlate a handshake to its route handler via the per-request env object identity.
-  const pending = new Map<unknown, Wire>();
-
-  const upgradeWebSocket = defineWebSocketHelper(async (c, events, options) => {
-    if (c.req.header("upgrade")?.toLowerCase() !== "websocket") return;
-    const url = c.req.url;
-    pending.set(c.env, (ws) => {
-      const onError = options?.onError ?? ((e: unknown) => console.error(e));
-      const ctx = new WSContext<WebSocket>({
-        send: (data, opts) => ws.send(data, { compress: opts?.compress }),
-        close: (code, reason) => ws.close(code, reason),
-        raw: ws,
-        url,
-        protocol: ws.protocol,
-        get readyState() {
-          return ws.readyState;
-        },
-      });
-      try {
-        events.onOpen?.(new Event("open"), ctx);
-      } catch (e) {
-        onError(e);
-      }
-      ws.on("message", (data, isBinary) => {
-        for (const chunk of Array.isArray(data) ? data : [data]) {
-          try {
-            const payload = isBinary
-              ? chunk instanceof ArrayBuffer
-                ? chunk
-                : chunk.buffer.slice(chunk.byteOffset, chunk.byteOffset + chunk.byteLength)
-              : chunk.toString("utf-8");
-            events.onMessage?.(new MessageEvent("message", { data: payload }), ctx);
-          } catch (e) {
-            onError(e);
-          }
-        }
-      });
-      ws.on("close", (code, reason) => {
-        try {
-          events.onClose?.(new CloseEvent("close", { code, reason: reason.toString() }), ctx);
-        } catch (e) {
-          onError(e);
-        }
-      });
-      // Node 24 has no global ErrorEvent; a browser's ws.onerror gets a plain Event anyway.
-      ws.on("error", (error) => {
-        onError(error);
-        try {
-          events.onError?.(new Event("error"), ctx);
-        } catch (e) {
-          onError(e);
-        }
-      });
-    });
-    return new Response();
-  });
-
-  const handler = {
-    fetch: (request: Request) => app.fetch(request),
-    async upgrade(req: IncomingMessage, socket: Duplex, head: Buffer) {
-      const url = new URL(req.url ?? "/", baseUrl);
-      const headers = new Headers();
-      for (const [key, value] of Object.entries(req.headers)) {
-        if (value) headers.append(key, Array.isArray(value) ? value[0] : value);
-      }
-      // The env object identity links this request back to the route handler above.
-      const env = { incoming: req, outgoing: undefined };
-      const response = await app.request(url, { headers }, env);
-      const wire = pending.get(env);
-      pending.delete(env);
-      if (!wire) {
-        socket.end(`HTTP/1.1 ${response.status} ${STATUS_CODES[response.status] ?? ""}\r\nConnection: close\r\nContent-Length: 0\r\n\r\n`);
-        return;
-      }
-      wss.handleUpgrade(req, socket, head, (ws) => wire(ws));
-    },
-  };
-
-  return { upgradeWebSocket, handler };
-}
-```
-
-How it works: the `upgrade` handler runs the handshake request through `app.request(...)` so Hono's router matches the `upgradeWebSocket` route; the helper registers a `wire` callback keyed by the per-request `env` object; if a route matched, `wss.handleUpgrade` accepts the socket and `wire` attaches the lifecycle handlers, otherwise the socket is closed with the route's status (e.g. 401/404).
-
-## Usage
-
-Because the handshake is routed through `app.request`, **auth and other gating are just normal Hono middleware on the route** — verify the `?token=` and return 401 before the upgrade:
-
-```typescript
-// src/index.ts
-import { Hono } from "hono";
-import { createNeonWebSocket } from "./hono-ws";
-
-const app = new Hono();
-const { upgradeWebSocket, handler } = createNeonWebSocket(app);
-
-app.get("/", (c) => c.text("ok"));
-
-app.get(
-  "/ws",
-  async (c, next) => {
-    const identity = await verifyToken(c.req.query("token")); // your JWT check
-    if (!identity) 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
-```
-
-## Caveats
-
-- **No header-modifying middleware on the WS route.** Per [Hono's docs](https://hono.dev/docs/helpers/websocket), middleware that changes headers (e.g. CORS) on an `upgradeWebSocket` route throws ("can't modify immutable headers"), because the helper rewrites headers internally. Auth middleware that only reads the query/headers and returns 401 is fine.
-- **Send a heartbeat.** A socket is dropped once it goes silent — Neon's window is 15 minutes ([Timeouts](../SKILL.md#timeouts-and-runtime-limits)), but intermediary proxies are usually far stricter (tens of seconds). Send a keepalive every ~25–30s so the connection never goes quiet. With the raw `ws` socket use `ws.ping()` (the browser auto-replies with a pong); through this helper you don't hold the raw socket, so send an app-level `ws.send("ping")` the client ignores instead. See [Heartbeat](../SKILL.md#heartbeat-keep-the-socket-alive).
-- **Fan-out and reconnect still apply.** This adapter only covers the per-isolate handshake. For a genuinely shared chat across isolates, fan out through Postgres (poll by default, or `LISTEN`/`NOTIFY` on always-on compute), and have clients reconnect with backoff — see [Keeping clients in sync across isolates](../SKILL.md#keeping-clients-in-sync-across-isolates-do-not-skip-this) and [Client must reconnect](../SKILL.md#client-must-reconnect).
-- **Node-only globals.** Relies on `Event`, `MessageEvent`, and `CloseEvent` (all present on Neon's Node 24 runtime). `ErrorEvent` is intentionally avoided since it isn't a Node global.