geonix 1.30.4 → 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.4",
+    "version": "1.31.0",
     "type": "module",
     "description": "",
     "bin": {

package/src/Connection.js

@@ -62,6 +62,19 @@ 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),

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";
@@ -397,9 +397,15 @@ 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;

package/src/LocalBus.js

@@ -0,0 +1,190 @@
+import { Buffer } from "node:buffer";
+
+const LOCAL_MAX_PAYLOAD = 8 * 1024 * 1024;
+
+/**
+ * NATS-style subject matcher. Tokens split on `.`.
+ *   `*` matches exactly one token.
+ *   `>` matches one or more trailing tokens; must be the last token in the pattern.
+ *
+ * @param {string} pattern
+ * @param {string} subject
+ * @returns {boolean}
+ */
+export function subjectMatch(pattern, subject) {
+    const p = pattern.split(".");
+    const s = subject.split(".");
+    for (let i = 0; i < p.length; i++) {
+        if (p[i] === ">") {
+            return i === p.length - 1 && s.length > i;
+        }
+        if (i >= s.length) {
+            return false;
+        }
+        if (p[i] !== "*" && p[i] !== s[i]) {
+            return false;
+        }
+    }
+    return p.length === s.length;
+}
+
+/**
+ * A single subscription on the in-memory bus. Async iterable; yields `{ data, subject }`
+ * events in publish order. Auto-closes after `max` deliveries when `max` is set.
+ */
+class LocalSubscription {
+    #subject;
+    #queueGroup;
+    #max;
+    #count = 0;
+    #queue = [];
+    #waiters = [];
+    #closed = false;
+    #onClose;
+
+    constructor(subject, options, onClose) {
+        this.#subject = subject;
+        this.#queueGroup = options?.queue;
+        this.#max = options?.max;
+        this.#onClose = onClose;
+    }
+
+    get subject() { return this.#subject; }
+    get queue() { return this.#queueGroup; }
+    get isClosed() { return this.#closed; }
+
+    deliver(event) {
+        if (this.#closed) { return; }
+        this.#count++;
+        if (this.#waiters.length > 0) {
+            this.#waiters.shift().resolve({ value: event, done: false });
+        } else {
+            this.#queue.push(event);
+        }
+        if (this.#max != null && this.#count >= this.#max) {
+            this.#close();
+        }
+    }
+
+    #close() {
+        if (this.#closed) { return; }
+        this.#closed = true;
+        this.#onClose?.(this);
+        for (const w of this.#waiters) {
+            w.resolve({ value: undefined, done: true });
+        }
+        this.#waiters = [];
+    }
+
+    unsubscribe() { this.#close(); }
+    drain() { this.#close(); return Promise.resolve(); }
+
+    [Symbol.asyncIterator]() {
+        return {
+            next: () => {
+                if (this.#queue.length > 0) {
+                    return Promise.resolve({ value: this.#queue.shift(), done: false });
+                }
+                if (this.#closed) {
+                    return Promise.resolve({ value: undefined, done: true });
+                }
+                const w = Promise.withResolvers();
+                this.#waiters.push(w);
+                return w.promise;
+            },
+            return: () => {
+                this.#close();
+                return Promise.resolve({ value: undefined, done: true });
+            },
+        };
+    }
+}
+
+/**
+ * In-memory NATS-shaped pub/sub bus. Implements the subset of `NatsConnection` that Geonix
+ * consumes: `publish`, `subscribe`, `drain`, `closed`, `status`, `info.max_payload`.
+ * Single-process only — no socket, no inter-process delivery.
+ *
+ * Semantics matched against real NATS:
+ *   - Wildcards (`*`, `>`) per NATS subject spec.
+ *   - Queue groups: one delivery per group per publish; round-robin within the group.
+ *   - Plain (non-queue) subscriptions: each receives its own copy of every match.
+ *   - `{ max: N }` auto-closes the subscription after N deliveries.
+ *   - Within a subscription, FIFO.
+ *   - Defensive copy on publish (publisher mutation after publish is safe).
+ */
+class LocalBus {
+    #subs = new Set();
+    #info = { max_payload: LOCAL_MAX_PAYLOAD };
+    #closed = false;
+    #closedDeferred = Promise.withResolvers();
+    #queueCounters = new Map();
+
+    get info() { return this.#info; }
+
+    isClosed() { return this.#closed; }
+
+    async publish(subject, data) {
+        if (this.#closed) { return; }
+
+        const buf = Buffer.from(data);
+
+        const byQueue = new Map();
+        const plain = [];
+        for (const sub of this.#subs) {
+            if (!subjectMatch(sub.subject, subject)) { continue; }
+            if (sub.queue) {
+                if (!byQueue.has(sub.queue)) { byQueue.set(sub.queue, []); }
+                byQueue.get(sub.queue).push(sub);
+            } else {
+                plain.push(sub);
+            }
+        }
+
+        for (const sub of plain) {
+            sub.deliver({ data: buf, subject });
+        }
+
+        for (const [group, members] of byQueue) {
+            const idx = (this.#queueCounters.get(group) ?? 0) % members.length;
+            this.#queueCounters.set(group, idx + 1);
+            members[idx].deliver({ data: buf, subject });
+        }
+    }
+
+    async subscribe(subject, options) {
+        if (this.#closed) {
+            throw new Error("LocalBus: subscribe on closed bus");
+        }
+        const sub = new LocalSubscription(subject, options, (s) => this.#subs.delete(s));
+        this.#subs.add(sub);
+        return sub;
+    }
+
+    async drain() {
+        if (this.#closed) { return; }
+        for (const sub of [...this.#subs]) {
+            sub.unsubscribe();
+        }
+        this.#closed = true;
+        this.#closedDeferred.resolve();
+    }
+
+    closed() { return this.#closedDeferred.promise; }
+
+    status() {
+        // never-yielding async iterable — the bus has no transport to lose
+        return {
+            [Symbol.asyncIterator]() {
+                return {
+                    next: () => new Promise(() => { /* never resolves */ }),
+                    return: () => Promise.resolve({ value: undefined, done: true }),
+                };
+            },
+        };
+    }
+}
+
+export function createLocalBus() {
+    return new LocalBus();
+}

package/src/Request.js

@@ -1,6 +1,6 @@
 import { connection } from "./Connection.js";
 import { registry } from "./Registry.js";
-import { fetchWithTimeout, hash } from "./Util.js";
+import { fetchWithTimeout, hash, isLoopbackAddress } from "./Util.js";
 import { AsyncLocalStorage } from "node:async_hooks";
 import { _requestOptionsSymbol } from "./RequestOptions.js";
 import { isStream, streamToString } from "./Stream.js";
@@ -98,7 +98,10 @@ export async function directRequest(identifier, method, args, context, options,
     if (entries.length === 1) {
         const addresses = entries[0].a || [];
         if (addresses.length > 0) {
-            const address = addresses[_httpRpcRoundRobin++ % addresses.length];
+            const loopback = addresses.filter(isLoopbackAddress);
+            const remote = addresses.filter((a) => !isLoopbackAddress(a));
+            const pool = loopback.length > 0 ? loopback : remote;
+            const address = pool[_httpRpcRoundRobin++ % pool.length];
 
             const url = `http://${address}/!!_gx/rpc/${hash(entries[0].i)}`;
             const rpcPayload = { m: method, a: args, c: context, o: originator };

package/src/Util.js

@@ -203,24 +203,31 @@ export async function getFirstItemFromAsyncIterable(asyncIterable) {
 }
 
 export function getNetworkAddresses() {
-    const list = [];
-    const interfaces = networkInterfaces();
-
-    for (let interfaceAddresses of Object.values(interfaces)) {
-        for (let addressObject of interfaceAddresses) {
-            if (addressObject.family === "IPv4") {
-                list.push(addressObject.address);
-            }
-
-            if (addressObject.family === "IPv6") {
-                list.push(`[${addressObject.address}]`);
-            }
+    // Loopback entries are seeded first so same-host callers prefer them; the OS-reported
+    // duplicates are filtered out below to keep the prepended ones canonical.
+    const list = ["127.0.0.1", "[::1]"];
+    const interfaces = networkInterfaces() ?? {};
+
+    for (const interfaceAddresses of Object.values(interfaces)) {
+        if (!interfaceAddresses) { continue; }
+        for (const addressObject of interfaceAddresses) {
+            const addr = addressObject.family === "IPv4"
+                ? addressObject.address
+                : addressObject.family === "IPv6"
+                    ? `[${addressObject.address}]`
+                    : null;
+            if (!addr) { continue; }
+            if (addr === "127.0.0.1" || addr === "[::1]") { continue; }
+            list.push(addr);
         }
     }
 
     return list;
 }
 
+export const isLoopbackAddress = (addressWithPort) =>
+    addressWithPort.startsWith("127.0.0.1:") || addressWithPort.startsWith("[::1]:");
+
 export function isIterable(obj) {
     return obj && (typeof obj[Symbol.iterator] === "function" || typeof obj[Symbol.asyncIterator] === "function");
 }