@nsshunt/stsmessaging 1.0.78 → 1.0.79

package/README.IPCMessageHandlerPairManager.md

@@ -0,0 +1,1289 @@
+# IPCMessageHandlerPairManager
+
+`IPCMessageHandlerPairManager` manages a collection of `IPCMessageHandlerPair` instances on the **server / cluster primary** side.
+
+Each worker gets its own dedicated `IPCMessageHandlerPair`.
+
+The manager is responsible for:
+
+- maintaining the worker collection;
+- creating and removing worker pairs;
+- sending messages to one worker;
+- broadcasting messages to all workers;
+- registering events across every pair;
+- applying existing event registrations to workers added later;
+- automatically cleaning up worker pairs when workers exit.
+
+---
+
+# Architecture
+
+The manager uses a **collection of one-to-one IPC pairs**.
+
+```text
+IPCMessageHandlerPairManager
+│
+├── Worker 1 -> IPCMessageHandlerPair -> MessagingManager
+├── Worker 2 -> IPCMessageHandlerPair -> MessagingManager
+├── Worker 3 -> IPCMessageHandlerPair -> MessagingManager
+└── Worker 4 -> IPCMessageHandlerPair -> MessagingManager
+```
+
+Each `IPCMessageHandlerPair` is responsible for exactly one primary/worker IPC relationship.
+
+The manager owns the collection.
+
+This separates responsibilities cleanly:
+
+```text
+IPCMessageHandlerPairManager
+    -> worker collection
+    -> worker lifecycle
+    -> targeted messaging
+    -> broadcasting
+    -> event propagation
+
+IPCMessageHandlerPair
+    -> one worker connection
+    -> IPC send/receive
+    -> event dispatch
+    -> request/response messaging
+
+MessagingManager
+    -> message IDs
+    -> request/response correlation
+    -> timeouts
+    -> message protocol
+```
+
+---
+
+# Why This Class Exists
+
+Previously, `IPCMessageHandler` combined two separate responsibilities:
+
+```text
+IPC connection handling
++
+worker collection management
+```
+
+`IPCMessageHandlerPairManager` separates those responsibilities.
+
+Instead of:
+
+```text
+IPCMessageHandler
+    |
+    +-- Worker 1
+    +-- Worker 2
+    +-- Worker 3
+```
+
+the architecture becomes:
+
+```text
+IPCMessageHandlerPairManager
+    |
+    +-- IPCMessageHandlerPair -> Worker 1
+    +-- IPCMessageHandlerPair -> Worker 2
+    +-- IPCMessageHandlerPair -> Worker 3
+```
+
+This allows the pair class to remain focused on a single IPC connection while the manager handles multi-worker behavior.
+
+---
+
+# File
+
+```text
+ipcMessageHandlerPairManager.ts
+```
+
+---
+
+# Constructor
+
+```ts
+new IPCMessageHandlerPairManager(options);
+```
+
+## Options
+
+```ts
+export interface IPCMessageHandlerPairManagerOptions {
+    logger: ISTSLogger;
+    requestResponseMessageTimeout: number;
+    namespace: string;
+    ignoreEvents?: string[];
+    autoRemoveOnWorkerExit?: boolean;
+}
+```
+
+---
+
+## logger
+
+Logger passed to every `IPCMessageHandlerPair`.
+
+```ts
+logger: ISTSLogger;
+```
+
+---
+
+## requestResponseMessageTimeout
+
+Request/response timeout passed to each pair.
+
+```ts
+requestResponseMessageTimeout: 5000;
+```
+
+Each pair creates its own `MessagingManager`, so each worker connection has its own in-flight request tracking and timeout handling.
+
+---
+
+## namespace
+
+Messaging namespace shared by all pairs managed by this instance.
+
+Example:
+
+```ts
+namespace: "STS_WORKERS";
+```
+
+All worker pairs can use the same namespace while their underlying `MessagingManager` instances maintain their own message identities.
+
+---
+
+## ignoreEvents
+
+Optional event names whose errors should be ignored by the pair's `emit()` implementation.
+
+```ts
+ignoreEvents: ["optional-event"];
+```
+
+---
+
+## autoRemoveOnWorkerExit
+
+Controls whether a pair is automatically removed when its cluster worker exits.
+
+```ts
+autoRemoveOnWorkerExit: true;
+```
+
+This is the default.
+
+Disable automatic cleanup with:
+
+```ts
+autoRemoveOnWorkerExit: false;
+```
+
+This can be useful when another higher-level process manager already owns worker lifecycle cleanup.
+
+---
+
+# Internal Collections
+
+The manager maintains three important collections.
+
+## Pair Collection
+
+```ts
+Map<number, IPCMessageHandlerPair>;
+```
+
+The key is the Node.js cluster worker ID.
+
+Conceptually:
+
+```text
+1 -> IPCMessageHandlerPair
+2 -> IPCMessageHandlerPair
+3 -> IPCMessageHandlerPair
+```
+
+---
+
+## Worker Collection
+
+The manager also retains the actual `Worker` references.
+
+Conceptually:
+
+```text
+1 -> Worker
+2 -> Worker
+3 -> Worker
+```
+
+This allows worker lifecycle management to remain separate from the pair abstraction.
+
+---
+
+## Event Collection
+
+Manager-level event handlers are also retained.
+
+Conceptually:
+
+```text
+"worker-ready" -> callback
+"status"       -> callback
+"shutdown"     -> callback
+```
+
+This is important because workers can be added after events have already been registered.
+
+---
+
+# size
+
+Returns the number of workers currently managed.
+
+```ts
+manager.size;
+```
+
+Example:
+
+```ts
+console.log(manager.size);
+```
+
+If three workers are registered:
+
+```text
+3
+```
+
+---
+
+# pairs
+
+Returns a read-only view of the current worker-to-pair map.
+
+```ts
+manager.pairs;
+```
+
+Example:
+
+```ts
+for (const [workerId, pair] of manager.pairs) {
+    console.log(workerId, pair);
+}
+```
+
+---
+
+# workerIds
+
+Returns all worker IDs currently managed.
+
+```ts
+manager.workerIds;
+```
+
+Example:
+
+```ts
+const ids = manager.workerIds;
+```
+
+Possible result:
+
+```ts
+[1, 2, 3];
+```
+
+---
+
+# AddWorker()
+
+Adds a cluster worker to the manager and creates its dedicated `IPCMessageHandlerPair`.
+
+```ts
+manager.AddWorker(worker);
+```
+
+Example:
+
+```ts
+const worker = cluster.fork();
+
+manager.AddWorker(worker);
+```
+
+Internally the manager:
+
+1. checks whether the worker is already registered;
+2. creates a new `IPCMessageHandlerPair`;
+3. configures the pair with `role: "SERVER"`;
+4. copies all existing manager event registrations into the pair;
+5. starts the pair with the worker;
+6. stores the pair;
+7. stores the worker;
+8. optionally registers automatic worker-exit cleanup.
+
+Conceptually:
+
+```text
+AddWorker(worker)
+        |
+        v
+Create IPCMessageHandlerPair
+        |
+        v
+Apply existing events
+        |
+        v
+pair.Start(worker)
+        |
+        v
+Store pair + worker
+```
+
+---
+
+## Existing Worker
+
+If the same `Worker` instance is already registered, the existing pair is returned.
+
+```ts
+const pair1 = manager.AddWorker(worker);
+const pair2 = manager.AddWorker(worker);
+
+pair1 === pair2;
+```
+
+Result:
+
+```text
+true
+```
+
+---
+
+## Reused Worker ID
+
+If a worker ID already exists but belongs to a different `Worker` instance, the old pair is removed before the new one is added.
+
+This helps avoid stale worker/pair relationships.
+
+---
+
+# RemoveWorker()
+
+Stops and removes a worker's pair.
+
+The method accepts either:
+
+```ts
+manager.RemoveWorker(worker);
+```
+
+or:
+
+```ts
+manager.RemoveWorker(worker.id);
+```
+
+It returns:
+
+```ts
+boolean;
+```
+
+`true` means a worker/pair was removed.
+
+`false` means no pair existed for that worker ID.
+
+Internally it:
+
+1. removes any automatic `"exit"` listener;
+2. stops the pair;
+3. removes the pair;
+4. removes the worker reference.
+
+---
+
+# HasWorker()
+
+Checks whether a worker is currently managed.
+
+```ts
+manager.HasWorker(workerId);
+```
+
+Example:
+
+```ts
+if (manager.HasWorker(worker.id)) {
+    console.log("Worker is registered");
+}
+```
+
+---
+
+# GetPair()
+
+Returns the `IPCMessageHandlerPair` associated with a worker ID.
+
+```ts
+const pair = manager.GetPair(workerId);
+```
+
+Return type:
+
+```ts
+IPCMessageHandlerPair | undefined;
+```
+
+This is useful when direct access to a pair is required.
+
+---
+
+# GetWorker()
+
+Returns the cluster `Worker` associated with a worker ID.
+
+```ts
+const worker = manager.GetWorker(workerId);
+```
+
+Return type:
+
+```ts
+Worker | undefined;
+```
+
+---
+
+# Event Registration
+
+The manager exposes:
+
+```ts
+on();
+off();
+```
+
+These behave differently from calling `on()` directly on one pair because the registration applies across the entire pair collection.
+
+---
+
+# on()
+
+Registers an incoming IPC event across all workers.
+
+```ts
+manager.on(event, callback);
+```
+
+Example:
+
+```ts
+manager.on("worker-ready", (data, callback) => {
+    console.log("Worker ready:", data);
+
+    callback({
+        status: "OK",
+    });
+});
+```
+
+The handler is applied to:
+
+```text
+Pair 1
+Pair 2
+Pair 3
+...
+```
+
+---
+
+## Event Propagation to Future Workers
+
+The manager also remembers event registrations.
+
+For example:
+
+```ts
+manager.on("get-status", callback);
+
+manager.AddWorker(worker1);
+manager.AddWorker(worker2);
+```
+
+Both workers receive the event registration even though they were added after `on()` was called.
+
+The reverse order also works:
+
+```ts
+manager.AddWorker(worker1);
+manager.AddWorker(worker2);
+
+manager.on("get-status", callback);
+```
+
+The event is immediately registered on both existing pairs.
+
+Therefore these two sequences are equivalent:
+
+```text
+Register event
+Add workers
+```
+
+and:
+
+```text
+Add workers
+Register event
+```
+
+This is an important responsibility of the manager because every `IPCMessageHandlerPair` owns its own event map.
+
+---
+
+# off()
+
+Removes an event from all current pairs.
+
+```ts
+manager.off("get-status");
+```
+
+The event is also removed from the manager's retained event collection, so workers added later will not receive it.
+
+---
+
+# Targeted Messaging
+
+One of the main benefits of the pair-based architecture is that the manager can target an individual worker directly.
+
+---
+
+# SendMessageTo()
+
+Sends a raw request/response payload to one worker.
+
+```ts
+const response = await manager.SendMessageTo(workerId, payload);
+```
+
+Example:
+
+```ts
+const response = await manager.SendMessageTo(worker.id, {
+    command: "status",
+});
+```
+
+Conceptually:
+
+```text
+Manager
+   |
+   +------> Pair 2 ------> Worker 2
+```
+
+Only the selected worker receives the message.
+
+---
+
+# emitTo()
+
+Sends an event to one worker and returns its response.
+
+```ts
+const response = await manager.emitTo(workerId, event, ...args);
+```
+
+Example:
+
+```ts
+const response = await manager.emitTo(worker.id, "get-status");
+```
+
+With arguments:
+
+```ts
+const response = await manager.emitTo(
+    worker.id,
+    "process-resource",
+    resourceId
+);
+```
+
+Conceptually:
+
+```text
+Primary
+   |
+   v
+Manager
+   |
+   v
+Pair(workerId)
+   |
+   v
+Worker
+```
+
+---
+
+# emitNoResponseTo()
+
+Sends a fire-and-forget event to one worker.
+
+```ts
+await manager.emitNoResponseTo(workerId, event, ...args);
+```
+
+Example:
+
+```ts
+await manager.emitNoResponseTo(worker.id, "refresh-config");
+```
+
+No response is expected.
+
+---
+
+# Broadcasting
+
+The manager provides explicit broadcast operations.
+
+This is intentionally different from `IPCMessageHandler`, where server-side `SendMessage()` implicitly meant "send to every worker."
+
+With the pair manager the caller chooses explicitly between:
+
+```text
+Send to one worker
+```
+
+and:
+
+```text
+Send to all workers
+```
+
+---
+
+# SendMessageToAll()
+
+Sends a raw payload to all workers.
+
+```ts
+const responses = await manager.SendMessageToAll(payload);
+```
+
+Return type:
+
+```ts
+IPCMessageHandlerPairManagerResponse[]
+```
+
+Each result contains:
+
+```ts
+{
+    (workerId, response);
+}
+```
+
+Example:
+
+```ts
+const responses = await manager.SendMessageToAll({
+    command: "status",
+});
+
+for (const result of responses) {
+    console.log(result.workerId, result.response);
+}
+```
+
+---
+
+## Promise.all() Behavior
+
+`SendMessageToAll()` uses `Promise.all()` semantics.
+
+Therefore if one worker rejects or times out:
+
+```text
+Worker 1 -> success
+Worker 2 -> timeout
+Worker 3 -> success
+```
+
+the entire broadcast Promise rejects.
+
+Use `SendMessageToAllSettled()` when every worker result is required regardless of individual failures.
+
+---
+
+# SendMessageToAllSettled()
+
+Broadcasts a raw payload without allowing one failed worker to reject the complete operation.
+
+```ts
+const responses = await manager.SendMessageToAllSettled(payload);
+```
+
+Each result contains:
+
+```ts
+{
+    workerId,
+    status,
+    response?,
+    error?
+}
+```
+
+Possible result:
+
+```ts
+[
+    {
+        workerId: 1,
+        status: "fulfilled",
+        response: {
+            status: "OK",
+        },
+    },
+    {
+        workerId: 2,
+        status: "rejected",
+        error: ...
+    },
+    {
+        workerId: 3,
+        status: "fulfilled",
+        response: {
+            status: "OK",
+        },
+    },
+]
+```
+
+This is generally safer for operational broadcasts where one failed worker should not hide successful responses from the others.
+
+---
+
+# emitToAll()
+
+Broadcasts an event to all workers.
+
+```ts
+const responses = await manager.emitToAll(event, ...args);
+```
+
+Example:
+
+```ts
+const responses = await manager.emitToAll("get-status");
+```
+
+Conceptually:
+
+```text
+                    Pair 1 -> Worker 1
+                   /
+Manager ----------- Pair 2 -> Worker 2
+                   \
+                    Pair 3 -> Worker 3
+```
+
+Each response includes the associated worker ID.
+
+---
+
+# emitToAllSettled()
+
+Broadcasts an event to all workers and returns the result of every worker independently.
+
+```ts
+const responses = await manager.emitToAllSettled("get-status");
+```
+
+Example:
+
+```ts
+for (const result of responses) {
+    if (result.status === "fulfilled") {
+        console.log(`Worker ${result.workerId}`, result.response);
+    } else {
+        console.error(`Worker ${result.workerId} failed`, result.error);
+    }
+}
+```
+
+This is useful for:
+
+- health checks;
+- worker status collection;
+- cluster diagnostics;
+- configuration refresh;
+- coordinated operations across many workers.
+
+---
+
+# emitNoResponseToAll()
+
+Broadcasts a fire-and-forget event to every worker.
+
+```ts
+await manager.emitNoResponseToAll(event, ...args);
+```
+
+Example:
+
+```ts
+await manager.emitNoResponseToAll("refresh-config");
+```
+
+Conceptually:
+
+```text
+Manager
+  |
+  +----> Worker 1
+  +----> Worker 2
+  +----> Worker 3
+```
+
+No worker response is expected.
+
+---
+
+# Automatic Worker Cleanup
+
+By default:
+
+```ts
+autoRemoveOnWorkerExit !== false;
+```
+
+causes the manager to register:
+
+```ts
+worker.once("exit", ...)
+```
+
+When the worker exits, the manager automatically removes its pair.
+
+Conceptually:
+
+```text
+Worker exits
+    |
+    v
+RemoveWorker(workerId)
+    |
+    +-- remove exit listener
+    +-- pair.Stop()
+    +-- remove pair
+    +-- remove worker
+```
+
+This prevents dead worker references from remaining in the collection.
+
+---
+
+# Disabling Automatic Cleanup
+
+If another process manager already owns worker cleanup:
+
+```ts
+const manager = new IPCMessageHandlerPairManager({
+    logger,
+    requestResponseMessageTimeout: 5000,
+    namespace: "STS_WORKERS",
+    autoRemoveOnWorkerExit: false,
+});
+```
+
+The caller must then explicitly perform:
+
+```ts
+manager.RemoveWorker(worker.id);
+```
+
+---
+
+# Stop()
+
+Stops every managed pair and clears the active worker collection.
+
+```ts
+manager.Stop();
+```
+
+Conceptually:
+
+```text
+Before:
+
+Manager
+├── Pair 1 -> Worker 1
+├── Pair 2 -> Worker 2
+└── Pair 3 -> Worker 3
+
+
+manager.Stop()
+
+
+After:
+
+Manager
+```
+
+Each pair is stopped before removal.
+
+---
+
+## Event Registrations Are Retained
+
+`Stop()` intentionally does not clear manager-level event registrations.
+
+For example:
+
+```ts
+manager.on("get-status", callback);
+
+manager.Stop();
+
+manager.AddWorker(newWorker);
+```
+
+`newWorker` still receives the `"get-status"` registration.
+
+This allows a manager to be stopped and reused without rebuilding all of its event configuration.
+
+---
+
+# Typical Primary Process Usage
+
+```ts
+import cluster from "node:cluster";
+
+import { IPCMessageHandlerPairManager } from "./ipcMessageHandlerPairManager.js";
+
+const manager = new IPCMessageHandlerPairManager({
+    logger,
+    requestResponseMessageTimeout: 5000,
+    namespace: "STS_WORKERS",
+});
+
+manager.on("worker-ready", (data, callback) => {
+    console.log("Worker ready:", data);
+
+    callback({
+        status: "OK",
+    });
+});
+
+const worker1 = cluster.fork();
+const worker2 = cluster.fork();
+const worker3 = cluster.fork();
+
+manager.AddWorker(worker1);
+manager.AddWorker(worker2);
+manager.AddWorker(worker3);
+```
+
+Result:
+
+```text
+manager
+│
+├── worker1 -> pair1
+├── worker2 -> pair2
+└── worker3 -> pair3
+```
+
+---
+
+# Send to One Worker
+
+```ts
+const response = await manager.emitTo(worker2.id, "get-status");
+
+console.log(response);
+```
+
+Only `worker2` receives the event.
+
+---
+
+# Send to All Workers
+
+```ts
+const responses = await manager.emitToAll("get-status");
+
+console.log(responses);
+```
+
+Every registered worker receives the event.
+
+---
+
+# Safe Broadcast
+
+```ts
+const results = await manager.emitToAllSettled("get-status");
+
+for (const result of results) {
+    if (result.status === "fulfilled") {
+        console.log(`Worker ${result.workerId} OK`, result.response);
+    } else {
+        console.log(`Worker ${result.workerId} FAILED`, result.error);
+    }
+}
+```
+
+---
+
+# Worker-Side Usage
+
+The worker does **not** use `IPCMessageHandlerPairManager`.
+
+Each worker uses one `IPCMessageHandlerPair`.
+
+```ts
+import { IPCMessageHandlerPair } from "./ipcMessageHandlerPair.js";
+
+const ipc = new IPCMessageHandlerPair({
+    logger,
+    requestResponseMessageTimeout: 5000,
+    namespace: "STS_WORKERS",
+    role: "CLIENT",
+});
+
+ipc.on("get-status", (callback) => {
+    callback({
+        pid: process.pid,
+        status: "OK",
+    });
+});
+
+ipc.Start();
+```
+
+Architecture:
+
+```text
+PRIMARY
+
+IPCMessageHandlerPairManager
+        |
+        +-- Pair 1
+        +-- Pair 2
+        +-- Pair 3
+
+
+WORKERS
+
+Worker 1
+    |
+    +-- IPCMessageHandlerPair(CLIENT)
+
+Worker 2
+    |
+    +-- IPCMessageHandlerPair(CLIENT)
+
+Worker 3
+    |
+    +-- IPCMessageHandlerPair(CLIENT)
+```
+
+---
+
+# Difference from IPCMessageHandlerPair
+
+`IPCMessageHandlerPairManager` and `IPCMessageHandlerPair` have deliberately different responsibilities.
+
+## IPCMessageHandlerPair
+
+Represents one IPC relationship.
+
+```text
+Primary <----------> Worker
+```
+
+It handles:
+
+- one worker;
+- message sending;
+- message receiving;
+- event dispatch;
+- request/response communication.
+
+---
+
+## IPCMessageHandlerPairManager
+
+Represents a collection of those relationships.
+
+```text
+Manager
+│
+├── Pair -> Worker 1
+├── Pair -> Worker 2
+└── Pair -> Worker 3
+```
+
+It handles:
+
+- worker collection;
+- pair creation;
+- pair removal;
+- targeted worker selection;
+- broadcasts;
+- event propagation;
+- worker cleanup.
+
+---
+
+# Difference from IPCMessageHandler
+
+`IPCMessageHandlerPairManager` replaces the multi-worker responsibilities that were previously built directly into `IPCMessageHandler`.
+
+## IPCMessageHandler
+
+The old model combines:
+
+```text
+worker collection
++
+IPC connection handling
++
+broadcasting
++
+event handling
+```
+
+inside one class.
+
+Conceptually:
+
+```text
+IPCMessageHandler
+│
+├── Worker 1
+├── Worker 2
+└── Worker 3
+```
+
+---
+
+## IPCMessageHandlerPairManager
+
+The pair-manager model separates the responsibilities:
+
+```text
+IPCMessageHandlerPairManager
+│
+├── IPCMessageHandlerPair -> Worker 1
+├── IPCMessageHandlerPair -> Worker 2
+└── IPCMessageHandlerPair -> Worker 3
+```
+
+The manager manages the collection.
+
+Each pair manages one connection.
+
+---
+
+# Comparison
+
+| Feature                          | IPCMessageHandlerPairManager | IPCMessageHandlerPair      | IPCMessageHandler            |
+| -------------------------------- | ---------------------------- | -------------------------- | ---------------------------- |
+| Primary purpose                  | Manage many IPC pairs        | Manage one IPC connection  | Manage many workers directly |
+| Relationship                     | One-to-many via pairs        | One-to-one                 | One-to-many                  |
+| Stores worker collection         | Yes                          | No                         | Yes                          |
+| Stores one worker                | Per pair                     | Yes                        | No                           |
+| Creates pair per worker          | Yes                          | N/A                        | No                           |
+| Target one worker                | Yes                          | Naturally                  | Not its main model           |
+| Broadcast                        | Yes                          | No                         | Yes                          |
+| Event propagation                | Across all pairs             | One pair only              | Internal collection          |
+| Future-worker event registration | Yes                          | N/A                        | N/A                          |
+| Automatic worker cleanup         | Yes                          | No manager-level lifecycle | Manual client removal        |
+| Separation of concerns           | Strong                       | Strong                     | More combined                |
+| Recommended server abstraction   | Yes                          | Used by manager            | Older combined model         |
+
+---
+
+# Recommended Responsibility Model
+
+The intended architecture is:
+
+```text
+Process / Worker Manager
+        |
+        v
+IPCMessageHandlerPairManager
+        |
+        +-------------------+
+        |                   |
+        v                   v
+IPCMessageHandlerPair   IPCMessageHandlerPair
+        |                   |
+        v                   v
+MessagingManager        MessagingManager
+        |                   |
+        v                   v
+Worker 1               Worker 2
+```
+
+Responsibilities should remain:
+
+```text
+Process Manager
+    -> decides when workers should exist
+
+IPCMessageHandlerPairManager
+    -> manages IPC relationships for those workers
+
+IPCMessageHandlerPair
+    -> manages one IPC relationship
+
+MessagingManager
+    -> manages the message protocol
+```
+
+---
+
+# When to Use IPCMessageHandlerPairManager
+
+Use `IPCMessageHandlerPairManager` on the cluster primary/server side when:
+
+- multiple workers exist;
+- each worker should have its own `IPCMessageHandlerPair`;
+- individual workers must be addressable;
+- broadcasts are required;
+- worker lifecycle cleanup should be centralized;
+- event registrations should automatically apply to every pair.
+
+The key distinction is:
+
+```text
+IPCMessageHandlerPair
+    = "this worker connection"
+
+IPCMessageHandlerPairManager
+    = "all of my worker connections"
+```
+
+This makes the pair manager the natural server-side abstraction for managing IPC communication across a Node.js worker cluster.