@nsshunt/stsrunnerframework 1.0.200 → 2.0.1

package/types/workerStateSynchroniser.d.ts

@@ -0,0 +1,161 @@
+ 
+/**
+ * WorkerStateSynchroniser
+ * =======================
+ *
+ * Synchronises the manager-side in-memory worker/runner model with the current
+ * state held inside the actual worker runtimes.
+ *
+ * Architectural role
+ * ------------------
+ * The manager-side registry (`WorkerRegistry`) stores live `IWorkerEx` and
+ * `IRunnerEx` objects. However, the true current runner state is maintained
+ * inside the actual worker runtime until it is pushed back or explicitly queried.
+ *
+ * `WorkerStateSynchroniser` provides the "pull" side of that synchronisation:
+ *
+ * - it asks each worker for its current runners via `GetRunners`
+ * - it applies the returned runner snapshots to the live manager-side runner objects
+ * - it then returns either:
+ *   - the full worker map, or
+ *   - the reduced/core worker map
+ *
+ * Responsibilities
+ * ----------------
+ * - issue `GetRunners` requests to all live workers
+ * - await all worker responses
+ * - apply returned runner state into the manager-side runtime graph
+ * - expose synchronised full and reduced worker views
+ *
+ * Design notes
+ * ------------
+ * - This class does not own workers or runners directly.
+ * - It relies on:
+ *   - {@link WorkerRegistry} for the live manager-side object graph
+ *   - {@link STSMessageBroker} for request/response communication
+ *   - {@link RunnerLifecycleManager} for applying runner state updates consistently
+ *
+ * Typical usage
+ * -------------
+ * - `GetSyncedWorkers()` when you want the full current worker/runners model
+ * - `GetSyncedWorkersCore(states)` when you want a lighter summary view,
+ *   optionally filtered by runner state
+ */
+import { IRunnerState, IWorkers, IWorkerCore } from './commonTypes';
+import { STSMessageBroker } from './messageBroker';
+import { WorkerRegistry } from './workerRegistry';
+import { RunnerLifecycleManager } from './runnerLifecycleManager';
+import { ISTSLogger } from '@nsshunt/stsutils';
+/**
+ * Constructor options for {@link WorkerStateSynchroniser}.
+ */
+export interface IWorkerStateSynchroniserOptions {
+    /**
+     * Logger used for diagnostics and error reporting.
+     */
+    logger: ISTSLogger;
+    /**
+     * Shared live worker/runner registry.
+     *
+     * This contains the manager-side runtime graph that will be updated during synchronisation.
+     */
+    workerRegistry: WorkerRegistry;
+    /**
+     * Shared message broker used to send `GetRunners` requests to workers and await responses.
+     */
+    messageBroker: STSMessageBroker;
+    /**
+     * Runner lifecycle manager used to apply incoming runner snapshots to live
+     * manager-side runner objects in a consistent way.
+     */
+    runnerLifecycleManager: RunnerLifecycleManager;
+}
+/**
+ * Synchronises live manager-side worker/runner state with the actual worker runtimes.
+ */
+export declare class WorkerStateSynchroniser {
+    /**
+     * Immutable runtime configuration and dependencies.
+     */
+    private readonly options;
+    /**
+     * Construct a new worker state synchroniser.
+     *
+     * @param options Logger, registry, message broker, and runner lifecycle collaborators.
+     */
+    constructor(options: IWorkerStateSynchroniserOptions);
+    /**
+     * Synchronise all live workers from their current worker-runtime state.
+     *
+     * Behaviour
+     * ---------
+     * 1. Resolve all live workers from the registry
+     * 2. Send `GetRunners` to each worker through the message broker
+     * 3. Await all worker responses
+     * 4. For each returned runner snapshot:
+     *    - resolve the owning worker from the registry
+     *    - resolve that worker's live runner map
+     *    - if the runner exists in the registry, apply the snapshot to the live runner
+     *      object using `RunnerLifecycleManager.SyncRunnerData(...)`
+     *
+     * Important notes
+     * ---------------
+     * - This method only updates existing manager-side runner objects.
+     * - It does not create missing runners if a worker returns a runner id that is
+     *   not already present in the registry.
+     * - It assumes the manager-side registry and worker runtime are already aligned
+     *   in terms of which runners exist.
+     *
+     * Error handling
+     * --------------
+     * - Logs and re-throws unexpected errors.
+     *
+     * @returns Resolves when all workers have been queried and all returned runner snapshots
+     *          have been applied to the manager-side runtime graph.
+     * @throws Re-throws unexpected errors after logging.
+     */
+    private SyncAllWorkers;
+    /**
+     * Get the full synchronised workers model.
+     *
+     * Behaviour
+     * ---------
+     * - First synchronises all workers by querying their current runtime state
+     * - Then returns the full serialisable workers map from the registry
+     *
+     * Returned model
+     * --------------
+     * The returned `IWorkers` structure includes:
+     * - all live workers
+     * - each worker's full serialisable runner set
+     *
+     * @returns Fully synchronised full workers model.
+     * @throws Re-throws unexpected errors after logging.
+     */
+    GetSyncedWorkers: () => Promise<IWorkers>;
+    /**
+     * Get the reduced/core synchronised workers model.
+     *
+     * Behaviour
+     * ---------
+     * - First synchronises all workers by querying their current runtime state
+     * - Then returns the reduced/core workers map from the registry
+     *
+     * Runner state filtering
+     * ----------------------
+     * - `undefined` => include all runners
+     * - `[]` => include all runners
+     * - populated array => include only runners whose state matches one of the supplied states
+     *
+     * Returned model
+     * --------------
+     * The returned structure includes a reduced representation of each worker and runner,
+     * suitable for lightweight status/dashboard style views.
+     *
+     * @param states Optional runner-state filter.
+     * @returns Fully synchronised reduced/core workers model.
+     * @throws Re-throws unexpected errors after logging.
+     */
+    GetSyncedWorkersCore: (states?: IRunnerState[]) => Promise<Record<string, IWorkerCore>>;
+}
+//# sourceMappingURL=workerStateSynchroniser.d.ts.map

package/types/workerStateSynchroniser.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"workerStateSynchroniser.d.ts","sourceRoot":"","sources":["../src/workerStateSynchroniser.ts"],"names":[],"mappings":";AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AAGH,OAAO,EAEH,YAAY,EAGZ,QAAQ,EACR,WAAW,EACd,MAAM,eAAe,CAAC;AAEvB,OAAO,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AACnD,OAAO,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAClD,OAAO,EAAE,sBAAsB,EAAE,MAAM,0BAA0B,CAAC;AAClE,OAAO,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAE/C;;GAEG;AACH,MAAM,WAAW,+BAA+B;IAC5C;;OAEG;IACH,MAAM,EAAE,UAAU,CAAC;IAEnB;;;;OAIG;IACH,cAAc,EAAE,cAAc,CAAC;IAE/B;;OAEG;IACH,aAAa,EAAE,gBAAgB,CAAC;IAEhC;;;OAGG;IACH,sBAAsB,EAAE,sBAAsB,CAAC;CAClD;AAED;;GAEG;AACH,qBAAa,uBAAuB;IAChC;;OAEG;IACH,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAkC;IAE1D;;;;OAIG;gBACS,OAAO,EAAE,+BAA+B;IAIpD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA6BG;IACH,OAAO,CAAC,cAAc,CAwDpB;IAEF;;;;;;;;;;;;;;;;OAgBG;IACH,gBAAgB,QAAa,OAAO,CAAC,QAAQ,CAAC,CAQ5C;IAEF;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACH,oBAAoB,GAAU,SAAS,YAAY,EAAE,KAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC,CAQ1F;CACL"}