geonix 1.30.2 → 1.31.0

package/README.md

@@ -287,7 +287,7 @@ Each returned part has:
 
 | Env Variable | Default | Description |
 |---|---|---|
-| `GX_TRANSPORT` | `nats://localhost` | NATS server URL(s) |
+| `GX_TRANSPORT` | `nats://localhost` | NATS server URL(s). Set to `local://` for single-process monolith mode — see "Local transport" below. |
 | `GX_PORT` | `8080` | Gateway listen port |
 | `GX_LOCAL_PORT` | random | Force service HTTP server to a specific port |
 | `GX_VERSION` | `999.999.<seconds>` | Service version |
@@ -298,6 +298,14 @@ Each returned part has:
 | `GX_SECRET` | — | Encryption key: AES-256-GCM payloads + HMAC-SHA256 subjects. Services without the same key cannot communicate. |
 | `GX_DEBUG_ENDPOINT` | — | Mount path for the debug router (e.g. `/_debug`). Disabled when unset. |
 
+## Local transport (`GX_TRANSPORT=local://`)
+
+For single-process monolith deployments, set `GX_TRANSPORT=local://` to replace the NATS connection with an in-process pub/sub bus. Services running in the same Node process announce themselves, the registry populates, and `Remote<T>()` calls work end-to-end without a `nats-server` running anywhere.
+
+RPC traffic still flows through HTTP-on-loopback (`127.0.0.1:<servicePort>/!!_gx/rpc/...`) — the bus only replaces the discovery and NATS-control plane. The wire contract is identical to a distributed deployment, so migrating from monolith to multi-host is a single env var change (`GX_TRANSPORT=nats://your-host:4222`); no code changes.
+
+Semantics matched against real NATS: subject wildcards (`*`, `>`), queue groups, `{ max: N }`, FIFO per subscription, byte payloads with defensive copy on publish. Not supported in local mode: multi-process (the bus is per-process), JetStream, and any feature Geonix doesn't already use.
+
 > **Deprecation notice:** The legacy unprefixed names `TRANSPORT`, `PORT`, `LOCAL_PORT`, `VERSION`, and `TRANSPORT_DEBUG` are still read as fallbacks but will be removed in the next major version. Migrate to the `GX_` prefixed names.
 
 ### Bus Encryption (`GX_SECRET`)

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "geonix",
-    "version": "1.30.2",
+    "version": "1.31.0",
     "type": "module",
     "description": "",
     "bin": {
@@ -34,4 +34,4 @@
         "eslint": "^10.1.0",
         "globals": "^17.4.0"
     }
-}
+}

package/src/Codec.js

@@ -30,4 +30,4 @@ export function decode(data) {
     } catch (e) {
         throw new Error(`Codec.decode: ${e.message}`, { cause: e });
     }
-}
+}

package/src/Connection.js

@@ -10,7 +10,7 @@ import { encryptPayload, decryptPayload, encryptSubject, wrapSubscription } from
 const CONNECTION_TIMEOUT = 10000;
 
 const defaultRequestOptions = {
-    timeout: 300000
+    timeout: 300000,
 };
 
 const DEFAULT_CONNECTION_COUNT = 1;
@@ -21,7 +21,16 @@ const defaultConnectionOptions = {
     debug: (process.env.GX_TRANSPORT_DEBUG || process.env.TRANSPORT_DEBUG) === "true",
     maxReconnectAttempts: 30,
     pingInterval: 30000,
-    waitOnFirstConnect: true
+    waitOnFirstConnect: true,
+};
+
+const TRANSPORT_TIMEOUT = 60_000;
+const WATCHDOG_INTERVAL = 1000;
+
+// env read via a function so tests can set GX_TRANSPORT_TIMEOUT after this module is imported
+const getTransportTimeout = () => {
+    const raw = parseInt(process.env.GX_TRANSPORT_TIMEOUT, 10);
+    return Number.isFinite(raw) ? raw : TRANSPORT_TIMEOUT;
 };
 // -------------------------------------------------------------------------------------------------
 
@@ -32,12 +41,13 @@ const defaultConnectionOptions = {
  * encryption are activated by setting the `GX_SECRET` environment variable.
  */
 class Connection {
-
     #draining = false;
     #closed = false;
     #ready = false;
     #connections = [];
     #connectionRoundRobin = 0;
+    #disconnectedSince = Date.now();
+    #watchdogInterval = null;
 
     #getConnection() {
         return this.#connections[this.#connectionRoundRobin++ % this.#connections.length];
@@ -52,22 +62,67 @@ class Connection {
      * @returns {Promise<void>}
      */
     async start(transport = process.env.GX_TRANSPORT || process.env.TRANSPORT || "nats://localhost") {
+        // local:// — in-process pub/sub bus, no socket, no nats package call
+        if (transport === "local://" || transport === "local") {
+            const { createLocalBus } = await import("./LocalBus.js");
+            this.#startWatchdog();
+            this.#connections.push(createLocalBus());
+            this.#disconnectedSince = null;
+            logger.info("gx.connection.connected (local)");
+            this.#ready = true;
+            this.monitorStatus();
+            this.waitUntilClosed().catch((e) => logger.error("gx.connection.waitUntilClosed:", e));
+            return;
+        }
+
         const { connections: _connectionCount, ...natsOptions } = {
             ...defaultConnectionOptions,
-            ...parseURL(transport)
+            ...parseURL(transport),
         };
         const connectionCount = parseInt(_connectionCount) || DEFAULT_CONNECTION_COUNT;
 
+        this.#startWatchdog();
+
         for (let i = 0; i < connectionCount; i++) {
             this.#connections.push(await connect(natsOptions));
         }
 
+        this.#disconnectedSince = null;
+
         logger.info("gx.connection.connected");
 
         this.#ready = true;
 
         this.monitorStatus();
-        this.waitUntilClosed().catch(e => logger.error("gx.connection.waitUntilClosed:", e));
+        this.waitUntilClosed().catch((e) => logger.error("gx.connection.waitUntilClosed:", e));
+    }
+
+    // Polls the disconnect timestamp; exits the process if the transport has been
+    // unreachable longer than GX_TRANSPORT_TIMEOUT (default 60s, 0 disables).
+    #startWatchdog() {
+        if (this.#watchdogInterval) {
+            return;
+        }
+
+        this.#watchdogInterval = setInterval(() => {
+            const limit = getTransportTimeout();
+            if (limit === 0) {
+                return;
+            }
+            if (this.#disconnectedSince === null) {
+                return;
+            }
+
+            const elapsed = Date.now() - this.#disconnectedSince;
+            if (elapsed >= limit) {
+                logger.error(
+                    `gx.connection: transport unreachable for ${Math.round(elapsed / 1000)}s (limit ${limit}ms), exiting`,
+                );
+                process.exit(1);
+            }
+        }, WATCHDOG_INTERVAL);
+
+        this.#watchdogInterval.unref?.();
     }
 
     /**
@@ -78,9 +133,17 @@ class Connection {
         for (const conn of this.#connections) {
             (async () => {
                 for await (const event of conn.status()) {
+                    if (event.type === "disconnect") {
+                        if (this.#disconnectedSince === null) {
+                            this.#disconnectedSince = Date.now();
+                        }
+                    } else if (event.type === "reconnect") {
+                        this.#disconnectedSince = null;
+                    }
+
                     logger.debug("gx.connection.status", JSON.stringify(event));
                 }
-            })().catch(e => logger.error("gx.connection.status:", e));
+            })().catch((e) => logger.error("gx.connection.status:", e));
         }
     }
 
@@ -92,11 +155,16 @@ class Connection {
      */
     async waitUntilClosed() {
         // wait for all connections to be closed
-        await Promise.all(this.#connections.map(connection => connection.closed()));
+        await Promise.all(this.#connections.map((connection) => connection.closed()));
 
         this.#closed = true;
         logger.info("gx.connection.closed");
 
+        if (this.#watchdogInterval) {
+            clearInterval(this.#watchdogInterval);
+            this.#watchdogInterval = null;
+        }
+
         webserver.stop();
 
         await sleep(5000);
@@ -118,9 +186,9 @@ class Connection {
 
     /**
      * Publish JSON
-     * 
-     * @param {string} subject 
-     * @param {object} json 
+     *
+     * @param {string} subject
+     * @param {object} json
      * @returns void
      */
     async publish(subject, json) {
@@ -150,21 +218,24 @@ class Connection {
             return;
         }
 
-        await this.#getConnection().publish(encryptSubject(subject), encryptPayload(data != null ? Buffer.from(data) : Buffer.alloc(0)));
+        await this.#getConnection().publish(
+            encryptSubject(subject),
+            encryptPayload(data != null ? Buffer.from(data) : Buffer.alloc(0)),
+        );
     }
 
     /**
      * Request/Reply pattern on top of pub/sub
-     * 
-     * @param {string} subject 
-     * @param {object} json 
-     * @param {object} options 
+     *
+     * @param {string} subject
+     * @param {object} json
+     * @param {object} options
      * @returns any
      */
     async request(subject, json, opts = {}) {
         const options = {
             ...defaultRequestOptions,
-            ...opts
+            ...opts,
         };
 
         const respondTo = `gx2.r.${picoid(16)}`;
@@ -235,9 +306,8 @@ class Connection {
     async drain() {
         this.#draining = true;
 
-        await Promise.all(this.#connections.map(connection => connection.drain()));
+        await Promise.all(this.#connections.map((connection) => connection.drain()));
     }
-
 }
 
 /**
@@ -247,7 +317,7 @@ class Connection {
  * @type {Connection}
  */
 export const connection = new Connection();
-connection.start().catch(e => {
+connection.start().catch((e) => {
     logger.error("gx.connection.start:", e);
     process.exit(1);
 });

package/src/Crypto.js

@@ -3,7 +3,11 @@ import { createCipheriv, createDecipheriv, createHash, createHmac, randomBytes }
 const _secret = process.env.GX_SECRET || null;
 
 // Subject key is derived separately so HMAC-subject and AES-payload never share key material.
-const _subjectKey = _secret ? createHash("sha256").update(_secret + "\x00subject").digest() : null;
+const _subjectKey = _secret
+    ? createHash("sha256")
+          .update(_secret + "\x00subject")
+          .digest()
+    : null;
 
 /**
  * AES-256-GCM key derived from `GX_SECRET`, or `null` when encryption is disabled.
@@ -11,7 +15,11 @@ const _subjectKey = _secret ? createHash("sha256").update(_secret + "\x00subject
  *
  * @type {Buffer|null}
  */
-export const _payloadKey = _secret ? createHash("sha256").update(_secret + "\x00payload").digest() : null;
+export const _payloadKey = _secret
+    ? createHash("sha256")
+          .update(_secret + "\x00payload")
+          .digest()
+    : null;
 
 /**
  * Encrypts `data` with AES-256-GCM using {@link _payloadKey}. Returns `data` unchanged when
@@ -21,7 +29,9 @@ export const _payloadKey = _secret ? createHash("sha256").update(_secret + "\x00
  * @returns {Buffer}
  */
 export function encryptPayload(data) {
-    if (!_payloadKey) { return data; }
+    if (!_payloadKey) {
+        return data;
+    }
     const buf = data != null ? Buffer.from(data) : Buffer.alloc(0);
     const iv = randomBytes(12);
     const cipher = createCipheriv("aes-256-gcm", _payloadKey, iv);
@@ -42,7 +52,9 @@ export function encryptPayload(data) {
  * @returns {Buffer}
  */
 export function decryptPayload(data) {
-    if (!_payloadKey) { return data; }
+    if (!_payloadKey) {
+        return data;
+    }
     const buf = Buffer.from(data);
     const decipher = createDecipheriv("aes-256-gcm", _payloadKey, buf.subarray(0, 12));
     decipher.setAuthTag(buf.subarray(12, 28));
@@ -64,10 +76,12 @@ export function encryptSubject(subject) {
         return subject;
     }
 
-    return subject.split(".").map(seg =>
-        (seg === "*" || seg === ">") ? seg
-            : createHmac("sha256", _subjectKey).update(seg).digest("hex").slice(0, 32)
-    ).join(".");
+    return subject
+        .split(".")
+        .map((seg) =>
+            seg === "*" || seg === ">" ? seg : createHmac("sha256", _subjectKey).update(seg).digest("hex").slice(0, 32),
+        )
+        .join(".");
 }
 
 /**
@@ -94,7 +108,7 @@ export function wrapSubscription(sub) {
                     }
 
                     return { value: { ...value, data: decryptPayload(value.data) }, done: false };
-                }
+                },
             };
         },
         drain: () => sub.drain(),

package/src/Gateway.js

@@ -1,6 +1,6 @@
 import { connection } from "./Connection.js";
 import { registry } from "./Registry.js";
-import { cleanupWebsocketUrl, createTCPServer, GeonixVersion, hash, picoid, proxyHttp, sleep } from "./Util.js";
+import { cleanupWebsocketUrl, createTCPServer, GeonixVersion, hash, isLoopbackAddress, picoid, proxyHttp, sleep } from "./Util.js";
 import express, { Router } from "express";
 import { Request } from "./Request.js";
 import expressWs from "express-ws";
@@ -15,12 +15,14 @@ const MAX_SESSIONS = 16384;
 // Real client IP — checks well-known CDN/proxy headers before falling back to socket address
 function getClientIp(req) {
     const header =
-        req.headers["cf-connecting-ip"] ||       // Cloudflare
-        req.headers["true-client-ip"] ||          // Cloudflare Enterprise / Akamai
-        req.headers["x-real-ip"] ||               // nginx
-        req.headers["x-forwarded-for"];           // standard (may be comma-separated list)
+        req.headers["cf-connecting-ip"] || // Cloudflare
+        req.headers["true-client-ip"] || // Cloudflare Enterprise / Akamai
+        req.headers["x-real-ip"] || // nginx
+        req.headers["x-forwarded-for"]; // standard (may be comma-separated list)
 
-    if (header) { return header.split(",")[0].trim(); }
+    if (header) {
+        return header.split(",")[0].trim();
+    }
     return req.socket?.remoteAddress || "unknown";
 }
 
@@ -39,12 +41,12 @@ const stats = {
     requests: 0,
     proxied: 0,
     proxied_over_nats: 0,
-    debug_requests: 0
+    debug_requests: 0,
 };
 
 const defaultOpts = {
-    beforeRequest: (_req, _res) => { },
-    afterRequest: (_req, _res) => { }
+    beforeRequest: (_req, _res) => {},
+    afterRequest: (_req, _res) => {},
 };
 
 /**
@@ -53,7 +55,6 @@ const defaultOpts = {
  * dynamically as services join and leave the bus.
  */
 export class Gateway {
-
     /**
      * Creates and starts a new Gateway instance.
      *
@@ -85,7 +86,7 @@ export class Gateway {
 
         this.#opts = { ...this.#opts, ...opts };
 
-        this.#start().catch(e => logger.error("gx.gateway.start:", e));
+        this.#start().catch((e) => logger.error("gx.gateway.start:", e));
     }
 
     async #start(port = 8080) {
@@ -179,7 +180,7 @@ export class Gateway {
         this.#api.all("*", (req, res) => {
             res.status(404).send({
                 error: 404,
-                source: "gw"
+                source: "gw",
             });
         });
 
@@ -253,7 +254,7 @@ export class Gateway {
             return true;
         };
 
-        entries = (await Promise.all(entries.map(processEntry))).filter(result => result === true);
+        entries = (await Promise.all(entries.map(processEntry))).filter((result) => result === true);
 
         if (entries.length > 0) {
             this.#rebuildRouter = true;
@@ -285,7 +286,7 @@ export class Gateway {
         });
 
         router.get("/services", (req, res) => {
-            const services = Object.values(registry.getEntries()).map(e => (`${e.n}@${e.v}`));
+            const services = Object.values(registry.getEntries()).map((e) => `${e.n}@${e.v}`);
             services.sort();
             res.send(services);
         });
@@ -312,11 +313,11 @@ export class Gateway {
                 node: {
                     version: process.version,
                     platform: process.platform,
-                    arch: process.arch
+                    arch: process.arch,
                 },
                 mem: process.memoryUsage(),
                 rss: process.memoryUsage.rss(),
-                cpu: process.cpuUsage()
+                cpu: process.cpuUsage(),
             });
         });
 
@@ -341,19 +342,21 @@ export class Gateway {
             });
 
             const dataLoop = async () => {
-                for await (const event of ingress) { client.write(event.data); }
+                for await (const event of ingress) {
+                    client.write(event.data);
+                }
             };
 
-            dataLoop().catch(e => logger.error("nats.proxy.dataLoop:", e));
+            dataLoop().catch((e) => logger.error("nats.proxy.dataLoop:", e));
         }
     }
 
     /**
      * Proxies websocket connection
-     * 
-     * @param {string} target 
-     * @param {Readable} inbound 
-     * @param {Request} req 
+     *
+     * @param {string} target
+     * @param {Readable} inbound
+     * @param {Request} req
      */
     #proxyWebsocket(target, inbound, req) {
         try {
@@ -366,7 +369,7 @@ export class Gateway {
 
             backend.on("open", () => {
                 backend.on("message", (data, isBinary) => inbound.send(isBinary ? data : data.toString()));
-                inbound.on("message", data => backend.send(data));
+                inbound.on("message", (data) => backend.send(data));
 
                 backend.on("close", () => inbound.close());
                 inbound.on("close", () => backend.close());
@@ -394,22 +397,32 @@ export class Gateway {
             const endpoints = [];
 
             for (let { entry, proxy } of entries) {
-                const backendAddr = proxy
-                    ? `127.0.0.1:${proxy.port}`
-                    : entry.a?.[Math.floor(Math.random() * entry.a.length)];
+                let backendAddr;
+                if (proxy) {
+                    backendAddr = `127.0.0.1:${proxy.port}`;
+                } else {
+                    const addrs = entry.a ?? [];
+                    const loopback = addrs.filter(isLoopbackAddress);
+                    const pool = loopback.length > 0 ? loopback : addrs;
+                    backendAddr = pool.length > 0 ? pool[Math.floor(Math.random() * pool.length)] : undefined;
+                }
 
-                if (!backendAddr) { continue; }
+                if (!backendAddr) {
+                    continue;
+                }
 
                 // generate global endpoint list
                 for (let e of entry.m) {
                     const endpointMatch = endpointMatcher.exec(e);
                     if (endpointMatch) {
                         const endpoint = endpointMatch.groups;
-                        const parsed = endpoint.options ? Object.fromEntries(new URLSearchParams(endpoint.options)) : {};
+                        const parsed = endpoint.options
+                            ? Object.fromEntries(new URLSearchParams(endpoint.options))
+                            : {};
                         const parsedOrder = parseInt(parsed.order, 10);
                         let options = {
                             ...parsed,
-                            order: Number.isNaN(parsedOrder) ? 100 : parsedOrder
+                            order: Number.isNaN(parsedOrder) ? 100 : parsedOrder,
                         };
 
                         try {
@@ -418,7 +431,7 @@ export class Gateway {
                                 version: semver.coerce(entry.v).version,
                                 options,
                                 endpoint,
-                                backend: [backendAddr]
+                                backend: [backendAddr],
                             });
                         } catch (e) {
                             logger.error("gateway.buildRouter.error:", entry);
@@ -435,7 +448,10 @@ export class Gateway {
                 const url = `${endpoints[index].endpoint.verb} ${endpoints[index].endpoint.url}`;
 
                 for (let n = 0; n < index; n++) {
-                    if (`${endpoints[n].endpoint.verb} ${endpoints[n].endpoint.url}` === url && endpoints[n].version === version) {
+                    if (
+                        `${endpoints[n].endpoint.verb} ${endpoints[n].endpoint.url}` === url &&
+                        endpoints[n].version === version
+                    ) {
                         endpoints[n].backend = endpoints[n].backend.concat(endpoints[index].backend);
                         endpoints.splice(index, 1);
                         break;
@@ -509,5 +525,4 @@ export class Gateway {
         this.#isActive = false;
         clearInterval(this.#rebuildRouterInterval);
     }
-
 }