geonix 1.30.4 → 1.32.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/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.30.4",
+    "version": "1.32.0",
     "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/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";
@@ -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;
@@ -397,9 +407,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/Registry.js

@@ -60,6 +60,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 +92,7 @@ class Registry extends EventEmitter {
 
         this.#registry[data.i] = {
             ...data,
+            advertised,
             timeout: Date.now() + REGISTRY_ENTRY_TIMEOUT,
         };
 
@@ -102,6 +106,51 @@ 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; if the beacon carries an `.a` that differs from
+    // the cached advertised list, kick off a re-probe to rebuild the healthy subset.
+    #refreshKnown(entry, advertised) {
+        entry.timeout = Date.now() + REGISTRY_ENTRY_TIMEOUT;
+        if (!Array.isArray(advertised)) {
+            return;
+        }
+        if (this.#sameAddresses(entry.advertised ?? [], advertised)) {
+            return;
+        }
+        entry.advertised = [...advertised];
+        this.#reprobe(entry).catch((e) => logger.error("registry.reprobe:", e));
+    }
+
     async #beaconListener() {
         const subscription = await connection.subscribe("gx2.beacon");
 
@@ -110,18 +159,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/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/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

@@ -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");
 }