feat: add new unsafeInspectorProxy option to miniflare (#8357)

---------

Co-authored-by: Pete Bacon Darwin <[email protected]>

Author: dario-piotrowicz

.changeset/little-spiders-sell.md

@@ -0,0 +1,49 @@
+---
+"miniflare": patch
+---
+
+feat: add new `unsafeInspectorProxy` option to miniflare
+
+Add a new `unsafeInspectorProxy` option to the miniflare worker options, if
+at least one worker has the option set then miniflare will establish a proxy
+between itself and workerd for the v8 inspector APIs which exposes only the
+requested workers to inspector clients. The inspector proxy communicates through
+miniflare's `inspectorPort` and exposes each requested worker via a path comprised
+of the worker's name
+
+example:
+
+```js
+import { Miniflare } from "miniflare";
+
+const mf = new Miniflare({
+	// the inspector proxy will be accessible through port 9229
+	inspectorPort: 9229,
+	workers: [
+		{
+			name: "worker-a",
+			scriptPath: "./worker-a.js",
+			// enable the inspector proxy for worker-a
+			unsafeInspectorProxy: true,
+		},
+		{
+			name: "worker-b",
+			scriptPath: "./worker-b.js",
+			// worker-b is not going to be proxied
+		},
+		{
+			name: "worker-c",
+			scriptPath: "./worker-c.js",
+			// enable the inspector proxy for worker-c
+			unsafeInspectorProxy: true,
+		},
+	],
+});
+```
+
+In the above example an inspector proxy gets set up which exposes `worker-a` and `worker-b`,
+inspector clients can discover such workers via `http://localhost:9229` and communicate with
+them respectively via `ws://localhost:9229/worker-a` and `ws://localhost:9229/worker-b`
+
+Note: this API is experimental, thus it's not being added to the public documentation and
+it's prefixed by `unsafe`

packages/miniflare/package.json

@@ -83,6 +83,7 @@
 		"eslint-plugin-es": "^4.1.0",
 		"eslint-plugin-prettier": "^5.0.1",
 		"expect-type": "^0.15.0",
+		"get-port": "^7.1.0",
 		"heap-js": "^2.5.0",
 		"http-cache-semantics": "^4.1.0",
 		"kleur": "^4.1.5",

packages/miniflare/src/index.ts

@@ -78,6 +78,7 @@ import {
 	reviveError,
 	ServiceDesignatorSchema,
 } from "./plugins/core";
+import { InspectorProxyController } from "./plugins/core/inspector-proxy";
 import {
 	Config,
 	Extension,
@@ -744,12 +745,32 @@ export class Miniflare {
 	readonly #webSocketServer: WebSocketServer;
 	readonly #webSocketExtraHeaders: WeakMap<http.IncomingMessage, Headers>;
 
+	#maybeInspectorProxyController?: InspectorProxyController;
+	#previousRuntimeInspectorPort?: number;
+
 	constructor(opts: MiniflareOptions) {
 		// Split and validate options
 		const [sharedOpts, workerOpts] = validateOptions(opts);
 		this.#sharedOpts = sharedOpts;
 		this.#workerOpts = workerOpts;
 
+		const workerNamesToProxy = new Set(
+			this.#workerOpts
+				.filter(({ core: { unsafeInspectorProxy } }) => !!unsafeInspectorProxy)
+				.map((w) => w.core.name ?? "")
+		);
+
+		const enableInspectorProxy = workerNamesToProxy.size > 0;
+
+		if (enableInspectorProxy) {
+			if (this.#sharedOpts.core.inspectorPort === undefined) {
+				throw new MiniflareCoreError(
+					"ERR_MISSING_INSPECTOR_PROXY_PORT",
+					"inspector proxy requested but without an inspectorPort specified"
+				);
+			}
+		}
+
 		// Add to registry after initial options validation, before any servers/
 		// child processes are started
 		if (maybeInstanceRegistry !== undefined) {
@@ -760,6 +781,21 @@ export class Miniflare {
 
 		this.#log = this.#sharedOpts.core.log ?? new NoOpLog();
 
+		if (enableInspectorProxy) {
+			if (this.#sharedOpts.core.inspectorPort === undefined) {
+				throw new MiniflareCoreError(
+					"ERR_MISSING_INSPECTOR_PROXY_PORT",
+					"inspector proxy requested but without an inspectorPort specified"
+				);
+			}
+
+			this.#maybeInspectorProxyController = new InspectorProxyController(
+				this.#sharedOpts.core.inspectorPort,
+				this.#log,
+				workerNamesToProxy
+			);
+		}
+
 		this.#liveReloadServer = new WebSocketServer({ noServer: true });
 		this.#webSocketServer = new WebSocketServer({
 			noServer: true,
@@ -1406,14 +1442,21 @@ export class Miniflare {
 			configuredHost,
 			this.#sharedOpts.core.port
 		);
-		let inspectorAddress: string | undefined;
+		let runtimeInspectorAddress: string | undefined;
 		if (this.#sharedOpts.core.inspectorPort !== undefined) {
-			inspectorAddress = this.#getSocketAddress(
+			let runtimeInspectorPort = this.#sharedOpts.core.inspectorPort;
+			if (this.#maybeInspectorProxyController !== undefined) {
+				// if we have an inspector proxy let's use a
+				// random port for the actual runtime inspector
+				runtimeInspectorPort = 0;
+			}
+			runtimeInspectorAddress = this.#getSocketAddress(
 				kInspectorSocket,
-				this.#previousSharedOpts?.core.inspectorPort,
+				this.#previousRuntimeInspectorPort,
 				"localhost",
-				this.#sharedOpts.core.inspectorPort
+				runtimeInspectorPort
 			);
+			this.#previousRuntimeInspectorPort = runtimeInspectorPort;
 		}
 		const loopbackAddress = `${
 			maybeGetLocallyAccessibleHost(configuredHost) ??
@@ -1424,7 +1467,7 @@ export class Miniflare {
 			entryAddress,
 			loopbackAddress,
 			requiredSockets,
-			inspectorAddress,
+			inspectorAddress: runtimeInspectorAddress,
 			verbose: this.#sharedOpts.core.verbose,
 			handleRuntimeStdio: this.#sharedOpts.core.handleRuntimeStdio,
 		};
@@ -1445,6 +1488,19 @@ export class Miniflare {
 		// all of `requiredSockets` as keys.
 		this.#socketPorts = maybeSocketPorts;
 
+		if (this.#maybeInspectorProxyController !== undefined) {
+			// Try to get inspector port for the workers
+			const maybePort = this.#socketPorts.get(kInspectorSocket);
+			if (maybePort === undefined) {
+				throw new MiniflareCoreError(
+					"ERR_RUNTIME_FAILURE",
+					"Unable to access the runtime inspector socket."
+				);
+			} else {
+				this.#maybeInspectorProxyController.updateConnection(maybePort);
+			}
+		}
+
 		const entrySocket = config.sockets?.[0];
 		const secure = entrySocket !== undefined && "https" in entrySocket;
 		const previousEntryURL = this.#runtimeEntryURL;
@@ -1527,6 +1583,8 @@ export class Miniflare {
 		// `dispose()`d synchronously, immediately after constructing a `Miniflare`
 		// instance. In this case, return a discard URL which we'll ignore.
 		if (disposing) return new URL("http://[100::]/");
+		// if there is an inspector proxy let's wait for it to be ready
+		await this.#maybeInspectorProxyController?.ready;
 		// Make sure `dispose()` wasn't called in the time we've been waiting
 		this.#checkDisposed();
 		// `#runtimeEntryURL` is assigned in `#assembleAndUpdateConfig()`, which is
@@ -1551,6 +1609,10 @@ export class Miniflare {
 		this.#checkDisposed();
 		await this.ready;
 
+		if (this.#maybeInspectorProxyController !== undefined) {
+			return this.#maybeInspectorProxyController.getInspectorURL();
+		}
+
 		// `#socketPorts` is assigned in `#assembleAndUpdateConfig()`, which is
 		// called by `#init()`, and `ready` doesn't resolve until `#init()` returns
 		assert(this.#socketPorts !== undefined);
@@ -1900,6 +1962,9 @@ export class Miniflare {
 			// `rm -rf ${#tmpPath}`, this won't throw if `#tmpPath` doesn't exist
 			await fs.promises.rm(this.#tmpPath, { force: true, recursive: true });
 
+			// Close the inspector proxy server if there is one
+			await this.#maybeInspectorProxyController?.dispose();
+
 			// Remove from instance registry as last step in `finally`, to make sure
 			// all dispose steps complete
 			maybeInstanceRegistry?.delete(this);

packages/miniflare/src/plugins/core/index.ts

@@ -126,6 +126,8 @@ const CoreOptionsSchemaInput = z.intersection(
 		compatibilityDate: z.string().optional(),
 		compatibilityFlags: z.string().array().optional(),
 
+		unsafeInspectorProxy: z.boolean().optional(),
+
 		routes: z.string().array().optional(),
 
 		bindings: z.record(JsonSchema).optional(),
@@ -191,6 +193,7 @@ export const CoreSharedOptionsSchema = z.object({
 	httpsCertPath: z.string().optional(),
 
 	inspectorPort: z.number().optional(),
+
 	verbose: z.boolean().optional(),
 
 	log: z.instanceof(Log).optional(),

packages/miniflare/src/plugins/core/inspector-proxy/devtools.ts

@@ -0,0 +1,52 @@
+import type Protocol from "devtools-protocol/types/protocol-mapping";
+
+type _Params<ParamsArray extends [unknown?]> = ParamsArray extends [infer P]
+	? P
+	: undefined;
+
+type _EventMethods = keyof Protocol.Events;
+export type DevToolsEvent<Method extends _EventMethods> = Method extends unknown
+	? {
+			method: Method;
+			params: _Params<Protocol.Events[Method]>;
+		}
+	: never;
+
+export type DevToolsEvents = DevToolsEvent<_EventMethods>;
+
+type _CommandMethods = keyof Protocol.Commands;
+export type DevToolsCommandRequest<Method extends _CommandMethods> =
+	Method extends unknown
+		? _Params<Protocol.Commands[Method]["paramsType"]> extends undefined
+			? {
+					id: number;
+					method: Method;
+				}
+			: {
+					id: number;
+					method: Method;
+					params: _Params<Protocol.Commands[Method]["paramsType"]>;
+				}
+		: never;
+
+export type DevToolsCommandRequests = DevToolsCommandRequest<_CommandMethods>;
+
+export type DevToolsCommandResponse<Method extends _CommandMethods> =
+	Method extends unknown
+		? {
+				id: number;
+				result: Protocol.Commands[Method]["returnType"];
+			}
+		: never;
+export type DevToolsCommandResponses = DevToolsCommandResponse<_CommandMethods>;
+
+export function isDevToolsEvent<
+	Method extends DevToolsEvent<_EventMethods>["method"],
+>(event: unknown, name: Method): event is DevToolsEvent<Method> {
+	return (
+		typeof event === "object" &&
+		event !== null &&
+		"method" in event &&
+		event.method === name
+	);
+}

packages/miniflare/src/plugins/core/inspector-proxy/index.ts

@@ -0,0 +1 @@
+export { InspectorProxyController } from "./inspector-proxy-controller";