feat(cluster): make the separate HTTP debug server opt-in (#6073)

Configuring debugPort for a plain HTTP application calls listen() twice
on the same HTTP server, preventing both configured endpoints from
becoming usable. Add config.cluster.separateDebugServer as an opt-in to
create a separate HTTP debug listener.

The option defaults to false, preserving existing HTTP behavior as
requested in review. HTTPS already uses a separate HTTP server; this
option leaves that server selection unchanged. Document the option and
add its EggAppConfig type.

Tests cover omitted/false/true configuration, with and without
debugPort, plus the framework's false default. Real cluster tests cover
HTTP with default and explicit hostnames and HTTPS; both endpoints
respond and both ports are released after shutdown.

Validation on Windows, Node.js 22.23.2:
- Focused cluster tests: debug-port.test.ts, worker-protocol.test.ts,
and https.test.ts — 26 passed.
- Framework configuration tests — 2 passed.
- Restoring unconditional separate-server creation causes the two
default/false compatibility regressions to fail, with the remaining 18
protocol tests passing.
- Cluster tsc --noEmit passed. Final touched-file oxlint --type-aware
--type-check passed with three pre-existing redundant-union warnings in
packages/egg/src/lib/types.ts. All changed files were formatted with
oxfmt; git diff --check passed.

The runs use the package Vitest entry points and original configurations
with the existing focused dependency environment; this is not a full
monorepo installation or suite. The first sandbox-user attempts failed
before applications started because os.userInfo() returned
uv_os_get_passwd ENOMEM; the same tests passed under the normal Windows
user. Two final test typing annotations were checked by type-aware lint
after the successful runtime runs. No coverage percentage is claimed;
the updated CI/Codecov result is still required.

AI-assisted follow-up implementation and validation summary (GPT-6).

Follow-up validation for `8ab7b0b`: independent HTTP and HTTPS debug
listeners now route bind errors through the existing startup
log/worker-exit handler. The default shared HTTP listener retains
exactly one handler. Native occupied-port regressions live in a separate
file from the mocked protocol tests.

On Windows with Node.js 24.15.0 and the existing focused dependencies,
all 28 tests in worker-protocol, debug-port, https and debug-port-error
pass. Restoring only the preceding production source makes both
occupied-port regressions fail with real EADDRINUSE errors; the final
source was restored byte-for-byte. Cluster typecheck and final
three-file type-aware lint pass with no warnings. The earlier two
configuration tests are unchanged and were not repeated for this
handler-only follow-up. This remains focused local validation; updated
upstream CI/Codecov is pending.

<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit

* **New Features**
* HTTP applications can use a separate server for the debug port by
enabling `separateDebugServer`. The setting defaults to `false`, so the
debug port uses the application server unless configured otherwise.
* **Bug Fixes**
* Errors from the application server and any separate debug server are
now logged and trigger process exit.
* **Documentation**
* Documented the setting and its behavior for HTTP and HTTPS
applications.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->

Author: dvd233

packages/cluster/README.md

@@ -71,6 +71,25 @@ startCluster({
 | ports     | `Array`         | startup port of each app worker, such as: [7001, 7002, 7003], only effects when the startMode is 'worker_threads' |
 | env       | `String`        | custom env, default is process.env.EGG_SERVER_ENV                                                                 |
 
+### Separate HTTP Debug Server
+
+For an HTTP application, set `config.cluster.separateDebugServer` to `true` to
+serve the configured `debugPort` on a separate HTTP server:
+
+```js
+// config/config.default.js
+exports.cluster = {
+  separateDebugServer: true,
+};
+```
+
+Pass `port` and `debugPort` to `startCluster` as usual. Both ports serve the same
+application callback. The option defaults to `false`, preserving the existing
+HTTP behavior of reusing the application server for `debugPort`. Enable it when
+an HTTP application needs both listeners, since a Node.js server cannot listen
+on two ports at once. HTTPS applications already use a separate HTTP server for
+`debugPort` and are unaffected by this option.
+
 ## Env
 
 `EGG_APP_CLOSE_TIMEOUT`: app worker boot timeout value

packages/cluster/src/worker_protocol/app.ts

@@ -132,14 +132,18 @@ export function startAppWorker(
     } else {
       server = createHttpServer(app.callback());
       if (debugPort) {
-        debugPortServer = server;
+        debugPortServer = clusterConfig.separateDebugServer ? createHttpServer(app.callback()) : server;
       }
     }
 
-    server.once('error', (err: any) => {
+    const serverErrorHandler = (err: Error & { code?: string }) => {
       consoleLogger.error('[app_worker] server got error: %s, code: %s', err.message, err.code);
       exitProcess();
-    });
+    };
+    server.once('error', serverErrorHandler);
+    if (debugPortServer && debugPortServer !== server) {
+      debugPortServer.once('error', serverErrorHandler);
+    }
 
     // emit `server` event in app
     app.emit('server', server);

packages/cluster/test/debug-port-error.test.ts

@@ -0,0 +1,72 @@
+import { strict as assert } from 'node:assert';
+import { EventEmitter, once } from 'node:events';
+import { createServer, type Server } from 'node:http';
+import { fileURLToPath } from 'node:url';
+
+import { describe, it, vi } from 'vitest';
+
+import { startAppWorker } from '../src/worker_protocol/app.ts';
+
+describe('test/debug-port-error.test.ts', () => {
+  it.each(['http', 'https'])('handles an occupied separate debug port for %s', async (protocol) => {
+    const blocker = createServer();
+    let server: Server | undefined;
+    let timeout: ReturnType<typeof setTimeout> | undefined;
+    try {
+      // Match debugPortServer.listen(debugPort), including its default address family.
+      blocker.listen(0);
+      await once(blocker, 'listening');
+      const address = blocker.address();
+      assert.ok(address && typeof address !== 'string');
+
+      const app = new EventEmitter() as any;
+      app.config = { cluster: { listen: { port: 0 }, separateDebugServer: true } };
+      app.options = {};
+      app.ready = (callback: (err?: Error) => void) => callback();
+      app.callback = () => (_request: unknown, response: { end(): void }) => response.end();
+      app.close = () => {};
+      app.once('server', (value: Server) => {
+        server = value;
+      });
+      let resolveKilled: (() => void) | undefined;
+      const killed = new Promise<void>((resolve, reject) => {
+        resolveKilled = resolve;
+        timeout = setTimeout(() => reject(new Error('Debug-port bind failure did not request worker exit')), 2000);
+      });
+      const kill = vi.fn(() => resolveKilled!());
+      const logger = { error: vi.fn() } as any;
+      startAppWorker(
+        app,
+        {
+          debugPort: address.port,
+          ...(protocol === 'https'
+            ? {
+                https: {
+                  key: fileURLToPath(new URL('./fixtures/server.key', import.meta.url)),
+                  cert: fileURLToPath(new URL('./fixtures/server.cert', import.meta.url)),
+                },
+              }
+            : {}),
+        },
+        { workerId: 1, send() {}, kill, gracefulExit() {}, on() {} },
+        logger,
+      );
+      await killed;
+
+      assert.ok(server);
+      assert.equal(server.listenerCount('error'), 1);
+      assert.equal(kill.mock.calls.length, 1);
+      assert.equal(logger.error.mock.calls.length, 1);
+      assert.equal(logger.error.mock.calls[0][0], '[app_worker] server got error: %s, code: %s');
+      assert.match(logger.error.mock.calls[0][1], /EADDRINUSE/);
+      assert.equal(logger.error.mock.calls[0][2], 'EADDRINUSE');
+    } finally {
+      clearTimeout(timeout);
+      await Promise.all(
+        [server, blocker]
+          .filter((value): value is Server => value !== undefined)
+          .map((value) => new Promise<void>((resolve) => value.close(() => resolve()))),
+      );
+    }
+  });
+});

packages/cluster/test/debug-port.test.ts

@@ -0,0 +1,83 @@
+import { strict as assert } from 'node:assert';
+import { createConnection } from 'node:net';
+
+import { mm } from '@eggjs/mock';
+import { detectPort } from 'detect-port';
+import { HttpClient } from 'urllib';
+import { afterEach, describe, it } from 'vitest';
+
+import { cluster, getFilepath } from './utils.ts';
+
+const httpclient = new HttpClient({ connect: { rejectUnauthorized: false } });
+
+function isPortOpen(port: number): Promise<boolean> {
+  return new Promise((resolve, reject) => {
+    const socket = createConnection({ port, host: '127.0.0.1' });
+    socket.once('connect', () => {
+      socket.destroy();
+      resolve(true);
+    });
+    socket.once('error', (err: NodeJS.ErrnoException) => {
+      if (err.code === 'ECONNREFUSED') {
+        resolve(false);
+      } else {
+        reject(err);
+      }
+    });
+    socket.setTimeout(2000, () => socket.destroy(new Error('Timed out checking the closed listener')));
+  });
+}
+
+describe('test/debug-port.test.ts', () => {
+  let app: ReturnType<typeof cluster> | undefined;
+
+  afterEach(async () => {
+    try {
+      await app?.close();
+    } finally {
+      app = undefined;
+      await mm.restore();
+    }
+  });
+
+  it.each([
+    { name: 'HTTP without a hostname', protocol: 'http', hostname: '' },
+    { name: 'HTTP with an explicit hostname', protocol: 'http', hostname: '127.0.0.1' },
+    { name: 'HTTPS', protocol: 'https', hostname: '' },
+  ])('serves both ports and closes them for $name', async ({ protocol, hostname }) => {
+    const port = await detectPort();
+    const debugPort = await detectPort();
+    assert.notEqual(port, debugPort);
+    mm(process.env, 'EGG_TEST_CLUSTER_DEBUG_HOSTNAME', hostname);
+    mm(process.env, 'EGG_TEST_CLUSTER_SEPARATE_DEBUG_SERVER', String(protocol === 'http'));
+
+    const options = {
+      workers: 1,
+      port,
+      debugPort,
+      ...(protocol === 'https'
+        ? {
+            https: {
+              key: getFilepath('server.key'),
+              cert: getFilepath('server.cert'),
+              ca: getFilepath('server.ca'),
+            },
+          }
+        : {}),
+    };
+    app = cluster('apps/http-debug-server', options);
+    await app.ready();
+
+    const primary = await httpclient.request(`${protocol}://127.0.0.1:${port}`, { dataType: 'text' });
+    const debug = await httpclient.request(`http://127.0.0.1:${debugPort}`, { dataType: 'text' });
+    assert.equal(primary.status, 200);
+    assert.equal(debug.status, 200);
+    assert.equal(primary.data, 'debug-port server');
+    assert.equal(debug.data, primary.data);
+
+    await app.close();
+    app = undefined;
+    assert.equal(await isPortOpen(port), false);
+    assert.equal(await isPortOpen(debugPort), false);
+  });
+});

packages/cluster/test/fixtures/apps/http-debug-server/app/router.js

@@ -0,0 +1,5 @@
+module.exports = (app) => {
+  app.get('/', (ctx) => {
+    ctx.body = 'debug-port server';
+  });
+};

packages/cluster/test/fixtures/apps/http-debug-server/config/config.default.js

@@ -0,0 +1,9 @@
+'use strict';
+
+exports.keys = 'debug-port-test';
+exports.cluster = {
+  separateDebugServer: process.env.EGG_TEST_CLUSTER_SEPARATE_DEBUG_SERVER === 'true',
+  listen: {
+    hostname: process.env.EGG_TEST_CLUSTER_DEBUG_HOSTNAME || undefined,
+  },
+};

packages/cluster/test/fixtures/apps/http-debug-server/package.json

@@ -0,0 +1,3 @@
+{
+  "name": "http-debug-server"
+}

packages/cluster/test/worker-protocol.test.ts

@@ -4,7 +4,7 @@ import type { Server } from 'node:http';
 import os from 'node:os';
 import { Worker } from 'node:worker_threads';
 
-import { describe, it, vi } from 'vitest';
+import { describe, it, vi, type MockInstance } from 'vitest';
 
 import { startAgentWorker } from '../src/worker_protocol/agent.ts';
 import { startAppWorker } from '../src/worker_protocol/app.ts';
@@ -35,6 +35,50 @@ vi.mock('node:http', async (importOriginal) => {
 });
 
 describe('test/worker-protocol.test.ts', () => {
+  describe.each([undefined, false, true])('separateDebugServer: %s', (separateDebugServer) => {
+    it.each([undefined, 7002])('preserves the HTTP listener behavior with debugPort: %s', async (debugPort) => {
+      const app = new EventEmitter() as any;
+      app.config = {
+        cluster: {
+          listen: { port: 7001 },
+          ...(separateDebugServer === undefined ? {} : { separateDebugServer }),
+        },
+      };
+      app.options = {};
+      app.ready = (callback: (err?: Error) => void) => callback();
+      app.callback = vi.fn(() => (_request: unknown, response: { end(): void }) => response.end());
+      app.close = () => {};
+
+      let server: Server | undefined;
+      let listen: MockInstance<Server['listen']> | undefined;
+      app.once('server', (value: Server) => {
+        server = value;
+        listen = vi.spyOn(value, 'listen');
+      });
+      startAppWorker(
+        app,
+        { debugPort },
+        {
+          workerId: 1,
+          send() {},
+          kill() {
+            assert.fail('HTTP app should not be killed');
+          },
+          gracefulExit() {},
+          on() {},
+        },
+      );
+      await Promise.resolve();
+
+      assert.ok(server);
+      assert.ok(listen);
+      assert.equal(server.listenerCount('error'), 1);
+      assert.deepEqual(listen.mock.calls, debugPort && !separateDebugServer ? [[7001], [debugPort]] : [[7001]]);
+      assert.equal(app.callback.mock.calls.length, debugPort && separateDebugServer ? 2 : 1);
+      server.close();
+    });
+  });
+
   it('uses parentPort without terminating the main process', async () => {
     const worker = new Worker(new URL('./fixtures/worker-thread-io.mjs', import.meta.url));
     const workerId = worker.threadId;

packages/egg/src/config/config.default.ts

@@ -355,6 +355,7 @@ const factory: EggConfigFactory = defineConfigFactory((appInfo): PartialEggConfi
   /**
    * The options of cluster
    * @member {Object} Config#cluster
+   * @property {Boolean} separateDebugServer - use a separate HTTP server for debugPort on HTTP applications, default is `false`.
    * @property {Object} listen - listen options, see {@link https://nodejs.org/api/http.html#http_server_listen_port_hostname_backlog_callback}
    * @property {String} listen.path - set a unix sock path when server listen
    * @property {Number} listen.port - set a port when server listen
@@ -363,6 +364,7 @@ const factory: EggConfigFactory = defineConfigFactory((appInfo): PartialEggConfi
    *   Only available on Linux 3.9+, DragonFlyBSD 3.6+, FreeBSD 12.0+, Solaris 11.4, and AIX 7.2.5+.
    */
   config.cluster = {
+    separateDebugServer: false,
     listen: {
       path: '',
       port: 7001,

packages/egg/src/lib/types.ts

@@ -278,6 +278,8 @@ export interface EggAppConfig extends EggCoreAppConfig {
   serverTimeout: number | null;
 
   cluster: {
+    /** Use a separate HTTP server for debugPort on HTTP applications, defaults to `false`. */
+    separateDebugServer?: boolean;
     listen: {
       path: string;
       port: number;