@nsshunt/stsrunnerframework 1.0.199 → 2.0.1

package/types/workerInstance.d.ts

@@ -1,20 +1,344 @@
-import { MessagePort } from 'worker_threads';
-import { IRunnerInstance, IRunner, ITestRunnerTelemetryPayload, IWorkerOptions } from './commonTypes';
-import { ISTSLogger } from '@nsshunt/stsutils';
-export interface IRunnerEx2RunState {
-    runnerInstance: IRunnerInstance;
-    runner: IRunner;
-    archived: boolean;
+ 
+/**
+ * WorkerInstance
+ * ----------------
+ * Concrete runtime implementation of {@link IWorkerEx}.
+ *
+ * A WorkerInstance represents a single worker process/thread plus the collection
+ * of runner instances hosted inside that worker.
+ *
+ * Responsibilities:
+ * - Own the in-memory collection of runner instances for this worker
+ * - Dispatch commands to individual runners via the message broker
+ * - Dispatch bulk commands to all runners in this worker
+ * - Create and register new runners in this worker
+ * - Expose serialisable worker models (`toJSON`, `toWorker`, `toWorkerCore`)
+ * - Maintain worker-level event subscriptions
+ * - Coordinate worker termination and registry cleanup
+ */
+import { IExecuteRunnerActionResult, IRunnerEvent, IRunnerEx, IRunnerOptions, IRunnerState, IWorker, IWorkerCore, IWorkerEx, IWorkerFactory, IWorkerOptions, IWorkerEvent } from './commonTypes';
+import { WorkerRegistry } from './workerRegistry';
+import { STSMessageBroker } from './messageBroker';
+import { AsyncRunnerInstanceManager } from './asyncRunnerInstanceManager';
+import type { Worker as NodeWorker, MessagePort as NodeMessagePort } from 'node:worker_threads';
+/**
+ * Runtime worker type supporting both browser and Node.js workers.
+ */
+export type RuntimeWorker = Worker | NodeWorker;
+/**
+ * Runtime message port type supporting both browser and Node.js message ports.
+ */
+export type RuntimeMessagePort = MessagePort | NodeMessagePort;
+/**
+ * Constructor options required to create a {@link WorkerInstance}.
+ *
+ * Notes:
+ * - `workerManagerId` identifies the owning worker manager instance.
+ * - `workerOptions` contains the runtime configuration for the worker itself.
+ * - `messagePort` is the communication port already allocated for this worker.
+ * - `workerFactory` is responsible for creating the underlying actual worker thread/process.
+ * - `messageBroker` is used for request/response message dispatch to the worker.
+ * - `workerRegistry` is used for central registry cleanup during termination.
+ * - `asyncRunnerInstanceManager` is used to construct runner instances for this worker.
+ * - `logger` is intentionally minimal and only requires debug/error methods.
+ */
+export interface IWorkerInstanceOptions {
+    /** Id of the owning worker manager. */
+    workerManagerId: string;
+    /** Worker-specific runtime configuration. */
+    workerOptions: IWorkerOptions;
+    /** Message port used by this worker for brokered communications. */
+    messagePort: RuntimeMessagePort;
+    /** Factory used to construct the underlying worker implementation. */
+    workerFactory: IWorkerFactory;
+    /** Broker used to send commands and correlate responses for this worker. */
+    messageBroker: STSMessageBroker;
+    /** Shared registry containing all live worker instances. */
+    workerRegistry: WorkerRegistry;
+    /** Factory/manager used to create runner instances for this worker. */
+    asyncRunnerInstanceManager: AsyncRunnerInstanceManager;
+    /** Logger abstraction used by this class. */
+    logger: {
+        debug: (message: any) => void;
+        error: (message: any) => void;
+    };
 }
-export declare abstract class WorkerInstance {
+/**
+ * Concrete worker runtime instance.
+ *
+ * This class owns:
+ * - the underlying worker handle (`worker`)
+ * - the broker message port (`messagePort`)
+ * - all runner instances hosted inside this worker (`__runnersEx`)
+ * - worker-level event subscriptions (`workerEvents`)
+ * - runner-level event subscription collections (`runnersEvents`)
+ *
+ * Design notes:
+ * - `__runnersEx` is intentionally private to stop callers from mutating the
+ *   runner collection directly.
+ * - The class delegates command dispatch to the message broker rather than
+ *   communicating with the underlying worker directly.
+ * - Most public methods are thin orchestration methods over private helpers.
+ */
+export declare class WorkerInstance implements IWorkerEx {
     #private;
-    get logger(): ISTSLogger;
-    constructor();
-    GetRandomInt: (max: number) => number;
-    PostTelemetryById: (id: string) => void;
-    get CollectorCollectorPort(): MessagePort | null;
-    get Options(): IWorkerOptions | null;
-    CreateAsyncRunner: (testRunnerTelemetryPayload: ITestRunnerTelemetryPayload) => Promise<IRunnerInstance | null>;
-    ProcessMessage: (data: any) => Promise<void>;
+    /** Unique identifier for this worker instance. */
+    id: string;
+    /** Id of the owning worker manager. */
+    workerManagerId: string;
+    /**
+     *  Underlying actual worker runtime (browser worker or Node worker thread).
+     */
+    worker: RuntimeWorker;
+    /**
+     * Registered worker-level event subscriptions.
+     *
+     * Typical events may include lifecycle events emitted elsewhere in the system,
+     * such as `exit`, `error`, etc.
+     */
+    workerEvents: IWorkerEvent[];
+    /**
+     * Communication port used by the message broker for this worker.
+     */
+    messagePort: RuntimeMessagePort;
+    /** Worker runtime configuration. */
+    options: IWorkerOptions;
+    /**
+     * Per-runner event subscription collections, keyed by runner id.
+     *
+     * Each runner id maps to a list of subscriptions interested in events
+     * for that specific runner.
+     */
+    runnersEvents: Record<string, IRunnerEvent[]>;
+    /**
+     * Private in-memory map of runner runtime instances owned by this worker.
+     *
+     * Key: runner id
+     * Value: live runner runtime instance
+     */
+    private __runnersEx;
+    /**
+     * Construct a new live worker runtime instance.
+     *
+     * Behaviour:
+     * - Generates a new worker id
+     * - Creates the underlying concrete worker using the provided factory
+     * - Stores the provided message port and runtime options
+     * - Stores references to collaborating services
+     *
+     * @param options Dependencies and configuration required to construct the worker.
+     */
+    constructor(options: IWorkerInstanceOptions);
+    /**
+     * Add an already-created runner runtime instance into this worker's internal collection.
+     *
+     * This method only updates local in-memory state. It does not send any message
+     * to the underlying worker. Use {@link AddRunner} when you want the runner to be
+     * both created locally and pushed into the underlying worker process/thread.
+     *
+     * @param runnerEx Runner runtime instance to register under this worker.
+     */
+    AddRunnerEx(runnerEx: IRunnerEx): void;
+    /**
+     * Get a single runner runtime instance by id.
+     *
+     * @param id Runner id to look up.
+     * @returns The runner instance if found, otherwise `null`.
+     */
+    GetRunnerEx(id: string): IRunnerEx | null;
+    /**
+     * Get the raw internal runner map for this worker.
+     *
+     * Note:
+     * This returns the live in-memory map, not a defensive copy.
+     *
+     * @returns Record of runner id -> runner instance.
+     */
+    GetAllRunnersExMap(): Record<string, IRunnerEx>;
+    /**
+     * Get all runner runtime instances currently hosted by this worker.
+     *
+     * @returns Array of all runner instances.
+     */
+    GetAllRunnersEx(): IRunnerEx[];
+    /**
+     * Get runner runtime instances filtered by runner id.
+     *
+     * Behaviour:
+     * - If `runnerIds` is empty, all runners are returned.
+     * - Otherwise only matching runner ids are returned.
+     *
+     * @param runnerIds List of runner ids to include. Use `[]` to include all.
+     * @returns Filtered runner list.
+     */
+    GetRunnersEx(runnerIds: string[]): IRunnerEx[];
+    /**
+     * Create a new runner runtime instance, register it in this worker,
+     * and send an `AddRunner` command to the underlying worker.
+     *
+     * @param runnerOptions Runtime options for the new runner.
+     * @returns Newly created runner instance once successfully registered with the underlying worker.
+     */
+    AddRunner(runnerOptions: IRunnerOptions): Promise<IRunnerEx>;
+    /**
+     * Send a `StartRunner` command for the specified runner.
+     *
+     * @param runner Target runner.
+     * @returns Action result returned by the worker.
+     */
+    StartRunner(runner: IRunnerEx): Promise<IExecuteRunnerActionResult>;
+    /**
+     * Send a `StopRunner` command for the specified runner.
+     *
+     * @param runner Target runner.
+     * @returns Action result returned by the worker.
+     */
+    StopRunner(runner: IRunnerEx): Promise<IExecuteRunnerActionResult>;
+    /**
+     * Send a `PauseRunner` command for the specified runner.
+     *
+     * @param runner Target runner.
+     * @returns Action result returned by the worker.
+     */
+    PauseRunner(runner: IRunnerEx): Promise<IExecuteRunnerActionResult>;
+    /**
+     * Send a `ResumeRunner` command for the specified runner.
+     *
+     * @param runner Target runner.
+     * @returns Action result returned by the worker.
+     */
+    ResumeRunner(runner: IRunnerEx): Promise<IExecuteRunnerActionResult>;
+    /**
+     * Send a `TerminateRunner` command for the specified runner.
+     *
+     * @param runner Target runner.
+     * @returns Action result returned by the worker.
+     */
+    TerminateRunner(runner: IRunnerEx): Promise<IExecuteRunnerActionResult>;
+    /**
+     * Send a `ResetRunner` command for the specified runner.
+     *
+     * @param runner Target runner.
+     * @returns Action result returned by the worker.
+     */
+    ResetRunner(runner: IRunnerEx): Promise<IExecuteRunnerActionResult>;
+    /**
+     * Send an `ExecuteRunner` command for the specified runner.
+     *
+     * @param runner Target runner.
+     * @returns Action result returned by the worker.
+     */
+    ExecuteRunner(runner: IRunnerEx): Promise<IExecuteRunnerActionResult>;
+    /**
+     * Send an `UpdateRunner` command for the specified runner.
+     *
+     * @param runner Target runner.
+     * @param runnerOptions Partial runner option updates to apply.
+     * @returns Action result returned by the worker.
+     */
+    UpdateRunner(runner: IRunnerEx, runnerOptions: Partial<IRunnerOptions>): Promise<IExecuteRunnerActionResult>;
+    /**
+     * Send `Start` to all runners in this worker.
+     *
+     * @returns Array of per-runner action results.
+     */
+    Start(): Promise<IExecuteRunnerActionResult[]>;
+    /**
+     * Send `Stop` to all runners in this worker.
+     *
+     * @returns Array of per-runner action results.
+     */
+    Stop(): Promise<IExecuteRunnerActionResult[]>;
+    /**
+     * Send `Pause` to all runners in this worker.
+     *
+     * @returns Array of per-runner action results.
+     */
+    Pause(): Promise<IExecuteRunnerActionResult[]>;
+    /**
+     * Send `Resume` to all runners in this worker.
+     *
+     * @returns Array of per-runner action results.
+     */
+    Resume(): Promise<IExecuteRunnerActionResult[]>;
+    /**
+     * Send `Reset` to all runners in this worker.
+     *
+     * @returns Array of per-runner action results.
+     */
+    Reset(): Promise<IExecuteRunnerActionResult[]>;
+    /**
+     * Send `Execute` to all runners in this worker.
+     *
+     * @returns Array of per-runner action results.
+     */
+    Execute(): Promise<IExecuteRunnerActionResult[]>;
+    /**
+     * Send `Update` to all runners in this worker.
+     *
+     * @param runnerOptions Partial runner option updates to apply to all runners.
+     * @returns Array of per-runner action results.
+     */
+    Update(runnerOptions: Partial<IRunnerOptions>): Promise<IExecuteRunnerActionResult[]>;
+    /**
+     * Terminate all runners in this worker and then terminate the underlying worker itself.
+     *
+     * Behaviour:
+     * - Calls `Terminate()` on all runner instances first
+     * - Waits for those promises via `Promise.all`
+     * - Schedules actual worker termination 500ms later
+     * - Removes the worker from the central registry after terminating the worker
+     *
+     * Notes:
+     * - This method intentionally handles worker-level shutdown separately rather than
+     *   using {@link #invokeCommand} because worker termination involves additional
+     *   cleanup beyond runner termination.
+     * - The 500ms timeout is a grace period before terminating the underlying worker.
+     *
+     * @returns Array of per-runner action results, or `[]` if termination setup fails.
+     */
+    Terminate(): Promise<IExecuteRunnerActionResult[]>;
+    /**
+     * Register a worker-level event subscription.
+     *
+     * This supports a fluent style:
+     * `worker.on('exit', cb).on('error', cb2)`
+     *
+     * @param eventName Name of the event to subscribe to.
+     * @param cb Callback to invoke when the event is emitted.
+     * @returns The current worker instance for chaining.
+     */
+    on(eventName: string, cb: (args?: any) => void): IWorkerEx;
+    /**
+     * Convert this live worker runtime instance into a serialisable worker model.
+     *
+     * Behaviour:
+     * - Copies worker metadata
+     * - Serialises all live runners via `runnerEx.toJSON()`
+     *
+     * @returns Full serialisable worker model.
+     */
+    toJSON(): IWorker;
+    /**
+     * Alias for {@link toJSON}.
+     *
+     * @returns Full serialisable worker model.
+     */
+    toWorker(): IWorker;
+    /**
+     * Convert this worker into a reduced/core representation.
+     *
+     * Behaviour:
+     * - Includes only the worker id plus filtered runner core models
+     * - If `states` is:
+     *   - `undefined`: includes all runners
+     *   - `[]`: includes all runners
+     *   - populated: includes only runners whose state matches one of the provided states
+     *
+     * @param states Optional runner state filter.
+     * @returns Core worker model containing core runner representations.
+     * @throws Re-throws any error after logging.
+     */
+    toWorkerCore(states?: IRunnerState[]): IWorkerCore;
 }
 //# sourceMappingURL=workerInstance.d.ts.map

package/types/workerInstance.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"workerInstance.d.ts","sourceRoot":"","sources":["../src/workerInstance.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAI7C,OAAO,EAAuE,eAAe,EAC7D,OAAO,EAAE,2BAA2B,EAAE,cAAc,EAGnF,MAAM,eAAe,CAAA;AAMtB,OAAO,EAAE,UAAU,EAAwB,MAAM,mBAAmB,CAAC;AAErE,MAAM,WAAW,kBAAkB;IAC/B,cAAc,EAAE,eAAe,CAAA;IAC/B,MAAM,EAAE,OAAO,CAAA;IACf,QAAQ,EAAE,OAAO,CAAA;CACpB;AAED,8BAAsB,cAAc;;IAOhC,IAAI,MAAM,IAAI,UAAU,CAEvB;;IA4FD,YAAY,GAAI,KAAK,MAAM,YAEzB;IAEF,iBAAiB,GAAI,IAAI,MAAM,UAE9B;IAED,IAAI,sBAAsB,IAAI,WAAW,GAAG,IAAI,CAE/C;IAED,IAAI,OAAO,IAAI,cAAc,GAAG,IAAI,CAEnC;IAiCD,iBAAiB,GAAU,4BAA4B,2BAA2B,KAAG,OAAO,CAAC,eAAe,GAAG,IAAI,CAAC,CAEnH;IA2gBD,cAAc,GAAS,MAAM,GAAG,mBA4D/B;CACJ"}
+{"version":3,"file":"workerInstance.d.ts","sourceRoot":"","sources":["../src/workerInstance.ts"],"names":[],"mappings":"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"}

package/types/workerInstanceMannager.d.ts

@@ -0,0 +1,170 @@
+ 
+/**
+ * WorkerInstanceManager
+ * =====================
+ *
+ * Factory and lifecycle helper responsible for:
+ *
+ * - constructing manager-side worker runtime objects (`IWorkerEx`)
+ * - wiring shared dependencies into those worker instances
+ * - attaching low-level system/runtime event handlers to the underlying actual worker
+ * - translating native worker events into higher-level worker events
+ * - removing failed/exited workers from the shared registry
+ *
+ * Role in the architecture
+ * ------------------------
+ * This class lives on the **manager/controller side** of the system.
+ *
+ * It should not be confused with:
+ *
+ * - the actual browser Web Worker / Node worker thread runtime, or
+ * - the abstract worker-runtime execution host that runs inside the worker
+ *
+ * Instead, this class is responsible for creating and configuring the
+ * manager-side `IWorkerEx` object that represents a live worker to the rest
+ * of the coordination layer.
+ *
+ * Typical responsibilities in practice
+ * ------------------------------------
+ * 1. Create a new manager-side worker object using the configured factory
+ * 2. Inject shared collaborators such as:
+ *    - message broker
+ *    - worker registry
+ *    - async runner instance manager
+ * 3. Attach low-level native worker runtime event listeners:
+ *    - Node.js: `exit`, `error`
+ *    - Browser: `onerror`, `onmessageerror`
+ * 4. Forward those low-level events into higher-level worker events
+ * 5. Remove failed/exited workers from the shared registry when appropriate
+ */
+import { IWorkerEx, IWorkerFactory, IWorkerOptions } from './commonTypes';
+import { ISTSLogger } from '@nsshunt/stsutils';
+import { STSMessageBroker } from './messageBroker';
+import { AsyncRunnerInstanceManager } from './asyncRunnerInstanceManager';
+import { WorkerRegistry } from './workerRegistry';
+/**
+ * Constructor options for {@link WorkerInstanceManager}.
+ */
+export interface IWorkerInstanceManagerOptions {
+    /**
+     * Id of the top-level worker manager that owns all workers created through this manager.
+     */
+    workerManagerId: string;
+    /**
+     * Logger used for diagnostics and error reporting.
+     */
+    logger: ISTSLogger;
+    /**
+     * Shared message broker used by created worker instances to communicate with their
+     * underlying actual worker runtime.
+     */
+    messageBroker: STSMessageBroker;
+    /**
+     * Shared live worker registry.
+     *
+     * Used when system events require worker removal/cleanup.
+     */
+    workerRegistry: WorkerRegistry;
+    /**
+     * Shared async runner instance manager used by worker instances when creating runners.
+     */
+    asyncRunnerInstanceManager: AsyncRunnerInstanceManager;
+}
+/**
+ * Manager-side factory/helper for worker instances.
+ *
+ * This class creates concrete manager-side {@link IWorkerEx} objects and attaches
+ * platform-specific system event listeners to the underlying worker runtime.
+ */
+export declare class WorkerInstanceManager {
+    /**
+     * Immutable runtime configuration and dependencies for this manager.
+     */
+    private readonly options;
+    /**
+     * Construct a new worker instance manager.
+     *
+     * @param options Shared collaborators required to create and manage worker instances.
+     */
+    constructor(options: IWorkerInstanceManagerOptions);
+    /**
+     * Create a new manager-side worker instance.
+     *
+     * Behaviour:
+     * - constructs a new concrete {@link WorkerInstance}
+     * - injects all shared collaborators required by that worker instance
+     * - returns the created manager-side worker object
+     *
+     * Notes:
+     * - This does not automatically register the worker in the registry
+     * - This does not automatically attach system/runtime event handlers
+     * - Those are handled separately by the caller
+     *
+     * Dependencies injected into the worker include:
+     * - worker manager id
+     * - worker-specific options
+     * - message port
+     * - worker factory
+     * - message broker
+     * - worker registry
+     * - async runner instance manager
+     * - logger
+     *
+     * @param workerOptions Worker-specific runtime configuration.
+     * @param port Message port used for brokered worker communication.
+     * @param workerFactory Factory used to create the underlying actual worker runtime.
+     * @returns Newly created manager-side worker instance.
+     */
+    CreateWorkerInstance: (workerOptions: IWorkerOptions, port: any, workerFactory: IWorkerFactory) => IWorkerEx;
+    /**
+     * Attach low-level system/runtime event handlers to the underlying actual worker.
+     *
+     * Environment-specific behaviour:
+     *
+     * Node.js worker thread:
+     * - attaches `exit`
+     * - attaches `error`
+     *
+     * Browser Web Worker:
+     * - attaches `onerror`
+     * - attaches `onmessageerror`
+     *
+     * Event handling behaviour
+     * ------------------------
+     * - Logs the low-level worker event
+     * - Emits a higher-level worker event to any subscribers on `workerEx.workerEvents`
+     * - Removes the worker from the shared registry when appropriate
+     *
+     * Registry removal behaviour:
+     * - Node `exit` -> deletes worker from registry
+     * - Browser `onerror` -> deletes worker from registry
+     * - Node `error` does not immediately delete the worker
+     * - Browser `onmessageerror` does not immediately delete the worker
+     *
+     * Notes:
+     * - This method should typically be called after creating the worker instance
+     *   and before the worker is considered fully live
+     * - For mocked workers or other special worker implementations, callers may
+     *   choose not to attach these runtime handlers
+     *
+     * @param stsWorkerEx Manager-side worker instance whose underlying actual worker should be monitored.
+     */
+    SetupWorkerSystemEvents: (stsWorkerEx: IWorkerEx) => void;
+    /**
+     * Emit a higher-level worker event to any registered worker event subscribers.
+     *
+     * Behaviour:
+     * - iterates the worker's registered `workerEvents`
+     * - matches handlers whose `eventName` equals the supplied event name
+     * - invokes each matching callback with the live worker instance
+     *
+     * This method is used to translate low-level native worker/runtime events into
+     * the higher-level event model used by the rest of the framework.
+     *
+     * @param eventName Name of the worker event to emit.
+     * @param workerEx Live manager-side worker instance associated with the event.
+     * @throws Re-throws unexpected errors after logging.
+     */
+    private _EmitWorkerEvent;
+}
+//# sourceMappingURL=workerInstanceMannager.d.ts.map

package/types/workerInstanceMannager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"workerInstanceMannager.d.ts","sourceRoot":"","sources":["../src/workerInstanceMannager.ts"],"names":[],"mappings":";AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AAGH,OAAO,EAAE,SAAS,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAE1E,OAAO,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAO/C,OAAO,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AACnD,OAAO,EAAE,0BAA0B,EAAE,MAAM,8BAA8B,CAAC;AAC1E,OAAO,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAGlD;;GAEG;AACH,MAAM,WAAW,6BAA6B;IAC1C;;OAEG;IACH,eAAe,EAAE,MAAM,CAAC;IAExB;;OAEG;IACH,MAAM,EAAE,UAAU,CAAC;IAEnB;;;OAGG;IACH,aAAa,EAAE,gBAAgB,CAAC;IAEhC;;;;OAIG;IACH,cAAc,EAAE,cAAc,CAAC;IAE/B;;OAEG;IACH,0BAA0B,EAAE,0BAA0B,CAAC;CAC1D;AAED;;;;;GAKG;AACH,qBAAa,qBAAqB;IAC9B;;OAEG;IACH,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAgC;IAExD;;;;OAIG;gBACS,OAAO,EAAE,6BAA6B;IAIlD;;;;;;;;;;;;;;;;;;;;;;;;;;;OA2BG;IACH,oBAAoB,GAChB,eAAe,cAAc,EAC7B,MAAM,GAAG,EACT,eAAe,cAAc,KAC9B,SAAS,CAWV;IAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAgCG;IACH,uBAAuB,GAAI,aAAa,SAAS,UAqF/C;IAEF;;;;;;;;;;;;;;OAcG;IACH,OAAO,CAAC,gBAAgB,CAWtB;CACL"}