@eggjs/cluster 4.0.0-beta.18 → 4.0.0-beta.20

package/dist/index.d.ts

@@ -1,10 +1,445 @@
-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";
+import { ReadyEventEmitter } from "get-ready";
+import { EggConsoleLogger, Logger } from "egg-logger";
+import { SecureContextOptions } from "node:tls";
+import { EventEmitter } from "node:events";
+import { Worker } from "node:worker_threads";
+import { ChildProcess } from "node:child_process";
+import { Options } from "graceful-process";
+import { Worker as Worker$1 } from "node:cluster";
+import * as worker_threads0 from "worker_threads";
+import * as cluster0 from "cluster";
+import * as child_process0 from "child_process";
 
+//#region src/utils/mode/base/agent.d.ts
+declare abstract class BaseAgentWorker<T = ChildProcess | Worker> {
+  #private;
+  instance: T;
+  constructor(instance: T);
+  abstract get workerId(): number;
+  get id(): number;
+  set id(id: number);
+  get status(): string;
+  set status(status: string);
+  abstract send(message: MessageBody): void;
+  static send(_message: MessageBody): void;
+  static kill(): void;
+  static gracefulExit(_options: any): void;
+}
+type LogFun$1 = (msg: any, ...args: any[]) => void;
+declare abstract class BaseAgentUtils extends EventEmitter {
+  protected options: MasterOptions;
+  protected messenger: Messenger;
+  protected log: LogFun$1;
+  protected logger: Logger;
+  startTime: number;
+  constructor(options: MasterOptions, {
+    log,
+    logger,
+    messenger
+  }: {
+    log: LogFun$1;
+    logger: Logger;
+    messenger: Messenger;
+  });
+  getAgentWorkerFile(): string;
+  fork(): void;
+  clean(): void;
+  abstract kill(timeout: number): Promise<void>;
+}
+//#endregion
+//#region src/utils/worker_manager.d.ts
+declare class WorkerManager extends EventEmitter {
+  agent: BaseAgentWorker | null;
+  workers: Map<number, BaseAppWorker<worker_threads0.Worker | cluster0.Worker>>;
+  exception: number;
+  timer: NodeJS.Timeout;
+  constructor();
+  getWorkers(): number[];
+  setAgent(agent: BaseAgentWorker): void;
+  getAgent(): BaseAgentWorker<worker_threads0.Worker | child_process0.ChildProcess> | null;
+  deleteAgent(): void;
+  setWorker(worker: BaseAppWorker): void;
+  getWorker(workerId: number): BaseAppWorker<worker_threads0.Worker | cluster0.Worker> | undefined;
+  deleteWorker(workerId: number): void;
+  listWorkerIds(): number[];
+  listWorkers(): BaseAppWorker<worker_threads0.Worker | cluster0.Worker>[];
+  getListeningWorkerIds(): number[];
+  count(): {
+    agent: number;
+    worker: number;
+  };
+  startCheck(): void;
+}
+//#endregion
+//#region src/utils/messenger.d.ts
+type MessageCharacter = 'agent' | 'app' | 'master' | 'parent';
+interface MessageBody {
+  action: string;
+  data?: unknown;
+  to?: MessageCharacter;
+  from?: MessageCharacter;
+  /**
+   * @deprecated Keep compatible, please use receiverWorkerId instead
+   */
+  receiverPid?: string;
+  receiverWorkerId?: string;
+  senderWorkerId?: string;
+}
+/**
+ * master messenger, provide communication between parent, master, agent and app.
+ *
+ *             ┌────────┐
+ *             │ parent │
+ *            /└────────┘\
+ *           /     |      \
+ *          /  ┌────────┐  \
+ *         /   │ master │   \
+ *        /    └────────┘    \
+ *       /     /         \    \
+ *     ┌───────┐         ┌───────┐
+ *     │ agent │ ------- │  app  │
+ *     └───────┘         └───────┘
+ *
+ *
+ * in app worker
+ *
+ * ```js
+ * process.send({
+ *   action: 'xxx',
+ *   data: '',
+ *   to: 'agent/master/parent', // default to agent
+ * });
+ * ```
+ *
+ * in agent worker
+ *
+ * ```js
+ * process.send({
+ *   action: 'xxx',
+ *   data: '',
+ *   to: 'app/master/parent', // default to app
+ * });
+ * ```
+ *
+ * in parent
+ *
+ * ```js
+ * process.send({
+ *   action: 'xxx',
+ *   data: '',
+ *   to: 'app/agent/master', // default to master
+ * });
+ * ```
+ */
+declare class Messenger {
+  #private;
+  constructor(master: Master, workerManager: WorkerManager);
+  /**
+   * send message
+   * @param {Object} data message body
+   *  - {String} from from who
+   *  - {String} to to who
+   */
+  send(data: MessageBody): void;
+  /**
+   * send message to master self
+   * @param {Object} data message body
+   */
+  sendToMaster(data: MessageBody): void;
+  /**
+   * send message to parent process
+   * @param {Object} data message body
+   */
+  sendToParent(data: MessageBody): void;
+  /**
+   * send message to app worker
+   * @param {Object} data message body
+   */
+  sendToAppWorker(data: MessageBody): void;
+  /**
+   * send message to agent worker
+   * @param {Object} data message body
+   */
+  sendToAgentWorker(data: MessageBody): void;
+}
+//#endregion
+//#region src/utils/mode/base/app.d.ts
+declare abstract class BaseAppWorker<T = Worker | Worker$1> {
+  instance: T;
+  constructor(instance: T);
+  abstract get workerId(): number;
+  abstract get id(): number;
+  get state(): string;
+  set state(state: string);
+  abstract get exitedAfterDisconnect(): boolean;
+  abstract get exitCode(): number;
+  get disableRefork(): boolean;
+  set disableRefork(disableRefork: boolean);
+  get isDevReload(): boolean;
+  set isDevReload(isDevReload: boolean);
+  abstract send(data: MessageBody): void;
+  clean(): void;
+  static get workerId(): number;
+  static on(..._args: any[]): void;
+  static send(_message: MessageBody): void;
+  static kill(): void;
+  static gracefulExit(_options: any): void;
+}
+type LogFun = (msg: any, ...args: any[]) => void;
+declare abstract class BaseAppUtils extends EventEmitter {
+  options: MasterOptions;
+  protected messenger: Messenger;
+  protected log: LogFun;
+  protected logger: Logger;
+  protected isProduction: boolean;
+  startTime: number;
+  startSuccessCount: number;
+  isAllWorkerStarted: boolean;
+  constructor(options: MasterOptions, {
+    log,
+    logger,
+    messenger,
+    isProduction
+  }: {
+    log: LogFun;
+    logger: Logger;
+    messenger: Messenger;
+    isProduction: boolean;
+  });
+  getAppWorkerFile(): string;
+  fork(): void;
+  abstract kill(timeout: number): Promise<void>;
+}
+//#endregion
+//#region src/utils/options.d.ts
+interface ClusterHTTPSSecureOptions {
+  key: SecureContextOptions['key'];
+  cert: SecureContextOptions['cert'];
+  ca?: SecureContextOptions['ca'];
+  passphrase?: SecureContextOptions['passphrase'];
+}
+type ClusterStartMode = 'process' | 'worker_threads';
+/** Cluster start options */
+interface ClusterOptions {
+  /**
+   * specify framework that can be absolute path or npm package
+   */
+  framework?: string;
+  /**
+   * @deprecated please use framework instead
+   */
+  customEgg?: string;
+  /** directory of application, default to `process.cwd()` */
+  baseDir?: string;
+  /**
+   * numbers of app workers, default to `os.cpus().length`
+   */
+  workers?: number | string;
+  /**
+   * listening port, default to `7001`(http) or `8443`(https)
+   */
+  port?: number | string | null;
+  /**
+   * listening a debug port on http protocol
+   */
+  debugPort?: number;
+  /**
+   * https options, { key, cert, ca }, full path
+   */
+  https?: ClusterHTTPSSecureOptions | boolean;
+  /**
+   * @deprecated please use `options.https.key` instead
+   */
+  key?: ClusterHTTPSSecureOptions['key'];
+  /**
+   * @deprecated please use `options.https.cert` instead
+   */
+  cert?: ClusterHTTPSSecureOptions['cert'];
+  /**
+   * will inject into worker/agent process
+   */
+  require?: string | string[];
+  /**
+   * will save master pid to this file
+   */
+  pidFile?: string;
+  /**
+   * custom env, default is `process.env.EGG_SERVER_ENV`
+   */
+  env?: string;
+  /**
+   * default is `'process'`, use `'worker_threads'` to start the app & agent worker by worker_threads
+   */
+  startMode?: ClusterStartMode;
+  /**
+   * startup port of each app worker, such as: `[7001, 7002, 7003]`, only effects when the startMode is `'worker_threads'`
+   */
+  ports?: number[];
+  /**
+   * sticky mode server
+   */
+  sticky?: boolean;
+  /** customized plugins, for unittest */
+  plugins?: object;
+  isDebug?: boolean;
+}
+interface ParsedClusterOptions extends ClusterOptions {
+  port?: number;
+  baseDir: string;
+  workers: number;
+  framework: string;
+  startMode: ClusterStartMode;
+}
+//#endregion
+//#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;
+  instance: AgentProcessWorker;
+  fork(): this;
+  clean(): void;
+  kill(timeout: number): Promise<void>;
+}
+//#endregion
+//#region src/utils/mode/impl/process/app.d.ts
+declare class AppProcessUtils extends BaseAppUtils {
+  fork(): this;
+  kill(timeout: number): Promise<void>;
+}
+//#endregion
+//#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;
+  instance: AgentThreadWorker;
+  fork(): void;
+  clean(): void;
+  kill(): Promise<void>;
+}
+//#endregion
+//#region src/utils/mode/impl/worker_threads/app.d.ts
+declare class AppThreadUtils extends BaseAppUtils {
+  #private;
+  fork(): this;
+  kill(): Promise<void>;
+}
+//#endregion
+//#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
+//#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
+//#region src/error/ClusterWorkerExceptionError.d.ts
+declare class ClusterWorkerExceptionError extends Error {
+  count: {
+    agent: number;
+    worker: number;
+  };
+  constructor(agent: number, worker: number);
+}
+//#endregion
 //#region src/index.d.ts
-
 /**
  * cluster start flow:
  *