systemlynx 1.20.0 → 1.21.0

package/API.md

@@ -252,6 +252,27 @@ function notifyClients(req, res, next) {
 
 ---
 
+### Built-in `"error"` event
+
+SystemLynx emits a local `"error"` event on a module whenever one of its methods sends an error back to the client (a thrown error, a rejected promise, or a middleware error). This is a **server-side, local-only** event — it is *not* broadcast over WebSockets to clients (the failing client already receives the error over HTTP). It lets observers monitor failures that bypass `after` middleware.
+
+| Event | Payload | Description |
+|:---|:---|:---|
+| `"error"` | `{ module_name, fn, arguments, status, message, error }` | Fires when a method on this module returns an error to the client |
+
+```javascript
+Service.module("Orders", function () {
+  this.on("error", (info) => {
+    console.log(`${info.module_name}.${info.fn} failed (${info.status}): ${info.message}`);
+    console.log("called with:", info.arguments);
+  });
+});
+```
+
+A plugin can subscribe across every module via [`App.getModules()`](#appgetmodulename--appgetmodules).
+
+---
+
 ### module.$clearEvent(eventName [, fn])
 
 Removes event listeners. If a function is provided, removes only the listener matching that function's name. If no function is provided, removes all listeners for that event.
@@ -447,6 +468,26 @@ App.module("Users", function () {
 
 ---
 
+### App.getModule(name) / App.getModules()
+
+Return the live module objects hosted on this App. `getModule(name)` returns a single module (or `undefined`); `getModules()` returns an object keyed by module name (`{ [name]: module }`).
+
+Modules are constructed during initialization, so the live references only exist **after** the `"ready"` event. Before that, `getModule` returns `undefined` and `getModules` returns an empty object. Call them inside an `App.on("ready", ...)` handler — this is how a plugin (e.g. a monitoring/observability plugin) gets a handle on modules to observe or decorate them.
+
+```javascript
+App.use((App) => {
+  App.on("ready", () => {
+    Object.entries(App.getModules()).forEach(([name, module]) => {
+      module.on("error", (info) => {
+        console.log(`[${name}] ${info.module_name}.${info.fn} failed:`, info.message);
+      });
+    });
+  });
+});
+```
+
+---
+
 ### App.before / App.after
 
 Same as [`Service.before`](#servicebeforename-middleware) and [`Service.after`](#serviceafterename-middleware).

package/RFCs/002-module-handle-and-internal-error-events.md

@@ -0,0 +1,135 @@
+# RFC: Module Handle + Internal Error Events
+
+## Context
+
+SystemView is a SystemLynx plugin (installed via `App.use`) that wants to act as the
+observability/logging layer for a SystemLynx service — monitoring requests and errors
+under the hood, and letting modules log through SystemView.
+
+Today the plugin gets `(App, system)` but has no *supported* way to reach the live module
+objects, and SystemLynx emits **no internal events** on the request/error lifecycle. This
+RFC adds the minimal SystemLynx-side surface to enable that. **All SystemView-specific
+behavior (the log function, the monitoring sink) lives in the SystemView plugin, not in
+SystemLynx.** SystemLynx only exposes access + an emit point.
+
+---
+
+## Two gaps, two changes
+
+### Gap 1 — No supported handle on the live modules
+
+A plugin receives `App` and `system`, and live modules already exist at
+`system.modules[i].module` after construction. But:
+
+- Reaching into `system.modules[].module` couples the plugin to internal shape.
+- At `plugin.apply` time the modules are **not built yet** — `system.modules` holds only
+  `{ name, __constructor }`. The live `.module` is assigned later in `loadModules`, right
+  before `App.emit("ready", system)`.
+
+**Change:** Add `App.getModules()` (and `App.getModule(name)`) returning the live module
+objects. Returns them after `ready`; empty/undefined before.
+
+### Gap 2 — Errors bypass the lifecycle
+
+`before`/`after` middleware already let a plugin observe the request happy-path. But every
+error to the client funnels through `res.sendError` in `Router.js`, which writes the HTTP
+response and **does not call `next()`** — so afterware and the response middleware are
+skipped. `after` hooks never see failures.
+
+**Change:** Emit a **local-only** `"error"` event on the module from inside `sendError`.
+The failing client already receives the error over HTTP; this event is purely for
+server-side observers. Use `$emit` (local) **not** `emit` (which would broadcast the error
+over websockets to every connected client).
+
+---
+
+## Files to Change
+
+### 1. `systemlynx/App/App.js`
+
+Add module accessors. The live module is at `system.modules[i].module` once built.
+
+```js
+App.getModule = (name) => {
+  const found = system.modules.find((m) => m.name === name);
+  return found ? found.module : undefined;
+};
+
+App.getModules = () =>
+  system.modules.reduce((obj, { name, module }) => {
+    if (module) obj[name] = module;
+    return obj;
+  }, {});
+```
+
+`getModules()` returns an object **keyed by module name** (`{ [name]: module }`) —
+consistent with how SystemLynx exposes service modules elsewhere (`useService(name)`
+returns named module keys). `getModule(name)` returns a single live module. Both only
+return live modules after the `ready` event (before that, `module` is undefined). Plugins
+should call these inside an `App.on("ready", ...)` handler.
+
+### 2. `systemlynx/ServerManager/components/Router.js`
+
+Emit a local `"error"` event from the single error chokepoint, `sendError` (inside
+`parseRequest`). `req.Module` is the live module dispatcher.
+
+```js
+const sendError = (error) => {
+  const status = (error || {}).status || 500;
+  const message = (error || {}).message || unhandledMessage;
+  if (req.Module && typeof req.Module.$emit === "function")
+    req.Module.$emit("error", {
+      module_name,
+      fn,
+      arguments: req.arguments,
+      status,
+      message,
+      error,
+    });
+  res.status(status).json({ ...presets, ...error, status, message, SystemLynxService: true });
+};
+```
+
+The payload carries the call identity (`module_name` + `fn`) and the inputs
+(`arguments`) so an observer can reconstruct what was called and with what. The raw
+Express `req` is intentionally **not** included — args-only keeps the event lean; if a
+consumer later needs headers we can revisit.
+
+`$emit` is the local-only emitter installed by `SocketEmitter` (see `SocketEmitter.js` —
+`Emitter.$emit = Emitter.emit` before `emit` is overridden to broadcast). Guard with a
+typeof check so a module without SocketEmitter applied doesn't throw.
+
+---
+
+## Files NOT Changed
+
+- `systemlynx/ServerManager/components/SocketEmitter.js` — `$emit` already exists; we only
+  consume it.
+- `systemlynx/Service/Service.js` — module construction unchanged.
+- HTTP response shape — unchanged; the `"error"` event is additive and server-side only.
+
+---
+
+## Plugin-side usage (for reference — lives in SystemView, not this repo)
+
+```js
+App.use((App, system) => {
+  App.on("ready", () => {
+    Object.entries(App.getModules()).forEach(([name, module]) => {
+      module.on("error", (info) => { /* SystemView records the failure */ });
+      module.log = (...args) => { /* SystemView log routing */ };
+    });
+  });
+});
+```
+
+---
+
+## Verification
+
+1. `npm test` — existing suite stays green (changes are additive).
+2. New test: register a module whose method throws, call it over HTTP, assert the module's
+   local `"error"` event fired with `{ module_name, fn, status, message, error }` and that
+   the event did **not** go out over the websocket.
+3. New test: `App.getModule(name)` returns the live module after `ready`, undefined before.
+4. Confirm the failing HTTP response body is unchanged from current behavior.

package/index.test.js

@@ -46,7 +46,9 @@ describe("SystemLynx Objects", () => {
         "onLoad",
         "config",
         "server",
-        "WebSocket"
+        "WebSocket",
+        "getModule",
+        "getModules"
       )
       .that.respondsTo("module")
       .that.respondsTo("on")
@@ -58,7 +60,9 @@ describe("SystemLynx Objects", () => {
       .that.respondsTo("startService")
       .that.respondsTo("loadService")
       .that.respondsTo("onLoad")
-      .that.respondsTo("config");
+      .that.respondsTo("config")
+      .that.respondsTo("getModule")
+      .that.respondsTo("getModules");
   });
 
   it("should return a SystemLynx Client", () => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "systemlynx",
-  "version": "1.20.0",
+  "version": "1.21.0",
   "description": "",
   "main": "index.js",
   "browser": {

package/systemlynx/App/App.js

@@ -43,6 +43,20 @@ module.exports = function createApp(server, WebSocket, customClient) {
     return App;
   };
 
+  // Live module accessors. Modules are constructed during initialization, so the
+  // `module` reference only exists after the "ready" event — before that these
+  // return undefined / an empty list.
+  App.getModule = (name) => {
+    const found = system.modules.find((mod) => mod.name === name);
+    return found ? found.module : undefined;
+  };
+
+  App.getModules = () =>
+    system.modules.reduce((obj, { name, module }) => {
+      if (module) obj[name] = module;
+      return obj;
+    }, {});
+
   App.before = (...args) => {
     system.Service.before(...args);
     return App;

package/systemlynx/App/tests/App.test.js

@@ -24,9 +24,13 @@ describe("createApp()", () => {
         "onLoad",
         "config",
         "server",
-        "WebSocket"
+        "WebSocket",
+        "getModule",
+        "getModules"
       )
       .that.respondsTo("module")
+      .that.respondsTo("getModule")
+      .that.respondsTo("getModules")
       .that.respondsTo("on")
       .that.respondsTo("emit")
       .that.respondsTo("$clearEvent")
@@ -393,6 +397,66 @@ describe("App SystemObjects: Initializing Modules,  Modules and configurations",
     );
   });
 
+  it("should expose live modules via App.getModule(name) and App.getModules() after ready", async () => {
+    const App = createApp();
+    const route = "test-service";
+    const port = "8495";
+
+    App.module("mod", function () {
+      this.test = () => {};
+    }).module("mod2", function () {
+      this.test = () => {};
+    });
+
+    // before initialization the live module reference does not exist yet
+    expect(App.getModule("mod")).to.equal(undefined);
+    expect(App.getModules()).to.be.an("object").that.is.empty;
+
+    await new Promise((resolve) => App.startService({ route, port }).on("ready", resolve));
+
+    const mod = App.getModule("mod");
+    expect(mod).to.be.an("object").that.respondsTo("on").that.respondsTo("emit");
+    expect(App.getModule("missing")).to.equal(undefined);
+
+    const modules = App.getModules();
+    expect(modules).to.be.an("object").that.has.all.keys("mod", "mod2");
+    expect(modules.mod).to.respondTo("on").that.respondsTo("emit");
+  });
+
+  it("should emit a local 'error' event on the module when a method throws back to the client", async () => {
+    const App = createApp();
+    const route = "test-service";
+    const port = "8496";
+
+    App.module("errMod", function () {
+      this.boom = () => {
+        throw { status: 400, message: "boom went the method" };
+      };
+    });
+
+    await new Promise((resolve) => App.startService({ route, port }).on("ready", resolve));
+
+    const errMod = App.getModule("errMod");
+    const errorEvent = new Promise((resolve) => errMod.on("error", resolve));
+
+    const url = `http://localhost:${port}/${route}/errMod/boom`;
+    try {
+      await HttpClient.request({ method: "POST", url, body: { __arguments: [{ x: 1 }] } });
+    } catch (e) {
+      // expected — the method throws and the error is returned over HTTP
+    }
+
+    const info = await errorEvent;
+    expect(info)
+      .to.be.an("object")
+      .that.has.all.keys("module_name", "fn", "arguments", "status", "message", "error");
+    expect(info.module_name).to.equal("errMod");
+    expect(info.fn).to.equal("boom");
+    expect(info.status).to.equal(400);
+    expect(info.message).to.equal("boom went the method");
+    expect(info.arguments).to.deep.equal([{ x: 1 }]);
+  });
+
   it("should be able to use App.config(constructor) to construct a configuration module", async () => {
     const App = createApp();
 

package/systemlynx/ServerManager/components/Router.js

@@ -58,6 +58,18 @@ module.exports = function createRouter(server, config) {
     const sendError = (error) => {
       const status = (error || {}).status || 500;
       const message = (error || {}).message || unhandledMessage;
+      // Emit a local-only "error" event on the module so server-side observers
+      // (e.g. a SystemView plugin) can monitor failures. $emit does not broadcast
+      // over websockets — the failing client already receives the error over HTTP.
+      if (Module && typeof Module.$emit === "function")
+        Module.$emit("error", {
+          module_name,
+          fn,
+          arguments: req.arguments,
+          status,
+          message,
+          error,
+        });
       res.status(status).json({
         ...presets,
         ...error,