geonix 1.31.0 → 1.32.1

package/README.md

@@ -295,6 +295,7 @@ Each returned part has:
 | `GX_LEVEL` | `info` | Log level: `debug`, `info`, `warn`, `error` |
 | `GX_STREAM_TIMEOUT` | `90000` | Max wait for a stream consumer to connect (ms) |
 | `GX_INACTIVITY_TIMEOUT` | `90000` | TCP proxy (HTTP-over-NATS) inactivity timeout (ms) |
+| `GX_HEALTH_TIMEOUT` | `2000` | Registry health-probe timeout per advertised address (ms) |
 | `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. |
 

package/benchmarks/transport.js

@@ -0,0 +1,223 @@
+// Latency / throughput benchmark comparing NATS vs LocalBus.
+//
+// The parent process spawns a child per transport so each child gets a fresh
+// module load (Connection.start() auto-runs on import and reads GX_TRANSPORT).
+// Each child measures two paths and prints JSON; the parent tabulates.
+//
+//   Service RPC          end-to-end Remote(svc).method() — uses HTTP loopback
+//                        for either transport (entries.length === 1 forces the
+//                        HTTP-RPC branch in directRequest)
+//   connection.request   raw pub/sub round-trip — measures the actual transport
+//
+// Run: `node benchmarks/transport.js`
+// Options (env): BENCH_ITERATIONS=2000  BENCH_WARMUP=200  BENCH_PAYLOAD_SIZE=64
+
+import { spawn } from "node:child_process";
+import { fileURLToPath } from "node:url";
+import { dirname, resolve } from "node:path";
+
+const here = dirname(fileURLToPath(import.meta.url));
+const root = resolve(here, "..");
+
+const ITERATIONS = parseInt(process.env.BENCH_ITERATIONS) || 2000;
+const WARMUP = parseInt(process.env.BENCH_WARMUP) || 200;
+const PAYLOAD_SIZE = parseInt(process.env.BENCH_PAYLOAD_SIZE) || 64;
+
+if (process.env.BENCH_CHILD) {
+    await runChild();
+} else {
+    await runParent();
+}
+
+// ---------------------------------------------------------------------------
+// Parent: spawn one child per transport, collect JSON, print a comparison
+// ---------------------------------------------------------------------------
+
+async function runParent() {
+    const transports = [
+        { name: "NATS",     url: "nats://localhost" },
+        { name: "LocalBus", url: "local://" },
+    ];
+
+    process.stderr.write(`Iterations: ${ITERATIONS}, warmup: ${WARMUP}, payload: ${PAYLOAD_SIZE} bytes\n\n`);
+
+    const results = [];
+    for (const t of transports) {
+        process.stderr.write(`Running ${t.name} (${t.url})... `);
+        const t0 = Date.now();
+        try {
+            const r = await runChildProcess(t.url);
+            process.stderr.write(`ok (${((Date.now() - t0) / 1000).toFixed(1)}s)\n`);
+            results.push({ ...t, ...r });
+        } catch (e) {
+            process.stderr.write(`FAILED: ${e.message}\n`);
+            results.push({ ...t, error: e.message });
+        }
+    }
+
+    printTable(results);
+}
+
+function runChildProcess(transport) {
+    return new Promise((res, rej) => {
+        const child = spawn(process.execPath, [fileURLToPath(import.meta.url)], {
+            env: {
+                ...process.env,
+                GX_TRANSPORT: transport,
+                GX_LOG_LEVEL: "none",
+                BENCH_CHILD: "1",
+            },
+            stdio: ["ignore", "pipe", "pipe"],
+            cwd: root,
+        });
+        let stdout = "";
+        let stderr = "";
+        child.stdout.on("data", (c) => stdout += c.toString());
+        child.stderr.on("data", (c) => stderr += c.toString());
+        const timer = setTimeout(() => {
+            child.kill("SIGKILL");
+            rej(new Error(`child timed out after 120s; stderr=${stderr.slice(0, 500)}`));
+        }, 120_000);
+        child.on("exit", (code) => {
+            clearTimeout(timer);
+            if (code !== 0) {
+                return rej(new Error(`exit ${code}; stderr=${stderr.slice(0, 500)}`));
+            }
+            try {
+                res(JSON.parse(stdout));
+            } catch (_e) {
+                rej(new Error(`bad JSON from child; stdout=${stdout.slice(0, 500)}`));
+            }
+        });
+    });
+}
+
+function printTable(results) {
+    const header = ["transport", "path", "mean (ms)", "p50", "p95", "p99", "throughput (rps)"];
+    const rows = [];
+    for (const r of results) {
+        if (r.error) {
+            rows.push([r.name, "—", "error", "—", "—", "—", r.error.slice(0, 50)]);
+            continue;
+        }
+        const s = r.serviceRPC;
+        const c = r.connectionRequest;
+        rows.push([
+            r.name,
+            "Service RPC (Remote)",
+            s.mean.toFixed(3),
+            s.p50.toFixed(3),
+            s.p95.toFixed(3),
+            s.p99.toFixed(3),
+            Math.round(s.throughput).toString(),
+        ]);
+        rows.push([
+            r.name,
+            "connection.request",
+            c.mean.toFixed(3),
+            c.p50.toFixed(3),
+            c.p95.toFixed(3),
+            c.p99.toFixed(3),
+            Math.round(c.throughput).toString(),
+        ]);
+    }
+
+    const widths = header.map((h, i) =>
+        Math.max(h.length, ...rows.map((r) => String(r[i]).length))
+    );
+    const fmt = (row) => "│ " + row.map((v, i) => String(v).padEnd(widths[i])).join(" │ ") + " │";
+    const sep = (l, m, r) => l + widths.map((w) => "─".repeat(w + 2)).join(m) + r;
+
+    console.log();
+    console.log(sep("┌", "┬", "┐"));
+    console.log(fmt(header));
+    console.log(sep("├", "┼", "┤"));
+    for (const row of rows) {
+        console.log(fmt(row));
+    }
+    console.log(sep("└", "┴", "┘"));
+    console.log();
+}
+
+// ---------------------------------------------------------------------------
+// Child: actually run the benchmark and print JSON to stdout
+// ---------------------------------------------------------------------------
+
+async function runChild() {
+    const { Service, connection, registry, Remote } = await import("../exports.js");
+    const { decode } = await import("../src/Codec.js");
+    const { uniqueName, waitFor } = await import("../tests/helpers.js");
+
+    await connection.waitUntilReady();
+
+    const SVC = uniqueName("BenchSvc");
+    class BenchSvc extends Service {
+        echo(v) { return v; }
+    }
+    BenchSvc.start({ name: SVC });
+    await waitFor(() => registry.getIdentifier(SVC), 5000);
+
+    const payload = "x".repeat(PAYLOAD_SIZE);
+
+    function percentile(arr, p) {
+        const sorted = arr.slice().sort((a, b) => a - b);
+        return sorted[Math.min(Math.floor(sorted.length * p), sorted.length - 1)];
+    }
+
+    function summary(latencies, totalSeconds) {
+        return {
+            iterations: latencies.length,
+            mean: latencies.reduce((a, b) => a + b, 0) / latencies.length,
+            p50: percentile(latencies, 0.50),
+            p95: percentile(latencies, 0.95),
+            p99: percentile(latencies, 0.99),
+            throughput: latencies.length / totalSeconds,
+        };
+    }
+
+    // Path 1: Service RPC via Remote (HTTP-loopback under the hood)
+    const remote = Remote(SVC);
+    for (let i = 0; i < WARMUP; i++) {
+        await remote.echo(payload);
+    }
+    let latencies = [];
+    let runStart = process.hrtime.bigint();
+    for (let i = 0; i < ITERATIONS; i++) {
+        const t0 = process.hrtime.bigint();
+        await remote.echo(payload);
+        const t1 = process.hrtime.bigint();
+        latencies.push(Number(t1 - t0) / 1e6);
+    }
+    const serviceRPC = summary(latencies, Number(process.hrtime.bigint() - runStart) / 1e9);
+
+    // Path 2: direct connection.request (pure transport pub/sub round-trip)
+    const subject = `bench.rr.${Date.now()}.${Math.random().toString(36).slice(2)}`;
+    const responder = await connection.subscribe(subject);
+    (async () => {
+        for await (const event of responder) {
+            const call = decode(event.data);
+            await connection.publish(call.$r, call.p);
+        }
+    })().catch(() => { /* ignore on shutdown */ });
+
+    for (let i = 0; i < WARMUP; i++) {
+        await connection.request(subject, payload);
+    }
+    latencies = [];
+    runStart = process.hrtime.bigint();
+    for (let i = 0; i < ITERATIONS; i++) {
+        const t0 = process.hrtime.bigint();
+        await connection.request(subject, payload);
+        const t1 = process.hrtime.bigint();
+        latencies.push(Number(t1 - t0) / 1e6);
+    }
+    const connectionRequest = summary(latencies, Number(process.hrtime.bigint() - runStart) / 1e9);
+    responder.unsubscribe();
+
+    process.stdout.write(JSON.stringify({
+        payloadSize: PAYLOAD_SIZE,
+        serviceRPC,
+        connectionRequest,
+    }));
+    process.exit(0);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "geonix",
-    "version": "1.31.0",
+    "version": "1.32.1",
     "type": "module",
     "description": "",
     "bin": {
@@ -13,6 +13,7 @@
         "test:unit": "GX_LOG_LEVEL=none node --test --test-reporter=spec tests/unit/*.test.js",
         "test:integration": "GX_LOG_LEVEL=none node --test --test-concurrency=1 --test-reporter=spec tests/integration/*.test.js",
         "lint": "npx eslint src",
+        "bench": "node benchmarks/transport.js",
         "deploy": "npm run build && npm publish"
     },
     "author": "Davor Tarandek <dtarandek@tria.hr>",

package/src/Gateway.js

@@ -223,6 +223,16 @@ export class Gateway {
             const existing = this.#registry[entry.i];
 
             if (existing !== undefined) {
+                const hasAddresses = entry.a?.length > 0;
+                // Graduate from a NATS-tunnel proxy to direct HTTP once addresses become reachable
+                if (existing.proxy && hasAddresses) {
+                    logger.info(`gateway.upgradeToDirect: ${entry.n}@${entry.v} (#${entry.i})`);
+                    existing.proxy.server?.close();
+                    existing.proxy = undefined;
+                    existing.knownAddressCount = entry.a.length;
+                    this.#rebuildRouter = true;
+                    return false;
+                }
                 // trigger rebuild if a direct entry has gained new addresses since last seen
                 if (!existing.proxy && entry.a?.length !== existing.knownAddressCount) {
                     existing.knownAddressCount = entry.a.length;

package/src/Registry.js

@@ -8,6 +8,11 @@ import { logger } from "./Logger.js";
 
 const REGISTRY_ENTRY_TIMEOUT = 5000;
 const GARBAGE_COLLECTOR_INTERVAL = 500;
+const HEALTH_TIMEOUT = 2000;
+
+// Read via function so tests can mutate the env after module load. Mirrors the
+// pattern used by getTransportTimeout / getStreamTimeout (per CLAUDE.md N6).
+const getHealthTimeout = () => parseInt(process.env.GX_HEALTH_TIMEOUT, 10) || HEALTH_TIMEOUT;
 
 /**
  * Maintains a local, in-process view of all services currently present on the NATS bus.
@@ -43,7 +48,7 @@ class Registry extends EventEmitter {
         this.#isActive = false;
     }
 
-    async #checkHealth(address, addresses, onFirstHealthy, timeout = 500) {
+    async #checkHealth(address, addresses, onFirstHealthy, timeout = getHealthTimeout()) {
         try {
             const result = await (await fetchWithTimeout(`http://${address}/!!_gx/health`, {}, timeout)).json();
 
@@ -60,6 +65,9 @@ class Registry extends EventEmitter {
     }
 
     async #registerService(data) {
+        // Capture the full advertised list before probing collapses data.a to the healthy subset
+        const advertised = Array.isArray(data.a) ? [...data.a] : [];
+
         if (data.a?.length > 0) {
             const allAddresses = data.a;
             data.a = [];
@@ -89,6 +97,7 @@ class Registry extends EventEmitter {
 
         this.#registry[data.i] = {
             ...data,
+            advertised,
             timeout: Date.now() + REGISTRY_ENTRY_TIMEOUT,
         };
 
@@ -102,6 +111,56 @@ class Registry extends EventEmitter {
         this.emit("added", this.#registry[data.i]);
     }
 
+    // Returns true when both arrays contain the same addresses (order-insensitive).
+    #sameAddresses(a, b) {
+        if (a.length !== b.length) { return false; }
+        const set = new Set(a);
+        for (const x of b) {
+            if (!set.has(x)) { return false; }
+        }
+        return true;
+    }
+
+    // Single-flight re-probe: rebuilds `entry.a` from `entry.advertised`. If a new advertised
+    // list arrives while a probe is running, queues exactly one re-run via probeStale.
+    async #reprobe(entry) {
+        if (entry.probeInFlight) {
+            entry.probeStale = true;
+            return;
+        }
+        entry.probeInFlight = true;
+        try {
+            do {
+                entry.probeStale = false;
+                const candidates = [...(entry.advertised ?? [])];
+                const healthy = [];
+                await Promise.all(candidates.map((a) => this.#checkHealth(a, healthy, () => { })));
+                entry.a = healthy;
+            } while (entry.probeStale);
+        } finally {
+            entry.probeInFlight = false;
+        }
+    }
+
+    // Refresh timeout for a known entry; kick off a re-probe when either (a) the advertised
+    // list changed, or (b) the entry's healthy `a` is empty and the source is still advertising
+    // addresses — that's the "all probes failed at registration" case that needs to retry.
+    #refreshKnown(entry, advertised) {
+        entry.timeout = Date.now() + REGISTRY_ENTRY_TIMEOUT;
+        if (!Array.isArray(advertised)) {
+            return;
+        }
+        const changed = !this.#sameAddresses(entry.advertised ?? [], advertised);
+        const stuckEmpty = (entry.a?.length ?? 0) === 0 && advertised.length > 0;
+        if (!changed && !stuckEmpty) {
+            return;
+        }
+        if (changed) {
+            entry.advertised = [...advertised];
+        }
+        this.#reprobe(entry).catch((e) => logger.error("registry.reprobe:", e));
+    }
+
     async #beaconListener() {
         const subscription = await connection.subscribe("gx2.beacon");
 
@@ -110,18 +169,18 @@ class Registry extends EventEmitter {
 
             const exists = this.#registry[data.i] !== undefined;
 
-            // if this is a short beacon, request full service info on first discovery only
+            // Short beacon (no `.n`). May still carry an `.a` we should react to.
             if (!data.n) {
                 if (exists) {
-                    this.#registry[data.i].timeout = Date.now() + REGISTRY_ENTRY_TIMEOUT;
+                    this.#refreshKnown(this.#registry[data.i], data.a);
                     continue;
                 }
                 data = await directRequest(data.i, "$getServiceInfo");
             }
 
-            // known service — just refresh timeout, no re-probing
+            // Full beacon for an already-known service: refresh timeout and react to `.a` changes.
             if (exists) {
-                this.#registry[data.i].timeout = Date.now() + REGISTRY_ENTRY_TIMEOUT;
+                this.#refreshKnown(this.#registry[data.i], data.a);
                 continue;
             }
 

package/src/Service.js

@@ -157,7 +157,15 @@ export class Service {
      */
     async #beacon() {
         while (this.#isActive) {
-            const payload = this.#options.fullBeacon ? this.#me : { i: this.#me.i };
+            // Refresh addresses each tick so a service that came up before its network was
+            // fully configured self-heals on the next beacon. Only `.a` can change at runtime;
+            // identity fields (i, n, v, m, gx) are immutable post-startup.
+            this.#me.a = getNetworkAddresses().map((address) => `${address}:${webserver.getPort()}`);
+
+            const payload = this.#options.fullBeacon
+                ? this.#me
+                : { i: this.#me.i, a: this.#me.a };
+
             connection.publish("gx2.beacon", payload).catch((e) => logger.warn("beacon.publish:", e));
             await sleep(BEACON_INTERVAL);
         }

package/src/Util.js

@@ -211,6 +211,15 @@ export function getNetworkAddresses() {
     for (const interfaceAddresses of Object.values(interfaces)) {
         if (!interfaceAddresses) { continue; }
         for (const addressObject of interfaceAddresses) {
+            // Skip IPv6 link-local addresses (fe80::/10). They require a zone identifier
+            // (e.g. %eth0) to route, which `fetch()` doesn't accept — advertising them
+            // just wastes a probe slot.
+            if (
+                addressObject.family === "IPv6" &&
+                addressObject.address.toLowerCase().startsWith("fe80:")
+            ) {
+                continue;
+            }
             const addr = addressObject.family === "IPv4"
                 ? addressObject.address
                 : addressObject.family === "IPv6"