env-runner 0.1.1 → 0.1.2

package/dist/_chunks/runner2.mjs

@@ -1,25 +1,212 @@
 import { t as BaseEnvRunner } from "./base-runner.mjs";
+import { createRequire } from "node:module";
 import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { dirname, resolve } from "node:path";
+//#region src/runners/miniflare/wrapper.ts
+const IPC_PATH$1 = "/__env_runner_ipc";
+/**
+* Generates a wrapper module that imports the user entry and adds IPC glue.
+*
+* The user module is expected to export `fetch` and optionally `ipc`.
+* The wrapper uses a persistent WebSocket pair for bidirectional IPC:
+* - Init: `fetch` with `upgrade: websocket` creates a WebSocketPair
+* - Messages: JSON over the WebSocket (no per-message `dispatchFetch`)
+* - Reload: `{ type: "reload" }` triggers cache-busted re-import
+* - Shutdown: `{ type: "shutdown" }` calls `ipc.onClose()`
+*
+* Passed as an in-memory `script` to Miniflare (no temp files needed).
+*/
+function generateWrapper(entryPath, opts) {
+	const staticReExport = opts?.dynamicOnly ? "" : `export * from ${JSON.stringify(entryPath)};`;
+	const explicitExports = opts?.dynamicOnly && opts.exports?.length ? opts.exports.map((name) => `export { ${name} } from ${JSON.stringify(entryPath)};`).join("\n") : "";
+	const fetchBody = opts?.captureErrors ?? true ? `try {
+      return await entryFetch(request, env, ctx);
+    } catch (e) {
+      const error = e instanceof Error ? e : new Error(String(e));
+      const body = JSON.stringify({
+        error: error.message,
+        stack: error.stack,
+        name: error.constructor?.name || "Error",
+      });
+      return new Response(body, {
+        status: 500,
+        headers: { "Content-Type": "application/json", "X-Env-Runner-Error": "1" },
+      });
+    }` : `return entryFetch(request, env, ctx);`;
+	return `import __process from "node:process";
+if (!globalThis.process) { globalThis.process = __process; }
+${staticReExport}
+${explicitExports}
+
+const __IPC_PATH = "${IPC_PATH$1}";
+const __entryPath = ${JSON.stringify(entryPath)};
+let __userEntry;
+let __ipcInitialized = false;
+let __serverWs;
+
+async function __loadEntry(env, path) {
+  globalThis.__ENV_RUNNER_UNSAFE_EVAL__ = env.__ENV_RUNNER_UNSAFE_EVAL__;
+  const importFn = env.__ENV_RUNNER_UNSAFE_EVAL__.newAsyncFunction(
+    "return await import(path)",
+    "loadEntry",
+    "path"
+  );
+  const mod = await importFn(path);
+  return mod.default || mod;
+}
+
+function __sendMessage(message) {
+  if (__serverWs) {
+    __serverWs.send(JSON.stringify(message));
+  }
+}
+
+async function __handleWsMessage(env, data) {
+  let msg;
+  try { msg = JSON.parse(data); } catch { return; }
+
+  if (msg.type === "message") {
+    if (__userEntry?.ipc?.onMessage) {
+      __userEntry.ipc.onMessage(msg.data);
+    }
+    return;
+  }
+
+  if (msg.type === "reload" && env.__ENV_RUNNER_UNSAFE_EVAL__) {
+    const version = msg.version || 0;
+    try {
+      const newEntry = await __loadEntry(env, __entryPath + "?t=" + version);
+      if (__userEntry?.ipc?.onClose) {
+        await __userEntry.ipc.onClose();
+      }
+      __userEntry = newEntry;
+      __ipcInitialized = false;
+      if (__userEntry.ipc?.onOpen) {
+        __ipcInitialized = true;
+        await __userEntry.ipc.onOpen({ sendMessage: __sendMessage });
+      }
+      __sendMessage({ event: "module-reloaded" });
+    } catch (e) {
+      __sendMessage({ event: "module-reloaded", error: String(e) });
+    }
+    return;
+  }
+
+  if (msg.type === "shutdown") {
+    if (__userEntry?.ipc?.onClose) {
+      await __userEntry.ipc.onClose();
+    }
+    return;
+  }
+}
+
+export default {
+  async fetch(request, env, ctx) {
+    const url = new URL(request.url);
+
+    // WebSocket IPC handshake
+    if (url.pathname === __IPC_PATH && request.headers.get("upgrade") === "websocket") {
+      try {
+        if (!__userEntry) {
+          __userEntry = await __loadEntry(env, __entryPath);
+        }
+      } catch (e) {
+        return new Response("Failed to load entry: " + String(e), { status: 500 });
+      }
+
+      const pair = new WebSocketPair();
+      const client = pair[0];
+      const server = pair[1];
+      server.accept();
+      __serverWs = server;
+
+      server.addEventListener("message", (event) => {
+        __handleWsMessage(env, event.data);
+      });
+
+      // Initialize IPC hooks
+      if (!__ipcInitialized && __userEntry.ipc) {
+        __ipcInitialized = true;
+        if (__userEntry.ipc.onOpen) {
+          await __userEntry.ipc.onOpen({ sendMessage: __sendMessage });
+        }
+      }
+
+      return new Response(null, { status: 101, webSocket: client });
+    }
+
+    if (!__userEntry) {
+      return new Response("Worker not initialized", { status: 503 });
+    }
+    const entryFetch = __userEntry.fetch;
+    if (!entryFetch) {
+      return new Response("No fetch handler exported", { status: 500 });
+    }
+    ${fetchBody}
+  }
+};
+`;
+}
+//#endregion
 //#region src/runners/miniflare/runner.ts
-const IPC_HEADER = "x-env-runner-ipc";
+const IPC_PATH = "/__env_runner_ipc";
+const _miniflareCache = /* @__PURE__ */ new Map();
 var MiniflareEnvRunner = class extends BaseEnvRunner {
 	#miniflare;
 	#miniflareOptions;
+	#transformRequest;
+	#reloadCounter = 0;
+	#ws;
+	#persistent;
+	#cacheKey;
+	#exports;
+	#captureErrors;
 	constructor(opts) {
 		super({
 			...opts,
 			workerEntry: ""
 		});
 		this.#miniflareOptions = opts.miniflareOptions || {};
+		this.#transformRequest = opts.transformRequest;
+		this.#persistent = opts.persistent ?? false;
+		this.#exports = opts.exports ?? {};
+		this.#captureErrors = opts.captureErrors ?? true;
 		this.#init();
 	}
+	/** Dispose all persistent Miniflare instances from the cache. */
+	static async disposeAll() {
+		const entries = [..._miniflareCache.values()];
+		_miniflareCache.clear();
+		for (const entry of entries) await entry.mf.dispose().catch(() => {});
+	}
+	/** Fully dispose the Miniflare instance (even if persistent). */
+	async dispose() {
+		if (this.#miniflare) {
+			if (this.#ws) {
+				this.#ws.send(JSON.stringify({ type: "shutdown" }));
+				this.#ws.close();
+				this.#ws = void 0;
+			}
+			if (this.#cacheKey) _miniflareCache.delete(this.#cacheKey);
+			await this.#miniflare.dispose();
+			this.#miniflare = void 0;
+		}
+		if (!this.closed) await this.close();
+	}
 	async fetch(input, init) {
 		if (!this.#miniflare || this.closed) return new Response("miniflare env runner is unavailable", { status: 503 });
 		const url = typeof input === "string" ? input : input instanceof URL ? input.href : input.url;
-		return this.#miniflare.dispatchFetch(url, init);
+		const res = await this.#miniflare.dispatchFetch(url, init);
+		if (res instanceof Response) return res;
+		return new Response(res.body, {
+			status: res.status,
+			statusText: res.statusText,
+			headers: res.headers
+		});
 	}
 	sendMessage(message) {
-		if (!this.#miniflare) throw new Error("Miniflare env runner should be initialized before sending messages.");
+		if (!this.#ws) throw new Error("Miniflare env runner should be initialized before sending messages.");
 		if (message?.type === "ping") {
 			queueMicrotask(() => this._handleMessage({
 				type: "pong",
@@ -27,11 +214,45 @@ var MiniflareEnvRunner = class extends BaseEnvRunner {
 			}));
 			return;
 		}
-		this.#miniflare.dispatchFetch("http://localhost/__env_runner_ipc", {
-			method: "POST",
-			headers: { [IPC_HEADER]: "message" },
-			body: JSON.stringify(message)
-		}).catch(() => {});
+		this.#ws.send(JSON.stringify({
+			type: "message",
+			data: message
+		}));
+	}
+	/**
+	* Hot-reload the user entry module without recreating the Miniflare instance.
+	*
+	* Sends `reload-module` event over the WebSocket. The worker wrapper uses
+	* `unsafeEvalBinding` to re-import the entry with a cache-busting query string
+	* and responds with `module-reloaded` when done.
+	*/
+	async reloadModule(timeout = 5e3) {
+		if (!this.#ws) throw new Error("Miniflare env runner should be initialized before reloading.");
+		if (!this._data?.entry) return;
+		this.#reloadCounter++;
+		const version = this.#reloadCounter;
+		return new Promise((resolve, reject) => {
+			const timer = setTimeout(() => {
+				cleanup();
+				reject(/* @__PURE__ */ new Error("Module reload timed out"));
+			}, timeout);
+			const listener = (msg) => {
+				if (msg?.event === "module-reloaded") {
+					cleanup();
+					if (msg.error) reject(typeof msg.error === "string" ? new Error(msg.error) : msg.error);
+					else resolve();
+				}
+			};
+			const cleanup = () => {
+				clearTimeout(timer);
+				this.offMessage(listener);
+			};
+			this.onMessage(listener);
+			this.#ws.send(JSON.stringify({
+				type: "reload",
+				version
+			}));
+		});
 	}
 	_hasRuntime() {
 		return Boolean(this.#miniflare);
@@ -41,11 +262,21 @@ var MiniflareEnvRunner = class extends BaseEnvRunner {
 	}
 	async _closeRuntime() {
 		if (!this.#miniflare) return;
-		await this.#miniflare.dispatchFetch("http://localhost/__env_runner_ipc", {
-			method: "POST",
-			headers: { [IPC_HEADER]: "shutdown" }
-		}).catch(() => {});
-		await this.#miniflare.dispose();
+		if (this.#ws) {
+			this.#ws.send(JSON.stringify({ type: "shutdown" }));
+			this.#ws.close();
+			this.#ws = void 0;
+		}
+		if (this.#persistent && this.#cacheKey) {
+			const cached = _miniflareCache.get(this.#cacheKey);
+			if (cached) {
+				cached.refCount--;
+				if (cached.refCount <= 0) {
+					_miniflareCache.delete(this.#cacheKey);
+					await this.#miniflare.dispose();
+				}
+			}
+		} else await this.#miniflare.dispose();
 		this.#miniflare = void 0;
 	}
 	#init() {
@@ -57,29 +288,150 @@ var MiniflareEnvRunner = class extends BaseEnvRunner {
 	async #initAsync() {
 		const { Miniflare } = await import("miniflare");
 		const entryPath = this._data?.entry;
+		const userFlags = this.#miniflareOptions.compatibilityFlags || [];
 		const options = {
 			compatibilityDate: (/* @__PURE__ */ new Date()).toISOString().split("T")[0],
 			modules: true,
-			...this.#miniflareOptions
+			...this.#miniflareOptions,
+			compatibilityFlags: [...new Set(["nodejs_compat", ...userFlags])]
 		};
-		options.serviceBindings = {
-			...options.serviceBindings || {},
-			__ENV_RUNNER_IPC: async (request) => {
-				const message = await request.json().catch(() => null);
-				if (message !== null) this._handleMessage(message);
-				return new Response(null, { status: 204 });
+		if (entryPath && !options.script && !options.scriptPath) {
+			const resolvedEntry = resolve(entryPath);
+			const entryDir = dirname(resolvedEntry);
+			const detectedExports = this.#exports === false || this.#exports === void 0 ? [] : detectExportedClasses(resolvedEntry, typeof this.#exports === "object" ? this.#exports : {});
+			if (detectedExports.length > 0 && !options.durableObjects) {
+				const autoDOs = { ...this.#miniflareOptions.durableObjects || {} };
+				for (const name of detectedExports) {
+					const bindingName = toScreamingSnakeCase(name);
+					if (!autoDOs[bindingName]) autoDOs[bindingName] = name;
+				}
+				options.durableObjects = autoDOs;
 			}
-		};
-		if (entryPath && !options.script) {
-			options.script = wrapScript(readFileSync(entryPath, "utf8"));
-			delete options.scriptPath;
+			options.script = generateWrapper(resolvedEntry, {
+				dynamicOnly: true,
+				captureErrors: this.#captureErrors,
+				exports: detectedExports
+			});
+			options.scriptPath = entryDir + "/__env_runner_wrapper.mjs";
+			if (!options.modulesRoot) options.modulesRoot = "/";
+			options.unsafeEvalBinding = "__ENV_RUNNER_UNSAFE_EVAL__";
+			if (this.#transformRequest && !options.modulesRules) options.modulesRules = [{
+				type: "ESModule",
+				include: [
+					"**/*.ts",
+					"**/*.tsx",
+					"**/*.jsx",
+					"**/*.mts"
+				]
+			}];
+			if (!options.unsafeModuleFallbackService) {
+				const _require = createRequire(resolvedEntry);
+				const _transformRequest = this.#transformRequest;
+				options.unsafeUseModuleFallbackService = true;
+				const modulePathMap = /* @__PURE__ */ new Map();
+				options.unsafeModuleFallbackService = async (request) => {
+					const url = new URL(request.url);
+					const specifier = url.searchParams.get("specifier");
+					const rawSpecifier = url.searchParams.get("rawSpecifier");
+					const referrer = url.searchParams.get("referrer") || "";
+					if (!specifier) return new Response(null, { status: 404 });
+					const cleanSpecifier = specifier.split("?")[0] || specifier;
+					const cleanRaw = rawSpecifier?.split("?")[0];
+					let resolvedPath;
+					const fileUrlRaw = cleanRaw || cleanSpecifier;
+					if (fileUrlRaw.startsWith("file://")) try {
+						resolvedPath = fileURLToPath(fileUrlRaw);
+					} catch {
+						return new Response(null, { status: 404 });
+					}
+					else if (cleanRaw && !cleanRaw.startsWith(".") && !cleanRaw.startsWith("/")) {
+						const referrerKey = referrer.startsWith("/") ? referrer.slice(1) : referrer;
+						const referrerReal = modulePathMap.get(referrerKey);
+						const contextRequire = referrerReal ? createRequire(referrerReal) : _require;
+						if (cleanRaw.startsWith("node:")) {
+							const nodeName = cleanRaw.slice(5);
+							try {
+								resolvedPath = contextRequire.resolve(`unenv/node/${nodeName}`);
+							} catch {
+								return new Response(null, { status: 404 });
+							}
+						} else try {
+							resolvedPath = contextRequire.resolve(cleanRaw);
+						} catch {
+							const name = cleanSpecifier.startsWith("/") ? cleanSpecifier.slice(1) : cleanSpecifier;
+							return Response.json({
+								name,
+								esModule: "export default undefined;"
+							});
+						}
+					} else {
+						const referrerKey = referrer.startsWith("/") ? referrer.slice(1) : referrer;
+						const referrerDir = dirname(modulePathMap.get(referrerKey) || (referrer.startsWith("/") ? referrer : "/" + referrer));
+						const raw = cleanRaw || cleanSpecifier;
+						if (raw.startsWith(".")) resolvedPath = resolve(referrerDir, raw);
+						else if (cleanSpecifier.startsWith("/")) resolvedPath = cleanSpecifier;
+						else try {
+							resolvedPath = _require.resolve(raw);
+						} catch {
+							return new Response(null, { status: 404 });
+						}
+					}
+					const rawQuery = specifier.includes("?") ? specifier.slice(specifier.indexOf("?")) : "";
+					const name = (cleanSpecifier.startsWith("/") ? cleanSpecifier.slice(1) : cleanSpecifier) + rawQuery;
+					if (_transformRequest) try {
+						const result = await _transformRequest(resolvedPath);
+						if (result?.code) {
+							modulePathMap.set(name, resolvedPath);
+							return Response.json({
+								name,
+								esModule: result.code
+							});
+						}
+					} catch {}
+					try {
+						const contents = readFileSync(resolvedPath, "utf8");
+						modulePathMap.set(name, resolvedPath);
+						const isESM = resolvedPath.endsWith(".mjs") || !resolvedPath.endsWith(".cjs") && /\b(import\s|import\(|export\s|export\{|import\.meta\b)/.test(contents);
+						return Response.json({
+							name,
+							...isESM ? { esModule: contents } : { commonJsModule: contents }
+						});
+					} catch {
+						return new Response(null, { status: 404 });
+					}
+				};
+			}
+		}
+		if (this.#persistent && entryPath) {
+			this.#cacheKey = computeCacheKey(entryPath, this.#miniflareOptions);
+			const cached = _miniflareCache.get(this.#cacheKey);
+			if (cached) {
+				this.#miniflare = cached.mf;
+				cached.refCount++;
+			}
+		}
+		if (!this.#miniflare) {
+			this.#miniflare = new Miniflare(options);
+			await this.#miniflare.ready;
+			if (this.#persistent && this.#cacheKey) _miniflareCache.set(this.#cacheKey, {
+				mf: this.#miniflare,
+				refCount: 1
+			});
+		}
+		const initRes = await this.#miniflare.dispatchFetch("http://localhost" + IPC_PATH, { headers: { upgrade: "websocket" } });
+		const ws = initRes.webSocket;
+		if (!ws) {
+			const body = await initRes.text().catch(() => "");
+			throw new Error(`Failed to establish WebSocket IPC channel (${initRes.status}: ${body})`);
 		}
-		this.#miniflare = new Miniflare(options);
-		await this.#miniflare.ready;
-		await this.#miniflare.dispatchFetch("http://localhost/__env_runner_ipc", {
-			method: "POST",
-			headers: { [IPC_HEADER]: "init" }
-		}).catch(() => {});
+		ws.accept();
+		this.#ws = ws;
+		ws.addEventListener("message", (event) => {
+			try {
+				const parsed = JSON.parse(event.data);
+				this._handleMessage(parsed);
+			} catch {}
+		});
 		this._handleMessage({ address: {
 			host: "127.0.0.1",
 			port: 0
@@ -87,60 +439,28 @@ var MiniflareEnvRunner = class extends BaseEnvRunner {
 	}
 };
 /**
-* Wraps user module code with IPC glue.
-*
-* The user module is expected to `export default { fetch, ipc? }`.
-* The wrapper renames the user's default export, intercepts IPC requests,
-* and bridges the `ipc` hooks via `env.__ENV_RUNNER_IPC` service binding.
+* Detect `export class` declarations in the entry file.
+* Merges with explicitly declared exports from options.
 */
-function wrapScript(userCode) {
-	return `${userCode.replace(/export\s+default\s+/, "const __userEntry = ").replace(/export\s*\{([^}]*?\b(\w+)\b\s+as\s+default\b[^}]*)\}/, (_match, _inner, identifier) => `const __userEntry = ${identifier};`)}
-
-// --- env-runner IPC glue ---
-let __ipcInitialized = false;
-const __IPC_HEADER = "${IPC_HEADER}";
-
-export default {
-  async fetch(request, env, ctx) {
-    // Handle IPC control messages from runner
-    const ipcType = request.headers.get(__IPC_HEADER);
-    if (ipcType) {
-      if (ipcType === "init") {
-        if (!__ipcInitialized && __userEntry.ipc && env.__ENV_RUNNER_IPC) {
-          __ipcInitialized = true;
-          const sendMessage = (message) => {
-            env.__ENV_RUNNER_IPC.fetch("http://ipc/", {
-              method: "POST",
-              body: JSON.stringify(message),
-            });
-          };
-          if (__userEntry.ipc.onOpen) {
-            await __userEntry.ipc.onOpen({ sendMessage });
-          }
-        }
-        return new Response(null, { status: 204 });
-      }
-      if (ipcType === "message") {
-        const message = await request.json();
-        if (__userEntry.ipc?.onMessage) {
-          __userEntry.ipc.onMessage(message);
-        }
-        return new Response(null, { status: 204 });
-      }
-      if (ipcType === "shutdown") {
-        if (__userEntry.ipc?.onClose) {
-          await __userEntry.ipc.onClose();
-        }
-        return new Response(null, { status: 204 });
-      }
-      return new Response(null, { status: 400 });
-    }
-
-    // Delegate to user's fetch handler
-    return __userEntry.fetch(request, env, ctx);
-  }
-};
-`;
+function detectExportedClasses(entryPath, explicit) {
+	const names = new Set(Object.keys(explicit));
+	try {
+		const source = readFileSync(entryPath, "utf8");
+		const re = /\bexport\s+class\s+(\w+)/g;
+		let match;
+		while (match = re.exec(source)) if (match[1]) names.add(match[1]);
+	} catch {}
+	return [...names];
+}
+/** Convert PascalCase/camelCase to SCREAMING_SNAKE_CASE (e.g. `Counter` → `COUNTER`, `MyDurableObject` → `MY_DURABLE_OBJECT`). */
+function toScreamingSnakeCase(name) {
+	return name.replace(/([a-z0-9])([A-Z])/g, "$1_$2").toUpperCase();
+}
+/** Compute a stable cache key for persistent Miniflare instances. */
+function computeCacheKey(entryPath, opts) {
+	const serializableOpts = {};
+	for (const [k, v] of Object.entries(opts)) if (typeof v !== "function") serializableOpts[k] = v;
+	return `${resolve(entryPath)}::${JSON.stringify(serializableOpts)}`;
 }
 //#endregion
 export { MiniflareEnvRunner as t };

package/dist/_chunks/server.mjs

@@ -51,6 +51,54 @@ var RunnerManager = class {
 		this._messageListeners.delete(listener);
 		this._runner?.offMessage(listener);
 	}
+	waitForReady(timeout = 5e3) {
+		if (this.ready) return Promise.resolve();
+		return new Promise((resolve, reject) => {
+			const timer = setTimeout(() => {
+				this._messageListeners.delete(listener);
+				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);
+					resolve();
+				}
+			};
+			this._messageListeners.add(listener);
+		});
+	}
+	rpc(name, data, opts) {
+		const id = Math.random().toString(36).slice(2);
+		const timeout = opts?.timeout ?? 3e3;
+		return new Promise((resolve, reject) => {
+			const timer = setTimeout(() => {
+				cleanup();
+				reject(/* @__PURE__ */ new Error(`RPC "${name}" timed out`));
+			}, timeout);
+			const listener = (msg) => {
+				if (msg?.__rpc_id === id) {
+					cleanup();
+					if (msg.error) reject(typeof msg.error === "string" ? new Error(msg.error) : msg.error);
+					else resolve(msg.data);
+				}
+			};
+			const cleanup = () => {
+				clearTimeout(timer);
+				this.offMessage(listener);
+			};
+			this.onMessage(listener);
+			this.sendMessage({
+				__rpc: name,
+				__rpc_id: id,
+				data
+			});
+		});
+	}
+	async reloadModule(timeout) {
+		if (!this._runner?.reloadModule) throw new Error("Active runner does not support reloadModule()");
+		return this._runner.reloadModule(timeout);
+	}
 	async close() {
 		this._closed = true;
 		this._messageQueue.length = 0;

package/dist/_chunks/types.d.mts

@@ -0,0 +1,76 @@
+import { IncomingMessage } from "node:http";
+import { Socket } from "node:net";
+
+//#region src/types.d.ts
+/** Handler for proxying HTTP requests to the worker. */
+type FetchHandler = (input: string | URL | Request, init?: RequestInit) => Promise<Response>;
+/** Callback for receiving messages from the worker. */
+type RunnerMessageListener = (data: unknown) => void;
+/** Raw Node.js upgrade request context. */
+interface NodeUpgradeContext {
+  req: IncomingMessage;
+  socket: Socket;
+  head: any;
+}
+/** Context passed to the upgrade handler for WebSocket upgrades. */
+interface UpgradeContext {
+  node: NodeUpgradeContext;
+}
+/** Handler for proxying WebSocket upgrade requests to the worker. */
+type UpgradeHandler = (context: UpgradeContext) => void;
+/** Bidirectional RPC messaging interface between the runner and worker. */
+interface RunnerRPCHooks {
+  /** Send a message to the worker. */
+  sendMessage: (message: unknown) => void;
+  /** Register a listener for messages from the worker. */
+  onMessage: (listener: RunnerMessageListener) => void;
+  /** Remove a previously registered message listener. */
+  offMessage: (listener: RunnerMessageListener) => void;
+}
+/**
+ * Address reported by the worker once it is ready.
+ *
+ * Either a TCP `host`/`port` pair or a Unix `socketPath`.
+ */
+type WorkerAddress = {
+  host?: string;
+  port: number;
+  socketPath?: undefined;
+} | {
+  host?: undefined;
+  port?: undefined;
+  socketPath: string;
+};
+/** Lifecycle hooks for observing runner state changes. */
+interface WorkerHooks {
+  /** Called when the worker closes, optionally with the cause. */
+  onClose?: (worker: EnvRunner, cause?: unknown) => void;
+  /** Called when the worker is ready and listening at the given address. */
+  onReady?: (worker: EnvRunner, address?: WorkerAddress) => void;
+}
+/** Options for the `rpc()` method. */
+interface RPCOptions {
+  /** Timeout in milliseconds before the RPC call rejects. Default: 3000. */
+  timeout?: number;
+}
+/** Core runner interface combining lifecycle hooks, RPC, and request proxying. */
+interface EnvRunner extends WorkerHooks, RunnerRPCHooks {
+  /** Whether the worker is ready to accept requests. */
+  readonly ready: boolean;
+  /** Whether the runner has been closed. */
+  readonly closed: boolean;
+  /** Proxy an HTTP request to the worker. */
+  fetch: FetchHandler;
+  /** Proxy a WebSocket upgrade request to the worker. */
+  upgrade?: UpgradeHandler;
+  /** Returns a promise that resolves when the runner becomes ready. */
+  waitForReady(timeout?: number): Promise<void>;
+  /** Send an RPC request and wait for the response. */
+  rpc<T = unknown>(name: string, data?: unknown, opts?: RPCOptions): Promise<T>;
+  /** Re-import the entry module without restarting the worker/process. */
+  reloadModule?(timeout?: number): Promise<void>;
+  /** Gracefully shut down the worker. */
+  close(): Promise<void>;
+}
+//#endregion
+export { RunnerMessageListener as a, UpgradeHandler as c, RPCOptions as i, WorkerAddress as l, FetchHandler as n, RunnerRPCHooks as o, NodeUpgradeContext as r, UpgradeContext as s, EnvRunner as t, WorkerHooks as u };

package/dist/_chunks/worker-utils.mjs

@@ -12,5 +12,15 @@ function parseServerAddress(server) {
 		port: Number(url.port)
 	};
 }
+/**
+* Re-import the user entry module with cache busting.
+* Tears down old IPC hooks and re-initializes new ones.
+*/
+async function reloadEntryModule(entryPath, currentEntry, sendMessage) {
+	await currentEntry.ipc?.onClose?.();
+	const newEntry = await resolveEntry(entryPath + "?t=" + Date.now());
+	await newEntry.ipc?.onOpen?.({ sendMessage });
+	return newEntry;
+}
 //#endregion
-export { resolveEntry as n, parseServerAddress as t };
+export { reloadEntryModule as n, resolveEntry as r, parseServerAddress as t };