geonix 1.30.2 → 1.31.0

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/Logger.js

@@ -5,12 +5,16 @@ const LEVEL = LEVELS[process.env.GX_LOG_LEVEL] ?? LEVELS.info;
 const FORMAT = process.env.GX_LOG_FORMAT === "json" ? "json" : "text";
 
 const defaultLoggerOptions = {
-    timestamp: true
+    timestamp: true,
 };
 
 function serialize(val) {
-    if (val instanceof Error) { return val.stack || val.message; }
-    if (typeof val === "object" && val !== null) { return JSON.stringify(val); }
+    if (val instanceof Error) {
+        return val.stack || val.message;
+    }
+    if (typeof val === "object" && val !== null) {
+        return JSON.stringify(val);
+    }
     return String(val);
 }
 
@@ -22,7 +26,6 @@ function serialize(val) {
  * The output format is controlled by `GX_LOG_FORMAT` (`text` | `json`, default `text`).
  */
 export class Logger {
-
     #options = defaultLoggerOptions;
     #level = LEVEL;
     #format = FORMAT;
@@ -46,10 +49,17 @@ export class Logger {
     #log(level, ...args) {
         const stream = level === "error" ? process.stderr : process.stdout;
         if (this.#format === "json") {
-            stream.write(JSON.stringify({ time: new Date().toISOString(), level, msg: args.map(serialize).join(" ") }) + "\n");
+            stream.write(
+                JSON.stringify({ time: new Date().toISOString(), level, msg: args.map(serialize).join(" ") }) + "\n",
+            );
         } else {
             const ts = this.#options.timestamp ? new Date().toISOString() : undefined;
-            stream.write([ts, TAGS[level], ...args].filter($ => $ !== undefined).map(serialize).join(" ") + "\n");
+            stream.write(
+                [ts, TAGS[level], ...args]
+                    .filter(($) => $ !== undefined)
+                    .map(serialize)
+                    .join(" ") + "\n",
+            );
         }
     }
 
@@ -104,7 +114,6 @@ export class Logger {
     setFormat(format) {
         this.#format = format === "json" ? "json" : "text";
     }
-
 }
 
 /**

package/src/Registry.js

@@ -17,7 +17,6 @@ const GARBAGE_COLLECTOR_INTERVAL = 500;
  * @extends EventEmitter
  */
 class Registry extends EventEmitter {
-
     #isActive = false;
     #registry = {};
     #byIdentifier = new Map();
@@ -25,15 +24,15 @@ class Registry extends EventEmitter {
     constructor() {
         super();
 
-        this.#start().catch(e => logger.error("registry.start:", e));
+        this.#start().catch((e) => logger.error("registry.start:", e));
     }
 
     async #start() {
         this.#isActive = true;
         await connection.waitUntilReady();
 
-        this.#beaconListener().catch(e => logger.error("registry.beaconListener:", e));
-        this.#garbageCollector().catch(e => logger.error("registry.garbageCollector:", e));
+        this.#beaconListener().catch((e) => logger.error("registry.beaconListener:", e));
+        this.#garbageCollector().catch((e) => logger.error("registry.garbageCollector:", e));
     }
 
     /**
@@ -69,14 +68,17 @@ class Registry extends EventEmitter {
             let firstFound = false;
             const onFirstHealthy = () => {
                 if (!firstFound) {
-                    firstFound = true; resolveFirst();
+                    firstFound = true;
+                    resolveFirst();
                 }
             };
 
             // all checks run in parallel; background ones push into data.a,
             // which is the same array reference spread into the registry entry below
             // resolve promiseFirst when all checks are done so we don't wait on the timeout
-            Promise.all(allAddresses.map(a => this.#checkHealth(a, data.a, onFirstHealthy))).then(() => resolveFirst());
+            Promise.all(allAddresses.map((a) => this.#checkHealth(a, data.a, onFirstHealthy))).then(() =>
+                resolveFirst(),
+            );
 
             try {
                 await withTimeout(promiseFirst, 5000);
@@ -87,7 +89,7 @@ class Registry extends EventEmitter {
 
         this.#registry[data.i] = {
             ...data,
-            timeout: Date.now() + REGISTRY_ENTRY_TIMEOUT
+            timeout: Date.now() + REGISTRY_ENTRY_TIMEOUT,
         };
 
         const nameVersion = `${data.n}@${data.v}`;
@@ -124,7 +126,7 @@ class Registry extends EventEmitter {
             }
 
             // new service — dispatch registration without awaiting so the beacon loop stays unblocked
-            this.#registerService(data).catch(e => logger.error("registry.registerService:", e));
+            this.#registerService(data).catch((e) => logger.error("registry.registerService:", e));
         }
     }
 
@@ -144,7 +146,9 @@ class Registry extends EventEmitter {
                     const set = this.#byIdentifier.get(nameVersion);
                     if (set) {
                         set.delete(entry.i);
-                        if (set.size === 0) { this.#byIdentifier.delete(nameVersion); }
+                        if (set.size === 0) {
+                            this.#byIdentifier.delete(nameVersion);
+                        }
                     }
                     this.#byIdentifier.delete(entry.i);
 
@@ -174,8 +178,11 @@ class Registry extends EventEmitter {
      */
     getEntriesForIdentifier(identifier) {
         const ids = this.#byIdentifier.get(identifier);
-        if (!ids) { return []; }
-        return [...ids].map(i => this.#registry[i]).filter(Boolean);
+        if (!ids) {
+            return [];
+        }
+
+        return [...ids].map((i) => this.#registry[i]).filter(Boolean);
     }
 
     /**
@@ -215,7 +222,6 @@ class Registry extends EventEmitter {
             return `${matches[0].n}@${matches[0].v}`;
         }
     }
-
 }
 
 /**
@@ -223,4 +229,4 @@ class Registry extends EventEmitter {
  *
  * @type {Registry}
  */
-export const registry = new Registry();
+export const registry = new Registry();

package/src/Remote.js

@@ -10,12 +10,16 @@ import { Request } from "./Request.js";
  * @param {...any} context - Optional context values forwarded to the remote method.
  * @returns {Proxy} A proxy whose properties are async functions that call the remote service.
  */
-export const Remote = (service, ...context) => new Proxy({}, {
-    get: (_target, method) => {
-        if (typeof method !== "string" || method === "then") {
-            return undefined;
-        }
+export const Remote = (service, ...context) =>
+    new Proxy(
+        {},
+        {
+            get: (_target, method) => {
+                if (typeof method !== "string" || method === "then") {
+                    return undefined;
+                }
 
-        return async (...args) => Request(service, method, args, context);
-    }
-});
+                return async (...args) => Request(service, method, args, context);
+            },
+        },
+    );

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";
@@ -23,7 +23,7 @@ function waitForIdentifier(name, version, id, timeout) {
         return Promise.resolve(found);
     }
 
-    return new Promise(resolve => {
+    return new Promise((resolve) => {
         const timer = setTimeout(() => {
             registry.removeListener("added", onAdded);
             resolve(null);
@@ -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 };
@@ -109,11 +112,15 @@ export async function directRequest(identifier, method, args, context, options,
 
             let httpResponse;
             try {
-                const res = await fetchWithTimeout(url, {
-                    method: "POST",
-                    headers: { "content-type": contentType },
-                    body: fetchBody,
-                }, options?.httpTimeout ?? 5000);
+                const res = await fetchWithTimeout(
+                    url,
+                    {
+                        method: "POST",
+                        headers: { "content-type": contentType },
+                        body: fetchBody,
+                    },
+                    options?.httpTimeout ?? 5000,
+                );
                 if (res.ok) {
                     httpResponse = _payloadKey
                         ? JSON.parse(decryptPayload(Buffer.from(await res.arrayBuffer())))
@@ -124,7 +131,9 @@ export async function directRequest(identifier, method, args, context, options,
             }
 
             if (httpResponse) {
-                if (httpResponse.e) { throw Error(`Request: remote error: ${httpResponse.e}`); }
+                if (httpResponse.e) {
+                    throw Error(`Request: remote error: ${httpResponse.e}`);
+                }
                 if (isStream(httpResponse.r)) {
                     return JSON.parse(await streamToString(httpResponse.r));
                 }
@@ -142,19 +151,29 @@ export async function directRequest(identifier, method, args, context, options,
                 m: method,
                 a: args,
                 c: context,
-                o: originator
+                o: originator,
             },
-            options);
+            options,
+        );
 
         // automatically process streamed response
         if (isStream(response)) {
             response = JSON.parse(await streamToString(response));
         }
     } catch (e) {
-        logger.debug("GxError: directRequest", inspect({
-            originator, service: service ?? identifier, method, args, context, options,
-            error: e, duration: Date.now() - requestBegin
-        }));
+        logger.debug(
+            "GxError: directRequest",
+            inspect({
+                originator,
+                service: service ?? identifier,
+                method,
+                args,
+                context,
+                options,
+                error: e,
+                duration: Date.now() - requestBegin,
+            }),
+        );
 
         throw e;
     }
@@ -199,4 +218,4 @@ export async function Subscribe(subject, callback) {
     for await (const event of subscription) {
         callback(event.data);
     }
-}
+}