@eggjs/cluster 4.0.2-beta.25 → 4.0.2-beta.27

package/dist/agent_worker.js

@@ -1,5 +1,6 @@
-import { AgentProcessWorker } from "./utils/mode/impl/process/agent.js";
-import { AgentThreadWorker } from "./utils/mode/impl/worker_threads/agent.js";
+import { startAgentWorker } from "./worker_protocol/agent.js";
+import { createProcessWorkerIO } from "./worker_protocol/process.js";
+import { createWorkerThreadIO } from "./worker_protocol/worker-thread.js";
 import { debuglog } from "node:util";
 import { EggConsoleLogger } from "egg-logger";
 import { importModule } from "@eggjs/utils";
@@ -16,9 +17,7 @@ const debug = debuglog("egg/cluster/agent_worker");
 async function main() {
 	const options = JSON.parse(process.argv[2]);
 	if (options.require) for (const mod of options.require) await importModule(mod, { paths: [options.baseDir] });
-	let AgentWorker;
-	if (options.startMode === "worker_threads") AgentWorker = AgentThreadWorker;
-	else AgentWorker = AgentProcessWorker;
+	const workerIO = options.startMode === "worker_threads" ? createWorkerThreadIO() : createProcessWorkerIO();
 	const consoleLogger = new EggConsoleLogger({ level: process.env.EGG_AGENT_WORKER_LOGGER_LEVEL });
 	const { Agent } = await importModule(options.framework, { paths: [options.baseDir] });
 	debug("new Agent with options %j", options);
@@ -29,25 +28,7 @@ async function main() {
 		consoleLogger.error(err);
 		throw err;
 	}
-	function startErrorHandler(err) {
-		consoleLogger.error(err);
-		consoleLogger.error("[agent_worker] start error, exiting with code:1");
-		AgentWorker.kill();
-	}
-	agent.ready((err) => {
-		if (err) return;
-		agent.removeListener("error", startErrorHandler);
-		AgentWorker.send({
-			action: "agent-start",
-			to: "master"
-		});
-	});
-	agent.once("error", startErrorHandler);
-	AgentWorker.gracefulExit({
-		logger: consoleLogger,
-		label: "agent_worker",
-		beforeExit: () => agent.close()
-	});
+	startAgentWorker(agent, workerIO, consoleLogger);
 }
 main();
 

package/dist/app_worker.js

@@ -1,27 +1,16 @@
-import { AppProcessWorker } from "./utils/mode/impl/process/app.js";
-import { AppThreadWorker } from "./utils/mode/impl/worker_threads/app.js";
-import fs from "node:fs";
-import os from "node:os";
+import { createProcessWorkerIO } from "./worker_protocol/process.js";
+import { createWorkerThreadIO } from "./worker_protocol/worker-thread.js";
+import { startAppWorker } from "./worker_protocol/app.js";
 import { debuglog } from "node:util";
 import { EggConsoleLogger } from "egg-logger";
 import { importModule } from "@eggjs/utils";
-import { createServer } from "node:http";
-import { createServer as createServer$1 } from "node:https";
 
 //#region src/app_worker.ts
 const debug = debuglog("egg/cluster/app_worker");
-const REUSE_PORT_SUPPORTED_PLATFORMS = [
-	"linux",
-	"freebsd",
-	"sunos",
-	"aix"
-];
 async function main() {
 	const options = JSON.parse(process.argv[2]);
 	if (options.require) for (const mod of options.require) await importModule(mod, { paths: [options.baseDir] });
-	let AppWorker;
-	if (options.startMode === "worker_threads") AppWorker = AppThreadWorker;
-	else AppWorker = AppProcessWorker;
+	const workerIO = options.startMode === "worker_threads" ? createWorkerThreadIO() : createProcessWorkerIO();
 	const consoleLogger = new EggConsoleLogger({ level: process.env.EGG_APP_WORKER_LOGGER_LEVEL });
 	const { Application } = await importModule(options.framework, { paths: [options.baseDir] });
 	debug("[app_worker:%s] new Application with options %j", process.pid, options);
@@ -32,121 +21,7 @@ async function main() {
 		consoleLogger.error(err);
 		throw err;
 	}
-	app.ready(startServer);
-	function exitProcess() {
-		AppWorker.kill();
-	}
-	app.once("startTimeout", startTimeoutHandler);
-	function startTimeoutHandler() {
-		consoleLogger.error("[app_worker] start timeout, exiting with code:1");
-		exitProcess();
-	}
-	function startServer(err) {
-		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 = app.options.port = options.port || listenConfig.port;
-		const debugPort = options.debugPort;
-		const protocol = httpsOptions.key && httpsOptions.cert ? "https" : "http";
-		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, reusePort: %o", process.pid, listenConfig, port, protocol, debugPort, reusePort);
-		AppWorker.send({
-			to: "master",
-			action: "realport",
-			data: {
-				port,
-				protocol
-			}
-		});
-		app.removeListener("startTimeout", startTimeoutHandler);
-		let server;
-		let debugPortServer;
-		if (protocol === "https") {
-			httpsOptions.key = fs.readFileSync(httpsOptions.key);
-			httpsOptions.cert = fs.readFileSync(httpsOptions.cert);
-			httpsOptions.ca = httpsOptions.ca && fs.readFileSync(httpsOptions.ca);
-			server = createServer$1(httpsOptions, app.callback());
-			if (debugPort) debugPortServer = createServer(app.callback());
-		} else {
-			server = createServer(app.callback());
-			if (debugPort) debugPortServer = server;
-		}
-		server.once("error", (err$1) => {
-			consoleLogger.error("[app_worker] server got error: %s, code: %s", err$1.message, err$1.code);
-			exitProcess();
-		});
-		app.emit("server", server);
-		if (options.sticky && options.stickyWorkerPort) {
-			server.listen(options.stickyWorkerPort, "127.0.0.1");
-			AppWorker.on("message", (message, connection) => {
-				if (message !== "sticky-session:connection") return;
-				server.emit("connection", connection);
-				connection.resume();
-			});
-		} else {
-			if (listenConfig.path) server.listen(listenConfig.path);
-			else {
-				if (typeof port !== "number") {
-					consoleLogger.error("[app_worker:%s] port should be number, but got %s(%s)", process.pid, port, typeof port);
-					exitProcess();
-					return;
-				}
-				if (reusePort) {
-					const 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);
-				}
-			}
-			if (debugPortServer) {
-				debug("listen on debug port: %s", debugPort);
-				debugPortServer.listen(debugPort);
-			}
-		}
-		server.once("listening", () => {
-			let address = server.address() || { port };
-			if (typeof address === "string") address = {
-				address,
-				addressType: -1
-			};
-			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
-			});
-		});
-	}
-	AppWorker.gracefulExit({
-		logger: consoleLogger,
-		label: "app_worker",
-		beforeExit: () => app.close()
-	});
+	startAppWorker(app, options, workerIO, consoleLogger);
 }
 main();
 

package/dist/utils/mode/impl/process/agent.d.ts

@@ -1,15 +1,11 @@
 import { BaseAgentUtils, BaseAgentWorker } from "../../base/agent.js";
 import { MessageBody } from "../../../messenger.js";
 import { ChildProcess } from "node:child_process";
-import { Options } from "graceful-process";
 
 //#region src/utils/mode/impl/process/agent.d.ts
 declare class AgentProcessWorker extends BaseAgentWorker<ChildProcess> {
   get workerId(): number;
   send(message: MessageBody): void;
-  static send(message: MessageBody): void;
-  static kill(): void;
-  static gracefulExit(options: Options): void;
 }
 declare class AgentProcessUtils extends BaseAgentUtils {
   #private;

package/dist/utils/mode/impl/process/agent.js

@@ -3,7 +3,6 @@ import { terminate } from "../../../terminate.js";
 import { BaseAgentUtils, BaseAgentWorker } from "../../base/agent.js";
 import { debuglog } from "node:util";
 import { fork } from "node:child_process";
-import { graceful } from "graceful-process";
 import { sendmessage } from "sendmessage";
 
 //#region src/utils/mode/impl/process/agent.ts
@@ -15,17 +14,6 @@ var AgentProcessWorker = class extends BaseAgentWorker {
 	send(message) {
 		sendmessage(this.instance, message);
 	}
-	static send(message) {
-		message.senderWorkerId = String(process.pid);
-		process.send(message);
-	}
-	static kill() {
-		process.exitCode = 1;
-		process.kill(process.pid);
-	}
-	static gracefulExit(options) {
-		graceful(options);
-	}
 };
 var AgentProcessUtils = class extends BaseAgentUtils {
 	#agentProcess;
@@ -38,8 +26,13 @@ var AgentProcessUtils = class extends BaseAgentUtils {
 		if (process.platform === "win32") forkOptions.windowsHide = true;
 		const debugPort = process.env.EGG_AGENT_DEBUG_PORT ?? 5800;
 		if (this.options.isDebug) forkOptions.execArgv = process.execArgv.concat([`--inspect-port=${debugPort}`]);
+		if (this.options.agentSnapshotBlob) forkOptions.execArgv = [
+			...forkOptions.execArgv ?? process.execArgv,
+			"--snapshot-blob",
+			this.options.agentSnapshotBlob
+		];
 		debug("forkOptions: %j, args: %s", forkOptions, args);
-		const agentProcess = this.#agentProcess = fork(this.getAgentWorkerFile(), args, forkOptions);
+		const agentProcess = this.#agentProcess = fork(this.options.agentWorkerFile || this.getAgentWorkerFile(), args, forkOptions);
 		const agentWorker = this.instance = new AgentProcessWorker(agentProcess);
 		agentWorker.status = "starting";
 		agentWorker.id = ++this.#id;
@@ -93,4 +86,4 @@ var AgentProcessUtils = class extends BaseAgentUtils {
 };
 
 //#endregion
-export { AgentProcessUtils, AgentProcessWorker };
+export { AgentProcessUtils };

package/dist/utils/mode/impl/process/app.d.ts

@@ -1,6 +1,5 @@
 import { BaseAppUtils, BaseAppWorker } from "../../base/app.js";
 import { MessageBody } from "../../../messenger.js";
-import { Options } from "graceful-process";
 import { Worker } from "node:cluster";
 
 //#region src/utils/mode/impl/process/app.d.ts
@@ -11,11 +10,6 @@ declare class AppProcessWorker extends BaseAppWorker<Worker> {
   get exitCode(): number;
   send(message: MessageBody): void;
   clean(): void;
-  static get workerId(): number;
-  static on(event: string, listener: (...args: any[]) => void): void;
-  static send(message: MessageBody): void;
-  static kill(): void;
-  static gracefulExit(options: Options): void;
 }
 declare class AppProcessUtils extends BaseAppUtils {
   fork(): this;

package/dist/utils/mode/impl/process/app.js

@@ -1,13 +1,10 @@
 import { terminate } from "../../../terminate.js";
 import { BaseAppUtils, BaseAppWorker } from "../../base/app.js";
-import { debuglog } from "node:util";
-import { graceful } from "graceful-process";
 import { sendmessage } from "sendmessage";
 import cluster from "node:cluster";
 import { cfork } from "cfork";
 
 //#region src/utils/mode/impl/process/app.ts
-const debug = debuglog("egg/cluster/utils/mode/impl/process/app");
 var AppProcessWorker = class extends BaseAppWorker {
 	get id() {
 		return this.instance.id;
@@ -27,28 +24,6 @@ var AppProcessWorker = class extends BaseAppWorker {
 	clean() {
 		this.instance.removeAllListeners();
 	}
-	static get workerId() {
-		return process.pid;
-	}
-	static on(event, listener) {
-		process.on(event, listener);
-	}
-	static send(message) {
-		message.senderWorkerId = String(process.pid);
-		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);
-	}
-	static kill() {
-		process.exitCode = 1;
-		process.kill(process.pid);
-	}
-	static gracefulExit(options) {
-		graceful(options);
-	}
 };
 var AppProcessUtils = class extends BaseAppUtils {
 	fork() {
@@ -56,8 +31,14 @@ var AppProcessUtils = class extends BaseAppUtils {
 		this.startSuccessCount = 0;
 		const args = [JSON.stringify(this.options)];
 		this.log("[master] start appWorker with args %j (process)", args);
+		const execArgv = this.options.appSnapshotBlob ? [
+			...process.execArgv,
+			"--snapshot-blob",
+			this.options.appSnapshotBlob
+		] : void 0;
 		cfork({
-			exec: this.getAppWorkerFile(),
+			exec: this.options.appWorkerFile || this.getAppWorkerFile(),
+			...execArgv ? { execArgv } : {},
 			args,
 			silent: false,
 			count: this.options.workers,
@@ -121,4 +102,4 @@ var AppProcessUtils = class extends BaseAppUtils {
 };
 
 //#endregion
-export { AppProcessUtils, AppProcessWorker };
+export { AppProcessUtils };

package/dist/utils/mode/impl/worker_threads/agent.d.ts

@@ -1,15 +1,11 @@
 import { BaseAgentUtils, BaseAgentWorker } from "../../base/agent.js";
 import { MessageBody } from "../../../messenger.js";
 import { Worker } from "node:worker_threads";
-import { Options } from "graceful-process";
 
 //#region src/utils/mode/impl/worker_threads/agent.d.ts
 declare class AgentThreadWorker extends BaseAgentWorker<Worker> {
   get workerId(): number;
   send(message: MessageBody): void;
-  static send(message: MessageBody): void;
-  static kill(): void;
-  static gracefulExit(options: Options): void;
 }
 declare class AgentThreadUtils extends BaseAgentUtils {
   #private;

package/dist/utils/mode/impl/worker_threads/agent.js

@@ -1,7 +1,6 @@
 import { ClusterAgentWorkerError } from "../../../../error/ClusterAgentWorkerError.js";
 import { BaseAgentUtils, BaseAgentWorker } from "../../base/agent.js";
 import workerThreads from "node:worker_threads";
-import "graceful-process";
 
 //#region src/utils/mode/impl/worker_threads/agent.ts
 var AgentThreadWorker = class extends BaseAgentWorker {
@@ -11,20 +10,6 @@ var AgentThreadWorker = class extends BaseAgentWorker {
 	send(message) {
 		this.instance.postMessage(message);
 	}
-	static send(message) {
-		message.senderWorkerId = String(workerThreads.threadId);
-		workerThreads.parentPort.postMessage(message);
-	}
-	static kill() {
-		process.exit(1);
-	}
-	static gracefulExit(options) {
-		const { beforeExit } = options;
-		process.on("exit", async (code) => {
-			if (typeof beforeExit === "function") await beforeExit();
-			process.exit(code);
-		});
-	}
 };
 var AgentThreadUtils = class extends BaseAgentUtils {
 	#worker;
@@ -33,7 +18,7 @@ var AgentThreadUtils = class extends BaseAgentUtils {
 	fork() {
 		this.startTime = Date.now();
 		const argv = [JSON.stringify(this.options)];
-		const agentPath = this.getAgentWorkerFile();
+		const agentPath = this.options.agentWorkerFile || this.getAgentWorkerFile();
 		const worker = this.#worker = new workerThreads.Worker(agentPath, { argv });
 		const agentWorker = this.instance = new AgentThreadWorker(worker);
 		this.emit("agent_forked", agentWorker);
@@ -76,4 +61,4 @@ var AgentThreadUtils = class extends BaseAgentUtils {
 };
 
 //#endregion
-export { AgentThreadUtils, AgentThreadWorker };
+export { AgentThreadUtils };

package/dist/utils/mode/impl/worker_threads/app.d.ts

@@ -1,7 +1,6 @@
 import { BaseAppUtils, BaseAppWorker } from "../../base/app.js";
 import { MessageBody } from "../../../messenger.js";
 import { Worker } from "node:worker_threads";
-import { Options } from "graceful-process";
 
 //#region src/utils/mode/impl/worker_threads/app.d.ts
 declare class AppThreadWorker extends BaseAppWorker<Worker> {
@@ -15,11 +14,6 @@ declare class AppThreadWorker extends BaseAppWorker<Worker> {
   get exitCode(): number;
   send(message: MessageBody): void;
   clean(): void;
-  static get workerId(): number;
-  static on(event: string, listener: (...args: any[]) => void): void;
-  static send(message: MessageBody): void;
-  static kill(): void;
-  static gracefulExit(options: Options): void;
 }
 declare class AppThreadUtils extends BaseAppUtils {
   #private;

package/dist/utils/mode/impl/worker_threads/app.js

@@ -1,5 +1,5 @@
 import { BaseAppUtils, BaseAppWorker } from "../../base/app.js";
-import { Worker, parentPort, threadId } from "node:worker_threads";
+import { Worker } from "node:worker_threads";
 import { setTimeout } from "node:timers/promises";
 
 //#region src/utils/mode/impl/worker_threads/app.ts
@@ -34,25 +34,6 @@ var AppThreadWorker = class extends BaseAppWorker {
 	clean() {
 		this.instance.removeAllListeners();
 	}
-	static get workerId() {
-		return threadId;
-	}
-	static on(event, listener) {
-		parentPort.on(event, listener);
-	}
-	static send(message) {
-		message.senderWorkerId = String(threadId);
-		parentPort.postMessage(message);
-	}
-	static kill() {
-		process.exit(1);
-	}
-	static gracefulExit(options) {
-		process.on("exit", async (code) => {
-			if (typeof options.beforeExit === "function") await options.beforeExit();
-			process.exit(code);
-		});
-	}
 };
 var AppThreadUtils = class extends BaseAppUtils {
 	#workers = [];
@@ -103,11 +84,12 @@ var AppThreadUtils = class extends BaseAppUtils {
 	fork() {
 		this.startTime = Date.now();
 		this.startSuccessCount = 0;
+		const appWorkerFile = this.options.appWorkerFile || this.getAppWorkerFile();
 		if (this.options.reusePort) {
 			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);
+				this.#forkSingle(appWorkerFile, { argv }, i + 1);
 			}
 		} else {
 			const ports = this.options.ports ?? [];
@@ -117,7 +99,7 @@ var AppThreadUtils = class extends BaseAppUtils {
 			do {
 				const options = Object.assign({}, this.options, { port: ports[i] });
 				const argv = [JSON.stringify(options)];
-				this.#forkSingle(this.getAppWorkerFile(), { argv }, ++i);
+				this.#forkSingle(appWorkerFile, { argv }, ++i);
 			} while (i < ports.length);
 		}
 		return this;
@@ -133,4 +115,4 @@ var AppThreadUtils = class extends BaseAppUtils {
 };
 
 //#endregion
-export { AppThreadUtils, AppThreadWorker };
+export { AppThreadUtils };

package/dist/utils/options.d.ts

@@ -61,6 +61,22 @@ interface ClusterOptions {
   */
   startMode?: ClusterStartMode;
   /**
+  * custom app worker file
+  */
+  appWorkerFile?: string;
+  /**
+  * custom agent worker file
+  */
+  agentWorkerFile?: string;
+  /**
+  * V8 startup snapshot blob used to restore app workers, only available in process mode
+  */
+  appSnapshotBlob?: string;
+  /**
+  * V8 startup snapshot blob used to restore the agent worker, only available in process mode
+  */
+  agentSnapshotBlob?: string;
+  /**
   * startup port of each app worker, such as: `[7001, 7002, 7003]`, only effects when the startMode is `'worker_threads'`
   */
   ports?: number[];

package/dist/utils/options.js

@@ -46,6 +46,25 @@ async function parseOptions(options) {
 	if (options.require) {
 		if (typeof options.require === "string") options.require = [options.require];
 	}
+	for (const optionName of ["appWorkerFile", "agentWorkerFile"]) {
+		const workerFile = options[optionName];
+		if (!workerFile) {
+			options[optionName] = void 0;
+			continue;
+		}
+		options[optionName] = path.resolve(options.baseDir, workerFile);
+		assert(fs.existsSync(options[optionName]), `options.${optionName} file should exist: ${options[optionName]}`);
+	}
+	for (const optionName of ["appSnapshotBlob", "agentSnapshotBlob"]) {
+		const snapshotBlob = options[optionName];
+		if (!snapshotBlob) {
+			options[optionName] = void 0;
+			continue;
+		}
+		options[optionName] = path.resolve(options.baseDir, snapshotBlob);
+		assert(fs.existsSync(options[optionName]), `options.${optionName} file should exist: ${options[optionName]}`);
+		assert(options.startMode !== "worker_threads", `options.${optionName} only supports startMode "process"`);
+	}
 	if (process.env.NODE_ENV === "production") process.env.NO_DEPRECATION = "*";
 	const isDebug = process.execArgv.some((argv) => argv.includes("--debug") || argv.includes("--inspect"));
 	if (isDebug) options.isDebug = isDebug;

package/dist/worker_protocol/agent.d.ts

@@ -0,0 +1,23 @@
+import { MessageBody } from "../utils/messenger.js";
+import { EggConsoleLogger } from "egg-logger";
+import { Options } from "graceful-process";
+
+//#region src/worker_protocol/agent.d.ts
+
+/**
+* Transport used by the agent-worker protocol. Process and worker-thread
+* entries provide different implementations of this interface.
+*/
+interface AgentWorkerIO {
+  send(message: MessageBody): void;
+  kill(): void;
+  gracefulExit(options: Options): void;
+}
+/**
+* Run the agent-worker side of the Egg cluster protocol on an already
+* constructed agent: report `agent-start` on readiness, exit on start error,
+* and wire graceful exit.
+*/
+declare function startAgentWorker(agent: any, io: AgentWorkerIO, consoleLogger?: EggConsoleLogger): void;
+//#endregion
+export { AgentWorkerIO, startAgentWorker };

package/dist/worker_protocol/agent.js

@@ -0,0 +1,32 @@
+import { EggConsoleLogger } from "egg-logger";
+
+//#region src/worker_protocol/agent.ts
+/**
+* Run the agent-worker side of the Egg cluster protocol on an already
+* constructed agent: report `agent-start` on readiness, exit on start error,
+* and wire graceful exit.
+*/
+function startAgentWorker(agent, io, consoleLogger = new EggConsoleLogger({ level: process.env.EGG_AGENT_WORKER_LOGGER_LEVEL })) {
+	function startErrorHandler(err) {
+		consoleLogger.error(err);
+		consoleLogger.error("[agent_worker] start error, exiting with code:1");
+		io.kill();
+	}
+	agent.once("error", startErrorHandler);
+	agent.ready((err) => {
+		if (err) return;
+		agent.removeListener("error", startErrorHandler);
+		io.send({
+			action: "agent-start",
+			to: "master"
+		});
+	});
+	io.gracefulExit({
+		logger: consoleLogger,
+		label: "agent_worker",
+		beforeExit: () => agent.close()
+	});
+}
+
+//#endregion
+export { startAgentWorker };

package/dist/worker_protocol/app.d.ts

@@ -0,0 +1,30 @@
+import { AgentWorkerIO } from "./agent.js";
+import { EggConsoleLogger } from "egg-logger";
+
+//#region src/worker_protocol/app.d.ts
+
+/**
+* Transport used by the app-worker protocol. It extends the agent surface
+* with app-specific worker identity and sticky-session message handling.
+*/
+interface AppWorkerIO extends AgentWorkerIO {
+  readonly workerId: number | string;
+  on(event: string, listener: (...args: any[]) => void): void;
+}
+interface AppWorkerProtocolOptions {
+  port?: number;
+  debugPort?: number;
+  https?: object;
+  sticky?: boolean;
+  stickyWorkerPort?: number;
+  reusePort?: boolean;
+}
+/**
+* Run the app-worker side of the Egg cluster protocol on an already
+* constructed application: wait for readiness, create the HTTP(S) server
+* (sticky / reusePort / debug port variants), report `realport` and
+* `app-start` to the master, and wire graceful exit.
+*/
+declare function startAppWorker(app: any, options: AppWorkerProtocolOptions, io: AppWorkerIO, consoleLogger?: EggConsoleLogger): void;
+//#endregion
+export { AppWorkerIO, AppWorkerProtocolOptions, startAppWorker };

package/dist/worker_protocol/app.js

@@ -0,0 +1,141 @@
+import fs from "node:fs";
+import os from "node:os";
+import { debuglog } from "node:util";
+import { EggConsoleLogger } from "egg-logger";
+import { createServer } from "node:http";
+import { createServer as createServer$1 } from "node:https";
+
+//#region src/worker_protocol/app.ts
+const debug = debuglog("egg/cluster/worker_protocol/app");
+const REUSE_PORT_SUPPORTED_PLATFORMS = [
+	"linux",
+	"freebsd",
+	"sunos",
+	"aix"
+];
+/**
+* Run the app-worker side of the Egg cluster protocol on an already
+* constructed application: wait for readiness, create the HTTP(S) server
+* (sticky / reusePort / debug port variants), report `realport` and
+* `app-start` to the master, and wire graceful exit.
+*/
+function startAppWorker(app, options, io, consoleLogger = new EggConsoleLogger({ level: process.env.EGG_APP_WORKER_LOGGER_LEVEL })) {
+	function exitProcess() {
+		io.kill();
+	}
+	function startTimeoutHandler() {
+		consoleLogger.error("[app_worker] start timeout, exiting with code:1");
+		exitProcess();
+	}
+	app.once("startTimeout", startTimeoutHandler);
+	app.ready(startServer);
+	function startServer(err) {
+		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 = app.options.port = options.port || listenConfig.port;
+		const debugPort = options.debugPort;
+		const protocol = httpsOptions.key && httpsOptions.cert ? "https" : "http";
+		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, reusePort: %o", process.pid, listenConfig, port, protocol, debugPort, reusePort);
+		io.send({
+			to: "master",
+			action: "realport",
+			data: {
+				port,
+				protocol
+			}
+		});
+		app.removeListener("startTimeout", startTimeoutHandler);
+		let server;
+		let debugPortServer;
+		if (protocol === "https") {
+			httpsOptions.key = fs.readFileSync(httpsOptions.key);
+			httpsOptions.cert = fs.readFileSync(httpsOptions.cert);
+			httpsOptions.ca = httpsOptions.ca && fs.readFileSync(httpsOptions.ca);
+			server = createServer$1(httpsOptions, app.callback());
+			if (debugPort) debugPortServer = createServer(app.callback());
+		} else {
+			server = createServer(app.callback());
+			if (debugPort) debugPortServer = server;
+		}
+		server.once("error", (err$1) => {
+			consoleLogger.error("[app_worker] server got error: %s, code: %s", err$1.message, err$1.code);
+			exitProcess();
+		});
+		app.emit("server", server);
+		if (options.sticky && options.stickyWorkerPort) {
+			server.listen(options.stickyWorkerPort, "127.0.0.1");
+			io.on("message", (message, connection) => {
+				if (message !== "sticky-session:connection") return;
+				server.emit("connection", connection);
+				connection.resume();
+			});
+		} else {
+			if (listenConfig.path) server.listen(listenConfig.path);
+			else {
+				if (typeof port !== "number") {
+					consoleLogger.error("[app_worker:%s] port should be number, but got %s(%s)", process.pid, port, typeof port);
+					exitProcess();
+					return;
+				}
+				if (reusePort) {
+					const 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);
+				}
+			}
+			if (debugPortServer) {
+				debug("listen on debug port: %s", debugPort);
+				debugPortServer.listen(debugPort);
+			}
+		}
+		server.once("listening", () => {
+			let address = server.address() || { port };
+			if (typeof address === "string") address = {
+				address,
+				addressType: -1
+			};
+			debug("[app_worker:%s] listening at %j, reusePort: %o", process.pid, address, reusePort);
+			io.send({
+				to: "master",
+				action: "app-start",
+				data: {
+					address,
+					workerId: io.workerId
+				},
+				reusePort
+			});
+		});
+	}
+	io.gracefulExit({
+		logger: consoleLogger,
+		label: "app_worker",
+		beforeExit: () => app.close()
+	});
+}
+
+//#endregion
+export { startAppWorker };

package/dist/worker_protocol/process.d.ts

@@ -0,0 +1,14 @@
+import { AppWorkerIO } from "./app.js";
+
+//#region src/worker_protocol/process.d.ts
+
+/**
+* Process-backed worker transport shared by the traditional process entries
+* and the egg-bundler worker entry (plain boot or V8 snapshot restore).
+*
+* `node:cluster` is fetched only for the reusePort notification so snapshot
+* construction does not cache the build process's primary/worker flavor.
+*/
+declare function createProcessWorkerIO(): AppWorkerIO;
+//#endregion
+export { createProcessWorkerIO };

package/dist/worker_protocol/process.js

@@ -0,0 +1,38 @@
+import { graceful } from "graceful-process";
+
+//#region src/worker_protocol/process.ts
+/**
+* Process-backed worker transport shared by the traditional process entries
+* and the egg-bundler worker entry (plain boot or V8 snapshot restore).
+*
+* `node:cluster` is fetched only for the reusePort notification so snapshot
+* construction does not cache the build process's primary/worker flavor.
+*/
+function createProcessWorkerIO() {
+	return {
+		get workerId() {
+			return process.pid;
+		},
+		send(message) {
+			message.senderWorkerId = String(process.pid);
+			if (message.action === "app-start" && message.reusePort) {
+				process.getBuiltinModule("node:cluster").worker.send(message);
+				return;
+			}
+			process.send(message);
+		},
+		on(event, listener) {
+			process.on(event, listener);
+		},
+		kill() {
+			process.exitCode = 1;
+			process.kill(process.pid);
+		},
+		gracefulExit(options) {
+			graceful(options);
+		}
+	};
+}
+
+//#endregion
+export { createProcessWorkerIO };

package/dist/worker_protocol/worker-thread.d.ts

@@ -0,0 +1,11 @@
+import { AppWorkerIO } from "./app.js";
+
+//#region src/worker_protocol/worker-thread.d.ts
+
+/**
+* Worker-thread-backed transport shared by the standard worker entries and
+* generated bundle entries.
+*/
+declare function createWorkerThreadIO(): AppWorkerIO;
+//#endregion
+export { createWorkerThreadIO };

package/dist/worker_protocol/worker-thread.js

@@ -0,0 +1,34 @@
+import { parentPort, threadId } from "node:worker_threads";
+
+//#region src/worker_protocol/worker-thread.ts
+/**
+* Worker-thread-backed transport shared by the standard worker entries and
+* generated bundle entries.
+*/
+function createWorkerThreadIO() {
+	const port = parentPort;
+	if (!port) throw new Error("createWorkerThreadIO() must be called inside a worker thread");
+	return {
+		workerId: threadId,
+		send(message) {
+			message.senderWorkerId = String(threadId);
+			port.postMessage(message);
+		},
+		on(event, listener) {
+			port.on(event, listener);
+		},
+		kill() {
+			process.exit(1);
+		},
+		gracefulExit(options) {
+			const { beforeExit } = options;
+			process.on("exit", async (code) => {
+				if (typeof beforeExit === "function") await beforeExit();
+				process.exit(code);
+			});
+		}
+	};
+}
+
+//#endregion
+export { createWorkerThreadIO };

package/dist/worker_protocol.d.ts

@@ -0,0 +1,5 @@
+import { AgentWorkerIO, startAgentWorker } from "./worker_protocol/agent.js";
+import { AppWorkerIO, AppWorkerProtocolOptions, startAppWorker } from "./worker_protocol/app.js";
+import { createProcessWorkerIO } from "./worker_protocol/process.js";
+import { createWorkerThreadIO } from "./worker_protocol/worker-thread.js";
+export { type AgentWorkerIO, type AppWorkerIO, type AppWorkerProtocolOptions, createProcessWorkerIO, createWorkerThreadIO, startAgentWorker, startAppWorker };

package/dist/worker_protocol.js

@@ -0,0 +1,6 @@
+import { startAgentWorker } from "./worker_protocol/agent.js";
+import { createProcessWorkerIO } from "./worker_protocol/process.js";
+import { createWorkerThreadIO } from "./worker_protocol/worker-thread.js";
+import { startAppWorker } from "./worker_protocol/app.js";
+
+export { createProcessWorkerIO, createWorkerThreadIO, startAgentWorker, startAppWorker };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@eggjs/cluster",
-  "version": "4.0.2-beta.25",
+  "version": "4.0.2-beta.27",
   "description": "cluster manager for egg",
   "keywords": [
     "cluster",
@@ -29,6 +29,7 @@
     ".": "./dist/index.js",
     "./agent_worker": "./dist/agent_worker.js",
     "./app_worker": "./dist/app_worker.js",
+    "./worker_protocol": "./dist/worker_protocol.js",
     "./package.json": "./package.json"
   },
   "publishConfig": {
@@ -37,6 +38,7 @@
       ".": "./dist/index.js",
       "./agent_worker": "./dist/agent_worker.js",
       "./app_worker": "./dist/app_worker.js",
+      "./worker_protocol": "./dist/worker_protocol.js",
       "./package.json": "./package.json"
     }
   },
@@ -46,7 +48,7 @@
     "test": "vitest run"
   },
   "dependencies": {
-    "@eggjs/utils": "5.0.2-beta.25",
+    "@eggjs/utils": "5.0.2-beta.27",
     "@fengmk2/ps-tree": "^2.0.1",
     "cfork": "^2.0.0",
     "cluster-reload": "^2.0.0",
@@ -59,10 +61,10 @@
     "utility": "^2.5.0"
   },
   "devDependencies": {
-    "@eggjs/errors": "3.0.2-beta.25",
-    "@eggjs/mock": "7.0.2-beta.25",
-    "@eggjs/supertest": "9.0.2-beta.25",
-    "@eggjs/tsconfig": "3.1.2-beta.25",
+    "@eggjs/errors": "3.0.2-beta.27",
+    "@eggjs/mock": "7.0.2-beta.27",
+    "@eggjs/supertest": "9.0.2-beta.27",
+    "@eggjs/tsconfig": "3.1.2-beta.27",
     "address": "2",
     "coffee": "5",
     "tsdown": "^0.18.2",