Fix port conflicts by distributing custom server & mockttp configuration

Author: pimterry

package-lock.json

@@ -158,6 +158,7 @@
     "electron-context-menu": "^3.5.0",
     "electron-store": "^11.0.1",
     "electron-window-state": "^5.0.3",
+    "get-port": "^7.2.0",
     "os-proxy-config": "^1.1.1",
     "semver": "^7.2.1",
     "tslib": "^2.8.1",

package.json

@@ -20,7 +20,7 @@ interface LastRunData {
     timestamp: number;
 }
 
-// Read previous run record, or null if we've never written one (first run, or a pre-v1.27 install).
+// Read previous run record, or null if we've never written one (first run, or older install).
 const readLastRun = async (filePath: string): Promise<LastRunData | null> => {
     let content: string;
     try {
@@ -42,7 +42,7 @@ const readLastRun = async (filePath: string): Promise<LastRunData | null> => {
     }
 };
 
-// The window-state.json mtime, or null if absent. Used as a last-used fallback for pre-v1.27 installs,
+// The window-state.json mtime, or null if absent. Used as a last-used fallback for older installs,
 // which have no run record of their own but do leave this behind on every window move/resize/close.
 const readWindowStateMtime = async (userDataPath: string): Promise<number | null> => {
     try {

src/cache-cleanup.ts

@@ -22,10 +22,11 @@ import { getDeferred } from '@httptoolkit/util';
 
 import { getMenu, shouldAutoHideMenu } from './menu.ts';
 import { ContextMenuDefinition, openContextMenu } from './context-menu.ts';
+import getPort from 'get-port';
+
 import { stopServer } from './stop-server.ts';
 import { shouldClearStaleUICache, clearUICache, recordUIRun } from './cache-cleanup.ts';
 import { getDeviceDetails } from './device.ts';
-import { SERVER_PORTS, checkPortsInUse, checkWindowsReservedPorts } from './port-checks.ts';
 
 import packageJson from '../package.json' with { type: 'json' };
 
@@ -54,6 +55,23 @@ let windows: Electron.BrowserWindow[] = [];
 
 let server: ChildProcess | null = null;
 
+interface ServerPorts {
+    serverPort: number;
+    mockttpPort: number;
+}
+
+// Pick two random available ports in parallel. We deliberately don't constrain
+// to a fixed range: if there's a conflict or race, restarting the app picks
+// fresh ports and is likely to succeed.
+const pickServerPorts = async (): Promise<ServerPorts> => {
+    const [serverPort, mockttpPort] = await Promise.all([getPort(), getPort()]);
+    return { serverPort, mockttpPort };
+};
+
+// Resolved before any window or server is started, to inject into the renderer
+// synchronously via additionalArguments and into the server via CLI flags.
+let serverPorts: ServerPorts;
+
 app.commandLine.appendSwitch('ignore-connections-limit', 'app.httptoolkit.tech');
 app.commandLine.appendSwitch('disable-renderer-backgrounding');
 app.commandLine.appendSwitch('js-flags', [
@@ -86,7 +104,15 @@ const createWindow = () => {
         webPreferences: {
             preload: path.join(import.meta.dirname, 'preload.cjs'),
             contextIsolation: true,
-            nodeIntegration: false
+            nodeIntegration: false,
+            // Pass startup-time values into the preload synchronously, so the
+            // UI can read them via desktopApi getters without awaiting IPC.
+            additionalArguments: [
+                `--htk-desktop-version=${DESKTOP_VERSION}`,
+                `--htk-server-auth-token=${AUTH_TOKEN}`,
+                `--htk-server-port=${serverPorts.serverPort}`,
+                `--htk-mockttp-port=${serverPorts.mockttpPort}`
+            ]
         },
 
         show: false
@@ -153,7 +179,12 @@ const writeLog = (message: string) => {
     stream.write(message + '\n');
 }
 
-const openNewWindow = () => appReady.promise.then(() => createWindow());
+// Resolved once serverPorts is populated, after the main-instance branch
+// initialises it. createWindow reads serverPorts to seed additionalArguments.
+const portsResolved = getDeferred<ServerPorts>();
+
+const openNewWindow = () => Promise.all([appReady.promise, portsResolved.promise])
+    .then(() => createWindow());
 
 const amMainInstance = app.requestSingleInstanceLock();
 if (!amMainInstance) {
@@ -176,7 +207,7 @@ if (!amMainInstance) {
             serverKilled = true;
 
             try {
-                await stopServer(server, AUTH_TOKEN);
+                await stopServer(server, AUTH_TOKEN, serverPorts.serverPort);
             } catch (error) {
                 console.log('Failed to kill server', error);
                 logError(error);
@@ -413,7 +444,13 @@ if (!amMainInstance) {
                 ].join(' ')
         }
 
-        server = spawn(serverBinCommand, ['start'], {
+        const serverArgs = [
+            'start',
+            '--server-port', String(serverPorts.serverPort),
+            '--mockttp-port', String(serverPorts.mockttpPort)
+        ];
+
+        server = spawn(serverBinCommand, serverArgs, {
             windowsHide: true,
             stdio: ['inherit', 'pipe', 'pipe'],
             shell: isWindows, // Required to spawn a .cmd script
@@ -526,47 +563,18 @@ if (!amMainInstance) {
         process.env.COMSPEC = path.join(process.env.SystemRoot || 'C:\\Windows', 'System32', 'cmd.exe');
     }
 
-    // Check if our required ports are already in use by another process
-    const portsInUseCheck = checkPortsInUse('127.0.0.1', [...SERVER_PORTS])
-        .then(async (portsInUse) => {
-            if (portsInUse.length === 0) return;
-            if (DEV_MODE) return; // In full dev mode this is OK & expected
-
-            await appReady.promise;
-
-            const portList = portsInUse.join(', ');
-            showErrorAlert(
-                "HTTP Toolkit could not start",
-                `HTTP Toolkit's required port${portsInUse.length > 1 ? 's' : ''} (${portList}) ` +
-                `${portsInUse.length > 1 ? 'are' : 'is'} already in use.\n\n` +
-                "Do you have another HTTP Toolkit process running somewhere?\n" +
-                "Please close the other process using this port, and try again.\n\n" +
-                "(Having trouble? File an issue at github.com/httptoolkit/httptoolkit)"
-            );
-
-            process.exit(2);
-        });
-
-    // On Windows, check if Hyper-V/WSL has reserved our ports (separate from 'in use' above)
-    const reservedPortCheck = checkWindowsReservedPorts([...SERVER_PORTS])
-        .then(async (reservedPorts) => {
-            if (reservedPorts.length === 0) return;
-            if (DEV_MODE) return;
-
-            await appReady.promise;
-
-            const portList = reservedPorts.join(', ');
-            await showErrorAlert(
-                "HTTP Toolkit could not start",
-                `HTTP Toolkit's required port${reservedPorts.length > 1 ? 's' : ''} (${portList}) ` +
-                `${reservedPorts.length > 1 ? 'have' : 'has'} been reserved by Windows.\n\n` +
-                "This is usually caused by Hyper-V or WSL reserving ports for its own use. " +
-                "This can be fixed by adjusting your Windows network configuration.",
-                "https://httptoolkit.com/docs/guides/troubleshooting/#http-toolkit-conflicts-with-hyper-v"
-            );
-
-            process.exit(2);
-        });
+    // Pick random available ports for the server & mockttp admin API. Random
+    // (rather than a fixed range) means that a transient conflict or race is
+    // self-healing: restarting the app will likely pick a different pair.
+    // In DEV_MODE we use the historic defaults, so a separately-launched dev
+    // server stays reachable.
+    (DEV_MODE
+        ? Promise.resolve({ serverPort: 45457, mockttpPort: 45456 })
+        : pickServerPorts()
+    ).then((ports) => {
+        serverPorts = ports;
+        portsResolved.resolve(ports);
+    }, portsResolved.reject);
 
     // Check we're happy using the default proxy settings
     getSystemProxy()
@@ -623,8 +631,7 @@ if (!amMainInstance) {
 
     Promise.all([
         cleanupOldServers().catch(console.log),
-        portsInUseCheck,
-        reservedPortCheck
+        portsResolved.promise
     ]).then(() =>
         startServer()
     ).catch((err) => {
@@ -667,7 +674,7 @@ if (!amMainInstance) {
             });
     }
 
-    Promise.all([appReady.promise, portsInUseCheck, reservedPortCheck, uiCacheReady]).then(() => {
+    Promise.all([appReady.promise, portsResolved.promise, uiCacheReady]).then(() => {
         Menu.setApplicationMenu(getMenu(windows, openNewWindow));
         createWindow();
     });
@@ -750,8 +757,6 @@ ipcMain.handle('open-context-menu', ipcHandler((options: ContextMenuDefinition)
     openContextMenu(options)
 ));
 
-ipcMain.handle('get-desktop-version', ipcHandler(() => DESKTOP_VERSION));
-ipcMain.handle('get-server-auth-token', ipcHandler(() => AUTH_TOKEN));
 ipcMain.handle('get-device-info', ipcHandler(() => getDeviceDetails()));
 
 ipcMain.handle('set-component-versions', ipcHandler((versions: Record<string, string>) => {