geonix 1.23.8 → 1.30.4

package/src/Gateway.js

@@ -1,20 +1,38 @@
 import { connection } from "./Connection.js";
 import { registry } from "./Registry.js";
-import { cleanupWebsocketUrl, createTCPServer, GeonixVersion, picoid, proxyHttp, sleep } from "./Util.js";
+import { cleanupWebsocketUrl, createTCPServer, GeonixVersion, hash, picoid, proxyHttp, sleep } from "./Util.js";
 import express, { Router } from "express";
 import { Request } from "./Request.js";
-import { HEALTH_CHECK_ENDPOINT } from "./WebServer.js";
 import expressWs from "express-ws";
-import querystring from "querystring";
 import semver from "semver";
 import { WebSocket } from "ws";
 import { logger } from "./Logger.js";
 
-const DEBUG_ENDPOINT = "/lZ6jD2eC3iP0zB3jJ1yJ9pM8gG3yI3vS";
 const endpointMatcher = /^((?<options>.+)\|)?(?<verb>WS|GET|POST|PATCH|PUT|DELETE|HEAD|OPTIONS|ALL)\s(?<url>.*)/;
 
+const MAX_SESSIONS = 16384;
+
+// Real client IP — checks well-known CDN/proxy headers before falling back to socket address
+function getClientIp(req) {
+    const header =
+        req.headers["cf-connecting-ip"] || // Cloudflare
+        req.headers["true-client-ip"] || // Cloudflare Enterprise / Akamai
+        req.headers["x-real-ip"] || // nginx
+        req.headers["x-forwarded-for"]; // standard (may be comma-separated list)
+
+    if (header) {
+        return header.split(",")[0].trim();
+    }
+    return req.socket?.remoteAddress || "unknown";
+}
+
+// Deterministic index into an array based on a string key
+function stableIndex(str, length) {
+    return parseInt(hash(str).slice(0, 8), 16) % length;
+}
+
 const requestLogger = (req, res, next) => {
-    logger.info(`HTTP ${req.method} ${req.url}`);
+    logger.debug(`HTTP ${req.method} ${req.path}`);
 
     next();
 };
@@ -23,16 +41,26 @@ const stats = {
     requests: 0,
     proxied: 0,
     proxied_over_nats: 0,
-    debug_requests: 0
+    debug_requests: 0,
 };
 
 const defaultOpts = {
-    beforeRequest: (_req, _res) => { },
-    afterRequest: (_req, _res) => { }
+    beforeRequest: (_req, _res) => {},
+    afterRequest: (_req, _res) => {},
 };
 
+/**
+ * HTTP gateway that automatically discovers Geonix services via the registry and reverse-proxies
+ * incoming HTTP and WebSocket requests to the appropriate service instance. Routes are rebuilt
+ * dynamically as services join and leave the bus.
+ */
 export class Gateway {
-
+    /**
+     * Creates and starts a new Gateway instance.
+     *
+     * @param {object} [opts] - Gateway options (e.g. `cors`, `beforeRequest`, `afterRequest`).
+     * @returns {Gateway}
+     */
     static start(opts) {
         return new Gateway(opts);
     }
@@ -46,16 +74,19 @@ export class Gateway {
 
     #rebuildRouter = false;
     #buildRouterRunning = false;
+    #rebuildRouterInterval = null;
     #endpoints = [];
 
     #registry = {};
+    #server;
+    #sessions = new Map(); // _gx token → backend address
 
     constructor(opts) {
         expressWs(this.#api);
 
         this.#opts = { ...this.#opts, ...opts };
 
-        this.#start();
+        this.#start().catch((e) => logger.error("gx.gateway.start:", e));
     }
 
     async #start(port = 8080) {
@@ -63,36 +94,59 @@ export class Gateway {
 
         await connection.waitUntilReady();
 
-        this.#port = process.env.PORT || port;
-        this.#api.listen(this.#port);
-
-        logger.debug(`geonix.gateway: listening on http://0.0.0.0:${this.#port}`);
+        this.#port = process.env.GX_PORT || process.env.PORT || port;
 
         // logging
         this.#api.use(requestLogger);
 
         // cors
         this.#api.use((req, res, next) => {
+            const cors = this.#opts.cors;
             const origin = req.headers["origin"];
             const allMethods = "GET,PUT,POST,DELETE,OPTIONS,HEAD";
-            const allHeaders = "*";
             const requestMethod = req.headers["access-control-request-method"];
             const requestHeaders = req.headers["access-control-request-headers"];
 
-            res.set("Access-Control-Allow-Credentials", "true");
-            res.set("Access-Control-Allow-Origin", origin || "*");
-            res.set("Access-Control-Allow-Methods", requestMethod || allMethods);
             res.set("Allow", requestMethod || allMethods);
-            res.set("Access-Control-Allow-Headers", requestHeaders || allHeaders);
+
+            if (!cors) {
+                // off — no CORS headers
+            } else if (cors === "*") {
+                // wildcard — all origins, no credentials
+                res.set("Access-Control-Allow-Origin", "*");
+                res.set("Access-Control-Allow-Methods", requestMethod || allMethods);
+                res.set("Access-Control-Allow-Headers", requestHeaders || "*");
+            } else if (Array.isArray(cors)) {
+                // allowlist — credentials only for listed origins
+                if (origin && cors.includes(origin)) {
+                    res.set("Access-Control-Allow-Credentials", "true");
+                    res.set("Access-Control-Allow-Origin", origin);
+                    res.set("Access-Control-Allow-Methods", requestMethod || allMethods);
+                    res.set("Access-Control-Allow-Headers", requestHeaders || "*");
+                }
+            } else if (cors === true) {
+                // open — reflect any origin with credentials
+                if (origin) {
+                    res.set("Access-Control-Allow-Credentials", "true");
+                    res.set("Access-Control-Allow-Origin", origin);
+                    res.set("Access-Control-Allow-Methods", requestMethod || allMethods);
+                    res.set("Access-Control-Allow-Headers", requestHeaders || "*");
+                }
+            }
 
             next();
         });
 
-        // debug router (only available in non-production environments)
-        if (process.env.NODE_ENV !== "production") {
-            this.#api.use(DEBUG_ENDPOINT, this.#debugRouter());
+        // debug router (only mounted when GX_DEBUG_ENDPOINT is set)
+        if (process.env.GX_DEBUG_ENDPOINT) {
+            this.#api.use(process.env.GX_DEBUG_ENDPOINT, this.#debugRouter());
         }
 
+        // block internal gx namespace from being proxied to external clients
+        this.#api.all("/!!_gx/*", (req, res) => {
+            res.status(403).json({ error: 403, source: "gw" });
+        });
+
         this.#api.use((req, res, next) => {
             if (this.#opts.beforeRequest) {
                 this.#opts.beforeRequest(req, res);
@@ -126,11 +180,14 @@ export class Gateway {
         this.#api.all("*", (req, res) => {
             res.status(404).send({
                 error: 404,
-                source: "gw"
+                source: "gw",
             });
         });
 
-        setInterval(() => {
+        this.#server = this.#api.listen(this.#port);
+        logger.info(`geonix.gateway: listening on http://0.0.0.0:${this.#port}`);
+
+        this.#rebuildRouterInterval = setInterval(() => {
             if (this.#rebuildRouter) {
                 this.#buildRouter();
             }
@@ -141,7 +198,7 @@ export class Gateway {
                 // send keeplive to check if connection is still alive
                 await connection.publish("gx.gateway.keepalive", Date.now());
 
-                await this.#handleAddedServics();
+                await this.#handleAddedServices();
                 await this.#handleRemovedServices();
                 await sleep(1000);
 
@@ -153,42 +210,31 @@ export class Gateway {
             }
         }
 
-        await this.#api.close();
+        this.#server?.close();
 
         // terminate process
-        logger.debug("geonix.gateway: stopped");
+        logger.info("geonix.gateway: stopped");
     }
 
-    async #handleAddedServics() {
+    async #handleAddedServices() {
         let entries = Object.values(registry.getEntries());
 
         const processEntry = async (entry) => {
-            if (this.#registry[entry.i] !== undefined) { return false; }
+            const existing = this.#registry[entry.i];
 
-            logger.info(`gateway.onServiceAdded: ${entry.n}@${entry.v} (#${entry.i})`);
-
-            // figure out if endpoints is reachable via direct http call
-            let backend;
-            if (entry.a) {
-                for (let address of entry.a) {
-                    try {
-                        const ac = new AbortController();
-                        const timeout = setTimeout(() => ac.abort(), 500);
-                        const result = await (await fetch(`http://${address}${HEALTH_CHECK_ENDPOINT}`, { signal: ac.signal })).json();
-                        clearTimeout(timeout);
-                        if (result.status === "healthy" && result.services?.includes(entry.n)) {
-                            backend = address;
-                            logger.info(`${entry.n}@${entry.v} (#${entry.i}) directly reachable @ ${address}`);
-                            break;
-                        }
-                    } catch {
-                        // silently ignore errors
-                    }
+            if (existing !== undefined) {
+                // 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;
+                    this.#rebuildRouter = true;
                 }
+                return false;
             }
 
+            logger.info(`gateway.onServiceAdded: ${entry.n}@${entry.v} (#${entry.i})`);
+
             let proxy;
-            if (!backend) {
+            if (!entry.a?.length) {
                 // create proxy over nats
                 proxy = await createTCPServer(async (client) => {
                     const streamId = picoid();
@@ -200,16 +246,15 @@ export class Gateway {
                         logger.error("nats.proxy.error", e);
                         client.destroy();
                     }
-                }, 50000, 10000);
-                backend = `127.0.0.1:${proxy.port}`;
+                });
             }
 
-            this.#registry[entry.i] = { entry, proxy, backend };
+            this.#registry[entry.i] = { entry, proxy, knownAddressCount: entry.a?.length ?? 0 };
 
             return true;
         };
 
-        entries = (await Promise.all(entries.map(processEntry))).filter(result => result === true);
+        entries = (await Promise.all(entries.map(processEntry))).filter((result) => result === true);
 
         if (entries.length > 0) {
             this.#rebuildRouter = true;
@@ -241,7 +286,7 @@ export class Gateway {
         });
 
         router.get("/services", (req, res) => {
-            const services = Object.values(registry.getEntries()).map(e => (`${e.n}@${e.v}`));
+            const services = Object.values(registry.getEntries()).map((e) => `${e.n}@${e.v}`);
             services.sort();
             res.send(services);
         });
@@ -268,12 +313,11 @@ export class Gateway {
                 node: {
                     version: process.version,
                     platform: process.platform,
-                    arch: process.arch
+                    arch: process.arch,
                 },
-                env: process.env,
                 mem: process.memoryUsage(),
                 rss: process.memoryUsage.rss(),
-                cpu: process.cpuUsage()
+                cpu: process.cpuUsage(),
             });
         });
 
@@ -293,42 +337,46 @@ export class Gateway {
                 connection.unsubscribe(ingress);
                 connection.publish(`gx2.stream.${streamId}.c`, Buffer.from("end"));
             });
-            client.on("error", (_error) => {
-                // silently ignore errors
+            client.on("error", (e) => {
+                logger.debug("nats.proxy.client.error:", e);
             });
 
             const dataLoop = async () => {
-                for await (const event of ingress) { client.write(event.data); }
+                for await (const event of ingress) {
+                    client.write(event.data);
+                }
             };
 
-            dataLoop();
+            dataLoop().catch((e) => logger.error("nats.proxy.dataLoop:", e));
         }
     }
 
     /**
      * Proxies websocket connection
-     * 
-     * @param {string} target 
-     * @param {Readable} inbound 
-     * @param {Request} req 
+     *
+     * @param {string} target
+     * @param {Readable} inbound
+     * @param {Request} req
      */
-    #proxyWebsocketOverNats(target, inbound, req) {
+    #proxyWebsocket(target, inbound, req) {
         try {
-            const backend = new WebSocket(target, {
-                headers: {
-                    ...req.headers
-                }
+            const backend = new WebSocket(target, { headers: { ...req.headers } });
+
+            backend.on("error", (e) => {
+                logger.error("proxy.ws.backend.error:", e);
+                inbound.close();
             });
 
             backend.on("open", () => {
                 backend.on("message", (data, isBinary) => inbound.send(isBinary ? data : data.toString()));
-                inbound.on("message", data => backend.send(data));
+                inbound.on("message", (data) => backend.send(data));
 
                 backend.on("close", () => inbound.close());
                 inbound.on("close", () => backend.close());
             });
         } catch (e) {
-            logger.error(e);
+            logger.error("proxy.ws.backend.error:", e);
+            inbound.close();
         }
     }
 
@@ -348,14 +396,27 @@ export class Gateway {
 
             const endpoints = [];
 
-            for (let { entry, backend } of entries) {
+            for (let { entry, proxy } of entries) {
+                const backendAddr = proxy
+                    ? `127.0.0.1:${proxy.port}`
+                    : entry.a?.[Math.floor(Math.random() * entry.a.length)];
+
+                if (!backendAddr) {
+                    continue;
+                }
+
                 // generate global endpoint list
                 for (let e of entry.m) {
-                    if (endpointMatcher.test(e)) {
-                        const endpoint = endpointMatcher.exec(e).groups;
+                    const endpointMatch = endpointMatcher.exec(e);
+                    if (endpointMatch) {
+                        const endpoint = endpointMatch.groups;
+                        const parsed = endpoint.options
+                            ? Object.fromEntries(new URLSearchParams(endpoint.options))
+                            : {};
+                        const parsedOrder = parseInt(parsed.order, 10);
                         let options = {
-                            order: 100,
-                            ...(endpoint.options ? querystring.parse(endpoint.options) : {})
+                            ...parsed,
+                            order: Number.isNaN(parsedOrder) ? 100 : parsedOrder,
                         };
 
                         try {
@@ -364,7 +425,7 @@ export class Gateway {
                                 version: semver.coerce(entry.v).version,
                                 options,
                                 endpoint,
-                                backend: [backend]
+                                backend: [backendAddr],
                             });
                         } catch (e) {
                             logger.error("gateway.buildRouter.error:", entry);
@@ -381,7 +442,10 @@ export class Gateway {
                 const url = `${endpoints[index].endpoint.verb} ${endpoints[index].endpoint.url}`;
 
                 for (let n = 0; n < index; n++) {
-                    if (`${endpoints[n].endpoint.verb} ${endpoints[n].endpoint.url}` === url && endpoints[n].version === version) {
+                    if (
+                        `${endpoints[n].endpoint.verb} ${endpoints[n].endpoint.url}` === url &&
+                        endpoints[n].version === version
+                    ) {
                         endpoints[n].backend = endpoints[n].backend.concat(endpoints[index].backend);
                         endpoints.splice(index, 1);
                         break;
@@ -391,28 +455,45 @@ export class Gateway {
 
             // sort endpoints by order, if there is one
             endpoints.sort((a, b) => semver.rcompare(a.version, b.version));
-            endpoints.sort((a, b) => parseInt(a.options.order) - parseInt(b.options.order));
+            endpoints.sort((a, b) => a.options.order - b.options.order);
 
             this.#endpoints = endpoints;
 
             // build the router
             for (let endpoint of endpoints) {
                 let { verb, url: uri } = endpoint.endpoint;
-                let backend = endpoint.backend[endpoint.requests++ % endpoint.backend.length];
-
                 verb = verb.toLowerCase();
 
                 if (verb === "ws") {
                     router.ws(uri, (ws, req) => {
-                        let target = cleanupWebsocketUrl(`ws://${backend}${req.originalUrl}`);
+                        const backends = endpoint.backend;
+                        const gxToken = req.query?._gx;
+                        let selectedBackend;
+
+                        if (gxToken) {
+                            const stored = this.#sessions.get(gxToken);
+                            if (stored && backends.includes(stored)) {
+                                selectedBackend = stored;
+                            } else {
+                                // backend gone or first time seeing this token
+                                selectedBackend = backends[stableIndex(getClientIp(req), backends.length)];
+                                if (this.#sessions.size >= MAX_SESSIONS) {
+                                    this.#sessions.delete(this.#sessions.keys().next().value);
+                                }
+                                this.#sessions.set(gxToken, selectedBackend);
+                            }
+                        } else {
+                            selectedBackend = backends[stableIndex(getClientIp(req), backends.length)];
+                        }
 
+                        const target = cleanupWebsocketUrl(`ws://${selectedBackend}${req.originalUrl}`);
                         logger.debug("proxy.web.ws.to:", target);
-                        this.#proxyWebsocketOverNats(target, ws, req);
+                        this.#proxyWebsocket(target, ws, req);
                     });
                 } else {
                     router[verb](uri, async (req, res, _next) => {
                         stats.proxied++;
-                        backend = endpoint.backend[endpoint.requests++ % endpoint.backend.length];
+                        const backend = endpoint.backend[endpoint.requests++ % endpoint.backend.length];
 
                         try {
                             logger.debug("proxy.web.to:", backend + req.originalUrl);
@@ -430,8 +511,12 @@ export class Gateway {
         }
     }
 
-    async stop() {
+    /**
+     * Stops the gateway loop and closes the HTTP server.
+     * @returns {void}
+     */
+    stop() {
         this.#isActive = false;
+        clearInterval(this.#rebuildRouterInterval);
     }
-
 }

package/src/Logger.js

@@ -1,34 +1,124 @@
+const LEVELS = { debug: 0, info: 1, warn: 2, error: 3, none: 4 };
+const TAGS = { debug: "DBG", info: "INF", warn: "WRN", error: "ERR" };
+
+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,
 };
 
-export class Logger {
+function serialize(val) {
+    if (val instanceof Error) {
+        return val.stack || val.message;
+    }
+    if (typeof val === "object" && val !== null) {
+        return JSON.stringify(val);
+    }
+    return String(val);
+}
 
+/**
+ * Lightweight structured logger with configurable level filtering and output format.
+ * Each log method prefixes the message with an ISO timestamp (unless disabled) and a
+ * severity tag (`INF`, `WRN`, `ERR`, `DBG`). The active level is controlled by the
+ * `GX_LOG_LEVEL` environment variable (`debug` | `info` | `warn` | `error`).
+ * The output format is controlled by `GX_LOG_FORMAT` (`text` | `json`, default `text`).
+ */
+export class Logger {
     #options = defaultLoggerOptions;
+    #level = LEVEL;
+    #format = FORMAT;
 
+    /**
+     * @param {object} [options] - Logger options.
+     * @param {boolean} [options.timestamp=true] - Whether to prepend an ISO timestamp to each line (text format only).
+     * @param {'debug'|'info'|'warn'|'error'|'none'} [options.level] - Minimum level to emit. Use `none` to suppress all output. Overrides `GX_LOG_LEVEL`.
+     * @param {'text'|'json'} [options.format] - Output format. Overrides `GX_LOG_FORMAT`.
+     */
     constructor(options) {
         this.#options = { ...this.#options, ...options };
+        if (options?.level !== undefined) {
+            this.#level = LEVELS[options.level] ?? LEVEL;
+        }
+        if (options?.format !== undefined) {
+            this.#format = options.format === "json" ? "json" : "text";
+        }
     }
 
-    #log(...args) {
-        const ts = this.#options.timestamp ? new Date().toISOString() : undefined;
-
-        // eslint-disable-next-line no-console
-        console.log(...[ts, ...args].filter($ => $));
+    #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",
+            );
+        } else {
+            const ts = this.#options.timestamp ? new Date().toISOString() : undefined;
+            stream.write(
+                [ts, TAGS[level], ...args]
+                    .filter(($) => $ !== undefined)
+                    .map(serialize)
+                    .join(" ") + "\n",
+            );
+        }
     }
 
+    /**
+     * Emits an informational log line.
+     * @param {...any} args - Values to log.
+     * @returns {void}
+     */
     info(...args) {
-        this.#log("INF", ...args);
+        if (LEVELS.info >= this.#level) {
+            this.#log("info", ...args);
+        }
+    }
+
+    /**
+     * Emits a warning log line.
+     * @param {...any} args - Values to log.
+     * @returns {void}
+     */
+    warn(...args) {
+        if (LEVELS.warn >= this.#level) {
+            this.#log("warn", ...args);
+        }
     }
 
+    /**
+     * Emits an error log line.
+     * @param {...any} args - Values to log.
+     * @returns {void}
+     */
     error(...args) {
-        this.#log("ERR", ...args);
+        if (LEVELS.error >= this.#level) {
+            this.#log("error", ...args);
+        }
     }
 
+    /**
+     * Emits a debug log line. Only shown when the active level is `debug`.
+     * @param {...any} args - Values to log.
+     * @returns {void}
+     */
     debug(...args) {
-        this.#log("DBG", ...args);
+        if (LEVELS.debug >= this.#level) {
+            this.#log("debug", ...args);
+        }
     }
 
+    setLevel(level) {
+        this.#level = LEVELS[level] ?? LEVEL;
+    }
+
+    setFormat(format) {
+        this.#format = format === "json" ? "json" : "text";
+    }
 }
 
-export const logger = new Logger();
+/**
+ * Default {@link Logger} instance used throughout the Geonix internals.
+ *
+ * @type {Logger}
+ */
+export const logger = new Logger();