wrangler 0.0.0-e6e1daba → 0.0.0-e739b7fe

package/src/inspect.ts

@@ -1,782 +0,0 @@
-import { readFile } from "fs/promises";
-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 { SourceMapConsumer } from "source-map";
-import WebSocket, { WebSocketServer } from "ws";
-import { version } from "../package.json";
-import { logger } from "./logger";
-import { waitForPortToBeAvailable } from "./proxy";
-import { getAccessToken } from "./user/access";
-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;
-	/**
-	 * Sourcemap path, so that stacktraces can be interpretted
-	 */
-	sourceMapPath?: string | undefined;
-
-	host?: string;
-}
-
-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 {
-			// Since Wrangler proxies the inspector, reloading Chrome DevTools won't trigger debugger initialisation events (because it's connecting to an extant session).
-			// This sends a `Debugger.disable` message to the remote when a new WebSocket connection is initialised,
-			// with the assumption that the new connection will shortly send a `Debugger.enable` event and trigger re-initialisation.
-			// The key initialisation messages that are needed are the `Debugger.scriptParsed events`.
-			remoteWebSocket?.send(
-				JSON.stringify({
-					// This number is arbitrary, and is chosen to be high so as not to conflict with messages that DevTools might actually send.
-					// For completeness, these options don't work: 0, -1, or Number.MAX_SAFE_INTEGER
-					id: 100_000_000,
-					method: "Debugger.disable",
-				})
-			);
-			// 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);
-
-	const cfAccessRef = useRef<string>();
-
-	useEffect(() => {
-		const run = async () => {
-			if (props.host && !cfAccessRef.current) {
-				const token = await getAccessToken(props.host);
-				cfAccessRef.current = token;
-			}
-		};
-		if (props.host) void run();
-	}, [props.host]);
-
-	// 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, {
-			headers: {
-				cookie: `CF_Authorization=${cfAccessRef.current}`,
-			},
-		});
-		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", async (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;
-
-						// Parse stack trace with source map.
-						if (props.sourceMapPath) {
-							// Parse in the sourcemap
-							const mapContent = JSON.parse(
-								await readFile(props.sourceMapPath, "utf-8")
-							);
-
-							// Create the lines for the exception details log
-							const exceptionLines = [
-								params.exceptionDetails.exception?.description?.split("\n")[0],
-							];
-
-							await SourceMapConsumer.with(
-								mapContent,
-								null,
-								async (consumer) => {
-									// Pass each of the callframes into the consumer, and format the error
-									const stack = params.exceptionDetails.stackTrace?.callFrames;
-
-									stack?.forEach(
-										({ functionName, lineNumber, columnNumber }, i) => {
-											try {
-												if (lineNumber) {
-													// The line and column numbers in the stackTrace are zero indexed,
-													// whereas the sourcemap consumer indexes from one.
-													const pos = consumer.originalPositionFor({
-														line: lineNumber + 1,
-														column: columnNumber + 1,
-													});
-
-													// Print out line which caused error:
-													if (i === 0 && pos.source && pos.line) {
-														const fileSource = consumer.sourceContentFor(
-															pos.source
-														);
-														const fileSourceLine =
-															fileSource?.split("\n")[pos.line - 1] || "";
-														exceptionLines.push(fileSourceLine.trim());
-
-														// If we have a column, we can mark the position underneath
-														if (pos.column) {
-															exceptionLines.push(
-																`${" ".repeat(
-																	pos.column - fileSourceLine.search(/\S/)
-																)}^`
-															);
-														}
-													}
-
-													// From the way esbuild implements the "names" field:
-													// > To save space, the original name is only recorded when it's different from the final name.
-													// however, source-map consumer does not handle this
-													if (pos && pos.line != null) {
-														const convertedFnName =
-															pos.name || functionName || "";
-														exceptionLines.push(
-															`    at ${convertedFnName} (${pos.source}:${pos.line}:${pos.column})`
-														);
-													}
-												}
-											} catch {
-												// Line failed to parse through the sourcemap consumer
-												// We should handle this better
-											}
-										}
-									);
-								}
-							);
-
-							// Log the parsed stacktrace
-							logger.error(
-								params.exceptionDetails.text,
-								exceptionLines.join("\n")
-							);
-						} else {
-							// We log the stacktrace to the terminal
-							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,
-		props.sourceMapPath,
-		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":
-							ro.preview.entries === undefined
-								? args.push("{}")
-								: args.push(
-										"{\n" +
-											ro.preview.entries
-												.map(({ key, value }) => {
-													return `  ${key?.description ?? "<unknown>"} => ${
-														value.description
-													}`;
-												})
-												.join(",\n") +
-											(ro.preview.overflow ? "\n  ..." : "") +
-											"\n}"
-								  );
-
-							break;
-						case "weakset":
-						case "set":
-							ro.preview.entries === undefined
-								? args.push("{}")
-								: args.push(
-										"{ " +
-											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://devtools.devprod.cloudflare.dev/js_app?theme=systemPreferred&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,
-			},
-			{
-				name: open.apps.firefox,
-			},
-		],
-	});
-	childProcess.on("error", () => {
-		logger.warn(errorMessage);
-	});
-};