acrylblends 0.9.2 → 0.11.0

package/lib/{server-DvgMGtzo.js → test-websocket-ZXHNHQSU.js}

@@ -1,8 +1,10 @@
 import { defineWebSocketHelper } from "./ws.js";
 import "./helpers-CvTauQT5.js";
+import { createRequire } from "node:module";
 import { STATUS_CODES, ServerResponse, createServer } from "node:http";
 import { Http2ServerRequest, constants } from "node:http2";
 import { Readable } from "node:stream";
+import { EventEmitter } from "node:events";
 //#region ../../plugins/acryl-node-server/src/adapter/error.ts
 var RequestError = class extends Error {
 	constructor(message, options) {
@@ -1110,6 +1112,8 @@ const ErrorEvent = globalThis.ErrorEvent ?? class extends Event {
 	}
 };
 const generateConnectionSymbol = () => Symbol("connection");
+/** The codes an endpoint may send in a close frame (RFC 6455 section 7.4): 1000-1003, 1007-1014 and the private ranges 3000-4999. */
+const validCloseCode = (code) => code >= 1e3 && code <= 1014 && code !== 1004 && code !== 1005 && code !== 1006 || code >= 3e3 && code <= 4999;
 const CONNECTION_SYMBOL_KEY = Symbol("CONNECTION_SYMBOL_KEY");
 const WAIT_FOR_WEBSOCKET_SYMBOL = Symbol("WAIT_FOR_WEBSOCKET_SYMBOL");
 const responseHeadersToSkip = /* @__PURE__ */ new Set([
@@ -1177,7 +1181,10 @@ const setupWebSocket = (options) => {
 		});
 	};
 	server.on("upgrade", async (request, socket, head) => {
-		if (request.headers.upgrade?.toLowerCase() !== "websocket") return;
+		if (request.headers.upgrade?.toLowerCase() !== "websocket") {
+			if (server.listenerCount("upgrade") === 1) rejectUpgradeRequest(socket, 400);
+			return;
+		}
 		const env = {
 			incoming: request,
 			outgoing: void 0,
@@ -1232,6 +1239,7 @@ const upgradeWebSocket = defineWebSocketHelper(async (c, events, options) => {
 		let ws;
 		try {
 			ws = await waitForWebSocket(env.incoming, connectionSymbol);
+			options?.track?.(ws);
 		} catch {
 			return;
 		}
@@ -1243,13 +1251,16 @@ const upgradeWebSocket = defineWebSocketHelper(async (c, events, options) => {
 		const ctx = {
 			binaryType: "arraybuffer",
 			close(code, reason) {
-				ws.close(code, reason);
+				ws.close(code === void 0 || validCloseCode(code) ? code : 1011, reason);
 			},
 			protocol: ws.protocol,
 			raw: ws,
 			get readyState() {
 				return ws.readyState;
 			},
+			get bufferedAmount() {
+				return ws.bufferedAmount;
+			},
 			send(source, opts) {
 				ws.send(source, { compress: opts?.compress });
 			},
@@ -1261,6 +1272,7 @@ const upgradeWebSocket = defineWebSocketHelper(async (c, events, options) => {
 			(options?.onError ?? console.error)(e);
 		}
 		const handleMessage = (data, isBinary) => {
+			if (isBinary && options?.textOnly) return;
 			const datas = Array.isArray(data) ? data : [data];
 			for (const data of datas) try {
 				events?.onMessage?.(new MessageEvent("message", { data: isBinary ? data instanceof ArrayBuffer ? data : data.buffer.slice(data.byteOffset, data.byteOffset + data.byteLength) : typeof data === "string" ? data : Buffer.from(data).toString("utf-8") }), ctx);
@@ -1273,7 +1285,10 @@ const upgradeWebSocket = defineWebSocketHelper(async (c, events, options) => {
 		ws.on("message", (data, isBinary) => {
 			handleMessage(data, isBinary);
 		});
+		let closed = false;
 		ws.on("close", (code, reason) => {
+			if (closed) return;
+			closed = true;
 			try {
 				events?.onClose?.(new CloseEvent("close", {
 					code,
@@ -1320,4 +1335,211 @@ function serve(options, listeningListener) {
 	return server;
 }
 //#endregion
-export { Request$1 as a, getRequestListener as i, serve as n, RequestError as o, upgradeWebSocket as r, createAdaptorServer as t };
+//#region ../../plugins/acryl-node-server/src/upgrade-hub.ts
+/**
+* WebSocket upgrades for the Cordis adapters (spec 047 T009): one hub per HTTP transport. It owns the `ws` server (text and size limits, no compression), runs the ported
+* `setupWebSocket` on whatever emits `upgrade` events (a `node:http` server, or the Host web server's exact-path upgrade routes), pings every socket and ends the ones that stop
+* answering, and gives each mounting plugin an `upgradeWebSocket` whose accepted sockets belong to that plugin: when it unloads they are closed with 1001 within the grace, and
+* what is left is terminated. The handler sees `close` exactly once.
+*/
+/** The `ws` package, loaded when the first hub is made: an app that never upgrades does not need it. */
+function loadWs() {
+	try {
+		return createRequire(import.meta.url)("ws").WebSocketServer;
+	} catch (error) {
+		throw new Error(`WebSocket upgrades need the "ws" package (npm install ws): ${error instanceof Error ? error.message : String(error)}`);
+	}
+}
+var UpgradeHub = class {
+	server;
+	all = /* @__PURE__ */ new Set();
+	alive = /* @__PURE__ */ new WeakMap();
+	grace;
+	timer;
+	closed = false;
+	constructor(options = {}) {
+		const Server = loadWs();
+		this.server = new Server({
+			noServer: true,
+			maxPayload: options.maxPayload ?? 1024 * 1024,
+			perMessageDeflate: false
+		});
+		this.grace = options.grace ?? 2e3;
+		this.server.on("connection", (ws) => {
+			this.all.add(ws);
+			this.alive.set(ws, true);
+			ws.on("pong", () => this.alive.set(ws, true));
+			ws.on("close", () => this.all.delete(ws));
+		});
+		const heartbeat = options.heartbeat ?? 3e4;
+		if (heartbeat > 0) {
+			this.timer = setInterval(() => {
+				for (const ws of this.all) {
+					if (this.alive.get(ws) === false) {
+						ws.terminate();
+						continue;
+					}
+					this.alive.set(ws, false);
+					ws.ping();
+				}
+			}, heartbeat);
+			this.timer.unref();
+		}
+	}
+	/**
+	* Accept upgrades from `source` and answer them with `router`: the request runs through the router's middleware with the socket's peer address and local port as connection
+	* facts (so the same loopback, origin and host checks work), and the upgrade bindings travel in `c.env` for `upgradeWebSocket`.
+	*/
+	attach(source, router) {
+		const fetchCallback = (request, env) => {
+			const { incoming } = env;
+			return router.fetch(request, {
+				remoteAddress: incoming.socket.remoteAddress,
+				localPort: incoming.socket.localPort
+			}, env);
+		};
+		setupWebSocket({
+			server: source,
+			fetchCallback,
+			wss: this.server
+		});
+	}
+	/** How many sockets are open. */
+	get size() {
+		return this.all.size;
+	}
+	/** `upgradeWebSocket` for the plugin `owner`: the sockets it accepts are closed with 1001 when that plugin unloads. */
+	upgradeWebSocketFor(owner) {
+		const mine = /* @__PURE__ */ new Set();
+		owner.effect(() => () => this.closeAll(mine, 1001, "going away"), "upgrade sockets");
+		const track = (ws) => {
+			mine.add(ws);
+			ws.on("close", () => mine.delete(ws));
+		};
+		const owned = (...args) => {
+			const [first, second, third] = args;
+			return typeof first === "function" ? upgradeWebSocket(first, {
+				...second,
+				track
+			}) : upgradeWebSocket(first, second, {
+				...third,
+				track
+			});
+		};
+		return owned;
+	}
+	/** Close `sockets` with `code`, wait for their close handshakes up to the grace, terminate what is left. */
+	async closeAll(sockets, code, reason) {
+		const open = [...sockets].filter((ws) => ws.readyState < 3);
+		await Promise.all(open.map((ws) => new Promise((resolve) => {
+			const timer = setTimeout(() => {
+				ws.terminate();
+				resolve();
+			}, this.grace);
+			ws.on("close", () => {
+				clearTimeout(timer);
+				resolve();
+			});
+			if (ws.readyState === 1) ws.close(code, reason);
+			else if (ws.readyState === 3) {
+				clearTimeout(timer);
+				resolve();
+			}
+		})));
+	}
+	/** End everything: every socket closes with 1001, the heartbeat stops, the `ws` server closes. */
+	async close() {
+		if (this.closed) return;
+		this.closed = true;
+		if (this.timer !== void 0) clearInterval(this.timer);
+		await this.closeAll(this.all, 1001, "going away");
+		this.server.close();
+	}
+};
+/** A stand-in for a server's `upgrade` events, for transports that dispatch upgrades themselves (the Host web server's exact-path routes). */
+var UpgradeEmitter = class extends EventEmitter {};
+//#endregion
+//#region ../../plugins/acryl-node-server/src/test-websocket.ts
+/** A fake `ws` socket: events go both ways without a network. */
+var FakeSocket = class {
+	protocol = "";
+	readyState = 1;
+	bufferedAmount = 0;
+	sent = [];
+	closedWith;
+	listeners = /* @__PURE__ */ new Map();
+	on(event, listener) {
+		this.listeners.set(event, [...this.listeners.get(event) ?? [], listener]);
+		return this;
+	}
+	off(event, listener) {
+		this.listeners.set(event, (this.listeners.get(event) ?? []).filter((l) => l !== listener));
+		return this;
+	}
+	emit(event, ...args) {
+		for (const listener of this.listeners.get(event) ?? []) listener(...args);
+	}
+	send(data) {
+		this.sent.push(typeof data === "string" ? data : Buffer.from(data).toString("utf8"));
+	}
+	close(code, reason) {
+		if (this.readyState === 3) return;
+		this.closedWith = {
+			code,
+			reason
+		};
+		this.readyState = 3;
+		this.emit("close", code ?? 1005, Buffer.from(reason ?? ""));
+	}
+	ping() {}
+	terminate() {
+		this.close(1006);
+	}
+};
+async function testWebSocket(fetch, path, options = {}) {
+	const fake = new FakeSocket();
+	let waiter;
+	const env = {
+		incoming: {
+			headers: options.headers ?? {},
+			socket: {
+				remoteAddress: options.connection?.remoteAddress,
+				localPort: options.connection?.localPort
+			}
+		},
+		outgoing: void 0,
+		wss: {},
+		[WAIT_FOR_WEBSOCKET_SYMBOL]: (_request, connectionSymbol) => new Promise((resolve) => {
+			waiter = {
+				connectionSymbol,
+				resolve
+			};
+		})
+	};
+	const headers = new Headers({
+		upgrade: "websocket",
+		connection: "Upgrade",
+		...options.headers
+	});
+	const response = await fetch(new Request(new URL(path, options.base ?? "http://127.0.0.1"), { headers }), env);
+	if (!waiter || waiter.connectionSymbol !== env[CONNECTION_SYMBOL_KEY]) return { status: response.status };
+	waiter.resolve(fake);
+	await new Promise((resolve) => setTimeout(resolve, 0));
+	return {
+		status: 101,
+		socket: {
+			received: fake.sent,
+			get closed() {
+				return fake.closedWith;
+			},
+			send: (text) => fake.emit("message", text, false),
+			close: (code, reason) => {
+				if (fake.readyState === 3) return;
+				fake.readyState = 3;
+				fake.emit("close", code ?? 1005, Buffer.from(reason ?? ""));
+			}
+		}
+	};
+}
+//#endregion
+export { serve as a, Request$1 as c, createAdaptorServer as i, RequestError as l, UpgradeEmitter as n, upgradeWebSocket as o, UpgradeHub as r, getRequestListener as s, testWebSocket as t };

package/lib/ws.d.ts

@@ -1,2 +1,2 @@
-import { a as WSEvents, c as WebSocketHelperDefineContext, d as defineWebSocketHelper, i as WSContextInit, l as WebSocketHelperDefineHandler, n as UpgradeWebSocket, o as WSMessageReceive, r as WSContext, s as WSReadyState, t as SendOptions, u as createWSMessageEvent } from "./index-BvFh1Gfx.js";
+import { a as WSEvents, c as WebSocketHelperDefineContext, d as defineWebSocketHelper, i as WSContextInit, l as WebSocketHelperDefineHandler, n as UpgradeWebSocket, o as WSMessageReceive, r as WSContext, s as WSReadyState, t as SendOptions, u as createWSMessageEvent } from "./index-C-SklY6u.js";
 export { SendOptions, UpgradeWebSocket, WSContext, WSContextInit, WSEvents, WSMessageReceive, WSReadyState, WebSocketHelperDefineContext, WebSocketHelperDefineHandler, createWSMessageEvent, defineWebSocketHelper };

package/lib/ws.js

@@ -18,6 +18,9 @@ var WSContext = class {
 	get readyState() {
 		return this.#init.readyState;
 	}
+	get bufferedAmount() {
+		return this.#init.bufferedAmount ?? 0;
+	}
 	url;
 	protocol;
 	close(code, reason) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "acrylblends",
-  "version": "0.9.2",
+  "version": "0.11.0",
   "description": "The Acryl web framework (import { Acryl } from \"acrylblends\") and the acrylblends command that scaffolds Cordis apps.",
   "license": "MIT",
   "type": "module",
@@ -552,7 +552,8 @@
     "@deepseek-ai/cordis": "^4.0.2",
     "@deepseek-ai/schemastery": "~3.18.4",
     "react": ">=18",
-    "vitest": ">=3"
+    "vitest": ">=3",
+    "ws": ">=8"
   },
   "peerDependenciesMeta": {
     "@deepseek-ai/cordis": {
@@ -566,6 +567,9 @@
     },
     "vitest": {
       "optional": true
+    },
+    "ws": {
+      "optional": true
     }
   },
   "scripts": {

package/plugins/acryl-door/src/host/door.ts

@@ -43,8 +43,8 @@ export interface ToolsPort {
 export interface DoorDeps {
   readonly channel: UiChannel
   readonly audit: AuditLog
-  /** The app's name and folder. */
-  readonly app: { readonly name: string; readonly root: string }
+  /** The app's name, folder and, when it listens, its address (what `brief` prints so an agent can curl the running app). */
+  readonly app: { readonly name: string; readonly root: string; readonly url?: string | undefined }
   /** Read at each call: the services may come and go while the door runs. */
   readonly extensions: () => ExtensionsPort | undefined
   readonly tools: () => ToolsPort | undefined
@@ -99,11 +99,12 @@ export class Door {
   }
 
   brief(): VerbAnswer {
-    const { name, root } = this.deps.app
+    const { name, root, url } = this.deps.app
     const read = SELF_KNOWLEDGE.filter(path => existsSync(resolve(root, path)))
     const value = {
       app: name,
       root,
+      ...(url === undefined ? {} : { url }),
       read,
       page: this.deps.channel.connected ? 'open' : 'not open',
       plugins: this.deps.extensions() === undefined ? 'unavailable' : 'available',
@@ -111,6 +112,7 @@ export class Door {
     }
     const text = [
       `App ${name} in ${root}.`,
+      ...(url === undefined ? [] : [`Address: ${url} (the running app; curl it to check a route).`]),
       read.length === 0 ? 'No AGENTS.md or skill in the folder.' : `Read first: ${read.join(', ')}.`,
       `Page: ${value.page}${value.page === 'not open' ? ' (open the app in a browser to look and act)' : ''}.`,
       `Live plugins: ${value.plugins}.`,

package/plugins/acryl-door/src/index.ts

@@ -96,7 +96,7 @@ export function apply(ctx: Context, rawConfig: Config = {}): void {
   const door = new Door({
     channel,
     audit,
-    app: { name: app.name, root: app.root },
+    app: { name: app.name, root: app.root, url: loopbackUrl(server.url) },
     extensions: () => ctx.get('extensions') as unknown as ExtensionsPort | undefined,
     tools: () => ctx.get('tools') as unknown as ToolsPort | undefined,
     expose: config.tools?.expose ?? [],

package/plugins/acryl-node-server/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "acryl-node-server",
   "description": "The standalone HTTP server as a Cordis plugin: one node:http listener that sends every request to the router. Port, loopback host and next-free-port scan; ends open streams and frees the port when unloaded. Vendored from ACRYL.",
-  "requires": ["acryl-router", "acryl-router-http"],
+  "requires": ["acryl-router"],
   "inject": ["router"],
   "provides": ["nodeServer"],
   "dependencies": {

package/plugins/acryl-node-server/src/adapter/websocket-types.ts

@@ -19,11 +19,15 @@ export type WebSocketSendOptions = {
 export interface WebSocketLike {
   protocol: string
   readyState: WSReadyState
+  bufferedAmount: number
   close(code?: number, reason?: string): void
   send(data: string | ArrayBuffer | ArrayBufferView, options?: WebSocketSendOptions): void
   on(event: 'message', listener: (data: WebSocketData, isBinary: boolean) => void): this
   on(event: 'close', listener: (code: number, reason: Uint8Array) => void): this
   on(event: 'error', listener: (error: unknown) => void): this
+  on(event: 'pong', listener: () => void): this
+  ping(): void
+  terminate(): void
   off(event: 'message', listener: (data: WebSocketData, isBinary: boolean) => void): this
 }
 
@@ -41,5 +45,5 @@ export interface WebSocketServerLike {
     head: Buffer,
     callback: (ws: WebSocketLike) => void
   ): void
-  close(): void
+  close(callback?: () => void): void
 }

package/plugins/acryl-node-server/src/adapter/websocket.ts

@@ -3,7 +3,7 @@ import { defineWebSocketHelper } from 'acryl-router/helpers'
 import type { IncomingMessage } from 'node:http'
 import { STATUS_CODES } from 'node:http'
 import type { Duplex } from 'node:stream'
-import type { FetchCallback, ServerType } from './types.ts'
+import type { FetchCallback } from './types.ts'
 import type { WebSocketData, WebSocketLike, WebSocketServerLike } from './websocket-types.ts'
 
 interface CloseEventInit extends EventInit {
@@ -83,13 +83,17 @@ export const ErrorEvent: typeof globalThis.ErrorEvent =
 
 const generateConnectionSymbol = () => Symbol('connection')
 
+/** The codes an endpoint may send in a close frame (RFC 6455 section 7.4): 1000-1003, 1007-1014 and the private ranges 3000-4999. */
+export const validCloseCode = (code: number): boolean =>
+  (code >= 1000 && code <= 1014 && code !== 1004 && code !== 1005 && code !== 1006) || (code >= 3000 && code <= 4999)
+
 type WaitForWebSocket = (
   request: IncomingMessage,
   connectionSymbol: symbol
 ) => Promise<WebSocketLike>
 
-const CONNECTION_SYMBOL_KEY: unique symbol = Symbol('CONNECTION_SYMBOL_KEY')
-const WAIT_FOR_WEBSOCKET_SYMBOL: unique symbol = Symbol('WAIT_FOR_WEBSOCKET_SYMBOL')
+export const CONNECTION_SYMBOL_KEY: unique symbol = Symbol('CONNECTION_SYMBOL_KEY')
+export const WAIT_FOR_WEBSOCKET_SYMBOL: unique symbol = Symbol('WAIT_FOR_WEBSOCKET_SYMBOL')
 
 export type UpgradeBindings = {
   incoming: IncomingMessage
@@ -101,6 +105,10 @@ export type UpgradeBindings = {
 
 type UpgradeWebSocketOptions = {
   onError: (err: unknown) => void
+  /** Hand the handler text frames only; binary frames are dropped before `onMessage`. */
+  textOnly?: boolean
+  /** Called with each accepted socket: the mounting plugin's scope keeps it to close it when the plugin unloads. */
+  track?: (ws: WebSocketLike) => void
 }
 
 // Hop-by-hop headers per RFC 9110 Section 7.6.1
@@ -162,8 +170,15 @@ const createUpgradeRequest = (request: IncomingMessage): Request => {
   })
 }
 
+/** The part of a server `setupWebSocket` listens to: the Host's web server hands upgrades to a plain emitter with the same two methods. */
+export interface UpgradeSource {
+  on(event: 'upgrade', listener: (request: IncomingMessage, socket: Duplex, head: Buffer) => void): unknown
+  on(event: 'close', listener: () => void): unknown
+  listenerCount(event: 'upgrade'): number
+}
+
 export const setupWebSocket = (options: {
-  server: ServerType
+  server: UpgradeSource
   fetchCallback: FetchCallback
   wss: WebSocketServerLike
 }): void => {
@@ -202,6 +217,8 @@ export const setupWebSocket = (options: {
 
   server.on('upgrade', async (request, socket: Duplex, head) => {
     if (request.headers.upgrade?.toLowerCase() !== 'websocket') {
+      // Nobody else listens: an upgrade to another protocol is answered, not left hanging.
+      if (server.listenerCount('upgrade') === 1) rejectUpgradeRequest(socket, 400)
       return
     }
 
@@ -282,6 +299,7 @@ export const upgradeWebSocket: UpgradeWebSocket<WebSocketLike, UpgradeWebSocketO
       let ws: WebSocketLike
       try {
         ws = await waitForWebSocket(env.incoming, connectionSymbol)
+        options?.track?.(ws)
       } catch {
         return
       }
@@ -296,13 +314,17 @@ export const upgradeWebSocket: UpgradeWebSocket<WebSocketLike, UpgradeWebSocketO
       const shape: Pick<WSContext<WebSocketLike>, keyof WSContext<WebSocketLike>> = {
         binaryType: 'arraybuffer',
         close(code, reason) {
-          ws.close(code, reason)
+          // An application code (1013, 4404, ...) passes; one the protocol forbids on the wire would make `ws` throw, so it becomes 1011.
+          ws.close(code === undefined || validCloseCode(code) ? code : 1011, reason)
         },
         protocol: ws.protocol,
         raw: ws,
         get readyState() {
           return ws.readyState
         },
+        get bufferedAmount() {
+          return ws.bufferedAmount
+        },
         send(source, opts) {
           ws.send(source, {
             compress: opts?.compress,
@@ -319,6 +341,8 @@ export const upgradeWebSocket: UpgradeWebSocket<WebSocketLike, UpgradeWebSocketO
       }
 
       const handleMessage = (data: WebSocketData, isBinary: boolean) => {
+        // With `textOnly` a binary frame never reaches the handler.
+        if (isBinary && options?.textOnly) return
         const datas = Array.isArray(data) ? data : [data]
         for (const data of datas) {
           try {
@@ -349,7 +373,11 @@ export const upgradeWebSocket: UpgradeWebSocket<WebSocketLike, UpgradeWebSocketO
         handleMessage(data, isBinary)
       })
 
+      let closed = false
       ws.on('close', (code, reason) => {
+        // The handler sees close exactly once, whoever closed the socket.
+        if (closed) return
+        closed = true
         try {
           events?.onClose?.(new CloseEvent('close', { code, reason: reason.toString() }), ctx)
         } catch (e) {

package/plugins/acryl-node-server/src/index.ts

@@ -17,9 +17,14 @@ import z from '@deepseek-ai/schemastery'
 import type {} from 'acryl-router'
 import { Request as AdapterRequest } from './adapter/request.ts'
 import { createAdaptorServer } from './adapter/server.ts'
+import { UpgradeHub, type UpgradeHubOptions } from './upgrade-hub.ts'
+import type { UpgradeWebSocket } from 'acryl-router/helpers'
+import type { WebSocketLike } from './adapter/websocket-types.ts'
 
 export { serveStatic, type ServeStaticOptions } from './adapter/serve-static.ts'
 export { RequestError } from './adapter/request.ts'
+export { testWebSocket, type TestSocket, type TestWebSocketOptions, type TestWebSocketResult } from './test-websocket.ts'
+export { UpgradeEmitter, UpgradeHub, type UpgradeHubOptions, type UpgradeRouter } from './upgrade-hub.ts'
 
 /** Stable Cordis plugin name, equal to the package name and the Loader row id. */
 export const name = 'acryl-node-server'
@@ -29,6 +34,8 @@ export interface Config {
   hostname: string
   port: number
   scan: number
+  /** Limits of WebSocket upgrades (`upgrades()`); the defaults suit most apps. */
+  websocket: UpgradeHubOptions
 }
 
 /** Every field has a default, so a caller passes only what it changes: `ctx.plugin(plugin, { ... })` takes the partial shape. */
@@ -36,6 +43,13 @@ export const Config: z<Partial<Config>, Config> = z.object({
   hostname: z.string().default('127.0.0.1').description('Address to bind. Loopback by default; binding elsewhere exposes the app to the network.'),
   port: z.number().min(0).max(65535).default(0).description('Port to listen on; 0 lets the system choose. A taken port is followed by the next free one.'),
   scan: z.number().min(0).default(20).description('How many further ports to try when the configured one is taken.'),
+  websocket: z
+    .object({
+      maxPayload: z.number().min(1).default(1024 * 1024).description('The largest WebSocket frame accepted, in bytes; a bigger one closes the socket with 1009.'),
+      heartbeat: z.number().min(0).default(30_000).description('Milliseconds between pings; a peer that did not answer the last one is terminated. 0 turns it off.'),
+      grace: z.number().min(0).default(2000).description('Milliseconds a closing socket gets before it is terminated when its plugin unloads.'),
+    })
+    .default({}),
 })
 
 declare module '@deepseek-ai/cordis' {
@@ -48,6 +62,7 @@ export class NodeServer extends Service {
   readonly hostname: string
   readonly config: Config
   private readonly server: Server
+  private hub: UpgradeHub | undefined
   private bound = 0
 
   constructor(ctx: Context, config: Config) {
@@ -64,11 +79,30 @@ export class NodeServer extends Service {
       overrideGlobalObjects: false,
     }) as Server
     ctx.effect(() => async () => {
+      await this.hub?.close()
       this.server.closeAllConnections()
       if (this.server.listening) await new Promise<void>(resolve => { this.server.close(() => { resolve() }) })
     }, 'acryl-node-server: close listener and open connections')
   }
 
+  /**
+   * `upgradeWebSocket` for the plugin that asks (call it once, in `apply`): `app.get('/ws', upgrade((c) => ({ onMessage(event, ws) { ... } })))`. Checks go in ordinary middleware on the
+   * route, and a handler that returns a `Response` refuses the upgrade with that status before any handshake. Every socket it accepts belongs to the calling plugin: when the plugin
+   * unloads they are closed with 1001 within `websocket.grace` and the handler sees `close` once. Pass `{ textOnly: true }` to drop binary frames. Needs the `ws` package.
+   */
+  upgrades(): UpgradeWebSocket<WebSocketLike> {
+    if (!this.hub) {
+      this.hub = new UpgradeHub(this.config.websocket)
+      this.hub.attach(this.server, this.ctx.router)
+    }
+    return this.hub.upgradeWebSocketFor(this.ctx)
+  }
+
+  /** How many WebSocket connections are open now. */
+  get sockets(): number {
+    return this.hub?.size ?? 0
+  }
+
   /** The port in use, 0 before the server listens. */
   get port(): number {
     return this.bound
@@ -113,6 +147,6 @@ export function isPortUnavailable(error: unknown, platform: NodeJS.Platform = pr
 
 /** Loads once the server listens, so a plugin that injects `nodeServer` can rely on `url`. A failure to bind fails the plugin. */
 export async function apply(ctx: Context, config: Partial<Config> = {}): Promise<void> {
-  const server = new NodeServer(ctx, { hostname: '127.0.0.1', port: 0, scan: 20, ...config })
+  const server = new NodeServer(ctx, { hostname: '127.0.0.1', port: 0, scan: 20, websocket: {}, ...config })
   await server.listen()
 }