@nsshunt/stsrunnerframework 1.0.200 → 2.0.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nsshunt/stsrunnerframework",
-  "version": "1.0.200",
+  "version": "2.0.1",
   "description": "STS Runner Framework",
   "main": "./dist/stsrunnerframework.umd.js",
   "module": "./dist/stsrunnerframework.mjs",
@@ -52,10 +52,10 @@
     "@types/lodash.merge": "^4.6.9",
     "@typescript-eslint/eslint-plugin": "^8.57.0",
     "@typescript-eslint/parser": "^8.57.0",
-    "eslint": "^9.39.2",
+    "eslint": "^10.0.3",
     "globals": "^17.4.0",
     "typescript": "^5.9.3",
-    "vite": "^7.3.1",
-    "vitest": "^4.0.18"
+    "vite": "^8.0.0",
+    "vitest": "^4.1.0"
   }
 }

package/types/abstractRunnerExecutionWorker.d.ts

@@ -0,0 +1,194 @@
+ 
+/**
+ * AbstractRunnerExecutionWorker
+ * =============================
+ *
+ * Abstract base class for the *actual execution worker runtime* that lives inside:
+ *
+ * - a browser Web Worker, or
+ * - a Node.js worker thread
+ *
+ * This class is the worker-side execution host for runners. It is responsible for:
+ *
+ * - receiving commands from the manager/controller side
+ * - creating concrete executable runner instances
+ * - maintaining in-worker runner runtime state
+ * - driving runner execution loops
+ * - posting unsolicited telemetry and state changes back to the manager
+ * - posting solicited command responses back to the manager
+ * - retiring/removing finished runners from the worker's live runtime collection
+ *
+ * Important architectural distinction
+ * -----------------------------------
+ * This class is **not** the same as the manager-side worker model used in your
+ * registry/coordinator layer.
+ *
+ * Manager side:
+ * - owns worker metadata
+ * - issues commands
+ * - receives telemetry/results
+ *
+ * Worker side (this class):
+ * - actually runs the work
+ * - holds concrete runner implementations
+ * - manages runner execution lifecycle inside the worker runtime
+ *
+ * Why abstract?
+ * -------------
+ * The runner logic can be anything:
+ *
+ * - HTTP/API execution
+ * - synthetic load generation
+ * - browser automation
+ * - database work
+ * - arbitrary domain workflows
+ *
+ * This class provides the common runtime/lifecycle/message-handling framework,
+ * while subclasses override `CreateAsyncRunner(...)` to create a concrete
+ * `IRunnerInstance` that performs the actual work.
+ */
+import { MessagePort } from 'worker_threads';
+import { IRunnerInstance, IRunner, ITestRunnerTelemetryPayload, IWorkerOptions } from './commonTypes';
+import { ISTSLogger } from '@nsshunt/stsutils';
+/**
+ * Internal runtime record stored for each runner hosted inside this worker.
+ *
+ * This combines:
+ * - the serialisable runner DTO/state (`runner`)
+ * - the concrete executable runner implementation (`runnerInstance`)
+ * - an archive flag used for in-worker cleanup (`archived`)
+ */
+export interface IRunnerEx2RunState {
+    /**
+     * Concrete executable runner implementation.
+     *
+     * This is the object that performs the actual domain work.
+     */
+    runnerInstance: IRunnerInstance;
+    /**
+     * Current serialisable runner model/state.
+     *
+     * This is the object sent back to the manager for state/telemetry updates.
+     */
+    runner: IRunner;
+    /**
+     * Indicates whether the runner has already been archived/marked for removal
+     * from the worker's live runner collection.
+     */
+    archived: boolean;
+}
+/**
+ * Abstract worker-runtime base class.
+ *
+ * A concrete subclass is expected to:
+ * - run inside a real worker environment
+ * - override `CreateAsyncRunner(...)`
+ * - optionally expose its `ProcessMessage(...)` method as the worker message entry point
+ *
+ * High-level lifecycle
+ * --------------------
+ * 1. Manager bootstraps this worker by sending `MessagePort`
+ * 2. This class stores the manager communication port and worker options
+ * 3. Manager sends commands like:
+ *    - `AddRunner`
+ *    - `StartRunner`
+ *    - `PauseRunner`
+ *    - `GetRunners`
+ * 4. This class processes those commands and updates runner runtime state
+ * 5. This class sends:
+ *    - solicited responses for commands
+ *    - unsolicited state changes
+ *    - unsolicited telemetry
+ */
+export declare abstract class AbstractRunnerExecutionWorker {
+    #private;
+    /**
+     * Logger used by this worker runtime.
+     *
+     * Returns the shared default logger by default, but exposing this as a getter
+     * allows subclasses to override/customise logging behaviour if desired.
+     */
+    get logger(): ISTSLogger;
+    /**
+     * Construct the worker runtime host and start the background cleanup loop.
+     */
+    constructor();
+    /**
+     * Return a random integer between `0` and `max - 1`.
+     *
+     * Utility helper available to subclasses/runner logic.
+     *
+     * @param max Exclusive upper bound.
+     * @returns Random integer.
+     */
+    GetRandomInt: (max: number) => number;
+    /**
+     * Post unsolicited telemetry for a runner back to the manager.
+     *
+     * Uses the runner's current live serialisable state.
+     *
+     * @param id Runner id.
+     */
+    PostTelemetryById: (id: string) => void;
+    /**
+     * Get the manager communication port.
+     *
+     * @returns Manager communication port, or `null` if bootstrap is not complete.
+     */
+    get CollectorCollectorPort(): MessagePort | null;
+    /**
+     * Get the worker runtime options.
+     *
+     * @returns Worker options, or `null` if bootstrap is not complete.
+     */
+    get Options(): IWorkerOptions | null;
+    /**
+     * Factory method to create a concrete executable runner instance.
+     *
+     * This is the main extension point for subclasses.
+     *
+     * Subclasses should override this and return an `IRunnerInstance` that knows
+     * how to execute the actual domain work.
+     *
+     * Possible concrete runner behaviours:
+     * - REST/API load generation
+     * - browser automation
+     * - database execution
+     * - synthetic workflow orchestration
+     * - any arbitrary executable task
+     *
+     * Base implementation returns `null`.
+     *
+     * @param testRunnerTelemetryPayload Runner creation payload.
+     * @returns Concrete runner instance, or `null` if not implemented.
+     */
+    CreateAsyncRunner: (testRunnerTelemetryPayload: ITestRunnerTelemetryPayload) => Promise<IRunnerInstance | null>;
+    /**
+     * Main inbound message dispatcher for this worker runtime.
+     *
+     * This method is intended to be wired to the actual worker's message handler.
+     *
+     * Supported commands:
+     * - `MessagePort`
+     * - `AddRunner`
+     * - `StartRunner`
+     * - `StopRunner`
+     * - `TerminateRunner`
+     * - `PauseRunner`
+     * - `ResumeRunner`
+     * - `ResetRunner`
+     * - `ExecuteRunner`
+     * - `UpdateRunner`
+     * - `GetRunners`
+     *
+     * Behaviour:
+     * - interprets the inbound message
+     * - dispatches to the appropriate internal handler
+     * - bootstrap-initialises the worker on `MessagePort`
+     * - logs and ignores unknown commands
+     *
+     * @param data Raw inbound message payload.
+     */
+    ProcessMessage: (data: any) => Promise<void>;
+}
+//# sourceMappingURL=abstractRunnerExecutionWorker.d.ts.map

package/types/abstractRunnerExecutionWorker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"abstractRunnerExecutionWorker.d.ts","sourceRoot":"","sources":["../src/abstractRunnerExecutionWorker.ts"],"names":[],"mappings":";AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+CG;AAEH,OAAO,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAI7C,OAAO,EAIH,eAAe,EAEf,OAAO,EACP,2BAA2B,EAC3B,cAAc,EAMjB,MAAM,eAAe,CAAC;AAMvB,OAAO,EAAE,UAAU,EAAwB,MAAM,mBAAmB,CAAC;AAErE;;;;;;;GAOG;AACH,MAAM,WAAW,kBAAkB;IAC/B;;;;OAIG;IACH,cAAc,EAAE,eAAe,CAAC;IAEhC;;;;OAIG;IACH,MAAM,EAAE,OAAO,CAAC;IAEhB;;;OAGG;IACH,QAAQ,EAAE,OAAO,CAAC;CACrB;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,8BAAsB,6BAA6B;;IAqC/C;;;;;OAKG;IACH,IAAI,MAAM,IAAI,UAAU,CAEvB;IAoJD;;OAEG;;IAKH;;;;;;;OAOG;IACH,YAAY,GAAI,KAAK,MAAM,YAEzB;IAEF;;;;;;OAMG;IACH,iBAAiB,GAAI,IAAI,MAAM,UAE7B;IAEF;;;;OAIG;IACH,IAAI,sBAAsB,IAAI,WAAW,GAAG,IAAI,CAE/C;IAED;;;;OAIG;IACH,IAAI,OAAO,IAAI,cAAc,GAAG,IAAI,CAEnC;IAyCD;;;;;;;;;;;;;;;;;;;OAmBG;IACH,iBAAiB,GAAU,4BAA4B,2BAA2B,KAAG,OAAO,CAAC,eAAe,GAAG,IAAI,CAAC,CAElH;IAq0BF;;;;;;;;;;;;;;;;;;;;;;;;;OAyBG;IACH,cAAc,GAAU,MAAM,GAAG,mBAuE/B;CACL"}

package/types/archiveManager.d.ts

@@ -0,0 +1,172 @@
+ 
+/**
+ * ArchiveManager
+ * --------------
+ * Background lifecycle manager responsible for:
+ *
+ * - scanning all live workers/runners for runners that have reached an archiveable end state
+ * - stopping any active telemetry/instrument publishing for those runners
+ * - copying eligible runners into an in-memory archive list
+ * - marking runners as archived so they are not processed repeatedly
+ * - deleting archived runners from the live worker registry after a short delay
+ *
+ * High-level behaviour:
+ * 1. Periodically scan all workers and their runners
+ * 2. Identify runners in a terminal/archiveable state:
+ *    - completed
+ *    - error
+ *    - stopped
+ *    - terminated
+ * 3. For each matching runner:
+ *    - stop instrumentation publishing if active
+ *    - archive the runner unless it was terminated
+ *    - mark the runner as archived
+ *    - schedule deletion from the live registry after `archiveDeleteTimeout`
+ * 4. Repeat on a timed loop until `Terminate()` is called
+ *
+ * Notes:
+ * - Terminated runners are intentionally NOT added to the archive list,
+ *   but they are still marked as archived and later removed from the live registry.
+ * - The archive list is capped at `maxArchiveListLength`.
+ * - This class owns only the archive list and loop scheduling; live worker/runner
+ *   ownership remains with the {@link WorkerRegistry}.
+ */
+import { IRunner, IRunnerSearchFilters } from './commonTypes';
+import { ISTSLogger } from '@nsshunt/stsutils';
+import { WorkerRegistry } from './workerRegistry';
+/**
+ * Constructor options for {@link ArchiveManager}.
+ */
+export interface IArchiveManagerOptions {
+    /**
+     * Logger used for diagnostics and error reporting.
+     */
+    logger: ISTSLogger;
+    /**
+     * Maximum number of archived runner snapshots to keep in memory.
+     *
+     * When the archive exceeds this size, the oldest archived runner is removed.
+     */
+    maxArchiveListLength: number;
+    /**
+     * Shared live worker registry used to inspect workers/runners and delete
+     * archived runners from the active runtime graph.
+     */
+    workerRegistry: WorkerRegistry;
+}
+/**
+ * Archive manager for completed/stopped/failed runner instances.
+ */
+export declare class ArchiveManager {
+    /**
+     * Immutable runtime configuration for this archive manager.
+     */
+    private readonly options;
+    /**
+     * In-memory archive of serialised runner snapshots.
+     *
+     * Important:
+     * - This stores serialised runner DTOs, not live `IRunnerEx` instances.
+     * - The list is bounded by `maxArchiveListLength`.
+     */
+    private readonly archiveList;
+    /**
+     * Delay in seconds before removing an archived runner from the live worker registry.
+     *
+     * Purpose:
+     * - allows a short grace period after archiving
+     * - avoids immediate deletion of the live runner instance
+     *
+     * A value of `0` would disable delayed deletion.
+     */
+    private readonly archiveDeleteTimeout;
+    /**
+     * Timeout handle for the recurring archive scan loop.
+     *
+     * This is stored so the loop can be stopped later via {@link Terminate}.
+     */
+    private timeout;
+    /**
+     * Construct a new archive manager.
+     *
+     * @param options Logger, archive size cap, and worker registry dependencies.
+     */
+    constructor(options: IArchiveManagerOptions);
+    /**
+     * Execute a single archive scan cycle and schedule the next cycle.
+     *
+     * Behaviour:
+     * - scans all live workers and all live runners
+     * - collects runners eligible for archiving into a temporary `removeList`
+     * - processes the collected runners after a short delay
+     * - schedules the next loop execution
+     *
+     * Archiveable runner states:
+     * - `IRunnerState.completed`
+     * - `IRunnerState.error`
+     * - `IRunnerState.stopped`
+     * - `IRunnerState.terminated`
+     *
+     * Additional behaviour per matching runner:
+     * - If a publish instrument controller is attached, `EndPublish()` is called
+     * - If the runner state is NOT `terminated`, the runner is serialised and pushed
+     *   into the in-memory archive list
+     * - If the runner state IS `terminated`, it is skipped for archive storage
+     * - In both cases, the runner is marked `archived = true`
+     * - The live runner is scheduled for deletion from the worker registry after
+     *   `archiveDeleteTimeout`
+     *
+     * Loop scheduling:
+     * - If one or more runners were found, processing happens after 100 ms, then the
+     *   next scan is scheduled 1000 ms later
+     * - If none were found, the next scan is scheduled directly after 1000 ms
+     *
+     * Notes:
+     * - The short 100 ms processing delay helps separate detection and mutation phases.
+     * - In Node.js, delayed deletion timeouts are `unref()`'d so they do not keep the
+     *   process alive by themselves.
+     *
+     * @throws Re-throws unexpected errors after logging.
+     */
+    ProcessLoopExecutor: () => Promise<void>;
+    /**
+     * Get archived runner snapshots filtered by optional search criteria.
+     *
+     * Supported filters:
+     * - `plan`
+     * - `planInstanceId`
+     * - `tag`
+     * - `userDataKey`
+     *
+     * Filter behaviour:
+     * - If a filter property is absent/blank, it is ignored
+     * - All supplied filters are combined using logical AND
+     *
+     * Examples:
+     * - by runner plan name
+     * - by specific plan instance id
+     * - by tag membership
+     * - by existence of a userData key
+     *
+     * Notes:
+     * - This method returns archived DTOs (`IRunner[]`), not live runner instances
+     * - The archive list is in-memory only and bounded by `maxArchiveListLength`
+     *
+     * @param runnerSearchFilters Search/filter options to apply.
+     * @returns Filtered archive list. Returns an empty array on error.
+     */
+    GetArchiveList: (runnerSearchFilters: IRunnerSearchFilters) => Promise<IRunner[]>;
+    /**
+     * Stop the recurring archive scan loop.
+     *
+     * Behaviour:
+     * - Clears the currently scheduled scan timeout if present
+     * - Does not clear already scheduled delayed per-runner deletion timeouts
+     * - Does not modify the current archive list
+     *
+     * Intended use:
+     * - called during overall worker-manager shutdown/termination
+     */
+    Terminate: () => void;
+}
+//# sourceMappingURL=archiveManager.d.ts.map

package/types/archiveManager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"archiveManager.d.ts","sourceRoot":"","sources":["../src/archiveManager.ts"],"names":[],"mappings":";AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAEH,OAAO,EAAE,OAAO,EAAgB,oBAAoB,EAAE,MAAM,eAAe,CAAC;AAE5E,OAAO,EAAE,UAAU,EAAc,MAAM,mBAAmB,CAAC;AAO3D,OAAO,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAElD;;GAEG;AACH,MAAM,WAAW,sBAAsB;IACnC;;OAEG;IACH,MAAM,EAAE,UAAU,CAAC;IAEnB;;;;OAIG;IACH,oBAAoB,EAAE,MAAM,CAAC;IAE7B;;;OAGG;IACH,cAAc,EAAE,cAAc,CAAC;CAClC;AAED;;GAEG;AACH,qBAAa,cAAc;IACvB;;OAEG;IACH,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAyB;IAEjD;;;;;;OAMG;IACH,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAiB;IAE7C;;;;;;;;OAQG;IACH,OAAO,CAAC,QAAQ,CAAC,oBAAoB,CAAc;IAEnD;;;;OAIG;IACH,OAAO,CAAC,OAAO,CAAM;IAErB;;;;OAIG;gBACS,OAAO,EAAE,sBAAsB;IAI3C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAmCG;IACH,mBAAmB,sBA+JjB;IAEF;;;;;;;;;;;;;;;;;;;;;;;;;OAyBG;IACH,cAAc,GAAU,qBAAqB,oBAAoB,KAAG,OAAO,CAAC,OAAO,EAAE,CAAC,CA+BpF;IAEF;;;;;;;;;;OAUG;IACH,SAAS,aAIP;CACL"}

package/types/asyncRunnerInstanceManager.d.ts

@@ -0,0 +1,108 @@
+ 
+/**
+ * AsyncRunnerInstanceManager
+ * --------------------------
+ * Factory/creation manager responsible for constructing live {@link RunnerInstance}
+ * objects for a given worker.
+ *
+ * Responsibilities:
+ * - generate a unique runner id
+ * - build the hierarchical {@link IAsyncRunnerContext} for the runner
+ * - optionally create a child publish/instrument controller for the runner
+ * - construct and return a new live {@link RunnerInstance}
+ *
+ * High-level role in the architecture:
+ * - {@link WorkerInstance} owns runners
+ * - {@link AsyncRunnerInstanceManager} creates runners
+ * - {@link RunnerInstance} executes runner behaviour and communicates through the broker
+ *
+ * Notes:
+ * - This class does not register the runner into a worker; it only creates it.
+ * - Registration is handled elsewhere, typically by the worker that owns the runner.
+ * - This class centralises runner identity/context construction so that every runner
+ *   follows the same naming and instrumentation conventions.
+ */
+import { IWorkerEx, IRunnerEx, IRunnerOptions } from './commonTypes';
+import { PublishInstrumentController } from '@nsshunt/stsinstrumentmanagerclient';
+import { STSMessageBroker } from './messageBroker';
+/**
+ * Constructor options for {@link AsyncRunnerInstanceManager}.
+ */
+export interface IAsyncRunnerInstanceManagerOptions {
+    /**
+     * Id of the top-level worker manager that owns all workers/runners created through this factory.
+     */
+    workerManagerId: string;
+    /**
+     * Optional root publish/instrument controller.
+     *
+     * When supplied, a dedicated child publish controller is created for each new runner
+     * using the runner's async context.
+     */
+    instrumentController?: PublishInstrumentController;
+    /**
+     * Message broker used by created runner instances to send commands to the worker.
+     */
+    messageBroker: STSMessageBroker;
+}
+/**
+ * Factory/manager used to construct new live asynchronous runner instances.
+ *
+ * This class encapsulates:
+ * - runner id creation
+ * - async runner context creation
+ * - optional per-runner instrumentation publisher creation
+ * - `RunnerInstance` construction
+ */
+export declare class AsyncRunnerInstanceManager {
+    #private;
+    /**
+     * Construct a new async runner instance manager.
+     *
+     * @param options Worker-manager id, optional instrumentation controller, and message broker.
+     */
+    constructor(options: IAsyncRunnerInstanceManagerOptions);
+    /**
+     * Create a new live asynchronous runner instance for the supplied worker.
+     *
+     * Behaviour:
+     * - Generates a new unique runner id
+     * - Builds a hierarchical {@link IAsyncRunnerContext} for the runner
+     * - Optionally creates a child publish/instrument controller scoped to that runner
+     * - Constructs and returns a new {@link RunnerInstance}
+     *
+     * Async runner context structure:
+     *
+     * The generated context follows a 4-level hierarchy:
+     *
+     * 1. host
+     * 2. agent
+     * 3. worker/thread
+     * 4. runner
+     *
+     * The generated `nid` format is:
+     *
+     * `[level1]@[level2]^[level3]|[level4]`
+     *
+     * Concretely:
+     *
+     * `[hostName]@[agentId]-[userAgent]^[workerId]|[runnerId]`
+     *
+     * Where:
+     * - `hostName` identifies the host/runtime machine
+     * - `agentId-userAgent` identifies the logical agent/browser/session instance
+     * - `workerId` identifies the worker hosting the runner
+     * - `runnerId` identifies the runner inside that worker
+     *
+     * Notes:
+     * - This method only creates the runner instance; it does not add it to the worker's
+     *   internal runner map or push it into the underlying worker runtime.
+     * - That registration/bootstrap step is performed elsewhere by the owning worker.
+     *
+     * @param workerEx The live worker instance that will own the new runner.
+     * @param runnerOptions Runtime options/configuration for the new runner.
+     * @returns Newly constructed live runner instance.
+     */
+    CreateAsyncRunner: (workerEx: IWorkerEx, runnerOptions: IRunnerOptions) => IRunnerEx;
+}
+//# sourceMappingURL=asyncRunnerInstanceManager.d.ts.map

package/types/asyncRunnerInstanceManager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"asyncRunnerInstanceManager.d.ts","sourceRoot":"","sources":["../src/asyncRunnerInstanceManager.ts"],"names":[],"mappings":";AAEA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAGH,OAAO,EAAuB,SAAS,EAAE,SAAS,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAI1F,OAAO,EAAE,2BAA2B,EAAE,MAAM,qCAAqC,CAAC;AAOlF,OAAO,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AAInD;;GAEG;AACH,MAAM,WAAW,kCAAkC;IAC/C;;OAEG;IACH,eAAe,EAAE,MAAM,CAAC;IAExB;;;;;OAKG;IACH,oBAAoB,CAAC,EAAE,2BAA2B,CAAC;IAEnD;;OAEG;IACH,aAAa,EAAE,gBAAgB,CAAC;CACnC;AAED;;;;;;;;GAQG;AACH,qBAAa,0BAA0B;;IAMnC;;;;OAIG;gBACS,OAAO,EAAE,kCAAkC;IAIvD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAwCG;IACH,iBAAiB,GAAI,UAAU,SAAS,EAAE,eAAe,cAAc,KAAG,SAAS,CAsFjF;CACL"}