feat: experimental websocket support

docs/.config/docs.yaml

@@ -5,7 +5,7 @@ description: Create web servers with everything you need and deploy them whereve
 github: unjs/nitro
 url: https://nitro.unjs.io
 themeColor: "red"
-# automd: true
+automd: true
 redirects:
   /deploy/node: /deploy/runtimes/node
 landing:

docs/1.guide/8.websocket.md

@@ -0,0 +1,97 @@
+---
+icon: cib:socket-io
+---
+
+# WebSocket
+
+> Nitro natively support a cross platform WebSocket API
+
+Nitro natively supports runtime agnostic [WebSocket](https://developer.mozilla.org/en-US/docs/Web/API/WebSocket) API using [CrossWS](https://crossws.unjs.io/) and [H3 WebSocket](https://h3.unjs.io/guide/websocket).
+
+:read-more{title="WebSocket in MDN" to="https://developer.mozilla.org/en-US/docs/Web/API/WebSocket"}
+
+:read-more{title="CrossWS" to="https://crossws.unjs.io/"}
+
+> [!IMPORTANT]
+> WebSockets support is currently experimental and available in [nightly channel](/guide/nightly).
+> See [unjs/nitro#2171](https://github.com/unjs/nitro/issues/2171) for platform support status.
+
+## Usage
+
+Enable experimental flag first:
+
+::code-group
+```ts [nitro.config.ts]
+export default defineNitroConfig({
+  experimental: {
+    websocket: true
+  }
+})
+```
+
+```ts [nuxt.config.ts]
+export default defineNuxtConfig({
+  nitro: {
+    experimental: {
+      websocket: true
+    }
+  }
+})
+```
+::
+
+Create a websocket handler in `routes/_ws.ts` or `server/routes/_ws.ts` for Nuxt).
+
+<!-- automd:file code src="../../examples/websocket/routes/_ws.ts" -->
+
+```ts [_ws.ts]
+export default defineWebSocketHandler({
+  open(peer) {
+    console.log("[ws] open", peer);
+  },
+
+  message(peer, message) {
+    console.log("[ws] message", peer, message);
+    if (message.text().includes("ping")) {
+      peer.send("pong");
+    }
+  },
+
+  close(peer, event) {
+    console.log("[ws] close", peer, event);
+  },
+
+  error(peer, error) {
+    console.log("[ws] error", peer, error);
+  },
+});
+
+```
+
+<!-- /automd -->
+
+> [!NOTE]
+> Nitro allows you defining multiple websocket handlers using same routing of event handlers.
+
+Use a client to connect to server. Example: (`routes/websocket.ts` or `server/routes/websocket.ts` for Nuxt)
+
+<!-- automd:file code src="../../examples/websocket/routes/index.ts" -->
+
+```ts [index.ts]
+export default defineEventHandler(() => {
+  return $fetch(
+    "https://raw.githubusercontent.com/unjs/crossws/main/examples/h3/public/index.html"
+  );
+});
+
+```
+
+<!-- /automd -->
+
+Now you can try it on `/websocket` route!
+
+## Server Sent Events (SSE)
+
+As an alternative to WebSockets, you can use [Server-sent events](https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events)
+
+:read-more{to="https://h3.unjs.io/guide/websocket#server-sent-events-sse" title="SSE guide in H3"}

examples/websocket/nitro.config.ts

@@ -0,0 +1,5 @@
+export default defineNitroConfig({
+  experimental: {
+    websocket: true,
+  },
+});

examples/websocket/package.json

@@ -0,0 +1,11 @@
+{
+  "name": "example-hello-world",
+  "private": true,
+  "scripts": {
+    "dev": "nitro dev",
+    "build": "nitro build"
+  },
+  "devDependencies": {
+    "nitropack": "latest"
+  }
+}

examples/websocket/routes/_ws.ts

@@ -0,0 +1,20 @@
+export default defineWebSocketHandler({
+  open(peer) {
+    console.log("[ws] open", peer);
+  },
+
+  message(peer, message) {
+    console.log("[ws] message", peer, message);
+    if (message.text().includes("ping")) {
+      peer.send("pong");
+    }
+  },
+
+  close(peer, event) {
+    console.log("[ws] close", peer, event);
+  },
+
+  error(peer, error) {
+    console.log("[ws] error", peer, error);
+  },
+});

examples/websocket/routes/index.ts

@@ -0,0 +1,5 @@
+export default defineEventHandler(() => {
+  return $fetch(
+    "https://raw.githubusercontent.com/unjs/crossws/main/examples/h3/public/index.html"
+  );
+});

examples/websocket/tsconfig.json

@@ -0,0 +1,3 @@
+{
+  "extends": "./.nitro/types/tsconfig.json"
+}

package.json

@@ -78,6 +78,7 @@
     "citty": "^0.1.6",
     "consola": "^3.2.3",
     "cookie-es": "^1.0.0",
+    "crossws": "^0.2.3",
     "defu": "^6.1.4",
     "destr": "^2.0.3",
     "dot-prop": "^8.0.2",
@@ -87,7 +88,7 @@
     "fs-extra": "^11.2.0",
     "globby": "^14.0.1",
     "gzip-size": "^7.0.0",
-    "h3": "^1.11.0",
+    "h3": "^1.11.1",
     "hookable": "^5.5.3",
     "httpxy": "^0.1.5",
     "is-primitive": "^3.0.1",
@@ -128,6 +129,7 @@
     "@azure/static-web-apps-cli": "^1.1.6",
     "@cloudflare/workers-types": "^4.20240222.0",
     "@types/aws-lambda": "^8.10.134",
+    "@types/bun": "^1.0.7",
     "@types/estree": "^1.0.5",
     "@types/etag": "^1.8.3",
     "@types/fs-extra": "^11.0.4",

src/deps.ts

@@ -17,4 +17,5 @@ export const nitroRuntimeDependencies = [
   "unctx",
   "unenv",
   "unstorage",
+  "crossws",
 ];

src/dev/server.ts

@@ -246,6 +246,17 @@ export function createDevServer(nitro: Nitro): NitroDevServer {
   let listeners: Listener[] = [];
   const _listen: NitroDevServer["listen"] = async (port, opts?) => {
     const listener = await listen(toNodeListener(app), { port, ...opts });
+    listener.server.on("upgrade", (req, sock, head) => {
+      proxy.proxy.ws(
+        req,
+        sock as any,
+        {
+          target: getWorkerAddress(),
+          xfwd: true,
+        },
+        head
+      );
+    });
     listeners.push(listener);
     return listener;
   };

src/rollup/config.ts

@@ -202,6 +202,7 @@ export const getRollupConfig = (nitro: Nitro): RollupConfig => {
     "versions?.nitro": nitroPkg.version,
     // Internal
     _asyncContext: nitro.options.experimental.asyncContext,
+    _websocket: nitro.options.experimental.websocket,
   };
 
   // Universal import.meta

src/runtime/entries/bun.ts

@@ -1,23 +1,33 @@
 import "#internal/nitro/virtual/polyfill";
+import type {} from "bun";
+import wsAdapter from "crossws/adapters/bun";
 import { nitroApp } from "../app";
 
-// @ts-expect-error: Bun global
+const ws = import.meta._websocket
+  ? wsAdapter(nitroApp.h3App.websocket)
+  : undefined;
+
 const server = Bun.serve({
   port: process.env.NITRO_PORT || process.env.PORT || 3000,
-  async fetch(request: Request) {
-    const url = new URL(request.url);
+  websocket: import.meta._websocket ? ws.websocket : undefined,
+  async fetch(req, server) {
+    if (import.meta._websocket && (await ws.handleUpgrade(req, server))) {
+      return;
+    }
+
+    const url = new URL(req.url);
 
     let body;
-    if (request.body) {
-      body = await request.arrayBuffer();
+    if (req.body) {
+      body = await req.arrayBuffer();
     }
 
     return nitroApp.localFetch(url.pathname + url.search, {
       host: url.hostname,
       protocol: url.protocol,
-      headers: request.headers,
-      method: request.method,
-      redirect: request.redirect,
+      headers: req.headers,
+      method: req.method,
+      redirect: req.redirect,
       body,
     });
   },