feat(cluster): support reusePort on server listen (#5754)

Add SO_REUSEPORT socket option support for server listen, which allows
multiple server sockets to bind to the same port with the OS
distributing incoming connections. This improves load balancing in
cluster scenarios.

- Add reusePort option to ClusterOptions interface
- Add platform validation (linux, freebsd, sunos, aix)
- Use server.listen({ port, reusePort, host }) when reusePort is enabled
- Handle message routing for reusePort (cluster doesn't emit 'listening'
event)
- Support reusePort in worker_threads mode (all workers share same port)
- Add test fixtures and tests for reusePort functionality

Synced from eggjs/cluster#115

close #5728

🤖 Generated with [Claude Code](https://claude.com/claude-code)

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

## Summary by CodeRabbit

## Release Notes

* **New Features**
* Added reusePort configuration option for cluster server listening.
When enabled on supported platforms, this allows multiple workers to
bind to the same port, improving socket reuse behavior and resource
utilization (default: false).

* **Tests**
* Added test coverage and fixture applications for reusePort
functionality.

<sub>✏️ Tip: You can customize this high-level summary in your review
settings.</sub>

<!-- end of auto-generated comment: release notes by coderabbit.ai -->

Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>

Author: fengmk2

packages/cluster/src/app_worker.ts

@@ -1,7 +1,8 @@
 import fs from 'node:fs';
 import { createServer as createHttpServer, type Server } from 'node:http';
 import { createServer as createHttpsServer } from 'node:https';
-import type { Socket } from 'node:net';
+import type { Socket, ListenOptions } from 'node:net';
+import os from 'node:os';
 import { debuglog } from 'node:util';
 
 import { importModule } from '@eggjs/utils';
@@ -13,6 +14,12 @@ import { AppThreadWorker } from './utils/mode/impl/worker_threads/app.ts';
 
 const debug = debuglog('egg/cluster/app_worker');
 
+// https://nodejs.org/api/net.html#serverlistenoptions-callback
+// https://github.com/nodejs/node/blob/main/node.gypi#L310
+// https://docs.python.org/3/library/sys.html#sys.platform
+// This option is available only on some platforms, such as Linux 3.9+, DragonFlyBSD 3.6+, FreeBSD 12.0+, Solaris 11.4, and AIX 7.2.5+.
+const REUSE_PORT_SUPPORTED_PLATFORMS = ['linux', 'freebsd', 'sunos', 'aix'];
+
 async function main() {
   // $ node app_worker.js options-json-string
   const options = JSON.parse(process.argv[2]) as {
@@ -25,6 +32,7 @@ async function main() {
     https?: object;
     sticky?: boolean;
     stickyWorkerPort?: number;
+    reusePort?: boolean;
   };
   if (options.require) {
     // inject
@@ -89,13 +97,26 @@ async function main() {
     const port = (app.options.port = options.port || listenConfig.port);
     const debugPort = options.debugPort;
     const protocol = httpsOptions.key && httpsOptions.cert ? 'https' : 'http';
+
+    // Check reusePort option and validate platform support
+    let reusePort = options.reusePort ?? listenConfig.reusePort ?? false;
+    if (reusePort && !REUSE_PORT_SUPPORTED_PLATFORMS.includes(os.platform())) {
+      reusePort = false;
+      debug(
+        '[app_worker:%s] platform %s is not supported for reusePort, set reusePort to false',
+        process.pid,
+        os.platform(),
+      );
+    }
+
     debug(
-      '[app_worker:%s] listenConfig: %j, real port: %o, protocol: %o, debugPort: %o',
+      '[app_worker:%s] listenConfig: %j, real port: %o, protocol: %o, debugPort: %o, reusePort: %o',
       process.pid,
       listenConfig,
       port,
       protocol,
       debugPort,
+      reusePort,
     );
 
     AppWorker.send({
@@ -158,12 +179,23 @@ async function main() {
           exitProcess();
           return;
         }
-        const args = [port];
-        if (listenConfig.hostname) {
-          args.push(listenConfig.hostname);
+        if (reusePort) {
+          // https://nodejs.org/api/net.html#serverlistenoptions-callback
+          // Use options object when reusePort is enabled
+          const listenOptions: ListenOptions = { port, reusePort };
+          if (listenConfig.hostname) {
+            listenOptions.host = listenConfig.hostname;
+          }
+          debug('[app_worker:%s] listen with reusePort options %j', process.pid, listenOptions);
+          server.listen(listenOptions);
+        } else {
+          const args = [port];
+          if (listenConfig.hostname) {
+            args.push(listenConfig.hostname);
+          }
+          debug('listen options %j', args);
+          server.listen(...args);
         }
-        debug('listen options %j', args);
-        server.listen(...args);
       }
       if (debugPortServer) {
         debug('listen on debug port: %s', debugPort);
@@ -181,14 +213,15 @@ async function main() {
           addressType: -1,
         };
       }
-      debug('[app_worker:%s] listening at %j', process.pid, address);
+      debug('[app_worker:%s] listening at %j, reusePort: %o', process.pid, address, reusePort);
       AppWorker.send({
         to: 'master',
         action: 'app-start',
         data: {
           address,
           workerId: AppWorker.workerId,
         },
+        reusePort,
       });
     });
   }

packages/cluster/src/utils/messenger.ts

@@ -19,6 +19,12 @@ export interface MessageBody {
   receiverPid?: string;
   receiverWorkerId?: string;
   senderWorkerId?: string;
+  /**
+   * Whether reusePort is enabled for server listen.
+   * When reusePort is true, cluster won't get `listening` event,
+   * so we need to use cluster `message` event instead.
+   */
+  reusePort?: boolean;
 }
 
 /**

packages/cluster/src/utils/mode/impl/process/app.ts

@@ -1,4 +1,5 @@
 import cluster, { type Worker as ClusterProcessWorker } from 'node:cluster';
+import { debuglog } from 'node:util';
 
 import { cfork } from 'cfork';
 import { graceful as gracefulExit, type Options as gracefulExitOptions } from 'graceful-process';
@@ -8,6 +9,8 @@ import type { MessageBody } from '../../../messenger.ts';
 import { terminate } from '../../../terminate.ts';
 import { BaseAppWorker, BaseAppUtils } from '../../base/app.ts';
 
+const debug = debuglog('egg/cluster/utils/mode/impl/process/app');
+
 export class AppProcessWorker extends BaseAppWorker<ClusterProcessWorker> {
   get id(): number {
     return this.instance.id;
@@ -45,6 +48,13 @@ export class AppProcessWorker extends BaseAppWorker<ClusterProcessWorker> {
 
   static send(message: MessageBody): void {
     message.senderWorkerId = String(process.pid);
+    // cluster won't get `listening` event when reusePort is true,
+    // use cluster `message` event instead
+    if (message.action === 'app-start' && message.reusePort) {
+      debug('send app-start message with reusePort, use cluster.worker.send()');
+      cluster.worker!.send(message);
+      return;
+    }
     process.send!(message);
   }
 

packages/cluster/src/utils/mode/impl/worker_threads/app.ts

@@ -140,17 +140,30 @@ export class AppThreadUtils extends BaseAppUtils {
     this.startTime = Date.now();
     this.startSuccessCount = 0;
 
-    const ports = this.options.ports ?? [];
-    if (!ports.length) {
-      ports.push(this.options.port!);
+    if (this.options.reusePort) {
+      // When reusePort is enabled, all workers share the same port
+      // and each worker has its own socket
+      if (!this.options.port) {
+        throw new Error('options.port must be specified when reusePort is enabled');
+      }
+      for (let i = 0; i < this.options.workers; i++) {
+        const argv = [JSON.stringify(this.options)];
+        this.#forkSingle(this.getAppWorkerFile(), { argv }, i + 1);
+      }
+    } else {
+      // Normal mode: each worker can have a different port
+      const ports = this.options.ports ?? [];
+      if (!ports.length) {
+        ports.push(this.options.port!);
+      }
+      this.options.workers = ports.length;
+      let i = 0;
+      do {
+        const options = Object.assign({}, this.options, { port: ports[i] });
+        const argv = [JSON.stringify(options)];
+        this.#forkSingle(this.getAppWorkerFile(), { argv }, ++i);
+      } while (i < ports.length);
     }
-    this.options.workers = ports.length;
-    let i = 0;
-    do {
-      const options = Object.assign({}, this.options, { port: ports[i] });
-      const argv = [JSON.stringify(options)];
-      this.#forkSingle(this.getAppWorkerFile(), { argv }, ++i);
-    } while (i < ports.length);
 
     return this;
   }

packages/cluster/src/utils/options.ts

@@ -78,6 +78,12 @@ export interface ClusterOptions {
    * sticky mode server
    */
   sticky?: boolean;
+  /**
+   * enable SO_REUSEPORT socket option for server listen, default is `false`.
+   * Only available on Linux 3.9+, DragonFlyBSD 3.6+, FreeBSD 12.0+, Solaris 11.4, and AIX 7.2.5+.
+   * @see https://nodejs.org/api/net.html#serverlistenoptions-callback
+   */
+  reusePort?: boolean;
   /** customized plugins, for unittest */
   plugins?: object;
   isDebug?: boolean;

packages/cluster/test/app_worker.test.ts

@@ -285,6 +285,30 @@ describe.skipIf(process.version.startsWith('v24') || process.platform === 'win32
       const sock = encodeURIComponent(sockFile);
       await request(`http+unix://${sock}`).get('/').expect('done').expect(200);
     });
+
+    it.skipIf(process.platform !== 'linux')('should use reusePort in config on Linux', async () => {
+      app = cluster('apps/app-listen-reusePort', { port: 0, workers: 2 });
+      // app.debug();
+      await app.ready();
+
+      app.expect('code', 0);
+      app.expect('stdout', /egg started on http:\/\/127.0.0.1:17010/);
+
+      await request('http://127.0.0.1:17010').get('/').expect('done').expect(200);
+      await request('http://127.0.0.1:17010').get('/port').expect('17010').expect(200);
+    });
+
+    it('should set reusePort=true in config (non-Linux will fallback to false)', async () => {
+      app = cluster('apps/app-listen-reusePort', { port: 0 });
+      // app.debug();
+      await app.ready();
+
+      app.expect('code', 0);
+      app.expect('stdout', /egg started on http:\/\/127.0.0.1:17010/);
+
+      await request('http://127.0.0.1:17010').get('/').expect('done').expect(200);
+      await request('http://127.0.0.1:17010').get('/port').expect('17010').expect(200);
+    });
   });
 
   it('should exit when EADDRINUSE', async () => {

packages/cluster/test/fixtures/apps/app-listen-reusePort/app.js

@@ -0,0 +1,4 @@
+module.exports = (app) => {
+  // don't use the port that egg-mock defined
+  app._options.port = undefined;
+};

packages/cluster/test/fixtures/apps/app-listen-reusePort/app/router.js

@@ -0,0 +1,9 @@
+module.exports = (app) => {
+  app.get('/', (ctx) => {
+    ctx.body = 'done';
+  });
+
+  app.get('/port', (ctx) => {
+    ctx.body = ctx.app.options.port;
+  });
+};

packages/cluster/test/fixtures/apps/app-listen-reusePort/config/config.default.js

@@ -0,0 +1,9 @@
+module.exports = {
+  keys: '123',
+  cluster: {
+    listen: {
+      port: 17010,
+      reusePort: true,
+    },
+  },
+};

packages/cluster/test/fixtures/apps/app-listen-reusePort/package.json

@@ -0,0 +1,3 @@
+{
+  "name": "app-listen-reusePort"
+}