@eggjs/cluster 3.0.1 → 3.1.0-beta.2

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/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 };