wrangler 0.0.0-ece06ea → 0.0.0-ecfbb0c

package/src/inspect.ts

@@ -0,0 +1,662 @@
+import assert from "node:assert";
+import { createServer } from "node:http";
+import os from "node:os";
+import { URL } from "node:url";
+
+import open from "open";
+import { useEffect, useRef, useState } from "react";
+import WebSocket, { WebSocketServer } from "ws";
+import { version } from "../package.json";
+import { logger } from "./logger";
+import { waitForPortToBeAvailable } from "./proxy";
+import type Protocol from "devtools-protocol";
+import type { IncomingMessage, Server, ServerResponse } from "node:http";
+import type { MessageEvent } from "ws";
+
+/**
+ * `useInspector` is a hook for debugging Workers applications
+ *  when using `wrangler dev`.
+ *
+ * When we start a session with `wrangler dev`, the Workers platform
+ * also exposes a debugging websocket that implements the DevTools
+ * Protocol. While we could just start up DevTools and connect to this
+ * URL, that URL changes every time we make a change to the
+ * worker, or when the session expires. Instead, we start up a proxy
+ * server locally that acts as a bridge between the remote DevTools
+ * server and the local DevTools instance. So whenever the URL changes,
+ * we can can silently connect to it and keep the local DevTools instance
+ * up to date. Further, we also intercept these messages and selectively
+ * log them directly to the terminal (namely, calls to `console.<x>`,
+ * and exceptions)
+ */
+
+/**
+ * TODO:
+ * - clear devtools whenever we save changes to the worker
+ * - clear devtools when we switch between local/remote modes
+ * - handle more methods from console
+ */
+
+interface InspectorProps {
+	/**
+	 * The port that the local proxy server should listen on.
+	 */
+	port: number;
+	/**
+	 * The websocket URL exposed by Workers that the inspector should connect to.
+	 */
+	inspectorUrl: string | undefined;
+	/**
+	 * Whether console statements and exceptions should be logged to the terminal.
+	 * (We don't log them in local mode because they're already getting
+	 * logged to the terminal by nature of them actually running in node locally.)
+	 */
+	logToTerminal: boolean;
+}
+
+export default function useInspector(props: InspectorProps) {
+	/** A unique ID for this session. */
+	const inspectorIdRef = useRef(randomId());
+
+	/** The websocket from the devtools instance. */
+	const [localWebSocket, setLocalWebSocket] = useState<WebSocket>();
+	/**  The websocket from the edge */
+	const [remoteWebSocket, setRemoteWebSocket] = useState<WebSocket>();
+
+	/**
+	 *  The local proxy server that acts as the bridge between
+	 *  the remote websocket and the local DevTools instance.
+	 */
+	const serverRef = useRef<Server>();
+	if (serverRef.current === undefined) {
+		serverRef.current = createServer(
+			(req: IncomingMessage, res: ServerResponse) => {
+				switch (req.url) {
+					// We implement a couple of well known end points
+					// that are queried for metadata by chrome://inspect
+					case "/json/version":
+						res.setHeader("Content-Type", "application/json");
+						res.end(
+							JSON.stringify({
+								Browser: `wrangler/v${version}`,
+								// TODO: (someday): The DevTools protocol should match that of Edge Worker.
+								// This could be exposed by the preview API.
+								"Protocol-Version": "1.3",
+							})
+						);
+						return;
+					case "/json":
+					case "/json/list":
+						{
+							res.setHeader("Content-Type", "application/json");
+							const localHost = `localhost:${props.port}/ws`;
+							const devtoolsFrontendUrl = `devtools://devtools/bundled/js_app.html?experiments=true&v8only=true&ws=${localHost}`;
+							const devtoolsFrontendUrlCompat = `devtools://devtools/bundled/inspector.html?experiments=true&v8only=true&ws=${localHost}`;
+							res.end(
+								JSON.stringify([
+									{
+										id: inspectorIdRef.current,
+										type: "node",
+										description: "workers",
+										webSocketDebuggerUrl: `ws://${localHost}`,
+										devtoolsFrontendUrl,
+										devtoolsFrontendUrlCompat,
+										// Below are fields that are visible in the DevTools UI.
+										title: "Cloudflare Worker",
+										faviconUrl: "https://workers.cloudflare.com/favicon.ico",
+										url:
+											"https://" +
+											(remoteWebSocket
+												? new URL(remoteWebSocket.url).host
+												: "workers.dev"),
+									},
+								])
+							);
+						}
+						return;
+					default:
+						break;
+				}
+			}
+		);
+	}
+	const server = serverRef.current;
+
+	/**
+	 * The websocket server that runs on top of the proxy server.
+	 */
+	const wsServerRef = useRef<WebSocketServer>();
+	if (wsServerRef.current === undefined) {
+		wsServerRef.current = new WebSocketServer({
+			server,
+			clientTracking: true,
+		});
+	}
+	const wsServer = wsServerRef.current;
+
+	wsServer.on("connection", (ws: WebSocket) => {
+		if (wsServer.clients.size > 1) {
+			/** We only want to have one active Devtools instance at a time. */
+			logger.error(
+				"Tried to open a new devtools window when a previous one was already open."
+			);
+			ws.close(1013, "Too many clients; only one can be connected at a time");
+		} else {
+			// As promised, save the created websocket in a state hook
+			setLocalWebSocket(ws);
+
+			ws.addEventListener("close", () => {
+				// And and cleanup when devtools closes
+				setLocalWebSocket(undefined);
+			});
+		}
+	});
+
+	/**
+	 * We start and stop the server in an effect to take advantage
+	 * of the component lifecycle. Convenient.
+	 */
+	useEffect(() => {
+		const abortController = new AbortController();
+		async function startInspectorProxy() {
+			await waitForPortToBeAvailable(props.port, {
+				retryPeriod: 200,
+				timeout: 2000,
+				abortSignal: abortController.signal,
+			});
+			server.listen(props.port);
+		}
+		startInspectorProxy().catch((err) => {
+			if ((err as { code: string }).code !== "ABORT_ERR") {
+				logger.error("Failed to start inspector:", err);
+			}
+		});
+		return () => {
+			server.close();
+			// Also disconnect any open websockets/devtools connections
+			wsServer.clients.forEach((ws) => ws.close());
+			wsServer.close();
+			abortController.abort();
+		};
+	}, [props.port, server, wsServer]);
+
+	/**
+	 * When connecting to the remote websocket, if we don't start either
+	 * the devtools instance or make an actual request to the worker in time,
+	 * then the connecting process can error out. When this happens, we
+	 * want to simply retry the connection. We use a state hook to trigger retries
+	 * of the effect that connects to the remote websocket.
+	 */
+	const [
+		retryRemoteWebSocketConnectionSigil,
+		setRetryRemoteWebSocketConnectionSigil,
+	] = useState<number>(0);
+	function retryRemoteWebSocketConnection() {
+		setRetryRemoteWebSocketConnectionSigil((x) => x + 1);
+	}
+
+	/** A simple incrementing id to attach to messages we send to devtools */
+	const messageCounterRef = useRef(1);
+
+	// This effect tracks the connection to the remote websocket
+	// (stored in, no surprises here, `remoteWebSocket`)
+	useEffect(() => {
+		if (!props.inspectorUrl) {
+			return;
+		}
+		// The actual websocket instance
+		const ws = new WebSocket(props.inspectorUrl);
+		setRemoteWebSocket(ws);
+
+		/**
+		 * A handle to the interval we run to keep the websocket alive
+		 */
+		let keepAliveInterval: NodeJS.Timer;
+
+		/**
+		 * Test if the websocket is closed
+		 */
+		function isClosed() {
+			return (
+				ws.readyState === WebSocket.CLOSED ||
+				ws.readyState === WebSocket.CLOSING
+			);
+		}
+
+		/**
+		 * Send a message to the remote websocket
+		 */
+		function send(event: Record<string, unknown>): void {
+			if (!isClosed()) {
+				ws.send(JSON.stringify(event));
+			}
+		}
+
+		/**
+		 * Closes the inspector.
+		 */
+		function close(): void {
+			if (!isClosed()) {
+				try {
+					ws.close();
+				} catch (err) {
+					// Closing before the websocket is ready will throw an error.
+				}
+			}
+		}
+
+		/**
+		 * Since we have a handle on the remote websocket, we can tap
+		 * into its events, and log any pertinent ones directly to
+		 * the terminal (which means you have insight into your worker
+		 * without having to open the devtools).
+		 */
+		if (props.logToTerminal) {
+			ws.addEventListener("message", (event: MessageEvent) => {
+				if (typeof event.data === "string") {
+					const evt = JSON.parse(event.data);
+					if (evt.method === "Runtime.exceptionThrown") {
+						const params = evt.params as Protocol.Runtime.ExceptionThrownEvent;
+						logger.error(
+							params.exceptionDetails.text,
+							params.exceptionDetails.exception?.description ?? ""
+						);
+					}
+					if (evt.method === "Runtime.consoleAPICalled") {
+						logConsoleMessage(
+							evt.params as Protocol.Runtime.ConsoleAPICalledEvent
+						);
+					}
+				} else {
+					// We should never get here, but who know is 2022...
+					logger.error("Unrecognised devtools event:", event);
+				}
+			});
+		}
+
+		ws.addEventListener("open", () => {
+			send({ method: "Runtime.enable", id: messageCounterRef.current });
+			// TODO: This doesn't actually work. Must fix.
+			send({ method: "Network.enable", id: messageCounterRef.current++ });
+
+			keepAliveInterval = setInterval(() => {
+				send({
+					method: "Runtime.getIsolateId",
+					id: messageCounterRef.current++,
+				});
+			}, 10_000);
+		});
+
+		ws.on("unexpected-response", () => {
+			logger.log("Waiting for connection...");
+			/**
+			 * This usually means the worker is not "ready" yet
+			 * so we'll just retry the connection process
+			 */
+			retryRemoteWebSocketConnection();
+		});
+
+		ws.addEventListener("close", () => {
+			clearInterval(keepAliveInterval);
+		});
+
+		return () => {
+			// clean up! Let's first stop the heartbeat interval
+			clearInterval(keepAliveInterval);
+			// Then we'll send a message to the devtools instance to
+			// tell it to clear the console.
+			wsServer.clients.forEach((client) => {
+				// We could've used `localSocket` here, but
+				// then we would have had to add it to the effect
+				// change detection array, which would have made a
+				// bunch of other stuff complicated. So we'll just
+				// cycle through all of the server's connected clients
+				// (in practice, there should only be one or zero) and send
+				// the Log.clear message.
+				client.send(
+					JSON.stringify({
+						// TODO: This doesn't actually work. Must fix.
+						method: "Log.clear",
+						// we can disable the next eslint warning since
+						// we're referencing a ref that stays alive
+						// eslint-disable-next-line react-hooks/exhaustive-deps
+						id: messageCounterRef.current++,
+						params: {},
+					})
+				);
+			});
+			// Finally, we'll close the websocket
+			close();
+			// And we'll clear `remoteWebsocket`
+			setRemoteWebSocket(undefined);
+		};
+	}, [
+		props.inspectorUrl,
+		props.logToTerminal,
+		wsServer,
+		// We use a state value as a sigil to trigger a retry of the
+		// remote websocket connection. It's not used inside the effect,
+		// so react-hooks/exhaustive-deps doesn't complain if it's not
+		// included in the dependency array. But its presence is critical,
+		// so do NOT remove it from the dependency list.
+		retryRemoteWebSocketConnectionSigil,
+	]);
+
+	/**
+	 * We want to make sure we don't lose any messages we receive from the
+	 * remote websocket before devtools connects. So we use a ref to buffer
+	 * messages, and flush them whenever devtools connects.
+	 */
+	const messageBufferRef = useRef<MessageEvent[]>([]);
+
+	// This effect tracks the state changes _between_ the local
+	// and remote websockets, and handles how messages flow between them.
+	useEffect(() => {
+		/**
+		 * This event listener is used for buffering messages from
+		 * the remote websocket, and flushing them
+		 * when the local websocket connects.
+		 */
+		function bufferMessageFromRemoteSocket(event: MessageEvent) {
+			messageBufferRef.current.push(event);
+			// TODO: maybe we should have a max limit on this?
+			// if so, we should be careful when removing messages
+			// from the front, because they could be critical for
+			// devtools (like execution context creation, etc)
+		}
+
+		if (remoteWebSocket && !localWebSocket) {
+			// The local websocket hasn't connected yet, so we'll
+			// buffer messages until it does.
+			remoteWebSocket.addEventListener(
+				"message",
+				bufferMessageFromRemoteSocket
+			);
+		}
+
+		/** Send a message from the local websocket to the remote websocket */
+		function sendMessageToRemoteWebSocket(event: MessageEvent) {
+			try {
+				assert(
+					remoteWebSocket,
+					"Trying to send a message to an undefined `remoteWebSocket`"
+				);
+				remoteWebSocket.send(event.data);
+			} catch (e) {
+				if (
+					(e as Error).message !==
+					"WebSocket is not open: readyState 0 (CONNECTING)"
+				) {
+					/**
+					 * ^ this just means we haven't opened a websocket yet
+					 * usually happens until there's at least one request
+					 * which is weird, because we may miss something that
+					 * happens on the first request. Maybe we should buffer
+					 * these messages too?
+					 */
+					logger.error(e);
+				}
+			}
+		}
+
+		/** Send a message from the local websocket to the remote websocket */
+		function sendMessageToLocalWebSocket(event: MessageEvent) {
+			assert(
+				localWebSocket,
+				"Trying to send a message to an undefined `localWebSocket`"
+			);
+			localWebSocket.send(event.data);
+		}
+
+		if (localWebSocket && remoteWebSocket) {
+			// Both the remote and local websockets are connected, so let's
+			// start sending messages between them.
+			localWebSocket.addEventListener("message", sendMessageToRemoteWebSocket);
+			remoteWebSocket.addEventListener("message", sendMessageToLocalWebSocket);
+
+			// Also, let's flush any buffered messages
+			messageBufferRef.current.forEach(sendMessageToLocalWebSocket);
+			messageBufferRef.current = [];
+		}
+
+		return () => {
+			// Cleanup like good citizens
+			if (remoteWebSocket) {
+				remoteWebSocket.removeEventListener(
+					"message",
+					bufferMessageFromRemoteSocket
+				);
+				remoteWebSocket.removeEventListener(
+					"message",
+					sendMessageToLocalWebSocket
+				);
+			}
+			if (localWebSocket) {
+				localWebSocket.removeEventListener(
+					"message",
+					sendMessageToRemoteWebSocket
+				);
+			}
+		};
+	}, [localWebSocket, remoteWebSocket]);
+}
+
+// Credit: https://stackoverflow.com/a/2117523
+function randomId(): string {
+	return "xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx".replace(/[xy]/g, function (c) {
+		const r = (Math.random() * 16) | 0,
+			v = c == "x" ? r : (r & 0x3) | 0x8;
+		return v.toString(16);
+	});
+}
+
+/**
+ * This function converts a message serialised as a devtools event
+ * into arguments suitable to be called by a console method, and
+ * then actually calls the method with those arguments. Effectively,
+ * we're just doing a little bit of the work of the devtools console,
+ * directly in the terminal.
+ */
+
+export const mapConsoleAPIMessageTypeToConsoleMethod: {
+	[key in Protocol.Runtime.ConsoleAPICalledEvent["type"]]: Exclude<
+		keyof Console,
+		"Console"
+	>;
+} = {
+	log: "log",
+	debug: "debug",
+	info: "info",
+	warning: "warn",
+	error: "error",
+	dir: "dir",
+	dirxml: "dirxml",
+	table: "table",
+	trace: "trace",
+	clear: "clear",
+	count: "count",
+	assert: "assert",
+	profile: "profile",
+	profileEnd: "profileEnd",
+	timeEnd: "timeEnd",
+	startGroup: "group",
+	startGroupCollapsed: "groupCollapsed",
+	endGroup: "groupEnd",
+};
+
+function logConsoleMessage(evt: Protocol.Runtime.ConsoleAPICalledEvent): void {
+	const args: string[] = [];
+	for (const ro of evt.args) {
+		switch (ro.type) {
+			case "string":
+			case "number":
+			case "boolean":
+			case "undefined":
+			case "symbol":
+			case "bigint":
+				args.push(ro.value);
+				break;
+			case "function":
+				args.push(`[Function: ${ro.description ?? "<no-description>"}]`);
+				break;
+			case "object":
+				if (!ro.preview) {
+					args.push(
+						ro.subtype === "null"
+							? "null"
+							: ro.description ?? "<no-description>"
+					);
+				} else {
+					args.push(ro.preview.description ?? "<no-description>");
+
+					switch (ro.preview.subtype) {
+						case "array":
+							args.push(
+								"[ " +
+									ro.preview.properties
+										.map(({ value }) => {
+											return value;
+										})
+										.join(", ") +
+									(ro.preview.overflow ? "..." : "") +
+									" ]"
+							);
+
+							break;
+						case "weakmap":
+						case "map":
+							args.push(
+								"{\n" +
+									// Maps always have entries
+									// eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+									ro.preview
+										.entries!.map(({ key, value }) => {
+											return `  ${key?.description ?? "<unknown>"} => ${
+												value.description
+											}`;
+										})
+										.join(",\n") +
+									(ro.preview.overflow ? "\n  ..." : "") +
+									"\n}"
+							);
+
+							break;
+						case "weakset":
+						case "set":
+							args.push(
+								"{ " +
+									// Sets always have entries
+									// eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+									ro.preview
+										.entries!.map(({ value }) => {
+											return `${value.description}`;
+										})
+										.join(", ") +
+									(ro.preview.overflow ? ", ..." : "") +
+									" }"
+							);
+							break;
+						case "regexp":
+							break;
+						case "date":
+							break;
+						case "generator":
+							args.push(ro.preview.properties[0].value || "");
+							break;
+						case "promise":
+							if (ro.preview.properties[0].value === "pending") {
+								args.push(`{<${ro.preview.properties[0].value}>}`);
+							} else {
+								args.push(
+									`{<${ro.preview.properties[0].value}>: ${ro.preview.properties[1].value}}`
+								);
+							}
+							break;
+						case "node":
+						case "iterator":
+						case "proxy":
+						case "typedarray":
+						case "arraybuffer":
+						case "dataview":
+						case "webassemblymemory":
+						case "wasmvalue":
+							break;
+						case "error":
+						default:
+							// just a pojo
+							args.push(
+								"{\n" +
+									ro.preview.properties
+										.map(({ name, value }) => {
+											return `  ${name}: ${value}`;
+										})
+										.join(",\n") +
+									(ro.preview.overflow ? "\n  ..." : "") +
+									"\n}"
+							);
+					}
+				}
+				break;
+			default:
+				args.push(ro.description || ro.unserializableValue || "🦋");
+				break;
+		}
+	}
+
+	const method = mapConsoleAPIMessageTypeToConsoleMethod[evt.type];
+
+	if (method in console) {
+		switch (method) {
+			case "dir":
+				console.dir(args);
+				break;
+			case "table":
+				console.table(args);
+				break;
+			default:
+				// eslint-disable-next-line prefer-spread
+				console[method].apply(console, args);
+				break;
+		}
+	} else {
+		logger.warn(`Unsupported console method: ${method}`);
+		logger.warn("console event:", evt);
+	}
+}
+
+/**
+ * Opens the chrome debugger
+ */
+export const openInspector = async (inspectorPort: number) => {
+	const url = `https://built-devtools.pages.dev/js_app?experiments=true&v8only=true&ws=localhost:${inspectorPort}/ws`;
+	const errorMessage =
+		"Failed to open inspector.\nInspector depends on having a Chromium-based browser installed, maybe you need to install one?";
+
+	// see: https://github.com/sindresorhus/open/issues/177#issue-610016699
+	let braveBrowser: string;
+	switch (os.platform()) {
+		case "darwin":
+		case "win32":
+			braveBrowser = "Brave";
+			break;
+		default:
+			braveBrowser = "brave";
+	}
+
+	const childProcess = await open(url, {
+		app: [
+			{
+				name: open.apps.chrome,
+			},
+			{
+				name: braveBrowser,
+			},
+			{
+				name: open.apps.edge,
+			},
+		],
+	});
+	childProcess.on("error", () => {
+		logger.warn(errorMessage);
+	});
+};