@eggjs/cluster 3.0.1 → 3.1.0-beta.11

package/README.md

@@ -1,16 +1,12 @@
-# egg-cluster
+# @eggjs/cluster
 
 [![NPM version][npm-image]][npm-url]
-[![CI](https://github.com/eggjs/cluster/actions/workflows/nodejs.yml/badge.svg)](https://github.com/eggjs/cluster/actions/workflows/nodejs.yml)
-[![Test coverage][codecov-image]][codecov-url]
 [![Known Vulnerabilities][snyk-image]][snyk-url]
 [![npm download][download-image]][download-url]
 [![Node.js Version](https://img.shields.io/node/v/@eggjs/cluster.svg?style=flat)](https://nodejs.org/en/download/)
 
 [npm-image]: https://img.shields.io/npm/v/@eggjs/cluster.svg?style=flat-square
 [npm-url]: https://npmjs.org/package/@eggjs/cluster
-[codecov-image]: https://codecov.io/github/eggjs/cluster/coverage.svg?branch=master
-[codecov-url]: https://codecov.io/github/eggjs/cluster?branch=master
 [snyk-image]: https://snyk.io/test/npm/@eggjs/cluster/badge.svg?style=flat-square
 [snyk-url]: https://snyk.io/test/npm/@eggjs/cluster
 [download-image]: https://img.shields.io/npm/dm/@eggjs/cluster.svg?style=flat-square
@@ -59,21 +55,21 @@ startCluster({
 
 ## Options
 
-| Param        | Type      | Description                              |
-| ------------ | --------- | ---------------------------------------- |
-| baseDir      | `String`  | directory of application                 |
-| framework    | `String`  | specify framework that can be absolute path or npm package |
-| plugins      | `Object`  | plugins for unittest                     |
-| workers      | `Number`  | numbers of app workers                   |
-| sticky       | `Boolean` | sticky mode server                       |
-| port         | `Number`  | port                                     |
-| debugPort    | `Number`  | the debug port only listen on http protocol |
-| https        | `Object`  | start a https server, note: `key` / `cert` / `ca` should be full path to file |
-| require      | `Array\|String` | will inject into worker/agent process |
-| pidFile      | `String`  | will save master pid to this file |
-| startMode    | `String`  | default is 'process', use 'worker_threads' to start the app & agent worker by worker_threads |
-| 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 |
+| Param     | Type            | Description                                                                                                       |
+| --------- | --------------- | ----------------------------------------------------------------------------------------------------------------- |
+| baseDir   | `String`        | directory of application                                                                                          |
+| framework | `String`        | specify framework that can be absolute path or npm package                                                        |
+| plugins   | `Object`        | plugins for unittest                                                                                              |
+| workers   | `Number`        | numbers of app workers                                                                                            |
+| sticky    | `Boolean`       | sticky mode server                                                                                                |
+| port      | `Number`        | port                                                                                                              |
+| debugPort | `Number`        | the debug port only listen on http protocol                                                                       |
+| https     | `Object`        | start a https server, note: `key` / `cert` / `ca` should be full path to file                                     |
+| require   | `Array\|String` | will inject into worker/agent process                                                                             |
+| pidFile   | `String`        | will save master pid to this file                                                                                 |
+| startMode | `String`        | default is 'process', use 'worker_threads' to start the app & agent worker by worker_threads                      |
+| 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                                                                 |
 
 ## Env
 
@@ -87,6 +83,6 @@ startCluster({
 
 ## Contributors
 
-[![Contributors](https://contrib.rocks/image?repo=eggjs/cluster)](https://github.com/eggjs/cluster/graphs/contributors)
+[![Contributors](https://contrib.rocks/image?repo=eggjs/egg)](https://github.com/eggjs/egg/graphs/contributors)
 
 Made with [contributors-img](https://contrib.rocks).

package/dist/agent_worker.d.ts

@@ -0,0 +1 @@
+export { };

package/dist/agent_worker.js

@@ -0,0 +1,55 @@
+import { AgentProcessWorker } from "./utils/mode/impl/process/agent.js";
+import { AgentThreadWorker } from "./utils/mode/impl/worker_threads/agent.js";
+import { debuglog } from "node:util";
+import { EggConsoleLogger } from "egg-logger";
+import { importModule } from "@eggjs/utils";
+
+//#region src/agent_worker.ts
+const debug = debuglog("egg/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() {
+	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 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);
+	let agent;
+	try {
+		agent = new Agent(options);
+	} catch (err) {
+		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()
+	});
+}
+main();
+
+//#endregion
+export {  };

package/dist/app_worker.d.ts

@@ -0,0 +1 @@
+export { };

package/dist/app_worker.js

@@ -0,0 +1,131 @@
+import { AppProcessWorker } from "./utils/mode/impl/process/app.js";
+import { AppThreadWorker } from "./utils/mode/impl/worker_threads/app.js";
+import { debuglog } from "node:util";
+import fs from "node:fs";
+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");
+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 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);
+	let app;
+	try {
+		app = new Application(options);
+	} catch (err) {
+		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";
+		debug("[app_worker:%s] listenConfig: %j, real port: %o, protocol: %o, debugPort: %o", process.pid, listenConfig, port, protocol, debugPort);
+		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;
+				}
+				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", process.pid, address);
+			AppWorker.send({
+				to: "master",
+				action: "app-start",
+				data: {
+					address,
+					workerId: AppWorker.workerId
+				}
+			});
+		});
+	}
+	AppWorker.gracefulExit({
+		logger: consoleLogger,
+		label: "app_worker",
+		beforeExit: () => app.close()
+	});
+}
+main();
+
+//#endregion
+export {  };

package/dist/dirname.js

@@ -0,0 +1,11 @@
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+//#region src/dirname.ts
+function getSrcDirname() {
+	if (typeof __dirname !== "undefined") return __dirname;
+	return path.dirname(fileURLToPath(import.meta.url));
+}
+
+//#endregion
+export { getSrcDirname };

package/dist/error/ClusterAgentWorkerError.d.ts

@@ -0,0 +1,13 @@
+//#region src/error/ClusterAgentWorkerError.d.ts
+declare 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);
+}
+//#endregion
+export { ClusterAgentWorkerError };

package/dist/error/ClusterAgentWorkerError.js

@@ -0,0 +1,22 @@
+//#region src/error/ClusterAgentWorkerError.ts
+var ClusterAgentWorkerError = class extends Error {
+	id;
+	/**
+	* pid in process mode
+	* tid in worker_threads mode
+	*/
+	workerId;
+	status;
+	constructor(id, workerId, status, 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);
+	}
+};
+
+//#endregion
+export { ClusterAgentWorkerError };

package/dist/error/ClusterWorkerExceptionError.d.ts

@@ -0,0 +1,10 @@
+//#region src/error/ClusterWorkerExceptionError.d.ts
+declare class ClusterWorkerExceptionError extends Error {
+  count: {
+    agent: number;
+    worker: number;
+  };
+  constructor(agent: number, worker: number);
+}
+//#endregion
+export { ClusterWorkerExceptionError };

package/dist/error/ClusterWorkerExceptionError.js

@@ -0,0 +1,17 @@
+//#region src/error/ClusterWorkerExceptionError.ts
+var ClusterWorkerExceptionError = class extends Error {
+	count;
+	constructor(agent, worker) {
+		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);
+	}
+};
+
+//#endregion
+export { ClusterWorkerExceptionError };

package/dist/index.d.ts

@@ -0,0 +1,22 @@
+import { ClusterHTTPSSecureOptions, ClusterOptions, ClusterStartMode } from "./utils/options.js";
+import { Master, MasterOptions } from "./master.js";
+import { ClusterAgentWorkerError } from "./error/ClusterAgentWorkerError.js";
+import { ClusterWorkerExceptionError } from "./error/ClusterWorkerExceptionError.js";
+
+//#region src/index.d.ts
+
+/**
+ * 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}
+ */
+declare function startCluster(options: ClusterOptions): Promise<void>;
+//#endregion
+export { ClusterAgentWorkerError, type ClusterHTTPSSecureOptions, type ClusterOptions, type ClusterStartMode, ClusterWorkerExceptionError, Master, type MasterOptions, startCluster };

package/dist/index.js

@@ -0,0 +1,24 @@
+import "./utils/options.js";
+import { ClusterAgentWorkerError } from "./error/ClusterAgentWorkerError.js";
+import { ClusterWorkerExceptionError } from "./error/ClusterWorkerExceptionError.js";
+import { Master } from "./master.js";
+
+//#region src/index.ts
+/**
+* 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}
+*/
+async function startCluster(options) {
+	await new Master(options).ready();
+}
+
+//#endregion
+export { ClusterAgentWorkerError, ClusterWorkerExceptionError, Master, startCluster };

package/dist/master.d.ts

@@ -0,0 +1,96 @@
+import { WorkerManager } from "./utils/worker_manager.js";
+import { Messenger } from "./utils/messenger.js";
+import { BaseAppWorker } from "./utils/mode/base/app.js";
+import { ClusterOptions, ParsedClusterOptions } from "./utils/options.js";
+import { AgentProcessUtils } from "./utils/mode/impl/process/agent.js";
+import { AppProcessUtils } from "./utils/mode/impl/process/app.js";
+import { AgentThreadUtils } from "./utils/mode/impl/worker_threads/agent.js";
+import { AppThreadUtils } from "./utils/mode/impl/worker_threads/app.js";
+import { ReadyEventEmitter } from "get-ready";
+import { EggConsoleLogger } from "egg-logger";
+import * as worker_threads0 from "worker_threads";
+import * as cluster0 from "cluster";
+
+//#region src/master.d.ts
+interface MasterOptions extends ParsedClusterOptions {
+  clusterPort?: number;
+  stickyWorkerPort?: number;
+}
+declare class Master extends ReadyEventEmitter {
+  #private;
+  options: MasterOptions;
+  isStarted: boolean;
+  workerManager: WorkerManager;
+  messenger: Messenger;
+  isProduction: boolean;
+  agentWorkerIndex: number;
+  closed: boolean;
+  logger: EggConsoleLogger;
+  agentWorker: AgentProcessUtils | AgentThreadUtils;
+  appWorker: AppProcessUtils | AppThreadUtils;
+  constructor(options?: ClusterOptions);
+  startByProcess(): void;
+  startByWorkerThreads(): void;
+  detectPorts(): Promise<void>;
+  log(msg: string, ...args: any[]): void;
+  startMasterSocketServer(cb: (err?: Error) => void): void;
+  stickyWorker(ip: string): BaseAppWorker<worker_threads0.Worker | cluster0.Worker>;
+  forkAgentWorker(): void;
+  forkAppWorkers(): void;
+  /**
+   * close agent worker, App Worker will closed by cluster
+   *
+   * https://www.exratione.com/2013/05/die-child-process-die/
+   * make sure Agent Worker exit before master exit
+   *
+   * @param {number} timeout - kill agent timeout
+   * @return {Promise} -
+   */
+  killAgentWorker(timeout: number): Promise<void>;
+  killAppWorkers(timeout: number): Promise<void>;
+  /**
+   * Agent Worker exit handler
+   * Will exit during startup, and refork during running.
+   */
+  onAgentExit(data: {
+    /** exit code */
+    code: number;
+    /** received signal */
+    signal: string;
+  }): void;
+  onAgentStart(): void;
+  /**
+   * App Worker exit handler
+   */
+  onAppExit(data: {
+    workerId: number;
+    code: number;
+    signal: string;
+  }): void;
+  /**
+   * after app worker
+   */
+  onAppStart(data: {
+    workerId: number;
+    address: ListeningAddress;
+  }): void;
+  /**
+   * master exit handler
+   */
+  onExit(code: number): void;
+  onSignal(signal: string): void;
+  /**
+   * reload workers, for develop purpose
+   */
+  onReload(): void;
+  close(): Promise<void>;
+  _doClose(): Promise<void>;
+}
+interface ListeningAddress {
+  port: number;
+  protocol: string;
+  address?: string;
+  addressType?: number;
+}
+//#endregion
+export { Master, MasterOptions };