wrangler 0.0.0-e6733a3 → 0.0.0-e9307365

package/src/inspect.ts

@@ -1,11 +1,19 @@
-import type { MessageEvent } from "ws";
-import WebSocket, { WebSocketServer } from "ws";
-import type { IncomingMessage, Server, ServerResponse } from "http";
-import { createServer } from "http";
+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 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
@@ -32,384 +40,502 @@ import type Protocol from "devtools-protocol";
  */
 
 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: undefined | string;
-  /**
-   * 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;
+	/**
+	 * 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;
 }
 
 export default function useInspector(props: InspectorProps) {
-  /** A unique ID for this session. */
-  const inspectorIdRef = useRef(randomId());
-  /**
-   *  The local proxy server that acts as the bridge between
-   *  the remote websocket and the local DevTools instance.
-   */
-  const serverRef = useRef<Server>();
-  /** The websocket server that runs on top of the proxy server. */
-  const wsServerRef = useRef<WebSocketServer>();
-
-  /** The websocket from the devtools instance. */
-  const [localWebSocket, setLocalWebSocket] = useState<WebSocket | undefined>();
-  /**  The websocket from the edge */
-  const [remoteWebSocket, setRemoteWebSocket] = useState<
-    WebSocket | undefined
-  >();
-
-  if (!serverRef.current) {
-    // Let's create the proxy server!
-    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 edgeworker.
-                // 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;
-        }
-      }
-    );
-
-    // Let's create the websocket server on top of the proxy server
-    wsServerRef.current = new WebSocketServer({
-      server: serverRef.current,
-      clientTracking: true,
-    });
-    wsServerRef.current.on("connection", (ws: WebSocket) => {
-      if (wsServerRef.current.clients.size > 1) {
-        /** We only want to have one active Devtools instance at a time. */
-        console.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(() => {
-    serverRef.current.listen(props.port);
-    return () => {
-      serverRef.current.close();
-      // Also disconnect any open websockets/devtools connections
-      wsServerRef.current.clients.forEach((ws) => ws.close());
-      wsServerRef.current.close();
-    };
-  }, [props.port]);
-
-  /**
-   * 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;
-            console.error(
-              "🚨", // cheesy, but it works
-              // maybe we could use color here too.
-              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...
-          console.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", () => {
-      console.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.
-      wsServerRef.current.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,
-    retryRemoteWebSocketConnectionSigil,
-    props.logToTerminal,
-  ]);
-
-  /**
-   * 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 {
-        remoteWebSocket.send(event.data);
-      } catch (e) {
-        if (e.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?
-           */
-          console.error(e);
-        }
-      }
-    }
-
-    /** Send a message from the local websocket to the remote websocket */
-    function sendMessageToLocalWebSocket(event: MessageEvent) {
-      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]);
+	/** 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", 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?.replace(
+																`${mapContent.sourceRoot}/`,
+																""
+															)}:${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);
-  });
+	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);
+	});
 }
 
 /**
@@ -419,106 +545,206 @@ function randomId(): string {
  * 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 = [];
-  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}]`);
-        break;
-      case "object":
-        if (!ro.preview) {
-          args.push(ro.description);
-        } else {
-          args.push(ro.preview.description);
-
-          switch (ro.preview.subtype) {
-            case "array":
-              args.push(
-                "[ " +
-                  ro.preview.properties
-                    .map(({ value }) => {
-                      return value;
-                    })
-                    .join(", ") +
-                  (ro.preview.overflow ? "..." : "") +
-                  " ]"
-              );
-
-              break;
-            case "map":
-              args.push(
-                "{\n" +
-                  ro.preview.entries
-                    .map(({ key, value }) => {
-                      return `  ${key.description} => ${value.description}`;
-                    })
-                    .join(",\n") +
-                  (ro.preview.overflow ? "\n  ..." : "") +
-                  "\n}"
-              );
-
-              break;
-            case "set":
-              args.push(
-                "{ " +
-                  ro.preview.entries
-                    .map(({ value }) => {
-                      return `${value.description}`;
-                    })
-                    .join(", ") +
-                  (ro.preview.overflow ? ", ..." : "") +
-                  " }"
-              );
-
-              break;
-            case "null":
-              args.push("null");
-              break;
-            case "node":
-            case "regexp":
-            case "date":
-            case "weakmap":
-            case "weakset":
-            case "iterator":
-            case "generator":
-            case "error":
-            case "proxy":
-            case "promise":
-            case "typedarray":
-            case "arraybuffer":
-            case "dataview":
-            case "webassemblymemory":
-            case "wasmvalue":
-              break;
-            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;
-    }
-  }
-
-  console[evt.type](...args);
+	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);
+	});
+};