geonix 1.23.8 → 1.30.2

package/src/Registry.js

@@ -1,38 +1,105 @@
 import { connection } from "./Connection.js";
-import { sleep } from "./Util.js";
+import { fetchWithTimeout, sleep, withTimeout } from "./Util.js";
 import semver from "semver";
 import EventEmitter from "events";
 import { directRequest } from "./Request.js";
 import { decode } from "./Codec.js";
+import { logger } from "./Logger.js";
 
 const REGISTRY_ENTRY_TIMEOUT = 5000;
+const GARBAGE_COLLECTOR_INTERVAL = 500;
 
 /**
- * Registry maintains a local list of available services and their versions.
+ * Maintains a local, in-process view of all services currently present on the NATS bus.
+ * Entries are populated from beacon messages and expire after 5 seconds of silence.
+ * Emits `"added"` when a new entry is registered and `"removed"` when one expires.
+ *
+ * @extends EventEmitter
  */
 class Registry extends EventEmitter {
 
     #isActive = false;
     #registry = {};
+    #byIdentifier = new Map();
 
     constructor() {
         super();
 
-        this.#start();
+        this.#start().catch(e => logger.error("registry.start:", e));
     }
 
     async #start() {
         this.#isActive = true;
         await connection.waitUntilReady();
 
-        this.#beaconListener();
-        this.#garbageCollector();
+        this.#beaconListener().catch(e => logger.error("registry.beaconListener:", e));
+        this.#garbageCollector().catch(e => logger.error("registry.garbageCollector:", e));
     }
 
-    async stop() {
+    /**
+     * Stops the beacon listener and garbage collector.
+     * @returns {void}
+     */
+    stop() {
         this.#isActive = false;
     }
 
+    async #checkHealth(address, addresses, onFirstHealthy, timeout = 500) {
+        try {
+            const result = await (await fetchWithTimeout(`http://${address}/!!_gx/health`, {}, timeout)).json();
+
+            if (result.status === "healthy") {
+                addresses.push(address);
+                onFirstHealthy();
+                return true;
+            }
+        } catch {
+            // ignore errors
+        }
+
+        return false;
+    }
+
+    async #registerService(data) {
+        if (data.a?.length > 0) {
+            const allAddresses = data.a;
+            data.a = [];
+
+            let { promise: promiseFirst, resolve: resolveFirst } = Promise.withResolvers();
+            let firstFound = false;
+            const onFirstHealthy = () => {
+                if (!firstFound) {
+                    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());
+
+            try {
+                await withTimeout(promiseFirst, 5000);
+            } catch {
+                // safety net only — should not normally be reached
+            }
+        }
+
+        this.#registry[data.i] = {
+            ...data,
+            timeout: Date.now() + REGISTRY_ENTRY_TIMEOUT
+        };
+
+        const nameVersion = `${data.n}@${data.v}`;
+        if (!this.#byIdentifier.has(nameVersion)) {
+            this.#byIdentifier.set(nameVersion, new Set());
+        }
+        this.#byIdentifier.get(nameVersion).add(data.i);
+        this.#byIdentifier.set(data.i, new Set([data.i]));
+
+        this.emit("added", this.#registry[data.i]);
+    }
+
     async #beaconListener() {
         const subscription = await connection.subscribe("gx2.beacon");
 
@@ -41,19 +108,23 @@ class Registry extends EventEmitter {
 
             const exists = this.#registry[data.i] !== undefined;
 
-            // if this is a short beacon, request full service info
+            // if this is a short beacon, request full service info on first discovery only
             if (!data.n) {
+                if (exists) {
+                    this.#registry[data.i].timeout = Date.now() + REGISTRY_ENTRY_TIMEOUT;
+                    continue;
+                }
                 data = await directRequest(data.i, "$getServiceInfo");
             }
 
-            this.#registry[data.i] = {
-                ...data,
-                timeout: Date.now() + REGISTRY_ENTRY_TIMEOUT
-            };
-
-            if (!exists) {
-                this.emit("added", this.#registry[data.i]);
+            // known service — just refresh timeout, no re-probing
+            if (exists) {
+                this.#registry[data.i].timeout = Date.now() + REGISTRY_ENTRY_TIMEOUT;
+                continue;
             }
+
+            // new service — dispatch registration without awaiting so the beacon loop stays unblocked
+            this.#registerService(data).catch(e => logger.error("registry.registerService:", e));
         }
     }
 
@@ -69,18 +140,54 @@ class Registry extends EventEmitter {
                 if (now > entry.timeout) {
                     delete this.#registry[identifier];
 
+                    const nameVersion = `${entry.n}@${entry.v}`;
+                    const set = this.#byIdentifier.get(nameVersion);
+                    if (set) {
+                        set.delete(entry.i);
+                        if (set.size === 0) { this.#byIdentifier.delete(nameVersion); }
+                    }
+                    this.#byIdentifier.delete(entry.i);
+
                     this.emit("removed", entry);
                 }
             }
 
-            await sleep(500);
+            await sleep(GARBAGE_COLLECTOR_INTERVAL);
         }
     }
 
+    /**
+     * Returns the raw registry map keyed by instance ID.
+     *
+     * @returns {Object.<string, object>} All currently live registry entries.
+     */
     getEntries() {
         return this.#registry;
     }
 
+    /**
+     * Returns all live registry entries that match a given identifier string
+     * (e.g. `"MyService@1.0.0"` or a bare instance ID).
+     *
+     * @param {string} identifier - Identifier in the form `"Name@version"` or an instance ID.
+     * @returns {object[]} Array of matching registry entry objects.
+     */
+    getEntriesForIdentifier(identifier) {
+        const ids = this.#byIdentifier.get(identifier);
+        if (!ids) { return []; }
+        return [...ids].map(i => this.#registry[i]).filter(Boolean);
+    }
+
+    /**
+     * Looks up the best-matching service identifier for the given name, optional semver range,
+     * and optional static ID. Returns the highest-version match as a `"Name@version"` string,
+     * or the instance ID when an exact `id` is requested.
+     *
+     * @param {string} service - Service name to look up.
+     * @param {string} [version] - Optional semver range (e.g. `"^1.2"`).
+     * @param {string} [id] - Optional static service ID for targeting a specific instance.
+     * @returns {string|undefined} Resolved identifier, or `undefined` if not found.
+     */
     getIdentifier(service, version, id) {
         let matches = [];
 
@@ -111,4 +218,9 @@ class Registry extends EventEmitter {
 
 }
 
+/**
+ * Singleton {@link Registry} instance shared across the process.
+ *
+ * @type {Registry}
+ */
 export const registry = new Registry();

package/src/Remote.js

@@ -1,12 +1,21 @@
 import { Request } from "./Request.js";
 
 /**
- * Create a remote function proxy
- * 
- * @param {String} service 
- * @param  {...String|Stream|Object} context 
- * @returns {String|Stream|Object}
+ * Creates a proxy object that forwards property-access calls to a named remote service.
+ * Each property access returns an async function that invokes the corresponding method on
+ * the remote service via {@link Request}.
+ *
+ * @param {string} service - Service name, optionally with a version range or instance ID
+ *   (e.g. `"MyService"`, `"MyService@^1.2"`, `"MyService#<instanceId>"`).
+ * @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, _receiver) => async (...args) => Request(service, method, args, context)
+    get: (_target, method) => {
+        if (typeof method !== "string" || method === "then") {
+            return undefined;
+        }
+
+        return async (...args) => Request(service, method, args, context);
+    }
 });

package/src/Request.js

@@ -1,105 +1,140 @@
 import { connection } from "./Connection.js";
 import { registry } from "./Registry.js";
-import { Service } from "./Service.js";
-import { hash, sleep } from "./Util.js";
-import { RequestOptionsClass } from "./RequestOptions.js";
+import { fetchWithTimeout, hash } from "./Util.js";
+import { AsyncLocalStorage } from "node:async_hooks";
+import { _requestOptionsSymbol } from "./RequestOptions.js";
 import { isStream, streamToString } from "./Stream.js";
 import { inspect } from "node:util";
 import { logger } from "./Logger.js";
-
-const REGISTRY_TIMEOUT = 300000;
-
-/**
- * Get full v8 stack trace
- * @returns 
- */
-function getStack() {
-    const oldLimit = Error.stackTraceLimit;
-    const oldHandler = Error.prepareStackTrace;
-    const holder = {};
-
-    // set new values
-    Error.stackTraceLimit = Infinity;
-    Error.prepareStackTrace = (holder, stackTrace) => stackTrace;
-
-    // capture stack trace
-    Error.captureStackTrace(holder, getStack);
-
-    const stack = holder.stack;
-
-    // restore values
-    Error.prepareStackTrace = oldHandler;
-    Error.stackTraceLimit = oldLimit;
-
-    return stack;
-}
+import { _payloadKey, encryptPayload, decryptPayload } from "./Crypto.js";
 
 /**
- * Determine which service class is making the call. 
- * This information is then attached to the gx2.service call for debugging and monitoring purposes.
- * @returns 
+ * AsyncLocalStorage instance used to propagate the RPC call originator across async boundaries
+ * so that nested service calls can include accurate tracing information.
+ *
+ * @type {import('node:async_hooks').AsyncLocalStorage<{ originator: string }>}
  */
-function getOriginator() {
-    const stack = getStack();
+export const rpcContext = new AsyncLocalStorage();
+const REGISTRY_TIMEOUT = 300000;
 
-    for (const item of stack) {
-        const typeName = item.getTypeName();
+function waitForIdentifier(name, version, id, timeout) {
+    const found = registry.getIdentifier(name, version, id);
+    if (found) {
+        return Promise.resolve(found);
+    }
 
-        if (Service.serviceClasses.includes(typeName)) {
-            return `${typeName}.${item.getMethodName()}`;
+    return new Promise(resolve => {
+        const timer = setTimeout(() => {
+            registry.removeListener("added", onAdded);
+            resolve(null);
+        }, timeout);
+
+        function onAdded() {
+            const identifier = registry.getIdentifier(name, version, id);
+            if (identifier) {
+                clearTimeout(timer);
+                registry.removeListener("added", onAdded);
+                resolve(identifier);
+            }
         }
-    }
+
+        registry.on("added", onAdded);
+    });
 }
 
 /**
- * Send a request to a service
- * 
- * @param {string} service 
- * @param {string} method 
- * @param {any[]} args 
- * @param {any[]} context 
- * @param {object} options 
- * @returns 
+ * Sends a request to a named service, waiting in the registry for up to `timeout` ms if the
+ * service is not yet available. Tries HTTP RPC first, falls back to NATS.
+ *
+ * @param {string} service - Service name, optionally with version (`@^1.2`) or instance ID (`#<id>`).
+ * @param {string} method - Method name to invoke on the service.
+ * @param {any[]} args - Positional arguments to pass. The first argument may be a {@link RequestOptions} object.
+ * @param {any[]} [context] - Optional context values forwarded to the remote method.
+ * @param {object} [options] - Request options (e.g. `timeout`).
+ * @returns {Promise<any>} The value returned by the remote method.
+ * @throws {Error} If the service is not found within the timeout or the remote method throws.
  */
 export async function Request(service, method, args, context, options) {
     const match = /(?<name>[^@#]*)(@(?<version>[^@#]*))?(#(?<id>[^@#]*))?/.exec(service);
     const { name, version, id } = match.groups;
 
     // allow passing RequestOptions as first arg
-    if (args?.length > 0 && args[0] instanceof RequestOptionsClass) {
-        options = (args.shift())?.options;
+    if (args?.length > 0 && args[0]?.[_requestOptionsSymbol] !== undefined) {
+        options = args.shift()[_requestOptionsSymbol];
     }
 
-    let identifier = null;
-
-    // get service instance identifier and wait for it if it's not available
     const registryTimeout = options?.timeout ?? REGISTRY_TIMEOUT;
-    const delay = 5;
-    let retries = Math.floor(registryTimeout / delay);
-    while (identifier == null && retries-- > 0) {
-        identifier = registry.getIdentifier(name, version, id);
-        if (!identifier) {
-            await sleep(delay);
-        }
+    const identifier = await waitForIdentifier(name, version, id, registryTimeout);
+
+    if (!identifier) {
+        throw Error(`Request: service "${service}" not found within ${registryTimeout}ms`);
     }
 
     return directRequest(identifier, method, args, context, options, service);
 }
 
+let _httpRpcRoundRobin = 0;
+
 /**
- * Send a request to a service
- * 
- * @param {string} identifier 
- * @param {string} method 
- * @param {any[]} args 
- * @param {any[]} context 
- * @param {object} options 
- * @returns 
+ * Sends a request directly to a resolved registry identifier without performing a registry
+ * lookup. Prefers HTTP RPC for single-instance services; falls back to NATS otherwise.
+ *
+ * @param {string} identifier - Registry identifier in the form `"Name@version"` or an instance ID.
+ * @param {string} method - Method name to invoke on the service.
+ * @param {any[]} [args] - Positional arguments forwarded to the remote method.
+ * @param {any[]} [context] - Optional context values forwarded to the remote method.
+ * @param {object} [options] - Request options (e.g. `timeout`, `httpTimeout`).
+ * @param {string} [service] - Original service string used only for error logging.
+ * @returns {Promise<any>} The value returned by the remote method.
+ * @throws {Error} If the transport returns an error or the response is invalid.
  */
 export async function directRequest(identifier, method, args, context, options, service) {
+    const originator = rpcContext.getStore()?.originator;
+    const requestBegin = Date.now();
+
+    // try HTTP RPC first if the service has a single known instance with addresses
+    // (multiple instances use NATS so queue-group distribution is preserved)
+    const entries = registry.getEntriesForIdentifier(identifier);
+    if (entries.length === 1) {
+        const addresses = entries[0].a || [];
+        if (addresses.length > 0) {
+            const address = addresses[_httpRpcRoundRobin++ % addresses.length];
+
+            const url = `http://${address}/!!_gx/rpc/${hash(entries[0].i)}`;
+            const rpcPayload = { m: method, a: args, c: context, o: originator };
+            const fetchBody = _payloadKey
+                ? encryptPayload(Buffer.from(JSON.stringify(rpcPayload)))
+                : JSON.stringify(rpcPayload);
+            const contentType = _payloadKey ? "application/octet-stream" : "application/json";
+
+            let httpResponse;
+            try {
+                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())))
+                        : await res.json();
+                }
+            } catch (e) {
+                logger.debug("directRequest: HTTP RPC failed, falling back to NATS", address, e.message);
+            }
+
+            if (httpResponse) {
+                if (httpResponse.e) { throw Error(`Request: remote error: ${httpResponse.e}`); }
+                if (isStream(httpResponse.r)) {
+                    return JSON.parse(await streamToString(httpResponse.r));
+                }
+                return httpResponse.r;
+            }
+        }
+    }
+
+    // NATS fallback
     let response;
-    const originator = getOriginator();
-    let requestBegin = Date.now();
     try {
         response = await connection.request(
             `gx2.service.${hash(identifier)}`,
@@ -137,21 +172,23 @@ export async function directRequest(identifier, method, args, context, options,
 }
 
 /**
- * Publish payload to a subject
- * 
- * @param {string} subject 
- * @param {string|number} payload 
+ * Publishes a raw payload to a NATS subject. Fire-and-forget; no reply is expected.
+ *
+ * @param {string} subject - NATS subject to publish to.
+ * @param {string|Buffer} payload - Raw bytes or string to send.
+ * @returns {Promise<void>}
  */
 export async function Publish(subject, payload) {
-    connection.publishRaw(subject, Buffer.from(payload));
+    await connection.publishRaw(subject, Buffer.from(payload));
 }
 
 /**
- * Subscribe to subject
- * 
- * @param {string} subject 
- * @param {function} callback 
- * @returns 
+ * Subscribes to a NATS subject and invokes `callback` with the raw message data for each
+ * incoming message. Returns once the subscription is drained.
+ *
+ * @param {string} subject - NATS subject to subscribe to.
+ * @param {function(Buffer): void} callback - Function called with the raw message data.
+ * @returns {Promise<void>}
  */
 export async function Subscribe(subject, callback) {
     if (typeof callback !== "function") {

package/src/RequestOptions.js

@@ -1,11 +1,14 @@
-export class RequestOptionsClass {
-    options;
+const OPTS = Symbol("RequestOptions");
 
-    constructor(options) {
-        this.options = options;
-    }
+/**
+ * Wraps a plain options object in a sentinel that {@link Request} can detect and extract
+ * when it appears as the first argument of a service method call.
+ *
+ * @param {{ timeout?: number, httpTimeout?: number }} options - Request options to attach.
+ * @returns {{ [symbol]: object }} Sentinel object consumed by {@link Request}.
+ */
+export function RequestOptions(options) {
+    return { [OPTS]: options };
 }
 
-export const RequestOptions = (options) => {
-    return new RequestOptionsClass(options);
-};
+export { OPTS as _requestOptionsSymbol };