@nsshunt/stsmessaging 1.0.78 → 1.0.79

package/README.IPCMessageHandler.md

@@ -0,0 +1,624 @@
+# IPCMessageHandler
+
+`IPCMessageHandler` provides IPC-based request/response and event messaging between a Node.js cluster primary process and **multiple worker processes**.
+
+It is built on top of `MessagingManager` and exposes an event-oriented API using `on()`, `off()`, `emit()`, and `emitNoResponse()`.
+
+---
+
+## Purpose
+
+Use `IPCMessageHandler` when one server/primary process needs to communicate with a **collection of worker processes**.
+
+Typical topology:
+
+```text
+                      Worker 1
+                     /
+Primary / Server --- Worker 2
+                     \
+                      Worker 3
+```
+
+The primary process maintains the worker collection inside the message handler and can broadcast messages or events to all registered workers.
+
+---
+
+## Key Characteristics
+
+- Supports `SERVER` and `CLIENT` roles.
+- Designed for **one primary process to many workers**.
+- Maintains an internal collection of workers/clients.
+- Workers are registered with `AddClient()`.
+- Workers are removed with `RemoveClient()`.
+- Server-side `SendMessage()` sends the message to **all registered workers**.
+- Server-side `emitNoResponse()` sends the event to **all registered workers**.
+- Request/response sends are aggregated with `Promise.all()`.
+- Uses `MessagingManager` for the underlying request/response message protocol.
+- Supports event-style request handling through `on()` and `off()`.
+- Supports request messages that expect a response.
+- Supports fire-and-forget request messages through `emitNoResponse()`.
+
+---
+
+## Constructor
+
+```ts
+new IPCMessageHandler(options);
+```
+
+### Options
+
+```ts
+export interface IPCMessageHandlerOptions {
+    logger: ISTSLogger;
+    requestResponseMessageTimeout: number;
+    namespace: string;
+    role: "SERVER" | "CLIENT";
+    ignoreEvents?: string[];
+}
+```
+
+### `logger`
+
+Logger used when message processing or event emission fails.
+
+### `requestResponseMessageTimeout`
+
+Maximum time allowed for request/response messaging.
+
+On the client side this value is passed directly to `MessagingManager`.
+
+### `namespace`
+
+Namespace used by the underlying messaging layer.
+
+### `role`
+
+Determines how the handler is configured.
+
+```ts
+role: "SERVER";
+```
+
+Configures the handler for the cluster primary/server process.
+
+```ts
+role: "CLIENT";
+```
+
+Configures the handler for a worker/client process.
+
+### `ignoreEvents`
+
+Optional collection of event names whose errors should be ignored by `emit()`.
+
+---
+
+# Server Role
+
+When configured as:
+
+```ts
+role: "SERVER";
+```
+
+the handler is designed to manage **multiple workers**.
+
+The server-side handler keeps an internal client collection:
+
+```ts
+#clients: Record<string, IClientRecord> = {};
+```
+
+Each registered worker has:
+
+- the worker/client object;
+- its associated message listener.
+
+---
+
+## AddClient()
+
+```ts
+AddClient(client): string
+```
+
+Registers a worker with the handler.
+
+Example:
+
+```ts
+const workerId = ipcHandler.AddClient(worker);
+```
+
+`AddClient()`:
+
+1. Creates a unique identifier.
+2. Registers a `"message"` listener on the worker.
+3. Routes incoming messages into `MessagingManager.ProcessMessage()`.
+4. Stores the worker and listener in the internal client collection.
+5. Returns the generated client ID.
+
+Conceptually:
+
+```text
+IPCMessageHandler
+│
+├── client-id-1 -> Worker 1
+├── client-id-2 -> Worker 2
+└── client-id-3 -> Worker 3
+```
+
+---
+
+## RemoveClient()
+
+```ts
+RemoveClient(id);
+```
+
+Removes a previously registered worker.
+
+Example:
+
+```ts
+ipcHandler.RemoveClient(workerId);
+```
+
+The method:
+
+1. Finds the worker record.
+2. Removes its `"message"` listener.
+3. Removes the worker from the internal collection.
+
+---
+
+## clients
+
+```ts
+ipcHandler.clients;
+```
+
+Returns the current internal worker/client collection.
+
+---
+
+# Client Role
+
+When configured as:
+
+```ts
+role: "CLIENT";
+```
+
+the handler communicates with the parent process using Node.js process IPC.
+
+Outgoing messages use:
+
+```ts
+process.send(...)
+```
+
+Incoming messages are received with:
+
+```ts
+process.on("message", ...)
+```
+
+The worker does not maintain a collection of other workers.
+
+---
+
+# Start()
+
+```ts
+ipcHandler.Start();
+```
+
+Starts the underlying `MessagingManager`.
+
+No worker argument is required.
+
+On the server side, workers are managed separately through `AddClient()` and `RemoveClient()`.
+
+---
+
+# Stop()
+
+```ts
+ipcHandler.Stop();
+```
+
+Stops the underlying `MessagingManager`.
+
+Worker message listeners registered by `AddClient()` should be managed through `RemoveClient()`.
+
+---
+
+# SendMessage()
+
+```ts
+await ipcHandler.SendMessage(payload);
+```
+
+Sends a request message.
+
+## Client behavior
+
+When running as a client:
+
+```text
+Worker -> Primary
+```
+
+a single message is sent to the parent process.
+
+## Server behavior
+
+When running as a server:
+
+```text
+Primary -> Worker 1
+        -> Worker 2
+        -> Worker 3
+```
+
+the message is sent to **every registered worker**.
+
+The individual requests are collected into an array and executed using:
+
+```ts
+Promise.all(...)
+```
+
+The returned value therefore represents the results from all workers.
+
+Conceptually:
+
+```ts
+{
+    result: [worker1Response, worker2Response, worker3Response];
+}
+```
+
+This broadcast behavior is one of the most important characteristics of `IPCMessageHandler`.
+
+---
+
+# Event Registration
+
+## on()
+
+```ts
+ipcHandler.on(eventName, callback);
+```
+
+Registers a callback for an incoming IPC event.
+
+Example:
+
+```ts
+ipcHandler.on("get-status", (callback) => {
+    callback({
+        status: "OK",
+        pid: process.pid,
+    });
+});
+```
+
+Only one callback is stored for a given event name.
+
+Registering the same event again replaces the previous callback.
+
+---
+
+## off()
+
+```ts
+ipcHandler.off(eventName);
+```
+
+Removes the registered callback for an event.
+
+---
+
+# emit()
+
+```ts
+ipcHandler.emit(eventName, ...args, callback);
+```
+
+Sends an event that expects a response.
+
+Example:
+
+```ts
+ipcHandler.emit("get-status", (response) => {
+    console.log(response);
+});
+```
+
+Internally the event is converted into a messaging payload containing:
+
+```ts
+{
+    __eventName: eventName,
+    args: [...]
+}
+```
+
+The final argument is treated as the response callback.
+
+---
+
+## Server-side emit behavior
+
+Because `emit()` ultimately calls `SendMessage()`, a server-side `emit()` is broadcast to **all registered workers**.
+
+Therefore:
+
+```ts
+ipcHandler.emit("get-status", callback);
+```
+
+can produce responses from multiple workers.
+
+Conceptually:
+
+```text
+Primary
+  |
+  +----> Worker 1
+  |
+  +----> Worker 2
+  |
+  +----> Worker 3
+```
+
+---
+
+# emitNoResponse()
+
+```ts
+await ipcHandler.emitNoResponse(eventName, ...args);
+```
+
+Sends a fire-and-forget event.
+
+No response callback is expected.
+
+## Client behavior
+
+```text
+Worker -> Primary
+```
+
+## Server behavior
+
+The event is sent to **every registered worker**.
+
+```text
+Primary
+  |
+  +----> Worker 1
+  +----> Worker 2
+  +----> Worker 3
+```
+
+---
+
+# Message Processing
+
+Incoming request messages are processed by `#processPayload()`.
+
+The payload must contain:
+
+```ts
+requestPayload.__eventName;
+```
+
+The corresponding event callback is located in the internal event collection.
+
+Two request types are handled:
+
+```text
+REQUEST
+REQUEST_NO_RESPONSE
+```
+
+## REQUEST
+
+The registered callback receives the request arguments followed by a response callback.
+
+Conceptually:
+
+```ts
+handler.on("event-name", (...args, callback) => {
+    callback(response);
+});
+```
+
+## REQUEST_NO_RESPONSE
+
+The registered event callback is invoked without a response callback.
+
+---
+
+# Typical Server Usage
+
+```ts
+const ipcHandler = new IPCMessageHandler({
+    logger,
+    requestResponseMessageTimeout: 5000,
+    namespace: "workers",
+    role: "SERVER",
+});
+
+ipcHandler.Start();
+
+const worker1Id = ipcHandler.AddClient(worker1);
+const worker2Id = ipcHandler.AddClient(worker2);
+const worker3Id = ipcHandler.AddClient(worker3);
+
+ipcHandler.emit("refresh-config", (responses) => {
+    console.log(responses);
+});
+```
+
+The event is sent to all three workers.
+
+---
+
+# Typical Worker Usage
+
+```ts
+const ipcHandler = new IPCMessageHandler({
+    logger,
+    requestResponseMessageTimeout: 5000,
+    namespace: "workers",
+    role: "CLIENT",
+});
+
+ipcHandler.on("refresh-config", (callback) => {
+    // Refresh configuration.
+
+    callback({
+        pid: process.pid,
+        status: "OK",
+    });
+});
+
+ipcHandler.Start();
+```
+
+---
+
+# Difference from IPCMessageHandlerPair
+
+This is the most important distinction.
+
+## IPCMessageHandler is a one-to-many handler
+
+```text
+IPCMessageHandler
+
+                    Worker 1
+                   /
+Primary ---------- Worker 2
+                   \
+                    Worker 3
+```
+
+The class itself owns the worker collection.
+
+```ts
+#clients: Record<string, IClientRecord>
+```
+
+Workers are managed with:
+
+```ts
+AddClient(worker);
+RemoveClient(id);
+```
+
+Server-side messages are broadcast to every registered worker.
+
+---
+
+## IPCMessageHandlerPair is a one-to-one handler
+
+`IPCMessageHandlerPair` represents one primary/worker relationship:
+
+```text
+Primary <----------> Worker 1
+```
+
+It stores one worker:
+
+```ts
+#worker;
+```
+
+and starts that relationship using:
+
+```ts
+pair.Start(worker);
+```
+
+To manage three workers using `IPCMessageHandlerPair`, the surrounding application would normally maintain three handler instances:
+
+```text
+Worker Manager
+│
+├── IPCMessageHandlerPair -> Worker 1
+├── IPCMessageHandlerPair -> Worker 2
+└── IPCMessageHandlerPair -> Worker 3
+```
+
+---
+
+## Responsibility Difference
+
+### IPCMessageHandler
+
+The handler is responsible for:
+
+```text
+IPC messaging
++
+worker collection management
++
+broadcasting
+```
+
+### IPCMessageHandlerPair
+
+The handler is responsible for:
+
+```text
+IPC messaging
++
+one worker connection
+```
+
+Worker collection management and broadcasting are expected to happen outside the pair.
+
+---
+
+## Comparison
+
+| Feature                        | IPCMessageHandler               | IPCMessageHandlerPair       |
+| ------------------------------ | ------------------------------- | --------------------------- |
+| Relationship                   | One-to-many                     | One-to-one                  |
+| Server owns worker collection  | Yes                             | No                          |
+| Worker storage                 | `#clients` collection           | Single `#worker`            |
+| Add worker                     | `AddClient(worker)`             | `Start(worker)`             |
+| Remove worker                  | `RemoveClient(id)`              | `Stop()`                    |
+| Server `SendMessage()`         | Sends to all workers            | Sends to one worker         |
+| Server `emit()`                | Broadcasts                      | Sends to one worker         |
+| Server `emitNoResponse()`      | Broadcasts                      | Sends to one worker         |
+| Multiple responses             | Aggregated with `Promise.all()` | Single response             |
+| Broadcast built into transport | Yes                             | No                          |
+| Best suited for                | Cluster-wide communication      | Dedicated worker connection |
+
+---
+
+# When to Use IPCMessageHandler
+
+Use `IPCMessageHandler` when the message handler itself should own and manage the worker collection.
+
+It is particularly appropriate when the required abstraction is:
+
+```text
+"Send this message to my cluster workers."
+```
+
+rather than:
+
+```text
+"Send this message to this specific worker."
+```
+
+If the surrounding process manager already owns the worker collection, `IPCMessageHandlerPair` may provide a cleaner separation of responsibilities.