@nsshunt/stsmessaging 1.0.78 → 1.0.79

package/README.IPCMessageHandlerPairManagerGenNotes.md

@@ -0,0 +1,420 @@
+Yes — I think this is a cleaner architecture.
+
+I created the complete new class here:
+
+[Download `ipcMessageHandlerPairManager.ts`](sandbox:/mnt/data/ipcMessageHandlerPairManager.ts)
+
+### File: `ipcMessageHandlerPairManager.ts`
+
+The structure is now:
+
+```text
+IPCMessageHandlerPairManager
+│
+├── Worker 1 -> IPCMessageHandlerPair -> MessagingManager
+├── Worker 2 -> IPCMessageHandlerPair -> MessagingManager
+├── Worker 3 -> IPCMessageHandlerPair -> MessagingManager
+└── Worker 4 -> IPCMessageHandlerPair -> MessagingManager
+```
+
+Each `IPCMessageHandlerPair` continues doing exactly what it is good at: managing **one worker connection**. The existing pair already stores/starts a single worker relationship.
+
+The new manager takes over the things that were previously mixed into `IPCMessageHandler`: worker collection management and broadcasting.
+
+The important methods are:
+
+```ts
+manager.AddWorker(worker);
+
+manager.RemoveWorker(worker.id);
+
+manager.GetPair(worker.id);
+
+manager.GetWorker(worker.id);
+
+manager.on("some-event", callback);
+
+await manager.SendMessageTo(worker.id, payload);
+
+await manager.SendMessageToAll(payload);
+
+await manager.emitTo(worker.id, "some-event", arg1, arg2);
+
+await manager.emitToAll("some-event", arg1, arg2);
+
+await manager.emitNoResponseTo(worker.id, "some-event", arg1);
+
+await manager.emitNoResponseToAll("some-event", arg1);
+
+manager.Stop();
+```
+
+I also added:
+
+```ts
+await manager.SendMessageToAllSettled(payload);
+
+await manager.emitToAllSettled("some-event", arg1);
+```
+
+These are useful when broadcasting because one dead/timed-out worker won't cause you to lose the results from every other worker.
+
+For example:
+
+```ts
+const results = await pairManager.emitToAllSettled("get-status");
+
+for (const result of results) {
+    if (result.status === "fulfilled") {
+        console.log(`Worker ${result.workerId}:`, result.response);
+    } else {
+        console.log(`Worker ${result.workerId} failed:`, result.error);
+    }
+}
+```
+
+### Event registrations are handled properly
+
+This is something I specifically accounted for.
+
+If you do:
+
+```ts
+pairManager.on("from-worker", (arg1, callback) => {
+    callback({
+        status: "OK",
+    });
+});
+```
+
+the manager registers that event on **every existing pair**.
+
+More importantly, it also remembers the registration. So if another worker is added later:
+
+```ts
+pairManager.AddWorker(newWorker);
+```
+
+that new pair automatically receives all the existing event registrations.
+
+Without this, this architecture would have a subtle bug where:
+
+```text
+manager.on(...)
+AddWorker(worker1)
+AddWorker(worker2)
+```
+
+would behave differently from:
+
+```text
+AddWorker(worker1)
+AddWorker(worker2)
+manager.on(...)
+```
+
+The manager makes both cases work.
+
+### Example primary process
+
+```ts
+import { IPCMessageHandlerPairManager } from "./ipcMessageHandlerPairManager.js";
+
+const pairManager = new IPCMessageHandlerPairManager({
+    logger: this.options.logger,
+    requestResponseMessageTimeout: 5000,
+    namespace: "STS_WORKERS",
+});
+
+pairManager.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();
+
+pairManager.AddWorker(worker1);
+pairManager.AddWorker(worker2);
+pairManager.AddWorker(worker3);
+```
+
+You can now address one worker:
+
+```ts
+const response = await pairManager.emitTo(worker2.id, "get-status");
+```
+
+or broadcast:
+
+```ts
+const responses = await pairManager.emitToAll("get-status");
+```
+
+That distinction is much cleaner than having `IPCMessageHandler.SendMessage()` silently mean "send to everybody."
+
+### Worker side stays simple
+
+Inside each worker, you **do not use the manager**.
+
+You continue using a single `IPCMessageHandlerPair`:
+
+```ts
+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();
+```
+
+So:
+
+```text
+PRIMARY
+
+IPCMessageHandlerPairManager
+        │
+        ├── Pair(worker 1)
+        ├── Pair(worker 2)
+        └── Pair(worker 3)
+
+
+WORKER 1                 WORKER 2                 WORKER 3
+
+Pair(CLIENT)             Pair(CLIENT)             Pair(CLIENT)
+```
+
+### Your `MessagingManager` fits this design particularly well
+
+There's an important reason I think this architecture fits your existing code.
+
+Each `MessagingManager` creates its own unique message header. Responses are matched against that specific header and the manager's own inflight-message records.
+
+But incoming requests are accepted based on the namespace prefix:
+
+```ts
+const checkName = `__STS__${this.#options.namespace}__`;
+
+if ((msg.header as string).includes(checkName)) {
+    ...
+}
+```
+
+That means you can have:
+
+```text
+Pair 1 -> MessagingManager(unique ID/header)
+Pair 2 -> MessagingManager(unique ID/header)
+Pair 3 -> MessagingManager(unique ID/header)
+```
+
+all using:
+
+```ts
+namespace: "STS_WORKERS";
+```
+
+Requests get recognised by the common namespace, while responses are correlated back to the specific `MessagingManager` that initiated them.
+
+That is almost exactly what you want for this pair-per-worker architecture.
+
+One other thing I deliberately included is automatic cleanup:
+
+```ts
+worker.once("exit", ...)
+```
+
+By default, when a worker exits, its pair is automatically:
+
+```text
+stopped
+message listener removed
+pair removed from manager
+worker removed from manager
+```
+
+You can disable that with:
+
+```ts
+autoRemoveOnWorkerExit: false;
+```
+
+if your existing process manager already wants complete control over worker cleanup.
+
+I think this new manager + `IPCMessageHandlerPair` can ultimately **replace `IPCMessageHandler` entirely**. The old class's one-to-many responsibilities now sit at the correct level, while the IPC transport itself remains one-to-one.
+
+# what is the difference between sendmessagetoall vs emittoall
+
+They use the **same underlying request/response mechanism**, but they operate at different abstraction levels.
+
+### `SendMessageToAll()`
+
+This is the lower-level API.
+
+```ts
+await manager.SendMessageToAll({
+    command: "get-status",
+    someOtherData: 123,
+});
+```
+
+It takes an arbitrary `JSONObject` and sends that exact payload to every pair:
+
+```ts
+pair.SendMessage(payload);
+```
+
+Conceptually:
+
+```text
+SendMessageToAll(payload)
+        |
+        +--> pair1.SendMessage(payload)
+        +--> pair2.SendMessage(payload)
+        +--> pair3.SendMessage(payload)
+```
+
+It doesn't know anything about your `on("event", ...)` event system.
+
+---
+
+### `emitToAll()`
+
+This is the higher-level **event API**.
+
+```ts
+await manager.emitToAll("get-status", arg1, arg2);
+```
+
+Internally it converts that into:
+
+```ts
+{
+    __eventName: "get-status",
+    args: [
+        arg1,
+        arg2,
+    ],
+}
+```
+
+and then calls:
+
+```ts
+SendMessageToAll(...)
+```
+
+So effectively:
+
+```ts
+emitToAll = async (event: string, ...args: any[]) => {
+    return this.SendMessageToAll({
+        __eventName: event,
+        args,
+    });
+};
+```
+
+The receiving `IPCMessageHandlerPair` then sees `__eventName` and invokes the handler registered using:
+
+```ts
+pair.on("get-status", callback);
+```
+
+---
+
+So the relationship is:
+
+```text
+emitToAll("get-status", arg1)
+        |
+        v
+{
+    __eventName: "get-status",
+    args: [arg1]
+}
+        |
+        v
+SendMessageToAll(...)
+        |
+        +----> Worker 1
+        +----> Worker 2
+        +----> Worker 3
+```
+
+### Practical difference
+
+|                                       | `SendMessageToAll()` | `emitToAll()`          |
+| ------------------------------------- | -------------------- | ---------------------- |
+| Level                                 | Low-level            | High-level             |
+| Input                                 | Any `JSONObject`     | Event name + arguments |
+| Uses `.on()` handlers                 | Not automatically    | Yes                    |
+| Adds `__eventName`                    | No                   | Yes                    |
+| Adds `args`                           | No                   | Yes                    |
+| Uses `MessagingManager.SendMessage()` | Yes                  | Yes                    |
+| Expects responses                     | Yes                  | Yes                    |
+| Broadcasts                            | Yes                  | Yes                    |
+
+For your framework, I would expect you to use **`emitToAll()` most of the time**.
+
+For example:
+
+```ts
+manager.on("reload-config", (config, callback) => {
+    // ...
+    callback({
+        status: "OK",
+    });
+});
+```
+
+Then:
+
+```ts
+const responses = await manager.emitToAll("reload-config", config);
+```
+
+That's much nicer than manually doing:
+
+```ts
+await manager.SendMessageToAll({
+    __eventName: "reload-config",
+    args: [config],
+});
+```
+
+In fact, those two examples are essentially equivalent.
+
+I'd treat them like this:
+
+```text
+SendMessageToAll()
+    = primitive messaging API
+
+emitToAll()
+    = event-oriented convenience API built on top of it
+```
+
+And the same relationship applies to:
+
+```text
+SendMessageTo(workerId, payload)
+        vs
+emitTo(workerId, event, ...args)
+```
+
+For your public framework API, you may eventually find that `SendMessageToAll()` is mostly an internal building block while `emitToAll()` is what application code normally uses.

package/dist/index.cjs

@@ -403,7 +403,7 @@ var RedisMessageHandler = class extends tiny_emitter.TinyEmitter {
 * IPC Message Handling.
 *
 * This class can be used to support messages between cluster.primary and cluster.worker instances using IPC.
-* This class can be used for both tghe cluster primary and the cluster worker.
+* This class can be used for both the cluster primary and the cluster worker.
 * Note: Currently groups handling is not supported. Use the redis version for this capability.
 */
 var IPCMessageHandler = class extends tiny_emitter.TinyEmitter {
@@ -575,7 +575,7 @@ var IPCMessageHandler = class extends tiny_emitter.TinyEmitter {
 * IPC Message Handling.
 *
 * This class can be used to support messages between cluster.primary and cluster.worker instances using IPC.
-* This class can be used for both tghe cluster primary and the cluster worker.
+* This class can be used for both the cluster primary and the cluster worker.
 * Note: Currently groups handling is not supported. Use the redis version for this capability.
 */
 var IPCMessageHandlerPair = class extends tiny_emitter.TinyEmitter {