@eggjs/cluster 3.0.0-beta.0

package/dist/esm/utils/terminate.js

@@ -0,0 +1,86 @@
+import { debuglog } from 'node:util';
+import { setTimeout as sleep } from 'node:timers/promises';
+import { once } from 'node:events';
+import { pstree } from '@fengmk2/ps-tree';
+const debug = debuglog('@eggjs/cluster/utils/terminate');
+export async function terminate(subProcess, timeout) {
+    const pid = subProcess.process?.pid ?? subProcess.pid;
+    const childPids = await getChildPids(pid);
+    await Promise.all([
+        killProcess(subProcess, timeout),
+        killChildren(childPids, timeout),
+    ]);
+}
+// kill process, if SIGTERM not work, try SIGKILL
+async function killProcess(subProcess, timeout) {
+    // https://github.com/nodejs/node/pull/34312
+    (subProcess.process ?? subProcess).kill('SIGTERM');
+    await Promise.race([
+        once(subProcess, 'exit'),
+        sleep(timeout),
+    ]);
+    if (subProcess.killed) {
+        return;
+    }
+    // SIGKILL: http://man7.org/linux/man-pages/man7/signal.7.html
+    // worker: https://github.com/nodejs/node/blob/master/lib/internal/cluster/worker.js#L22
+    // subProcess.kill is wrapped to subProcess.destroy, it will wait to disconnected.
+    (subProcess.process ?? subProcess).kill('SIGKILL');
+}
+// kill all children processes, if SIGTERM not work, try SIGKILL
+async function killChildren(childrenPids, timeout) {
+    if (childrenPids.length === 0) {
+        return;
+    }
+    kill(childrenPids, 'SIGTERM');
+    const start = Date.now();
+    // if timeout is 1000, it will check twice.
+    const checkInterval = 400;
+    let unterminated = [];
+    while (Date.now() - start < timeout - checkInterval) {
+        await sleep(checkInterval);
+        unterminated = getUnterminatedProcesses(childrenPids);
+        if (unterminated.length === 0) {
+            return;
+        }
+    }
+    kill(unterminated, 'SIGKILL');
+}
+async function getChildPids(pid) {
+    let childrenPids = [];
+    try {
+        const children = await pstree(pid);
+        childrenPids = children.map(c => parseInt(c.PID));
+    }
+    catch (err) {
+        // if get children error, just ignore it
+        debug('pstree %s error: %s, ignore it', pid, err);
+    }
+    return childrenPids;
+}
+function kill(pids, signal) {
+    for (const pid of pids) {
+        try {
+            process.kill(pid, signal);
+        }
+        catch (err) {
+            // ignore
+            debug('kill %s error: %s, signal: %s, ignore it', pid, err, signal);
+        }
+    }
+}
+function getUnterminatedProcesses(pids) {
+    return pids.filter(pid => {
+        try {
+            // success means it's still alive
+            process.kill(pid, 0);
+            return true;
+        }
+        catch (err) {
+            // error means it's dead
+            debug('kill %s error: %s, it still alive', pid, err);
+            return false;
+        }
+    });
+}
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoidGVybWluYXRlLmpzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vLi4vLi4vc3JjL3V0aWxzL3Rlcm1pbmF0ZS50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFBQSxPQUFPLEVBQUUsUUFBUSxFQUFFLE1BQU0sV0FBVyxDQUFDO0FBQ3JDLE9BQU8sRUFBRSxVQUFVLElBQUksS0FBSyxFQUFFLE1BQU0sc0JBQXNCLENBQUM7QUFDM0QsT0FBTyxFQUFFLElBQUksRUFBRSxNQUFNLGFBQWEsQ0FBQztBQUVuQyxPQUFPLEVBQUUsTUFBTSxFQUFFLE1BQU0sa0JBQWtCLENBQUM7QUFFMUMsTUFBTSxLQUFLLEdBQUcsUUFBUSxDQUFDLGdDQUFnQyxDQUFDLENBQUM7QUFNekQsTUFBTSxDQUFDLEtBQUssVUFBVSxTQUFTLENBQUMsVUFBc0IsRUFBRSxPQUFlO0lBQ3JFLE1BQU0sR0FBRyxHQUFHLFVBQVUsQ0FBQyxPQUFPLEVBQUUsR0FBRyxJQUFJLFVBQVUsQ0FBQyxHQUFHLENBQUM7SUFDdEQsTUFBTSxTQUFTLEdBQUcsTUFBTSxZQUFZLENBQUMsR0FBSSxDQUFDLENBQUM7SUFDM0MsTUFBTSxPQUFPLENBQUMsR0FBRyxDQUFDO1FBQ2hCLFdBQVcsQ0FBQyxVQUFVLEVBQUUsT0FBTyxDQUFDO1FBQ2hDLFlBQVksQ0FBQyxTQUFTLEVBQUUsT0FBTyxDQUFDO0tBQ2pDLENBQUMsQ0FBQztBQUNMLENBQUM7QUFFRCxpREFBaUQ7QUFDakQsS0FBSyxVQUFVLFdBQVcsQ0FBQyxVQUFzQixFQUFFLE9BQWU7SUFDaEUsNENBQTRDO0lBQzVDLENBQUMsVUFBVSxDQUFDLE9BQU8sSUFBSSxVQUFVLENBQUMsQ0FBQyxJQUFJLENBQUMsU0FBUyxDQUFDLENBQUM7SUFDbkQsTUFBTSxPQUFPLENBQUMsSUFBSSxDQUFDO1FBQ2pCLElBQUksQ0FBQyxVQUFVLEVBQUUsTUFBTSxDQUFDO1FBQ3hCLEtBQUssQ0FBQyxPQUFPLENBQUM7S0FDZixDQUFDLENBQUM7SUFDSCxJ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

package/dist/esm/utils/worker_manager.d.ts

@@ -0,0 +1,25 @@
+import { EventEmitter } from 'node:events';
+import { BaseAgentWorker } from './mode/base/agent.js';
+import { BaseAppWorker } from './mode/base/app.js';
+export declare class WorkerManager extends EventEmitter {
+    agent: BaseAgentWorker | null;
+    workers: Map<number, BaseAppWorker<import("worker_threads").Worker | import("cluster").Worker>>;
+    exception: number;
+    timer: NodeJS.Timeout;
+    constructor();
+    getWorkers(): number[];
+    setAgent(agent: BaseAgentWorker): void;
+    getAgent(): BaseAgentWorker<import("child_process").ChildProcess | import("worker_threads").Worker> | null;
+    deleteAgent(): void;
+    setWorker(worker: BaseAppWorker): void;
+    getWorker(workerId: number): BaseAppWorker<import("worker_threads").Worker | import("cluster").Worker> | undefined;
+    deleteWorker(workerId: number): void;
+    listWorkerIds(): number[];
+    listWorkers(): BaseAppWorker<import("worker_threads").Worker | import("cluster").Worker>[];
+    getListeningWorkerIds(): number[];
+    count(): {
+        agent: number;
+        worker: number;
+    };
+    startCheck(): void;
+}

package/dist/esm/utils/worker_manager.js

@@ -0,0 +1,72 @@
+import { EventEmitter } from 'node:events';
+// worker manager to record agent and worker forked by egg-cluster
+// can do some check stuff here to monitor the healthy
+export class WorkerManager extends EventEmitter {
+    agent;
+    workers = new Map();
+    exception = 0;
+    timer;
+    constructor() {
+        super();
+        this.agent = null;
+    }
+    getWorkers() {
+        return Array.from(this.workers.keys());
+    }
+    setAgent(agent) {
+        this.agent = agent;
+    }
+    getAgent() {
+        return this.agent;
+    }
+    deleteAgent() {
+        this.agent = null;
+    }
+    setWorker(worker) {
+        this.workers.set(worker.workerId, worker);
+    }
+    getWorker(workerId) {
+        return this.workers.get(workerId);
+    }
+    deleteWorker(workerId) {
+        this.workers.delete(workerId);
+    }
+    listWorkerIds() {
+        return Array.from(this.workers.keys());
+    }
+    listWorkers() {
+        return Array.from(this.workers.values());
+    }
+    getListeningWorkerIds() {
+        const keys = [];
+        for (const [id, worker] of this.workers.entries()) {
+            if (worker.state === 'listening') {
+                keys.push(id);
+            }
+        }
+        return keys;
+    }
+    count() {
+        return {
+            agent: this.agent?.status === 'started' ? 1 : 0,
+            worker: this.listWorkerIds().length,
+        };
+    }
+    // check agent and worker must both alive
+    // if exception appear 3 times, emit an exception event
+    startCheck() {
+        this.timer = setInterval(() => {
+            const count = this.count();
+            if (count.agent > 0 && count.worker > 0) {
+                this.exception = 0;
+                return;
+            }
+            this.exception++;
+            if (this.exception >= 3) {
+                this.emit('exception', count);
+                clearInterval(this.timer);
+            }
+        }, 10000);
+    }
+}
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoid29ya2VyX21hbmFnZXIuanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi8uLi9zcmMvdXRpbHMvd29ya2VyX21hbmFnZXIudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6IkFBQUEsT0FBTyxFQUFFLFlBQVksRUFBRSxNQUFNLGFBQWEsQ0FBQztBQUkzQyxrRUFBa0U7QUFDbEUsc0RBQXNEO0FBQ3RELE1BQU0sT0FBTyxhQUFjLFNBQVEsWUFBWTtJQUM3QyxLQUFLLENBQXlCO0lBQzlCLE9BQU8sR0FBRyxJQUFJLEdBQUcsRUFBeUIsQ0FBQztJQUMzQyxTQUFTLEdBQUcsQ0FBQyxDQUFDO0lBQ2QsS0FBSyxDQUFpQjtJQUV0QjtRQUNFLEtBQUssRUFBRSxDQUFDO1FBQ1IsSUFBSSxDQUFDLEtBQUssR0FBRyxJQUFJLENBQUM7SUFDcEIsQ0FBQztJQUVELFVBQVU7UUFDUixPQUFPLEtBQUssQ0FBQyxJQUFJLENBQUMsSUFBSSxDQUFDLE9BQU8sQ0FBQyxJQUFJLEVBQUUsQ0FBQyxDQUFDO0lBQ3pDLENBQUM7SUFFRCxRQUFRLENBQUMsS0FBc0I7UUFDN0IsSUFBSSxDQUFDLEtBQUssR0FBRyxLQUFLLENBQUM7SUFDckIsQ0FBQztJQUVELFFBQVE7UUFDTixPQUFPLElBQUksQ0FBQyxLQUFLLENBQUM7SUFDcEIsQ0FBQztJQUVELFdBQVc7UUFDVCxJQUFJLENBQUMsS0FBSyxHQUFHLElBQUksQ0FBQztJQUNwQixDQUFDO0lBRUQsU0FBUyxDQUFDLE1BQXFCO1FBQzdCLElBQUksQ0FBQyxPQUFPLENBQUMsR0FBRyxDQUFDLE1BQU0sQ0FBQyxRQUFRLEVBQUUsTUFBTSxDQUFDLENBQUM7SUFDNUMsQ0FBQztJQUVELFNBQVMsQ0FBQyxRQUFnQjtRQUN4QixPQUFPLElBQUksQ0FBQyxPQUFPLENBQUMsR0FBRyxDQUFDLFFBQVEsQ0FBQyxDQUFDO0lBQ3BDLENBQUM7SUFFRCxZQUFZLENBQUMsUUFBZ0I7UUFDM0IsSUFBSSxDQUFDLE9BQU8sQ0FBQyxNQUFNLENBQUMsUUFBUSxDQUFDLENBQUM7SUFDaEMsQ0FBQztJQUVELGFBQWE7UUFDWCxPQUFPLEtBQUssQ0FBQyxJQUFJLENBQUMsSUFBSSxDQUFDLE9BQU8sQ0FBQyxJQUFJLEVBQUUsQ0FBQyxDQUFDO0lBQ3pDLENBQUM7SUFFRCxXQUFXO1FBQ1QsT0FBTyxLQUFLLENBQUMsSUFBSSxDQUFDLElBQUksQ0FBQyxPQUFPLENBQUMsTUFBTSxFQUFFLENBQUMsQ0FBQztJQUMzQyxDQUFDO0lBRUQscUJBQXFCO1FBQ25CLE1BQU0sSUFBSSxHQUFHLEVBQUUsQ0FBQztRQUNoQixLQUFLLE1BQU0sQ0FBRSxFQUFFLEVBQUUsTUFBTSxDQUFFLElBQUksSUFBSSxDQUFDLE9BQU8sQ0FBQyxPQUFPLEVBQUUsRUFBRSxDQUFDO1lBQ3BELElBQUksTUFBTSxDQUFDLEtBQUssS0FBSyxXQUFXLEVBQUUsQ0FBQztnQkFDakMsSUFBSSxDQUFDLElBQUksQ0FBQyxFQUFFLENBQUMsQ0FBQztZQUNoQixDQUFDO1FBQ0gsQ0FBQztRQUNELE9BQU8sSUFBSSxDQUFDO0lBQ2QsQ0FBQztJQUVELEtBQUs7UUFDSCxPQUFPO1lBQ0wsS0FBSyxFQUFFLElBQUksQ0FBQyxLQUFLLEVBQUUsTUFBTSxLQUFLLFNBQVMsQ0FBQyxDQUFDLENBQUMsQ0FBQyxDQUFDLENBQUMsQ0FBQyxDQUFDO1lBQy9DLE1BQU0sRUFBRSxJQUFJLENBQUMsYUFBYSxFQUFFLENBQUMsTUFBTTtTQUNwQyxDQUFDO0lBQ0osQ0FBQztJQUVELHlDQUF5QztJQUN6Qyx1REFBdUQ7SUFDdkQsVUFBVTtRQUNSLElBQUksQ0FBQyxLQUFLLEdBQUcsV0FBVyxDQUFDLEdBQUcsRUFBRTtZQUM1QixNQUFNLEtBQUssR0FBRyxJQUFJLENBQUMsS0FBSyxFQUFFLENBQUM7WUFDM0IsSUFBSSxLQUFLLENBQUMsS0FBSyxHQUFHLENBQUMsSUFBSSxLQUFLLENBQUMsTUFBTSxHQUFHLENBQUMsRUFBRSxDQUFDO2dCQUN4QyxJQUFJLENBQUMsU0FBUyxHQUFHLENBQUMsQ0FBQztnQkFDbkIsT0FBTztZQUNULENBQUM7WUFDRCxJQUFJLENBQUMsU0FBUyxFQUFFLENBQUM7WUFDakIsSUFBSSxJQUFJLENBQUMsU0FBUyxJQUFJLENBQUMsRUFBRSxDQUFDO2dCQUN4QixJQUFJLENBQUMsSUFBSSxDQUFDLFdBQVcsRUFBRSxLQUFLLENBQUMsQ0FBQztnQkFDOUIsYUFBYSxDQUFDLElBQUksQ0FBQyxLQUFLLENBQUMsQ0FBQztZQUM1QixDQUFDO1FBQ0gsQ0FBQyxFQUFFLEtBQUssQ0FBQyxDQUFDO0lBQ1osQ0FBQztDQUNGIn0=

package/dist/package.json

@@ -0,0 +1,4 @@
+{
+  "name": "@eggjs/cluster",
+  "version": "3.0.0-beta.0"
+}

package/package.json

@@ -0,0 +1,94 @@
+{
+  "name": "@eggjs/cluster",
+  "version": "3.0.0-beta.0",
+  "publishConfig": {
+    "access": "public"
+  },
+  "description": "cluster manager for egg",
+  "main": "./dist/commonjs/index.js",
+  "scripts": {
+    "lint": "eslint --cache src test --ext .ts",
+    "pretest": "npm run lint -- --fix && npm run prepublishOnly",
+    "test": "egg-bin test",
+    "preci": "npm run lint && npm run prepublishOnly",
+    "ci": "egg-bin cov && attw --pack",
+    "prepublishOnly": "tshy && tshy-after"
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/eggjs/egg-cluster.git"
+  },
+  "keywords": [
+    "egg",
+    "cluster",
+    "process"
+  ],
+  "author": "dead-horse <dead_horse@qq.com>",
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/eggjs/egg-cluster/issues"
+  },
+  "homepage": "https://github.com/eggjs/egg-cluster#readme",
+  "dependencies": {
+    "@eggjs/utils": "^4.0.2",
+    "@fengmk2/ps-tree": "^2.0.1",
+    "cfork": "^2.0.0",
+    "cluster-reload": "^2.0.0",
+    "detect-port": "^2.0.1",
+    "egg-logger": "^3.6.0",
+    "get-ready": "^3.2.0",
+    "graceful-process": "^2.0.0",
+    "sendmessage": "^3.0.1",
+    "terminal-link": "^2.1.1",
+    "utility": "^2.2.0"
+  },
+  "devDependencies": {
+    "@arethetypeswrong/cli": "^0.17.1",
+    "@eggjs/tsconfig": "1",
+    "@types/mocha": "10",
+    "@types/node": "22",
+    "address": "^2.0.3",
+    "coffee": "^5.5.1",
+    "egg": "beta",
+    "egg-bin": "6",
+    "egg-errors": "^2.2.0",
+    "egg-mock": "beta",
+    "eslint": "8",
+    "eslint-config-egg": "14",
+    "supertest": "^7.0.0",
+    "ts-node": "^10.9.1",
+    "tshy": "3",
+    "tshy-after": "1",
+    "typescript": "5",
+    "urllib": "^4.6.8"
+  },
+  "engines": {
+    "node": ">= 18.19.0"
+  },
+  "type": "module",
+  "tshy": {
+    "exports": {
+      ".": "./src/index.ts",
+      "./package.json": "./package.json"
+    }
+  },
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/esm/index.d.ts",
+        "default": "./dist/esm/index.js"
+      },
+      "require": {
+        "types": "./dist/commonjs/index.d.ts",
+        "default": "./dist/commonjs/index.js"
+      }
+    },
+    "./package.json": "./package.json"
+  },
+  "types": "./dist/commonjs/index.d.ts",
+  "module": "./dist/esm/index.js"
+}

package/src/agent_worker.ts

@@ -0,0 +1,75 @@
+import { debuglog } from 'node:util';
+import { EggConsoleLogger as ConsoleLogger } from 'egg-logger';
+import { importModule } from '@eggjs/utils';
+import { BaseAgentWorker } from './utils/mode/base/agent.js';
+import { AgentThreadWorker } from './utils/mode/impl/worker_threads/agent.js';
+import { AgentProcessWorker } from './utils/mode/impl/process/agent.js';
+
+const debug = debuglog('@eggjs/cluster/agent_worker');
+
+/**
+ * agent worker is child_process forked by master.
+ *
+ * agent worker only exit in two cases:
+ *  - receive signal SIGTERM, exit code 0 (exit gracefully)
+ *  - receive disconnect event, exit code 110 (maybe master exit in accident)
+ */
+async function main() {
+  // $ node agent_worker.js options
+  const options = JSON.parse(process.argv[2]) as {
+    framework: string;
+    require?: string[];
+    startMode?: 'process' | 'worker_threads';
+  };
+  if (options.require) {
+    // inject
+    options.require.forEach(mod => {
+      require(mod);
+    });
+  }
+
+  let AgentWorker: typeof BaseAgentWorker;
+  if (options.startMode === 'worker_threads') {
+    AgentWorker = AgentThreadWorker as any;
+  } else {
+    AgentWorker = AgentProcessWorker as any;
+  }
+
+  const consoleLogger = new ConsoleLogger({ level: process.env.EGG_AGENT_WORKER_LOGGER_LEVEL });
+  const { Agent } = await importModule(options.framework);
+  debug('new Agent with options %j', options);
+  let agent: any;
+  try {
+    agent = new Agent(options);
+  } catch (err) {
+    consoleLogger.error(err);
+    throw err;
+  }
+
+  function startErrorHandler(err: Error) {
+    consoleLogger.error(err);
+    consoleLogger.error('[agent_worker] start error, exiting with code:1');
+    AgentWorker.kill();
+  }
+
+  agent.ready((err?: Error) => {
+    // don't send started message to master when start error
+    if (err) {
+      return;
+    }
+
+    agent.removeListener('error', startErrorHandler);
+    AgentWorker.send({ action: 'agent-start', to: 'master' });
+  });
+
+  // exit if agent start error
+  agent.once('error', startErrorHandler);
+
+  AgentWorker.gracefulExit({
+    logger: consoleLogger,
+    label: 'agent_worker',
+    beforeExit: () => agent.close(),
+  });
+}
+
+main();

package/src/app_worker.ts

@@ -0,0 +1,170 @@
+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 { debuglog } from 'node:util';
+import { EggConsoleLogger as ConsoleLogger } from 'egg-logger';
+import { importModule } from '@eggjs/utils';
+import { BaseAppWorker } from './utils/mode/base/app.js';
+import { AppThreadWorker } from './utils/mode/impl/worker_threads/app.js';
+import { AppProcessWorker } from './utils/mode/impl/process/app.js';
+
+const debug = debuglog('@eggjs/cluster/app_worker');
+
+async function main() {
+  // $ node app_worker.js options-json-string
+  const options = JSON.parse(process.argv[2]) as {
+    framework: string;
+    require?: string[];
+    startMode?: 'process' | 'worker_threads';
+    port?: number;
+    debugPort?: number;
+    https?: object;
+    sticky?: boolean;
+    stickyWorkerPort?: number;
+  };
+  if (options.require) {
+    // inject
+    for (const mod of options.require) {
+      await importModule(mod);
+    }
+  }
+
+  let AppWorker: typeof BaseAppWorker;
+  if (options.startMode === 'worker_threads') {
+    AppWorker = AppThreadWorker as any;
+  } else {
+    AppWorker = AppProcessWorker as any;
+  }
+
+  const consoleLogger = new ConsoleLogger({
+    level: process.env.EGG_APP_WORKER_LOGGER_LEVEL,
+  });
+  const { Application } = await importModule(options.framework);
+  debug('new Application with options %j', options);
+  let app: any;
+  try {
+    app = new Application(options);
+  } catch (err) {
+    consoleLogger.error(err);
+    throw err;
+  }
+
+  app.ready(startServer);
+
+  function exitProcess() {
+    // Use SIGTERM kill process, ensure trigger the gracefulExit
+    AppWorker.kill();
+  }
+
+  // exit if worker start timeout
+  app.once('startTimeout', startTimeoutHandler);
+
+  function startTimeoutHandler() {
+    consoleLogger.error('[app_worker] start timeout, exiting with code:1');
+    exitProcess();
+  }
+
+  function startServer(err?: Error) {
+    if (err) {
+      consoleLogger.error(err);
+      consoleLogger.error('[app_worker] start error, exiting with code:1');
+      exitProcess();
+      return;
+    }
+
+    const clusterConfig = app.config.cluster ?? {};
+    const listenConfig = clusterConfig.listen ?? {};
+    const httpsOptions = {
+      ...clusterConfig.https,
+      ...options.https,
+    };
+    const port = options.port = options.port ?? listenConfig.port;
+    const debugPort = options.debugPort;
+    const protocol = (httpsOptions.key && httpsOptions.cert) ? 'https' : 'http';
+
+    AppWorker.send({
+      to: 'master',
+      action: 'realport',
+      data: {
+        port,
+        protocol,
+      },
+    });
+
+    app.removeListener('startTimeout', startTimeoutHandler);
+
+    let server: Server;
+    let debugPortServer: Server | undefined;
+
+    // https config
+    if (protocol === 'https') {
+      httpsOptions.key = fs.readFileSync(httpsOptions.key);
+      httpsOptions.cert = fs.readFileSync(httpsOptions.cert);
+      httpsOptions.ca = httpsOptions.ca && fs.readFileSync(httpsOptions.ca);
+      server = createHttpsServer(httpsOptions, app.callback());
+      if (debugPort) {
+        debugPortServer = createHttpServer(app.callback());
+      }
+    } else {
+      server = createHttpServer(app.callback());
+      if (debugPort) {
+        debugPortServer = server;
+      }
+    }
+
+    server.once('error', (err: any) => {
+      consoleLogger.error('[app_worker] server got error: %s, code: %s', err.message, err.code);
+      exitProcess();
+    });
+
+    // emit `server` event in app
+    app.emit('server', server);
+
+    if (options.sticky && options.stickyWorkerPort) {
+      server.listen(options.stickyWorkerPort, '127.0.0.1');
+      // Listen to messages was sent from the master. Ignore everything else.
+      AppWorker.on('message', (message: string, connection: Socket) => {
+        if (message !== 'sticky-session:connection') {
+          return;
+        }
+        // Emulate a connection event on the server by emitting the
+        // event with the connection the master sent us.
+        server.emit('connection', connection);
+        connection.resume();
+      });
+    } else {
+      if (listenConfig.path) {
+        server.listen(listenConfig.path);
+      } else {
+        if (typeof port !== 'number') {
+          consoleLogger.error('[app_worker] port should be number, but got %s(%s)', port, typeof port);
+          exitProcess();
+          return;
+        }
+        const args = [ port ];
+        if (listenConfig.hostname) args.push(listenConfig.hostname);
+        debug('listen options %s', args);
+        server.listen(...args);
+      }
+      if (debugPortServer) {
+        debug('listen on debug port: %s', debugPort);
+        debugPortServer.listen(debugPort);
+      }
+    }
+
+    AppWorker.send({
+      to: 'master',
+      action: 'listening',
+      data: server.address() || { port },
+    });
+  }
+
+  AppWorker.gracefulExit({
+    logger: consoleLogger,
+    label: 'app_worker',
+    beforeExit: () => app.close(),
+  });
+}
+
+main();

package/src/dirname.ts

@@ -0,0 +1,11 @@
+import { fileURLToPath } from 'node:url';
+import path from 'node:path';
+
+export function getSrcDirname() {
+  if (typeof __dirname !== 'undefined') {
+    return __dirname;
+  }
+  // eslint-disable-next-line @typescript-eslint/ban-ts-comment
+  // @ts-ignore
+  return path.dirname(fileURLToPath(import.meta.url));
+}

package/src/error/ClusterAgentWorkerError.ts

@@ -0,0 +1,19 @@
+export class ClusterAgentWorkerError extends Error {
+  id: number;
+  /**
+   * pid in process mode
+   * tid in worker_threads mode
+   */
+  workerId: number;
+  status: string;
+
+  constructor(id: number, workerId: number, status: string, error: Error) {
+    const message = `Got agent worker error: ${error.message}`;
+    super(message, { cause: error });
+    this.name = this.constructor.name;
+    this.id = id;
+    this.workerId = workerId;
+    this.status = status;
+    Error.captureStackTrace(this, this.constructor);
+  }
+}

package/src/error/ClusterWorkerExceptionError.ts

@@ -0,0 +1,17 @@
+export class ClusterWorkerExceptionError extends Error {
+  count: {
+    agent: number;
+    worker: number;
+  };
+
+  constructor(agent: number, worker: number) {
+    const message = `[master] ${agent} agent and ${worker} worker(s) alive, exit to avoid unknown state`;
+    super(message);
+    this.name = this.constructor.name;
+    this.count = {
+      agent,
+      worker,
+    };
+    Error.captureStackTrace(this, this.constructor);
+  }
+}

package/src/error/index.ts

@@ -0,0 +1,2 @@
+export * from './ClusterAgentWorkerError.js';
+export * from './ClusterWorkerExceptionError.js';

package/src/index.ts

@@ -0,0 +1,26 @@
+import { Master, MasterOptions } from './master.js';
+import { ClusterOptions, ClusterHTTPSSecureOptions, ClusterStartMode } from './utils/options.js';
+
+/**
+ * cluster start flow:
+ *
+ * [startCluster] -> master -> agent_worker -> new [Agent]       -> agentWorkerLoader
+ *                         `-> app_worker   -> new [Application] -> appWorkerLoader
+ *
+ */
+
+/**
+ * start egg app
+ * @function Egg#startCluster
+ * @param {Object} options {@link Master}
+ */
+export async function startCluster(options: ClusterOptions) {
+  await new Master(options).ready();
+}
+
+export {
+  Master, MasterOptions,
+  ClusterOptions, ClusterHTTPSSecureOptions, ClusterStartMode,
+};
+
+export * from './error/index.js';