@nsshunt/stsmessaging 1.0.78 → 1.0.79

package/README.IPCMessageHandlerPair.md

@@ -0,0 +1,702 @@
+# IPCMessageHandlerPair
+
+`IPCMessageHandlerPair` provides IPC-based request/response and event messaging between a Node.js cluster primary process and **one specific worker process**.
+
+It is built on top of `MessagingManager` and exposes an event-oriented API using `on()`, `off()`, `emit()`, and `emitNoResponse()`.
+
+---
+
+## Purpose
+
+Use `IPCMessageHandlerPair` when each handler instance should represent a **single primary-to-worker IPC relationship**.
+
+Typical topology:
+
+```text
+Primary <----------> Worker
+```
+
+For multiple workers, create or maintain multiple pair instances:
+
+```text
+Worker Manager
+│
+├── Pair 1 <-------> Worker 1
+├── Pair 2 <-------> Worker 2
+└── Pair 3 <-------> Worker 3
+```
+
+The class does not maintain an internal collection of workers.
+
+---
+
+## Key Characteristics
+
+- Supports `SERVER` and `CLIENT` roles.
+- Designed around **one server/primary to one worker**.
+- Stores one worker reference.
+- Server-side `Start(worker)` associates the handler with that worker.
+- Server-side `SendMessage()` sends to that one worker.
+- Server-side `emit()` sends to that one worker.
+- Uses `MessagingManager` for request/response message handling.
+- Supports event registration through `on()` and `off()`.
+- Supports request messages that expect a response.
+- Supports fire-and-forget request messages through `emitNoResponse()`.
+- Does not perform server-side broadcast management.
+- Does not maintain a collection of cluster workers.
+
+---
+
+# Constructor
+
+```ts
+new IPCMessageHandlerPair(options);
+```
+
+### Options
+
+```ts
+export interface IPCMessageHandlerPairOptions {
+    logger: ISTSLogger;
+    requestResponseMessageTimeout: number;
+    namespace: string;
+    role: "SERVER" | "CLIENT";
+    ignoreEvents?: string[];
+}
+```
+
+### `logger`
+
+Logger used when event emission or message processing fails.
+
+### `requestResponseMessageTimeout`
+
+Maximum time allowed for request/response messages.
+
+### `namespace`
+
+Namespace supplied to the underlying `MessagingManager`.
+
+### `role`
+
+Determines which side of the IPC relationship is configured.
+
+```ts
+role: "SERVER";
+```
+
+Represents the primary/server side.
+
+```ts
+role: "CLIENT";
+```
+
+Represents the worker/client side.
+
+### `ignoreEvents`
+
+Optional list of event names whose errors should be ignored by `emit()`.
+
+---
+
+# Server Role
+
+When configured with:
+
+```ts
+role: "SERVER";
+```
+
+the handler is associated with one worker.
+
+The class stores:
+
+```ts
+#worker;
+```
+
+and the worker relationship is established through:
+
+```ts
+Start(worker);
+```
+
+---
+
+# Server-side Message Receiver
+
+The server-side implementation registers a `"message"` listener directly on the worker.
+
+Conceptually:
+
+```ts
+worker.on("message", handler);
+```
+
+Incoming messages are passed to:
+
+```ts
+MessagingManager.ProcessMessage(...)
+```
+
+with the associated worker supplied as message context.
+
+This gives the pair a direct relationship between:
+
+```text
+one IPCMessageHandlerPair
+          |
+          v
+       one Worker
+```
+
+---
+
+# Client Role
+
+When configured with:
+
+```ts
+role: "CLIENT";
+```
+
+the handler runs inside the worker process.
+
+Outgoing messages use Node.js process IPC:
+
+```ts
+process.send(...)
+```
+
+Incoming messages use:
+
+```ts
+process.on("message", ...)
+```
+
+The client side therefore communicates with its parent process.
+
+---
+
+# Start()
+
+```ts
+pair.Start(worker);
+```
+
+For a server-side pair, `Start()` associates the handler with one worker.
+
+Example:
+
+```ts
+const pair = new IPCMessageHandlerPair({
+    logger,
+    requestResponseMessageTimeout: 5000,
+    namespace: "worker-1",
+    role: "SERVER",
+});
+
+pair.Start(worker);
+```
+
+The handler then stores the worker reference and starts the underlying `MessagingManager` with it.
+
+---
+
+## Client-side Start()
+
+A worker/client does not need to supply a worker object:
+
+```ts
+pair.Start();
+```
+
+The client communicates with its parent through `process.send()` and `process.on("message")`.
+
+---
+
+# Stop()
+
+```ts
+pair.Stop();
+```
+
+When a worker is associated with the pair, `Stop()`:
+
+1. Stops `MessagingManager` using the worker context.
+2. Removes the worker message receiver through the configured messaging callbacks.
+3. Clears the stored worker reference.
+
+Conceptually:
+
+```text
+Before:
+
+IPCMessageHandlerPair ---> Worker
+
+After Stop():
+
+IPCMessageHandlerPair      Worker
+```
+
+---
+
+# worker
+
+```ts
+pair.worker;
+```
+
+Returns the worker currently associated with the pair.
+
+The value is `null` when no server-side worker is attached.
+
+---
+
+# SendMessage()
+
+```ts
+await pair.SendMessage(payload);
+```
+
+Sends a request message through the underlying `MessagingManager`.
+
+## Server behavior
+
+If a worker has been supplied through:
+
+```ts
+pair.Start(worker);
+```
+
+the message is sent specifically to that worker.
+
+```text
+Primary
+   |
+   v
+Worker
+```
+
+There is no iteration over a worker collection.
+
+There is no built-in broadcast.
+
+There is no `Promise.all()` aggregation of responses from multiple workers.
+
+## Client behavior
+
+When no worker is stored, the message is sent using the client-side messaging configuration, which uses:
+
+```ts
+process.send(...)
+```
+
+to communicate with the primary process.
+
+---
+
+# Event Registration
+
+## on()
+
+```ts
+pair.on(eventName, callback);
+```
+
+Registers an IPC event callback.
+
+Example:
+
+```ts
+pair.on("get-status", (callback) => {
+    callback({
+        pid: process.pid,
+        status: "OK",
+    });
+});
+```
+
+Only one event callback is retained for a given event name.
+
+Registering the same event again replaces the existing callback.
+
+---
+
+## off()
+
+```ts
+pair.off(eventName);
+```
+
+Removes an event callback.
+
+---
+
+# emit()
+
+```ts
+pair.emit(eventName, ...args, callback);
+```
+
+Sends an event that expects a response.
+
+Example:
+
+```ts
+pair.emit("get-status", (response) => {
+    console.log(response);
+});
+```
+
+Internally, the event is represented as a message payload containing:
+
+```ts
+{
+    __eventName: eventName,
+    args: [...]
+}
+```
+
+The final argument is used as the response callback.
+
+---
+
+## Server-side emit behavior
+
+A server-side `emit()` targets **the single worker associated with this pair**.
+
+```text
+IPCMessageHandlerPair
+          |
+          v
+       Worker
+```
+
+If the primary needs to emit the same event to three workers, the surrounding manager must invoke the corresponding three pair instances.
+
+For example:
+
+```ts
+for (const pair of workerPairs.values()) {
+    pair.emit("refresh-config", callback);
+}
+```
+
+Broadcasting is therefore a responsibility of the owner of the pair collection rather than of `IPCMessageHandlerPair` itself.
+
+---
+
+# emitNoResponse()
+
+```ts
+await pair.emitNoResponse(eventName, ...args);
+```
+
+Sends a fire-and-forget event.
+
+No response callback is required.
+
+Conceptually:
+
+```text
+Pair ------> remote process
+```
+
+Unlike `IPCMessageHandler`, this class does not iterate over an internal worker collection.
+
+---
+
+# Message Processing
+
+Incoming request messages are handled by `#processPayload()`.
+
+The payload identifies the event using:
+
+```ts
+requestPayload.__eventName;
+```
+
+The registered callback is retrieved from the internal event map.
+
+Supported request types include:
+
+```text
+REQUEST
+REQUEST_NO_RESPONSE
+```
+
+---
+
+## REQUEST
+
+The event callback is given the request arguments followed by a response callback.
+
+Conceptually:
+
+```ts
+pair.on("get-status", (...args, callback) => {
+    callback({
+        status: "OK",
+    });
+});
+```
+
+---
+
+## REQUEST_NO_RESPONSE
+
+The registered callback is invoked with only the supplied event arguments.
+
+No response is expected.
+
+---
+
+# Typical Primary Usage
+
+```ts
+const pair = new IPCMessageHandlerPair({
+    logger,
+    requestResponseMessageTimeout: 5000,
+    namespace: "worker-1",
+    role: "SERVER",
+});
+
+pair.Start(worker);
+
+pair.emit("get-status", (response) => {
+    console.log(response);
+});
+```
+
+The message is sent only to the worker associated with `pair`.
+
+---
+
+# Typical Worker Usage
+
+```ts
+const pair = new IPCMessageHandlerPair({
+    logger,
+    requestResponseMessageTimeout: 5000,
+    namespace: "worker-1",
+    role: "CLIENT",
+});
+
+pair.on("get-status", (callback) => {
+    callback({
+        pid: process.pid,
+        status: "OK",
+    });
+});
+
+pair.Start();
+```
+
+---
+
+# Managing Multiple Workers
+
+`IPCMessageHandlerPair` intentionally does not maintain a worker collection.
+
+A higher-level process manager can maintain the collection instead.
+
+For example:
+
+```ts
+const workerPairs = new Map<number, IPCMessageHandlerPair>();
+```
+
+Conceptually:
+
+```text
+WorkerProcessManager
+│
+├── Worker 1
+│      └── IPCMessageHandlerPair
+│
+├── Worker 2
+│      └── IPCMessageHandlerPair
+│
+└── Worker 3
+       └── IPCMessageHandlerPair
+```
+
+This separates two responsibilities:
+
+```text
+WorkerProcessManager
+    -> owns workers
+    -> handles worker lifecycle
+    -> performs broadcast operations
+
+IPCMessageHandlerPair
+    -> owns one IPC relationship
+    -> handles messages
+    -> handles request/response correlation
+```
+
+---
+
+# Difference from IPCMessageHandler
+
+This is the most important distinction.
+
+## IPCMessageHandlerPair is one-to-one
+
+One pair represents one worker relationship:
+
+```text
+Primary <----------> Worker
+```
+
+It stores one worker:
+
+```ts
+#worker;
+```
+
+and the server associates that worker with:
+
+```ts
+Start(worker);
+```
+
+A message from the server is sent only to that worker.
+
+---
+
+## IPCMessageHandler is one-to-many
+
+`IPCMessageHandler` owns a collection:
+
+```ts
+#clients;
+```
+
+Workers are added with:
+
+```ts
+AddClient(worker);
+```
+
+and removed with:
+
+```ts
+RemoveClient(id);
+```
+
+Its topology is:
+
+```text
+                    Worker 1
+                   /
+Primary ---------- Worker 2
+                   \
+                    Worker 3
+```
+
+When the server calls:
+
+```ts
+SendMessage(...)
+```
+
+the handler iterates through its worker collection and sends the message to all registered workers.
+
+---
+
+# Responsibility Difference
+
+This distinction is architectural, not merely a difference in method names.
+
+## IPCMessageHandlerPair
+
+```text
+one connection
++
+messaging
+```
+
+The class represents a single IPC relationship.
+
+A higher-level manager is responsible for:
+
+```text
+worker collection
+broadcasting
+worker lifecycle
+```
+
+## IPCMessageHandler
+
+```text
+worker collection
++
+messaging
++
+broadcasting
+```
+
+Those responsibilities are combined inside the handler.
+
+---
+
+# Comparison
+
+| Feature                                    | IPCMessageHandlerPair    | IPCMessageHandler          |
+| ------------------------------------------ | ------------------------ | -------------------------- |
+| Relationship                               | One-to-one               | One-to-many                |
+| Number of server-side workers per instance | One                      | Many                       |
+| Worker storage                             | Single `#worker`         | `#clients` collection      |
+| Attach worker                              | `Start(worker)`          | `AddClient(worker)`        |
+| Detach worker                              | `Stop()`                 | `RemoveClient(id)`         |
+| Server `SendMessage()`                     | One worker               | All workers                |
+| Server `emit()`                            | One worker               | All workers                |
+| Server `emitNoResponse()`                  | One target               | All workers                |
+| Multiple-response aggregation              | No                       | Yes, using `Promise.all()` |
+| Built-in worker collection                 | No                       | Yes                        |
+| Built-in broadcasting                      | No                       | Yes                        |
+| External manager naturally owns workers    | Yes                      | Not required               |
+| Best abstraction                           | "this worker connection" | "my worker cluster"        |
+
+---
+
+# When to Use IPCMessageHandlerPair
+
+Use `IPCMessageHandlerPair` when the surrounding process manager already knows which workers exist and should remain responsible for worker lifecycle.
+
+It is particularly appropriate when the desired abstraction is:
+
+```text
+"Send this message to this worker."
+```
+
+rather than:
+
+```text
+"Send this message to all workers."
+```
+
+It also provides a clean structure when each worker has other worker-specific state.
+
+For example:
+
+```ts
+interface WorkerRecord {
+    worker: Worker;
+    ipc: IPCMessageHandlerPair;
+    startedAt: Date;
+    state: WorkerState;
+}
+```
+
+The process manager can then choose whether to:
+
+- address one worker;
+- address a subset of workers;
+- broadcast to every worker;
+- remove a worker;
+- replace a worker.
+
+The IPC transport itself remains focused on the single primary/worker communication relationship.