env-runner 0.1.15 → 0.1.16

package/README.md

@@ -73,9 +73,36 @@ await envServer.reload();
 // Use with any HTTP server
 const server = serve({
   fetch: (request) => envServer.fetch(request),
+  // Proxy WebSocket upgrades to the worker (see "WebSocket proxying" below)
+  plugins: [await envServer.wsSrvxPlugin()],
 });
 ```
 
+#### WebSocket proxying
+
+To proxy WebSocket upgrades to the worker, attach the plugin returned by
+`wsSrvxPlugin()` (available on both `RunnerManager` and `EnvServer`) to your
+[srvx](https://srvx.h3.dev) server:
+
+```ts
+const server = serve({
+  fetch: (request) => envServer.fetch(request),
+  plugins: [await envServer.wsSrvxPlugin()],
+});
+```
+
+The plugin picks the proxy strategy by **host** runtime:
+
+- **Node** — proxies the raw upgrade socket to the worker (transparent
+  passthrough; subprotocol/extension negotiation stays end-to-end).
+- **Bun/Deno** — those runtimes serve natively and expose no Node upgrade
+  socket, so the client WebSocket is terminated with [crossws](https://crossws.h3.dev)
+  and bridged to the worker over a standard `WebSocket` client.
+
+It reads the active runner lazily, so it keeps working across hot-reloads, and
+waits for the worker to become ready before proxying. Your entry module should
+expose WebSocket hooks via the `websocket` field (see [Workers](#workers)).
+
 ### Manager (`RunnerManager`)
 
 Proxy manager for hot-reload with message queueing and listener forwarding:
@@ -147,7 +174,8 @@ await using runner = new NodeProcessEnvRunner({
 // Relative URLs are resolved against a placeholder origin
 const response = await runner.fetch("/api");
 
-// Proxy WebSocket upgrades
+// Proxy a raw WebSocket upgrade to the worker (Node host only — low-level;
+// prefer `manager.wsSrvxPlugin()` for cross-runtime proxying)
 runner.upgrade?.({ node: { req, socket, head } });
 
 // Wait for runner to be ready

package/dist/_chunks/common-base-runner.d.mts

@@ -50,6 +50,7 @@ declare abstract class BaseEnvRunner implements EnvRunner, AsyncDisposable {
     data?: EnvRunnerData;
   });
   get ready(): boolean;
+  get address(): WorkerAddress | undefined;
   fetch(input: string | URL | Request, init?: RequestInit): Promise<Response>;
   upgrade(context: {
     node: {

package/dist/_chunks/common-base-runner.mjs

@@ -23,13 +23,20 @@ var BaseEnvRunner = class {
 	get ready() {
 		return Boolean(!this.closed && this._address && this._hasRuntime());
 	}
+	get address() {
+		return this._address;
+	}
 	async fetch(input, init) {
 		for (let i = 0; i < 5 && !this._address && !this.closed; i++) await new Promise((r) => setTimeout(r, 100 * Math.pow(2, i)));
 		if (!this._address) return new Response(`${this._runtimeType()} env runner is unavailable`, { status: 503 });
 		return proxyFetch(this._address, this._resolveFetchInput(input), init);
 	}
 	async upgrade(context) {
-		if (!this.ready || !this._address) return;
+		if (!this.ready) await this.waitForReady().catch(() => {});
+		if (!this.ready || !this._address) {
+			context.node.socket.destroy();
+			return;
+		}
 		try {
 			await proxyUpgrade(this._address, context.node.req, context.node.socket, context.node.head);
 		} catch {}
@@ -40,7 +47,7 @@ var BaseEnvRunner = class {
 	offMessage(listener) {
 		this._messageListeners.delete(listener);
 	}
-	waitForReady(timeout = 5e3) {
+	waitForReady(timeout = 15e3) {
 		if (this.ready) return Promise.resolve();
 		if (this.closed) return Promise.reject(/* @__PURE__ */ new Error("Runner closed before becoming ready"));
 		return new Promise((resolve, reject) => {

package/dist/_chunks/server.mjs

@@ -1,4 +1,34 @@
 import { watch } from "node:fs";
+async function createRunnerWSProxyPlugin(getRunner) {
+	const isBun = "Bun" in globalThis;
+	const isDeno = "Deno" in globalThis;
+	if (!isBun && !isDeno) return (server) => {
+		server.ready().then(() => {
+			(server.node?.server)?.on("upgrade", (req, socket, head) => {
+				getRunner()?.upgrade?.({ node: {
+					req,
+					socket,
+					head
+				} });
+			});
+		}).catch(() => {});
+	};
+	const { createWebSocketProxy } = await import("crossws");
+	const { plugin } = isBun ? await import("crossws/server/bun") : await import("crossws/server/deno");
+	const proxy = createWebSocketProxy({ target: async (peer) => {
+		await getRunner()?.waitForReady?.().catch(() => {});
+		return resolveWSProxyTarget(getRunner()?.address, peer.request.url);
+	} });
+	return plugin({ resolve: () => proxy });
+}
+function resolveWSProxyTarget(address, requestUrl) {
+	if (!address) throw new Error("env runner worker is not ready");
+	const { pathname, search } = new URL(requestUrl);
+	if (address.socketPath) return `ws+unix://${address.socketPath}:${pathname}${search}`;
+	if (!address.port) throw new Error("env runner worker is not ready");
+	const host = address.host || "127.0.0.1";
+	return `ws://${host.includes(":") && !host.startsWith("[") ? `[${host}]` : host}:${address.port}${pathname}${search}`;
+}
 var RunnerManager = class {
 	_runner;
 	_messageQueue = [];
@@ -9,6 +39,7 @@ var RunnerManager = class {
 	_pendingModuleReload;
 	_closeListeners = /* @__PURE__ */ new Set();
 	_readyListeners = /* @__PURE__ */ new Set();
+	_readyRejectors = /* @__PURE__ */ new Set();
 	constructor(runner) {
 		if (runner) this._attach(runner);
 	}
@@ -18,6 +49,9 @@ var RunnerManager = class {
 	get closed() {
 		return this._closed;
 	}
+	get address() {
+		return this._runner?.address;
+	}
 	async reload(runner) {
 		this._reloading = true;
 		try {
@@ -49,9 +83,17 @@ var RunnerManager = class {
 		});
 		return this._pendingModuleReload;
 	}
-	upgrade = (context) => {
-		this._runner?.upgrade?.(context);
+	upgrade = async (context) => {
+		const runner = await this._waitForRunner();
+		if (!runner?.upgrade) {
+			context.node.socket.destroy();
+			return;
+		}
+		await runner.upgrade(context);
 	};
+	wsSrvxPlugin() {
+		return createRunnerWSProxyPlugin(() => this);
+	}
 	sendMessage(message) {
 		if (!this._runner || !this._runner.ready) {
 			this._messageQueue.push(message);
@@ -67,21 +109,31 @@ var RunnerManager = class {
 		this._messageListeners.delete(listener);
 		this._runner?.offMessage(listener);
 	}
-	waitForReady(timeout = 5e3) {
+	waitForReady(timeout = 15e3) {
 		if (this.ready) return Promise.resolve();
+		if (this._closed) return Promise.reject(/* @__PURE__ */ new Error("Runner closed before becoming ready"));
 		return new Promise((resolve, reject) => {
+			const cleanup = () => {
+				clearTimeout(timer);
+				this.offMessage(listener);
+				this._readyRejectors.delete(onClose);
+			};
 			const timer = setTimeout(() => {
-				this._messageListeners.delete(listener);
+				cleanup();
 				reject(/* @__PURE__ */ new Error("Runner did not become ready in time"));
 			}, timeout);
 			const listener = (message) => {
 				if (message?.address || this.ready) {
-					clearTimeout(timer);
-					this._messageListeners.delete(listener);
+					cleanup();
 					resolve();
 				}
 			};
-			this._messageListeners.add(listener);
+			const onClose = () => {
+				cleanup();
+				reject(/* @__PURE__ */ new Error("Runner closed before becoming ready"));
+			};
+			this.onMessage(listener);
+			this._readyRejectors.add(onClose);
 		});
 	}
 	rpc(name, data, opts) {
@@ -124,6 +176,8 @@ var RunnerManager = class {
 	async close() {
 		this._closed = true;
 		this._messageQueue.length = 0;
+		for (const rejectReady of this._readyRejectors) rejectReady();
+		this._readyRejectors.clear();
 		const runner = this._runner;
 		this._detach();
 		if (runner) await runner.close();

package/dist/_chunks/types.d.mts

@@ -62,6 +62,8 @@ interface EnvRunner extends RunnerRPCHooks, AsyncDisposable {
   readonly ready: boolean;
   /** Whether the runner has been closed. */
   readonly closed: boolean;
+  /** Address the worker is listening at, once ready (`undefined` before then). */
+  readonly address?: WorkerAddress;
   /** Proxy an HTTP request to the worker. */
   fetch: FetchHandler;
   /** Proxy a WebSocket upgrade request to the worker. */

package/dist/_chunks/vercel-runner.mjs

@@ -44,7 +44,9 @@ function _checkVercelOidcToken(token = process.env.VERCEL_OIDC_TOKEN) {
 let _defaultEntry;
 const _podId = Math.random().toString(32).slice(-5);
 function generateVercelId() {
-	return `dev1::${_podId}-${Date.now().toString(36)}-${randomBytes(6).toString("hex")}`;
+	const timestamp = Date.now().toString(36);
+	const random = randomBytes(6).toString("hex");
+	return `dev1::${_podId}-${timestamp}-${random}`;
 }
 var VercelEnvRunner = class extends NodeWorkerEnvRunner {
 	constructor(opts) {

package/dist/cli.mjs

@@ -50,16 +50,10 @@ const server = serve({
 	port: values.port,
 	hostname: values.host,
 	gracefulShutdown: false,
-	fetch: (request) => envServer.fetch(request)
+	fetch: (request) => envServer.fetch(request),
+	plugins: [await envServer.wsSrvxPlugin()]
 });
 await server.ready();
-server.node?.server?.on("upgrade", (req, socket, head) => {
-	envServer.upgrade({ node: {
-		req,
-		socket,
-		head
-	} });
-});
 for (const signal of ["SIGINT", "SIGTERM"]) process.once(signal, async () => {
 	console.log(`\n\x1B[2mShutting down...\x1B[0m`);
 	await envServer.close();

package/dist/index.d.mts

@@ -4,7 +4,7 @@ import { DenoProcessEnvRunner } from "./_chunks/deno-process-runner.mjs";
 import { MiniflareEnvRunner, MiniflareEnvRunnerOptions, MiniflareExportInfo, TransformResult } from "./_chunks/miniflare-runner.mjs";
 import { VercelEnvRunner } from "./_chunks/vercel-runner.mjs";
 import { NetlifyEnvRunner } from "./_chunks/netlify-runner.mjs";
-import { ServerOptions } from "srvx";
+import { ServerOptions, ServerPlugin } from "srvx";
 import { Hooks } from "crossws";
 /**
  * Manages an active `EnvRunner` instance, proxying all calls to it.
@@ -20,9 +20,11 @@ declare class RunnerManager implements EnvRunner, AsyncDisposable {
   private _pendingModuleReload;
   private _closeListeners;
   private _readyListeners;
+  private _readyRejectors;
   constructor(runner?: EnvRunner);
   get ready(): boolean;
   get closed(): boolean;
+  get address(): WorkerAddress | undefined;
   /**
    * Replace the active runner with a new one. Closes the previous runner.
    *
@@ -41,6 +43,14 @@ declare class RunnerManager implements EnvRunner, AsyncDisposable {
    */
   private _flushInvalidation;
   upgrade: UpgradeHandler;
+  /**
+   * Create a runtime-native WebSocket reverse-proxy plugin for the public srvx
+   * server. Attach it via `serve({ plugins: [await manager.wsSrvxPlugin()] })`:
+   * on Node it proxies the raw upgrade socket to the worker, and on Bun/Deno it
+   * bridges the WebSocket with crossws. The plugin reads the active runner
+   * lazily, so it keeps working across hot-reloads.
+   */
+  wsSrvxPlugin(): Promise<ServerPlugin>;
   sendMessage(message: unknown): void;
   onMessage(listener: RunnerMessageListener): void;
   offMessage(listener: RunnerMessageListener): void;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "env-runner",
-  "version": "0.1.15",
+  "version": "0.1.16",
   "description": "Generic environment runner for JavaScript runtimes.",
   "license": "MIT",
   "repository": "unjs/env-runner",
@@ -43,10 +43,10 @@
     "typecheck": "tsgo --noEmit --skipLibCheck"
   },
   "dependencies": {
-    "crossws": "^0.4.6",
+    "crossws": "^0.4.8",
     "exsolve": "^1.1.0",
-    "httpxy": "^0.5.3",
-    "srvx": "^0.11.17"
+    "httpxy": "^0.5.4",
+    "srvx": "^0.11.19"
   },
   "devDependencies": {
     "@netlify/runtime": "^4.1.25",