env-runner 0.0.0 → 0.1.0

package/dist/_chunks/runner.mjs

@@ -0,0 +1,87 @@
+import { t as BaseEnvRunner } from "./base-runner.mjs";
+import { existsSync } from "node:fs";
+import { spawn } from "node:child_process";
+import { fileURLToPath } from "node:url";
+//#region src/runners/deno-process/runner.ts
+let _defaultEntry;
+var DenoProcessEnvRunner = class extends BaseEnvRunner {
+	#process;
+	constructor(opts) {
+		_defaultEntry ||= fileURLToPath(import.meta.resolve("env-runner/runners/deno-process/worker"));
+		super({
+			...opts,
+			workerEntry: opts.workerEntry || _defaultEntry
+		});
+		this.#initProcess(opts.execArgv);
+	}
+	sendMessage(message) {
+		if (!this.#process) throw new Error("Deno env process should be initialized before sending messages.");
+		this.#process.send(message);
+	}
+	_hasRuntime() {
+		return Boolean(this.#process);
+	}
+	_runtimeType() {
+		return "process";
+	}
+	async _closeRuntime() {
+		if (!this.#process) return;
+		await this._requestGracefulShutdown(() => this.#process.send({ event: "shutdown" }), (resolve) => {
+			this.#process?.exited.then(() => resolve());
+		}, () => this.#process?._exitCode != null);
+		this.#process.removeAllListeners?.();
+		this.#process.kill();
+		this.#process = void 0;
+	}
+	#initProcess(execArgv) {
+		if (!existsSync(this._workerEntry)) {
+			this.close(`process entry not found in "${this._workerEntry}".`);
+			return;
+		}
+		const env = {
+			...process.env,
+			ENV_RUNNER_NAME: this._name,
+			ENV_RUNNER_DATA: JSON.stringify(this._data || {})
+		};
+		const child = spawn("deno", [
+			"run",
+			"--allow-all",
+			"--node-modules-dir=auto",
+			...execArgv || [],
+			this._workerEntry
+		], {
+			env,
+			stdio: [
+				"pipe",
+				"pipe",
+				"pipe",
+				"ipc"
+			]
+		});
+		const exited = new Promise((resolve) => {
+			child.once("exit", (code) => resolve(code ?? 1));
+		});
+		const handle = {
+			pid: child.pid,
+			kill: () => child.kill(),
+			send: (message) => child.send(message),
+			exited,
+			_exitCode: void 0,
+			removeAllListeners: () => child.removeAllListeners()
+		};
+		child.once("exit", (code) => {
+			handle._exitCode = code;
+			this.close(`process exited with code ${code}`);
+		});
+		child.once("error", (error) => {
+			console.error(`Process error:`, error);
+			this.close(error);
+		});
+		child.on("message", (message) => {
+			this._handleMessage(message);
+		});
+		this.#process = handle;
+	}
+};
+//#endregion
+export { DenoProcessEnvRunner as t };

package/dist/_chunks/runner2.d.mts

@@ -0,0 +1,21 @@
+import { d as WorkerHooks, n as EnvRunnerData, t as BaseEnvRunner } from "./base-runner.mjs";
+
+//#region src/runners/miniflare/runner.d.ts
+interface MiniflareEnvRunnerOptions {
+  name: string;
+  hooks?: WorkerHooks;
+  data?: EnvRunnerData;
+  /** Options passed directly to the Miniflare constructor. */
+  miniflareOptions?: Record<string, unknown>;
+}
+declare class MiniflareEnvRunner extends BaseEnvRunner {
+  #private;
+  constructor(opts: MiniflareEnvRunnerOptions);
+  fetch(input: string | URL | Request, init?: RequestInit): Promise<Response>;
+  sendMessage(message: unknown): void;
+  protected _hasRuntime(): boolean;
+  protected _runtimeType(): string;
+  protected _closeRuntime(): Promise<void>;
+}
+//#endregion
+export { MiniflareEnvRunnerOptions as n, MiniflareEnvRunner as t };

package/dist/_chunks/runner2.mjs

@@ -0,0 +1,145 @@
+import { t as BaseEnvRunner } from "./base-runner.mjs";
+import { readFileSync } from "node:fs";
+//#region src/runners/miniflare/runner.ts
+const IPC_HEADER = "x-env-runner-ipc";
+var MiniflareEnvRunner = class extends BaseEnvRunner {
+	#miniflare;
+	#miniflareOptions;
+	constructor(opts) {
+		super({
+			...opts,
+			workerEntry: ""
+		});
+		this.#miniflareOptions = opts.miniflareOptions || {};
+		this.#init();
+	}
+	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);
+	}
+	sendMessage(message) {
+		if (!this.#miniflare) throw new Error("Miniflare env runner should be initialized before sending messages.");
+		if (message?.type === "ping") {
+			queueMicrotask(() => this._handleMessage({
+				type: "pong",
+				data: message.data
+			}));
+			return;
+		}
+		this.#miniflare.dispatchFetch("http://localhost/__env_runner_ipc", {
+			method: "POST",
+			headers: { [IPC_HEADER]: "message" },
+			body: JSON.stringify(message)
+		}).catch(() => {});
+	}
+	_hasRuntime() {
+		return Boolean(this.#miniflare);
+	}
+	_runtimeType() {
+		return "miniflare";
+	}
+	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();
+		this.#miniflare = void 0;
+	}
+	#init() {
+		this.#initAsync().catch((error) => {
+			console.error("Miniflare runner init error:", error);
+			this.close(error);
+		});
+	}
+	async #initAsync() {
+		const { Miniflare } = await import("miniflare");
+		const entryPath = this._data?.entry;
+		const options = {
+			modules: true,
+			...this.#miniflareOptions
+		};
+		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.script = wrapScript(readFileSync(entryPath, "utf8"));
+			delete options.scriptPath;
+		}
+		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(() => {});
+		this._handleMessage({ address: {
+			host: "127.0.0.1",
+			port: 0
+		} });
+	}
+};
+/**
+* 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.
+*/
+function wrapScript(userCode) {
+	return `${userCode.replace(/export\s+default\s+/, "const __userEntry = ")}
+
+// --- 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);
+  }
+};
+`;
+}
+//#endregion
+export { MiniflareEnvRunner as t };

package/dist/_chunks/server.mjs

@@ -0,0 +1,186 @@
+import { watch } from "node:fs";
+//#region src/manager.ts
+/**
+* Manages an active `EnvRunner` instance, proxying all calls to it.
+* Supports hot-reload, auto-restart on unexpected exit, and message queueing.
+*/
+var RunnerManager = class {
+	_runner;
+	_messageQueue = [];
+	_messageListeners = /* @__PURE__ */ new Set();
+	_closed = false;
+	_reloading = false;
+	constructor(runner) {
+		if (runner) this._attach(runner);
+	}
+	get ready() {
+		return this._runner?.ready ?? false;
+	}
+	get closed() {
+		return this._closed;
+	}
+	/** Replace the active runner with a new one. Closes the previous runner. */
+	async reload(runner) {
+		this._reloading = true;
+		const prev = this._runner;
+		this._detach();
+		this._attach(runner);
+		this._reloading = false;
+		if (prev) await prev.close();
+	}
+	fetch = async (input, init) => {
+		const runner = await this._waitForRunner();
+		if (!runner) return new Response("Runner is unavailable", { status: 503 });
+		return runner.fetch(input, init);
+	};
+	upgrade = (context) => {
+		this._runner?.upgrade?.(context);
+	};
+	sendMessage(message) {
+		if (!this._runner || !this._runner.ready) {
+			this._messageQueue.push(message);
+			return;
+		}
+		this._runner.sendMessage(message);
+	}
+	onMessage(listener) {
+		this._messageListeners.add(listener);
+		this._runner?.onMessage(listener);
+	}
+	offMessage(listener) {
+		this._messageListeners.delete(listener);
+		this._runner?.offMessage(listener);
+	}
+	async close() {
+		this._closed = true;
+		this._messageQueue.length = 0;
+		const runner = this._runner;
+		this._detach();
+		if (runner) await runner.close();
+	}
+	onClose;
+	onReady;
+	_internalListener = (message) => {
+		if (message?.address) {
+			this._flushQueue();
+			this.onReady?.(this, message.address);
+		}
+	};
+	_attach(runner) {
+		this._runner = runner;
+		runner.onMessage(this._internalListener);
+		for (const listener of this._messageListeners) runner.onMessage(listener);
+		const originalClose = runner.close.bind(runner);
+		runner.close = async () => {
+			await originalClose();
+			if (this._runner === runner) {
+				this._runner = void 0;
+				this.onClose?.(this);
+			}
+		};
+		if (runner.ready) this._flushQueue();
+	}
+	_detach() {
+		const runner = this._runner;
+		if (!runner) return;
+		this._runner = void 0;
+		runner.offMessage(this._internalListener);
+		for (const listener of this._messageListeners) runner.offMessage(listener);
+	}
+	_waitForRunner(timeout = 3e3) {
+		if (this._runner) return Promise.resolve(this._runner);
+		if (!this._reloading) return Promise.resolve(void 0);
+		return new Promise((resolve) => {
+			const start = Date.now();
+			const check = () => {
+				if (this._runner) return resolve(this._runner);
+				if (this._closed || Date.now() - start >= timeout) return resolve(void 0);
+				setTimeout(check, 50);
+			};
+			setTimeout(check, 50);
+		});
+	}
+	_flushQueue() {
+		if (!this._runner || this._messageQueue.length === 0) return;
+		const queue = [...this._messageQueue];
+		this._messageQueue.length = 0;
+		for (const msg of queue) this._runner.sendMessage(msg);
+	}
+};
+//#endregion
+//#region src/loader.ts
+const loaders = {
+	"node-worker": () => import("env-runner/runners/node-worker").then((m) => m.NodeWorkerEnvRunner),
+	"node-process": () => import("env-runner/runners/node-process").then((m) => m.NodeProcessEnvRunner),
+	"bun-process": () => import("env-runner/runners/bun-process").then((m) => m.BunProcessEnvRunner),
+	"deno-process": () => import("env-runner/runners/deno-process").then((m) => m.DenoProcessEnvRunner),
+	self: () => import("env-runner/runners/self").then((m) => m.SelfEnvRunner),
+	miniflare: () => import("env-runner/runners/miniflare").then((m) => m.MiniflareEnvRunner)
+};
+async function loadRunner(runner, opts) {
+	return new (await (loaders[runner]()))(opts);
+}
+//#endregion
+//#region src/server.ts
+var EnvServer = class extends RunnerManager {
+	_opts;
+	_watchers = [];
+	_reloadTimeout;
+	runner = null;
+	/** Called when the runner is reloaded due to a file change. */
+	onReload;
+	constructor(opts) {
+		super();
+		this._opts = opts;
+	}
+	/** Start the server by loading and attaching the runner. */
+	async start() {
+		this.runner = await this._createRunner();
+		await this.reload(this.runner);
+		if (this._opts.watch) this._startWatching();
+		return this;
+	}
+	async close() {
+		this._stopWatching();
+		await super.close();
+	}
+	async _createRunner() {
+		return loadRunner(this._opts.runner, {
+			name: this._opts.name || this._opts.entry,
+			hooks: this._opts.hooks,
+			data: {
+				...this._opts.data,
+				entry: this._opts.entry
+			},
+			execArgv: this._opts.execArgv
+		});
+	}
+	_startWatching() {
+		const paths = [this._opts.entry, ...this._opts.watchPaths || []];
+		for (const path of paths) try {
+			const watcher = watch(path, { recursive: true }, () => {
+				this._scheduleReload();
+			});
+			this._watchers.push(watcher);
+		} catch {}
+	}
+	_stopWatching() {
+		clearTimeout(this._reloadTimeout);
+		for (const watcher of this._watchers) watcher.close();
+		this._watchers.length = 0;
+	}
+	_scheduleReload() {
+		clearTimeout(this._reloadTimeout);
+		this._reloadTimeout = setTimeout(async () => {
+			try {
+				this.runner = await this._createRunner();
+				await this.reload(this.runner);
+				this.onReload?.();
+			} catch (error) {
+				console.error("Failed to reload runner:", error);
+			}
+		}, 100);
+	}
+};
+//#endregion
+export { loadRunner as n, RunnerManager as r, EnvServer as t };

package/dist/_chunks/worker-utils.mjs

@@ -0,0 +1,16 @@
+//#region src/common/worker-utils.ts
+async function resolveEntry(entryPath) {
+	const mod = await import(entryPath);
+	const entry = mod.default || mod;
+	if (typeof entry.fetch !== "function") throw new Error(`[env-runner] Entry module "${entryPath}" must export a \`fetch\` handler (export default { fetch(req) { ... } }).`);
+	return entry;
+}
+function parseServerAddress(server) {
+	const url = new URL(server.url);
+	return {
+		host: url.hostname,
+		port: Number(url.port)
+	};
+}
+//#endregion
+export { resolveEntry as n, parseServerAddress as t };

package/dist/cli.d.mts

@@ -0,0 +1 @@
+export { };

package/dist/cli.mjs

@@ -0,0 +1,71 @@
+import { t as EnvServer } from "./_chunks/server.mjs";
+import { serve } from "srvx";
+import { resolve } from "node:path";
+import { parseArgs } from "node:util";
+//#region src/cli.ts
+const { values, positionals } = parseArgs({
+	allowPositionals: true,
+	options: {
+		runner: {
+			type: "string",
+			default: "node-process"
+		},
+		port: { type: "string" },
+		host: { type: "string" },
+		watch: {
+			type: "boolean",
+			short: "w"
+		},
+		help: { type: "boolean" }
+	}
+});
+const usage = `
+\x1B[1mUsage:\x1B[0m env-runner \x1B[36m<entry>\x1B[0m [options]
+
+\x1B[1mOptions:\x1B[0m
+  \x1B[33m--runner\x1B[0m <name>  Runner to use (node-worker, node-process, bun-process, self, miniflare) \x1B[2m(default: node-process)\x1B[0m
+  \x1B[33m--port\x1B[0m <port>    Port to listen on \x1B[2m(default: 3000)\x1B[0m
+  \x1B[33m--host\x1B[0m <host>    Host to bind to \x1B[2m(default: localhost)\x1B[0m
+  \x1B[33m-w, --watch\x1B[0m      Watch entry file for changes and auto-reload
+  \x1B[33m-h, --help\x1B[0m       Show this help message
+`.trim();
+const entry = positionals[0];
+if (values.help || !entry) {
+	console.log(usage);
+	process.exit(values.help ? 0 : 1);
+}
+const runner = values.runner;
+const envServer = new EnvServer({
+	runner,
+	entry: resolve(entry),
+	watch: values.watch
+});
+envServer.onReady = (_runner, address) => {
+	console.log(`\x1B[2m➜ Worker ready on ${address?.host}:${address?.port || address?.socketPath}\x1B[0m`);
+};
+envServer.onReload = () => {
+	console.log(`\x1B[2m↻ Reloading...\x1B[0m`);
+};
+await envServer.start();
+const server = serve({
+	port: values.port,
+	hostname: values.host,
+	gracefulShutdown: false,
+	fetch: (request) => envServer.fetch(request)
+});
+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();
+	await server.close();
+	process.exit(0);
+});
+//#endregion
+export {};

package/dist/index.d.mts

@@ -0,0 +1,100 @@
+import { a as NodeUpgradeContext, c as UpgradeContext, d as WorkerHooks, i as FetchHandler, l as UpgradeHandler, n as EnvRunnerData, o as RunnerMessageListener, r as EnvRunner, s as RunnerRPCHooks, t as BaseEnvRunner, u as WorkerAddress } from "./_chunks/base-runner.mjs";
+import { t as DenoProcessEnvRunner } from "./_chunks/runner.mjs";
+import { n as MiniflareEnvRunnerOptions, t as MiniflareEnvRunner } from "./_chunks/runner2.mjs";
+import { ServerOptions } from "srvx";
+
+//#region src/manager.d.ts
+/**
+ * Manages an active `EnvRunner` instance, proxying all calls to it.
+ * Supports hot-reload, auto-restart on unexpected exit, and message queueing.
+ */
+declare class RunnerManager implements EnvRunner {
+  private _runner;
+  private _messageQueue;
+  private _messageListeners;
+  private _closed;
+  private _reloading;
+  constructor(runner?: EnvRunner);
+  get ready(): boolean;
+  get closed(): boolean;
+  /** Replace the active runner with a new one. Closes the previous runner. */
+  reload(runner: EnvRunner): Promise<void>;
+  fetch: FetchHandler;
+  upgrade: UpgradeHandler;
+  sendMessage(message: unknown): void;
+  onMessage(listener: RunnerMessageListener): void;
+  offMessage(listener: RunnerMessageListener): void;
+  close(): Promise<void>;
+  onClose?: (runner: EnvRunner, cause?: unknown) => void;
+  onReady?: (runner: EnvRunner, address?: WorkerAddress) => void;
+  private _internalListener;
+  private _attach;
+  private _detach;
+  private _waitForRunner;
+  private _flushQueue;
+}
+//#endregion
+//#region src/loader.d.ts
+type RunnerName = "node-worker" | "node-process" | "bun-process" | "deno-process" | "self" | "miniflare";
+interface LoadRunnerOptions {
+  name: string;
+  workerEntry?: string;
+  hooks?: WorkerHooks;
+  data?: EnvRunnerData;
+  execArgv?: string[];
+}
+declare function loadRunner(runner: RunnerName, opts: LoadRunnerOptions): Promise<EnvRunner>;
+//#endregion
+//#region src/server.d.ts
+interface EnvServerOptions {
+  /** Runner implementation to use. */
+  runner: RunnerName;
+  /** Path to the user entry module (passed as `data.entry`). */
+  entry: string;
+  /** Runner instance name. */
+  name?: string;
+  /** Lifecycle hooks. */
+  hooks?: WorkerHooks;
+  /** Additional data passed to the runner. */
+  data?: Record<string, unknown>;
+  /** Custom exec arguments (e.g. `--inspect`). */
+  execArgv?: string[];
+  /** Enable watch mode to auto-reload on entry file changes. */
+  watch?: boolean;
+  /** Additional paths to watch (directories or files). */
+  watchPaths?: string[];
+}
+declare class EnvServer extends RunnerManager {
+  private _opts;
+  private _watchers;
+  private _reloadTimeout;
+  runner: Awaited<ReturnType<typeof loadRunner>> | null;
+  /** Called when the runner is reloaded due to a file change. */
+  onReload?: () => void;
+  constructor(opts: EnvServerOptions);
+  /** Start the server by loading and attaching the runner. */
+  start(): Promise<this>;
+  close(): Promise<void>;
+  private _createRunner;
+  private _startWatching;
+  private _stopWatching;
+  private _scheduleReload;
+}
+//#endregion
+//#region src/common/worker-utils.d.ts
+interface AppEntryIPCContext {
+  sendMessage: (message: unknown) => void;
+}
+interface AppEntryIPC {
+  onOpen?: (ctx: AppEntryIPCContext) => void | Promise<void>;
+  onMessage?: (message: unknown) => void | Promise<void>;
+  onClose?: () => void | Promise<void>;
+}
+interface AppEntry {
+  fetch: ServerOptions["fetch"];
+  middleware?: ServerOptions["middleware"];
+  plugins?: ServerOptions["plugins"];
+  ipc?: AppEntryIPC;
+}
+//#endregion
+export { type AppEntry, type AppEntryIPC, type AppEntryIPCContext, BaseEnvRunner, DenoProcessEnvRunner, type EnvRunnerData as DenoProcessEnvRunnerData, type EnvRunnerData, type EnvRunner, EnvServer, type EnvServerOptions, type FetchHandler, type LoadRunnerOptions, MiniflareEnvRunner, type MiniflareEnvRunnerOptions, type NodeUpgradeContext, RunnerManager, type RunnerMessageListener, type RunnerName, type RunnerRPCHooks, type UpgradeContext, type UpgradeHandler, type WorkerAddress, type WorkerHooks, loadRunner };

package/dist/index.mjs

@@ -0,0 +1,6 @@
+import "./_chunks/libs/std-env.mjs";
+import { t as BaseEnvRunner } from "./_chunks/base-runner.mjs";
+import { n as loadRunner, r as RunnerManager, t as EnvServer } from "./_chunks/server.mjs";
+import { t as DenoProcessEnvRunner } from "./_chunks/runner.mjs";
+import { t as MiniflareEnvRunner } from "./_chunks/runner2.mjs";
+export { BaseEnvRunner, DenoProcessEnvRunner, EnvServer, MiniflareEnvRunner, RunnerManager, loadRunner };

package/dist/runners/bun-process/runner.d.mts

@@ -0,0 +1,19 @@
+import { d as WorkerHooks, n as EnvRunnerData, t as BaseEnvRunner } from "../../_chunks/base-runner.mjs";
+
+//#region src/runners/bun-process/runner.d.ts
+declare class BunProcessEnvRunner extends BaseEnvRunner {
+  #private;
+  constructor(opts: {
+    name: string;
+    workerEntry?: string;
+    hooks?: WorkerHooks;
+    data?: EnvRunnerData;
+    execArgv?: string[];
+  });
+  sendMessage(message: unknown): void;
+  protected _hasRuntime(): boolean;
+  protected _runtimeType(): string;
+  protected _closeRuntime(): Promise<void>;
+}
+//#endregion
+export { BunProcessEnvRunner, type EnvRunnerData as BunProcessEnvRunnerData };