Merge pull request #212 from apify/fix/devtools-server-eaddrinuse

fix: prevent DevToolsServer port conflicts on BrowserPool relaunch

Fixes a Web Scraper dev-mode issue where DevToolsServer was started from BrowserPool’s preLaunchHook on every browser launch/relaunch, causing EADDRINUSE port conflicts after browser/page crashes or pool relaunches. The PR makes DevToolsServer startup idempotent by starting it only once per actor process (reusing a cached start promise on subsequent hook calls) and registers a single Actor.on('exit') cleanup to stop the server.

Author: nikitachapovskii-dev

packages/actor-scraper/web-scraper/src/internals/crawler_setup.ts

@@ -225,6 +225,37 @@ export class CrawlerSetup implements CrawlerSetupOptions {
         this.initPromise = this._initializeAsync();
     }
 
+    private static devToolsStartPromise: Promise<DevToolsServer | null> | null =
+        null;
+
+    private static async getDevToolsServer(): Promise<DevToolsServer | null> {
+        if (this.devToolsStartPromise) return this.devToolsStartPromise;
+
+        this.devToolsStartPromise = (async () => {
+            const url = process.env.ACTOR_WEB_SERVER_URL;
+            const portRaw = process.env.ACTOR_WEB_SERVER_PORT;
+            if (!url || !portRaw) return null;
+
+            const port = Number(portRaw);
+            if (!Number.isFinite(port)) return null;
+
+            const server = new DevToolsServer({
+                containerHost: new URL(url).host,
+                devToolsServerPort: port,
+                chromeRemoteDebuggingPort: CHROME_DEBUGGER_PORT,
+            });
+
+            await server.start();
+
+            Actor.on('exit', () => {
+                server.stop?.();
+            });
+            return server;
+        })();
+
+        return this.devToolsStartPromise;
+    }
+
     private async _initializeAsync() {
         // RequestList
         const startUrls = this.input.startUrls.map((req) => {
@@ -311,19 +342,8 @@ export class CrawlerSetup implements CrawlerSetupOptions {
             browserPoolOptions: {
                 preLaunchHooks: [
                     async () => {
-                        if (!this.isDevRun) {
-                            return;
-                        }
-
-                        const devToolsServer = new DevToolsServer({
-                            containerHost: new URL(
-                                process.env.ACTOR_WEB_SERVER_URL!,
-                            ).host,
-                            devToolsServerPort:
-                                process.env.ACTOR_WEB_SERVER_PORT,
-                            chromeRemoteDebuggingPort: CHROME_DEBUGGER_PORT,
-                        });
-                        await devToolsServer.start();
+                        if (!this.isDevRun) return;
+                        await CrawlerSetup.getDevToolsServer();
                     },
                 ],
             },

packages/actor-scraper/web-scraper/test/devtools-server.regression.test.ts

@@ -0,0 +1,52 @@
+import { describe, expect, it, vi } from 'vitest';
+
+describe('DevToolsServer (regression)', () => {
+    it('starts only once even if preLaunchHook calls it multiple times', async () => {
+        const oldEnv = process.env;
+        const actorOnMock = vi.fn();
+
+        const startMock = vi.fn(async () => {});
+        const stopMock = vi.fn(() => {});
+        const DevToolsCtorMock = vi.fn(() => ({
+            start: startMock,
+            stop: stopMock,
+        }));
+
+        try {
+            process.env = { ...oldEnv };
+            process.env.ACTOR_WEB_SERVER_URL = 'http://127.0.0.1:4321';
+            process.env.ACTOR_WEB_SERVER_PORT = '4321';
+
+            vi.resetModules();
+            vi.doMock('devtools-server', () => ({ default: DevToolsCtorMock }));
+            vi.doMock('apify', () => ({ Actor: { on: actorOnMock } }));
+
+            const mod = await import(
+                new URL('../src/internals/crawler_setup.ts', import.meta.url)
+                    .href
+            );
+            const { CrawlerSetup } = mod as any;
+
+            CrawlerSetup.devToolsServerPromise = null;
+
+            const fn =
+                CrawlerSetup.getDevToolsServer ??
+                CrawlerSetup.startDevToolsServerOnce;
+
+            await Promise.all(
+                Array.from({ length: 10 }, () => fn.call(CrawlerSetup)),
+            );
+
+            expect(DevToolsCtorMock).toHaveBeenCalledTimes(1);
+            expect(startMock).toHaveBeenCalledTimes(1);
+            expect(actorOnMock).toHaveBeenCalledTimes(1);
+            expect(actorOnMock).toHaveBeenCalledWith(
+                'exit',
+                expect.any(Function),
+            );
+        } finally {
+            process.env = oldEnv;
+            vi.resetModules();
+        }
+    });
+});