acrylblends 0.9.2 → 0.11.0

package/lib/cordis/node-server.d.ts

@@ -1,4 +1,5 @@
-import { t as RequestError } from "../error-t4N2js2I.js";
+import { c as UpgradeHubOptions, i as testWebSocket, l as UpgradeRouter, n as TestWebSocketOptions, o as UpgradeEmitter, p as WebSocketLike, r as TestWebSocketResult, s as UpgradeHub, t as TestSocket, u as RequestError } from "../test-websocket-DyeS50Tr.js";
+import { n as UpgradeWebSocket } from "../index-C-SklY6u.js";
 import { ServeStaticOptions, serveStatic } from "../node-server/serve-static.js";
 import { Context, Service } from "@deepseek-ai/cordis";
 import z from "@deepseek-ai/schemastery";
@@ -11,6 +12,8 @@ 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. */
 declare const Config: z<Partial<Config>, Config>;
@@ -23,8 +26,17 @@ declare class NodeServer extends Service {
   readonly hostname: string;
   readonly config: Config;
   private readonly server;
+  private hub;
   private bound;
   constructor(ctx: Context, config: Config);
+  /**
+   * `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>;
+  /** How many WebSocket connections are open now. */
+  get sockets(): number;
   /** The port in use, 0 before the server listens. */
   get port(): number;
   /** The address clients use. */
@@ -42,4 +54,4 @@ declare function isPortUnavailable(error: unknown, platform?: NodeJS.Platform):
 /** Loads once the server listens, so a plugin that injects `nodeServer` can rely on `url`. A failure to bind fails the plugin. */
 declare function apply(ctx: Context, config?: Partial<Config>): Promise<void>;
 //#endregion
-export { Config, NodeServer, RequestError, type ServeStaticOptions, apply, inject, isPortUnavailable, name, serveStatic };
+export { Config, NodeServer, RequestError, type ServeStaticOptions, type TestSocket, type TestWebSocketOptions, type TestWebSocketResult, UpgradeEmitter, UpgradeHub, type UpgradeHubOptions, type UpgradeRouter, apply, inject, isPortUnavailable, name, serveStatic, testWebSocket };

package/lib/cordis/node-server.js

@@ -1,4 +1,4 @@
-import { a as Request, o as RequestError, t as createAdaptorServer } from "../server-DvgMGtzo.js";
+import { c as Request, i as createAdaptorServer, l as RequestError, n as UpgradeEmitter, r as UpgradeHub, t as testWebSocket } from "../test-websocket-ZXHNHQSU.js";
 import { t as serveStatic } from "../serve-static-3uo_9rjF.js";
 import { Service } from "@deepseek-ai/cordis";
 import z from "@deepseek-ai/schemastery";
@@ -10,12 +10,18 @@ const inject = ["router"];
 const 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.")
+	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(3e4).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(2e3).description("Milliseconds a closing socket gets before it is terminated when its plugin unloads.")
+	}).default({})
 });
 var NodeServer = class extends Service {
 	hostname;
 	config;
 	server;
+	hub;
 	bound = 0;
 	constructor(ctx, config) {
 		super(ctx, "nodeServer");
@@ -31,6 +37,7 @@ var NodeServer = class extends Service {
 			overrideGlobalObjects: false
 		});
 		ctx.effect(() => async () => {
+			await this.hub?.close();
 			this.server.closeAllConnections();
 			if (this.server.listening) await new Promise((resolve) => {
 				this.server.close(() => {
@@ -39,6 +46,22 @@ var NodeServer = class extends Service {
 			});
 		}, "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() {
+		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() {
+		return this.hub?.size ?? 0;
+	}
 	/** The port in use, 0 before the server listens. */
 	get port() {
 		return this.bound;
@@ -86,8 +109,9 @@ async function apply(ctx, config = {}) {
 		hostname: "127.0.0.1",
 		port: 0,
 		scan: 20,
+		websocket: {},
 		...config
 	}).listen();
 }
 //#endregion
-export { Config, NodeServer, RequestError, apply, inject, isPortUnavailable, name, serveStatic };
+export { Config, NodeServer, RequestError, UpgradeEmitter, UpgradeHub, apply, inject, isPortUnavailable, name, serveStatic, testWebSocket };

package/lib/cordis/router-http.d.ts

@@ -1,5 +1,7 @@
-import { i as RouterHttpService } from "../index-BqVQkTnu.js";
+import { n as UpgradeWebSocket } from "../index-C-SklY6u.js";
+import { i as RouterHttpService } from "../index-D4nVR3wu.js";
 import { IncomingMessage, ServerResponse } from "node:http";
+import { Duplex } from "node:stream";
 import { Context, Service } from "@deepseek-ai/cordis";
 
 //#region ../../plugins/acryl-router-http/src/serve.d.ts
@@ -40,16 +42,37 @@ interface WebServerPort {
     readonly path: string;
     readonly handler: (req: IncomingMessage, res: ServerResponse) => void | Promise<void>;
   }): () => void;
+  /** One exact-path upgrade claim (`WebUpgradeRoute` of the web server); optional because an older web server has none. */
+  registerUpgrade?(route: {
+    readonly path: string;
+    readonly handler: (req: IncomingMessage, socket: Duplex, head: Buffer) => void | Promise<void>;
+  }): () => void;
 }
 declare class RouterHttp extends Service implements RouterHttpService {
   private readonly router;
   private readonly web;
+  private hub;
+  /** The adapter's own context: the hub lives as long as the adapter, whichever plugin asked for it first (`this.ctx` is the caller's). */
+  private readonly home;
+  private readonly upgradesIn;
   constructor(ctx: Context);
   /**
    * Serve `prefix` and everything below it through the router. Returns a remover; the mount also goes away when the
    * calling plugin unloads. A prefix another route already claims throws, as the webServer treats it as misconfiguration.
+   * `options.upgrade` names the exact paths that may be upgraded to a WebSocket: each must be inside the prefix, and each is one
+   * exact-path upgrade route of the web server, removed with the mount. No other path of the mount accepts an upgrade.
+   */
+  mount(prefix: string, options?: {
+    readonly upgrade?: readonly string[];
+  }): () => void;
+  /**
+   * `upgradeWebSocket` for the calling plugin: the sockets its routes accept are closed with 1001 when it unloads. Needs the `ws` package.
+   * The route must be on a path the plugin mounted with `upgrade: [path]`.
    */
-  mount(prefix: string): () => void;
+  upgrades(): UpgradeWebSocket;
+  /** How many WebSocket connections are open now. */
+  get sockets(): number;
+  private ensureHub;
 }
 declare function apply(ctx: Context): void;
 //#endregion

package/lib/cordis/router-http.js

@@ -1,3 +1,5 @@
+import { n as UpgradeEmitter, r as UpgradeHub } from "../test-websocket-ZXHNHQSU.js";
+import "./node-server.js";
 import { pipeline } from "node:stream/promises";
 import { Readable } from "node:stream";
 import { Service } from "@deepseek-ai/cordis";
@@ -88,27 +90,73 @@ const PREFIX_PATTERN = /^\/[A-Za-z0-9._~\-/]*[A-Za-z0-9._~-]$/;
 var RouterHttp = class extends Service {
 	router;
 	web;
+	hub;
+	/** The adapter's own context: the hub lives as long as the adapter, whichever plugin asked for it first (`this.ctx` is the caller's). */
+	home;
+	upgradesIn = new UpgradeEmitter();
 	constructor(ctx) {
 		super(ctx, "routerHttp");
+		this.home = ctx;
 		this.router = ctx.router;
 		this.web = ctx.get("webServer");
 	}
 	/**
 	* Serve `prefix` and everything below it through the router. Returns a remover; the mount also goes away when the
 	* calling plugin unloads. A prefix another route already claims throws, as the webServer treats it as misconfiguration.
+	* `options.upgrade` names the exact paths that may be upgraded to a WebSocket: each must be inside the prefix, and each is one
+	* exact-path upgrade route of the web server, removed with the mount. No other path of the mount accepts an upgrade.
 	*/
-	mount(prefix) {
+	mount(prefix, options = {}) {
 		if (!PREFIX_PATTERN.test(prefix)) throw new TypeError(`acryl-router-http: "${prefix}" is not a mountable path prefix`);
-		const remove = this.web.register({
-			kind: "prefix",
-			path: prefix,
-			handler: (req, res) => serve(this.router, req, res)
-		});
+		const upgrade = options.upgrade ?? [];
+		for (const path of upgrade) if (!PREFIX_PATTERN.test(path) || !(path === prefix || path.startsWith(`${prefix}/`))) throw new TypeError(`acryl-router-http: the upgrade path "${path}" is not inside the prefix "${prefix}"`);
+		if (upgrade.length > 0 && this.web.registerUpgrade === void 0) throw new TypeError("acryl-router-http: this web server cannot take WebSocket upgrades (it has no registerUpgrade)");
+		const removers = [];
+		try {
+			if (upgrade.length > 0) this.ensureHub();
+			for (const path of upgrade) removers.push(this.web.registerUpgrade({
+				path,
+				handler: (req, socket, head) => {
+					this.upgradesIn.emit("upgrade", req, socket, head);
+				}
+			}));
+			removers.push(this.web.register({
+				kind: "prefix",
+				path: prefix,
+				handler: (req, res) => serve(this.router, req, res)
+			}));
+		} catch (error) {
+			for (const remove of removers) remove();
+			throw error;
+		}
+		const remove = () => {
+			for (const undo of removers.splice(0)) undo();
+		};
 		this.ctx.effect(() => () => {
 			remove();
 		}, `acryl-router-http: mount ${prefix}`);
 		return remove;
 	}
+	/**
+	* `upgradeWebSocket` for the calling plugin: the sockets its routes accept are closed with 1001 when it unloads. Needs the `ws` package.
+	* The route must be on a path the plugin mounted with `upgrade: [path]`.
+	*/
+	upgrades() {
+		return this.ensureHub().upgradeWebSocketFor(this.ctx);
+	}
+	/** How many WebSocket connections are open now. */
+	get sockets() {
+		return this.hub?.size ?? 0;
+	}
+	ensureHub() {
+		if (!this.hub) {
+			const hub = new UpgradeHub();
+			hub.attach(this.upgradesIn, this.router);
+			this.hub = hub;
+			this.home.effect(() => () => hub.close(), "acryl-router-http: WebSocket hub");
+		}
+		return this.hub;
+	}
 };
 function apply(ctx) {
 	new RouterHttp(ctx);

package/lib/cordis/router.d.ts

@@ -3,6 +3,6 @@ import { c as StatusCode, n as ContentfulStatusCode } from "../http-status-DaAwG
 import { a as getConnInfo, i as connectionOf, n as RouterBindings, r as RouterEnv, t as ConnectionInfo } from "../connection-ZLEso7XL.js";
 import { t as Acryl } from "../app-D8riatvv.js";
 import { n as AppRequest, t as App } from "../deprecated-CTy4N7ng.js";
-import { a as TrailingSlash, i as RouterHttpService, n as MountableApp, o as apply, r as Router, s as name, t as Config } from "../index-BqVQkTnu.js";
+import { a as TrailingSlash, i as RouterHttpService, n as MountableApp, o as apply, r as Router, s as name, t as Config } from "../index-D4nVR3wu.js";
 import { t as HTTPException } from "../http-exception-kpGJkmpi.js";
 export { Acryl, type AcrylRequest, App, type AppRequest, Config, type ConnectionInfo, type ContentfulStatusCode, Context, type ContextRenderer, type ContextVariableMap, type Env, type ErrorHandler, type ExecutionContext, HTTPException, type Handler, type Input, type MiddlewareHandler, type MountableApp, type Next, type NotFoundHandler, type NotFoundResponse, Router, type RouterBindings, type RouterEnv, type RouterHttpService, type Schema, type StatusCode, type ToSchema, type TrailingSlash, type TypedResponse, type ValidationTargets, apply, connectionOf, getConnInfo, name };

package/lib/cordis/router.js

@@ -3,5 +3,5 @@ import { t as Context } from "../context-DDO0cfuP.js";
 import { t as Acryl } from "../app-BM0rTCp7.js";
 import { t as App } from "../deprecated-BP4fPt38.js";
 import { n as getConnInfo, t as connectionOf } from "../connection-C7xgP1hP.js";
-import { i as name, n as Router, r as apply, t as Config } from "../src-CwABFr6r.js";
+import { i as name, n as Router, r as apply, t as Config } from "../src-DNzw0Qsb.js";
 export { Acryl, App, Config, Context, HTTPException, Router, apply, connectionOf, getConnInfo, name };

package/lib/cordis/state.js

@@ -3,7 +3,7 @@ import { methodNotAllowed } from "../method-not-allowed.js";
 import { r as streamSSE } from "../streaming-DHST3Scg.js";
 import { loopbackOnly } from "../loopback-only.js";
 import "../helpers-CvTauQT5.js";
-import "../src-CwABFr6r.js";
+import "../src-DNzw0Qsb.js";
 import "../middleware-CPQ8himN.js";
 import { Service } from "@deepseek-ai/cordis";
 //#region ../../plugins/acryl-state/src/cell.ts

package/lib/door/host.js

@@ -1,2 +1,2 @@
-import { d as AuditLog, f as auditPath, n as HEARTBEAT_MS, p as UiChannel, r as pageChannelRoutes, t as renderSnapshot } from "../snapshot-text-D3NspDyT.js";
+import { d as AuditLog, f as auditPath, n as HEARTBEAT_MS, p as UiChannel, r as pageChannelRoutes, t as renderSnapshot } from "../snapshot-text-yaWlezbd.js";
 export { AuditLog, HEARTBEAT_MS, UiChannel, auditPath, pageChannelRoutes, renderSnapshot };

package/lib/{index-BvFh1Gfx.d.ts → index-C-SklY6u.d.ts}

@@ -33,6 +33,8 @@ interface WSContextInit<T = unknown> {
   close(code?: number, reason?: string): void;
   raw?: T;
   readyState: WSReadyState;
+  /** Bytes queued to send and not yet written to the socket; a sender that cares about back-pressure reads it. */
+  bufferedAmount?: number;
   url?: string | URL | null;
   protocol?: string | null;
 }
@@ -52,6 +54,7 @@ declare class WSContext<T = unknown> {
   raw?: T;
   binaryType: BinaryType;
   get readyState(): WSReadyState;
+  get bufferedAmount(): number;
   url: URL | null;
   protocol: string | null;
   close(code?: number, reason?: string): void;

package/lib/{index-BqVQkTnu.d.ts → index-D4nVR3wu.d.ts}

@@ -1,5 +1,6 @@
 import { B as NotFoundHandler, y as ErrorHandler } from "./context-DS3fYyG-.js";
 import { t as ConnectionInfo } from "./connection-ZLEso7XL.js";
+import { n as UpgradeWebSocket } from "./index-C-SklY6u.js";
 import { Context, Service } from "@deepseek-ai/cordis";
 import z from "@deepseek-ai/schemastery";
 
@@ -18,8 +19,21 @@ declare const Config: z<Partial<Config>, Config>;
  * served over HTTP without depending on the adapter package.
  */
 interface RouterHttpService {
-  /** Serve `prefix` and everything below it through the router; returns a remover. The mount also goes away when the calling plugin unloads. */
-  mount(prefix: string): () => void;
+  /**
+   * Serve `prefix` and everything below it through the router; returns a remover. The mount also goes away when the calling plugin unloads.
+   * `options.upgrade` lists the exact paths below the prefix that may be upgraded to a WebSocket (each must be inside the prefix); no other path of the mount accepts an upgrade.
+   */
+  mount(prefix: string, options?: {
+    readonly upgrade?: readonly string[];
+  }): () => void;
+  /**
+   * `upgradeWebSocket` for the calling plugin: `app.get('/terminal', upgrade((c) => ({ onMessage(event, ws) { ... } })))` on a route the plugin mounted with `upgrade: ['/terminal']`.
+   * Checks go in ordinary middleware on the route; a handler that returns a `Response` refuses with that status before any handshake. The sockets it accepts belong to the calling
+   * plugin: when it unloads they are closed with 1001 and the handler sees `close` once. Needs the `ws` package.
+   */
+  upgrades(): UpgradeWebSocket;
+  /** How many WebSocket connections are open now. */
+  readonly sockets: number;
 }
 declare module '@deepseek-ai/cordis' {
   interface Context {
@@ -83,8 +97,9 @@ declare class Router extends Service {
    * Run a request in process. Never throws: failures become a 500, a disposed router answers 503. `connection` describes the transport
    * (an HTTP adapter passes the socket's peer address and local port); an in-process caller omits it. Handlers read it with
    * `connectionOf(c)`, abort with `c.req.raw.signal` and keep the request in flight with `c.executionCtx.waitUntil(task)`.
+   * `bindings` is an object an adapter hands to the handler as `c.env` (an upgrade request's socket hooks, for `upgradeWebSocket`); `connection` is added to it.
    */
-  fetch(request: Request, connection?: ConnectionInfo): Promise<Response>;
+  fetch(request: Request, connection?: ConnectionInfo, bindings?: object): Promise<Response>;
   private dispatch;
   private app;
   /**

package/lib/node-server.d.ts

@@ -1,42 +1,12 @@
 import { t as Acryl } from "./app-D8riatvv.js";
-import { n as UpgradeWebSocket } from "./index-BvFh1Gfx.js";
-import { t as RequestError } from "./error-t4N2js2I.js";
+import { a as Owner, c as UpgradeHubOptions, d as upgradeWebSocket, f as WebSocketData, i as testWebSocket, l as UpgradeRouter, m as WebSocketServerLike, n as TestWebSocketOptions, o as UpgradeEmitter, p as WebSocketLike, r as TestWebSocketResult, s as UpgradeHub, t as TestSocket, u as RequestError } from "./test-websocket-DyeS50Tr.js";
 import { ServeStaticOptions, serveStatic } from "./node-server/serve-static.js";
 import { getConnInfo } from "./node-server/conninfo.js";
 import { AddressInfo } from "node:net";
 import { IncomingMessage, Server, ServerOptions, ServerResponse, createServer } from "node:http";
 import { Http2SecureServer, Http2Server, Http2ServerRequest, Http2ServerResponse, SecureServerOptions, ServerOptions as ServerOptions$1, createSecureServer, createServer as createServer$1 } from "node:http2";
-import { Duplex } from "node:stream";
 import { Server as Server$1, ServerOptions as ServerOptions$2, createServer as createServer$2 } from "node:https";
 
-//#region ../../plugins/acryl-node-server/src/adapter/websocket-types.d.ts
-type WSReadyState = 0 | 1 | 2 | 3;
-type WebSocketData = string | ArrayBuffer | Uint8Array | readonly Uint8Array[];
-type WebSocketSendOptions = {
-  compress?: boolean;
-};
-interface WebSocketLike {
-  protocol: string;
-  readyState: WSReadyState;
-  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;
-  off(event: 'message', listener: (data: WebSocketData, isBinary: boolean) => void): this;
-}
-interface WebSocketServerLike {
-  options: {
-    noServer?: boolean;
-  };
-  on(event: 'connection', listener: (ws: WebSocketLike, request: IncomingMessage) => void): this;
-  on(event: 'headers', listener: (headers: string[]) => void): this;
-  off(event: 'headers', listener: (headers: string[]) => void): this;
-  emit(event: 'connection', ws: WebSocketLike, request: IncomingMessage): boolean;
-  handleUpgrade(request: IncomingMessage, socket: Duplex, head: Buffer, callback: (ws: WebSocketLike) => void): void;
-  close(): void;
-}
-//#endregion
 //#region ../../plugins/acryl-node-server/src/adapter/types.d.ts
 type HttpBindings = {
   incoming: IncomingMessage;
@@ -107,12 +77,6 @@ declare function serve(options: HttpsOptions, listeningListener?: (info: Address
 declare function serve(options: HttpOptions, listeningListener?: (info: AddressInfo) => void): Server;
 declare function serve(options: Options, listeningListener?: (info: AddressInfo) => void): ServerType;
 //#endregion
-//#region ../../plugins/acryl-node-server/src/adapter/websocket.d.ts
-type UpgradeWebSocketOptions = {
-  onError: (err: unknown) => void;
-};
-declare const upgradeWebSocket: UpgradeWebSocket<WebSocketLike, UpgradeWebSocketOptions>;
-//#endregion
 //#region ../../plugins/acryl-node-server/src/adapter/listener.d.ts
 declare const getRequestListener: (fetchCallback: FetchCallback, options?: {
   hostname?: string;
@@ -161,4 +125,4 @@ declare function clientModules(options: ClientModulesOptions): Acryl;
  */
 declare function buildClientModules(options: BuildClientModulesOptions): string[];
 //#endregion
-export { type BuildClientModulesOptions, type ClientModulesOptions, type Http2Bindings, type HttpBindings, RequestError, type ServeStaticOptions, type ServerType, type WebSocketData, type WebSocketLike, type WebSocketServerLike, buildClientModules, clientModules, createAdaptorServer, getConnInfo, getRequestListener, serve, serveStatic, upgradeWebSocket };
+export { type BuildClientModulesOptions, type ClientModulesOptions, type Http2Bindings, type HttpBindings, type Owner, RequestError, type ServeStaticOptions, type ServerType, type TestSocket, type TestWebSocketOptions, type TestWebSocketResult, UpgradeEmitter, UpgradeHub, type UpgradeHubOptions, type UpgradeRouter, type WebSocketData, type WebSocketLike, type WebSocketServerLike, buildClientModules, clientModules, createAdaptorServer, getConnInfo, getRequestListener, serve, serveStatic, testWebSocket, upgradeWebSocket };

package/lib/node-server.js

@@ -1,5 +1,5 @@
-import { i as getRequestListener, n as serve, o as RequestError, r as upgradeWebSocket, t as createAdaptorServer } from "./server-DvgMGtzo.js";
+import { a as serve, i as createAdaptorServer, l as RequestError, n as UpgradeEmitter, o as upgradeWebSocket, r as UpgradeHub, s as getRequestListener, t as testWebSocket } from "./test-websocket-ZXHNHQSU.js";
 import { t as serveStatic } from "./serve-static-3uo_9rjF.js";
 import { getConnInfo } from "./node-server/conninfo.js";
 import { n as clientModules, t as buildClientModules } from "./client-modules-CLvWOjbd.js";
-export { RequestError, buildClientModules, clientModules, createAdaptorServer, getConnInfo, getRequestListener, serve, serveStatic, upgradeWebSocket };
+export { RequestError, UpgradeEmitter, UpgradeHub, buildClientModules, clientModules, createAdaptorServer, getConnInfo, getRequestListener, serve, serveStatic, testWebSocket, upgradeWebSocket };

package/lib/{snapshot-text-D3NspDyT.js → snapshot-text-yaWlezbd.js}

@@ -5,7 +5,7 @@ import { r as streamSSE } from "./streaming-DHST3Scg.js";
 import { loopbackAuthority, loopbackOnly } from "./loopback-only.js";
 import "./helpers-CvTauQT5.js";
 import { UiControlError, WINDOW_ID, parseChannelToHost } from "./door/protocol.js";
-import "./src-CwABFr6r.js";
+import "./src-DNzw0Qsb.js";
 import "./middleware-CPQ8himN.js";
 import { dirname, join } from "node:path";
 import { timingSafeEqual } from "node:crypto";

package/lib/{src-CwABFr6r.js → src-DNzw0Qsb.js}

@@ -186,8 +186,9 @@ var Router = class extends Service {
 	* Run a request in process. Never throws: failures become a 500, a disposed router answers 503. `connection` describes the transport
 	* (an HTTP adapter passes the socket's peer address and local port); an in-process caller omits it. Handlers read it with
 	* `connectionOf(c)`, abort with `c.req.raw.signal` and keep the request in flight with `c.executionCtx.waitUntil(task)`.
+	* `bindings` is an object an adapter hands to the handler as `c.env` (an upgrade request's socket hooks, for `upgradeWebSocket`); `connection` is added to it.
 	*/
-	fetch(request, connection = {}) {
+	fetch(request, connection = {}, bindings) {
 		if (this.state.closing) return Promise.resolve(new Response("Service Unavailable", { status: 503 }));
 		const controller = new AbortController();
 		const forward = () => controller.abort();
@@ -201,7 +202,7 @@ var Router = class extends Service {
 			passThroughOnException: () => {},
 			props: {}
 		};
-		const env = { connection };
+		const env = bindings === void 0 ? { connection } : Object.assign(bindings, { connection });
 		let bodyDone = Promise.resolve();
 		let endBody = () => {};
 		let resolveSettled;

package/lib/test-websocket-DyeS50Tr.d.ts

@@ -0,0 +1,136 @@
+import { n as UpgradeWebSocket } from "./index-C-SklY6u.js";
+import { IncomingMessage } from "node:http";
+import { Duplex } from "node:stream";
+import { EventEmitter } from "node:events";
+
+//#region ../../plugins/acryl-node-server/src/adapter/websocket-types.d.ts
+type WSReadyState = 0 | 1 | 2 | 3;
+type WebSocketData = string | ArrayBuffer | Uint8Array | readonly Uint8Array[];
+type WebSocketSendOptions = {
+  compress?: boolean;
+};
+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;
+}
+interface WebSocketServerLike {
+  options: {
+    noServer?: boolean;
+  };
+  on(event: 'connection', listener: (ws: WebSocketLike, request: IncomingMessage) => void): this;
+  on(event: 'headers', listener: (headers: string[]) => void): this;
+  off(event: 'headers', listener: (headers: string[]) => void): this;
+  emit(event: 'connection', ws: WebSocketLike, request: IncomingMessage): boolean;
+  handleUpgrade(request: IncomingMessage, socket: Duplex, head: Buffer, callback: (ws: WebSocketLike) => void): void;
+  close(callback?: () => void): void;
+}
+//#endregion
+//#region ../../plugins/acryl-node-server/src/adapter/websocket.d.ts
+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;
+};
+/** The part of a server `setupWebSocket` listens to: the Host's web server hands upgrades to a plain emitter with the same two methods. */
+interface UpgradeSource {
+  on(event: 'upgrade', listener: (request: IncomingMessage, socket: Duplex, head: Buffer) => void): unknown;
+  on(event: 'close', listener: () => void): unknown;
+  listenerCount(event: 'upgrade'): number;
+}
+declare const upgradeWebSocket: UpgradeWebSocket<WebSocketLike, UpgradeWebSocketOptions>;
+//#endregion
+//#region ../../plugins/acryl-node-server/src/adapter/error.d.ts
+declare class RequestError extends Error {
+  constructor(message: string, options?: {
+    cause?: unknown;
+  });
+}
+//#endregion
+//#region ../../plugins/acryl-node-server/src/upgrade-hub.d.ts
+interface UpgradeHubOptions {
+  /** The largest frame accepted, in bytes; a bigger one closes the socket with 1009. Default 1 MiB. */
+  maxPayload?: number;
+  /** Milliseconds between pings; a peer that did not answer the previous one is terminated. Default 30 000; 0 turns the heartbeat off. */
+  heartbeat?: number;
+  /** Milliseconds a closing socket gets to finish its close handshake before it is terminated. Default 2000. */
+  grace?: number;
+}
+/** The part of the router a hub calls: run a request with connection facts and the adapter's bindings. */
+interface UpgradeRouter {
+  fetch(request: Request, connection: {
+    remoteAddress?: string | undefined;
+    localPort?: number | undefined;
+  }, bindings?: object): Promise<Response>;
+}
+/** What a hub needs of a Cordis context: tying a disposer to the plugin that asked. */
+interface Owner {
+  effect(execute: () => () => unknown, label?: string): unknown;
+}
+declare class UpgradeHub {
+  readonly server: WebSocketServerLike;
+  private readonly all;
+  private readonly alive;
+  private readonly grace;
+  private timer;
+  private closed;
+  constructor(options?: UpgradeHubOptions);
+  /**
+   * 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: UpgradeSource, router: UpgradeRouter): void;
+  /** How many sockets are open. */
+  get size(): number;
+  /** `upgradeWebSocket` for the plugin `owner`: the sockets it accepts are closed with 1001 when that plugin unloads. */
+  upgradeWebSocketFor(owner: Owner): UpgradeWebSocket<WebSocketLike>;
+  /** Close `sockets` with `code`, wait for their close handshakes up to the grace, terminate what is left. */
+  closeAll(sockets: Iterable<WebSocketLike>, code: number, reason: string): Promise<void>;
+  /** End everything: every socket closes with 1001, the heartbeat stops, the `ws` server closes. */
+  close(): Promise<void>;
+}
+/** A stand-in for a server's `upgrade` events, for transports that dispatch upgrades themselves (the Host web server's exact-path routes). */
+declare class UpgradeEmitter extends EventEmitter {}
+//#endregion
+//#region ../../plugins/acryl-node-server/src/test-websocket.d.ts
+/** The client side of an accepted test connection. */
+interface TestSocket {
+  /** Frames the handler sent, in order (text only). */
+  readonly received: string[];
+  /** The code and reason the handler closed with, when it did. */
+  readonly closed: {
+    readonly code: number | undefined;
+    readonly reason: string | undefined;
+  } | undefined;
+  /** Send a text frame to the handler. */
+  send(text: string): void;
+  /** Close from the client side. */
+  close(code?: number, reason?: string): void;
+}
+interface TestWebSocketOptions {
+  readonly headers?: Record<string, string>;
+  /** The socket's peer address and local port, as an adapter would pass them. */
+  readonly connection?: {
+    readonly remoteAddress?: string;
+    readonly localPort?: number;
+  };
+  /** The URL origin the request is made against; default `http://127.0.0.1`. */
+  readonly base?: string;
+}
+interface TestWebSocketResult {
+  /** The refusal's status, or 101 when the upgrade was accepted. */
+  readonly status: number;
+  readonly socket?: TestSocket;
+}
+declare function testWebSocket(fetch: (request: Request, env: object) => Promise<Response>, path: string, options?: TestWebSocketOptions): Promise<TestWebSocketResult>;
+//#endregion
+export { Owner as a, UpgradeHubOptions as c, upgradeWebSocket as d, WebSocketData as f, testWebSocket as i, UpgradeRouter as l, WebSocketServerLike as m, TestWebSocketOptions as n, UpgradeEmitter as o, WebSocketLike as p, TestWebSocketResult as r, UpgradeHub as s, TestSocket as t, RequestError as u };