geonix 1.23.8 → 1.30.4

package/src/Connection.js

@@ -4,93 +4,166 @@ import { Stream } from "./Stream.js";
 import { webserver } from "./WebServer.js";
 import { logger } from "./Logger.js";
 import { decode, encode } from "./Codec.js";
+import { encryptPayload, decryptPayload, encryptSubject, wrapSubscription } from "./Crypto.js";
 
 // -------------------------------------------------------------------------------------------------
 const CONNECTION_TIMEOUT = 10000;
 
 const defaultRequestOptions = {
-    timeout: 300000
+    timeout: 300000,
 };
 
+const DEFAULT_CONNECTION_COUNT = 1;
+
 const defaultConnectionOptions = {
     timeout: CONNECTION_TIMEOUT,
     reconnect: true,
-    debug: process.env.TRANSPORT_DEBUG === "true",
+    debug: (process.env.GX_TRANSPORT_DEBUG || process.env.TRANSPORT_DEBUG) === "true",
     maxReconnectAttempts: 30,
     pingInterval: 30000,
     waitOnFirstConnect: true,
-    connections: 1
+};
+
+const TRANSPORT_TIMEOUT = 60_000;
+const WATCHDOG_INTERVAL = 1000;
+
+// env read via a function so tests can set GX_TRANSPORT_TIMEOUT after this module is imported
+const getTransportTimeout = () => {
+    const raw = parseInt(process.env.GX_TRANSPORT_TIMEOUT, 10);
+    return Number.isFinite(raw) ? raw : TRANSPORT_TIMEOUT;
 };
 // -------------------------------------------------------------------------------------------------
 
 /**
- * Connection class is responsible for starting a connection to a NATS server and provides shortcut
- * methods for publish, subscribe and request methods of the NATS client.
- * 
- * It is implemented as an singleton so that multiple services can be implemented in the same
- * process while using just a single connection to the NATS server.
+ * Manages one or more NATS connections and exposes publish, subscribe, and request helpers.
+ * Instantiated as a singleton (`connection`) so multiple services in the same process share a
+ * single pool of connections. Optional subject-level HMAC encryption and payload AES-GCM
+ * encryption are activated by setting the `GX_SECRET` environment variable.
  */
 class Connection {
-
     #draining = false;
     #closed = false;
     #ready = false;
     #connections = [];
     #connectionRoundRobin = 0;
+    #disconnectedSince = Date.now();
+    #watchdogInterval = null;
 
     #getConnection() {
-        this.#connectionRoundRobin = ++this.#connectionRoundRobin % this.#connections.length;
-        return this.#connections[this.#connectionRoundRobin];
+        return this.#connections[this.#connectionRoundRobin++ % this.#connections.length];
     }
 
     /**
-     * Initiates connection to transport
-     * @param {string} transport 
+     * Connects to the NATS transport. Called automatically on module load via the singleton.
+     *
+     * @param {string} [transport] - NATS URL, optionally including credentials and query-string
+     *   options (e.g. `nats://user:pass@host:4222?connections=2`). Defaults to `GX_TRANSPORT`,
+     *   `TRANSPORT`, or `nats://localhost`.
+     * @returns {Promise<void>}
      */
-    async start(transport = process.env.TRANSPORT || "nats://localhost") {
-        const options = {
+    async start(transport = process.env.GX_TRANSPORT || process.env.TRANSPORT || "nats://localhost") {
+        const { connections: _connectionCount, ...natsOptions } = {
             ...defaultConnectionOptions,
-            ...parseURL(transport)
+            ...parseURL(transport),
         };
+        const connectionCount = parseInt(_connectionCount) || DEFAULT_CONNECTION_COUNT;
+
+        this.#startWatchdog();
 
-        for (let i = 0; i < options.connections; i++) {
-            this.#connections.push(await connect(options));
+        for (let i = 0; i < connectionCount; i++) {
+            this.#connections.push(await connect(natsOptions));
         }
 
+        this.#disconnectedSince = null;
+
         logger.info("gx.connection.connected");
 
         this.#ready = true;
 
         this.monitorStatus();
-        this.waitUntilClosed();
+        this.waitUntilClosed().catch((e) => logger.error("gx.connection.waitUntilClosed:", e));
     }
 
-    async monitorStatus() {
-        for await (const event of this.#getConnection().status()) {
-            logger.info("gx.connection.status", JSON.stringify(event));
+    // Polls the disconnect timestamp; exits the process if the transport has been
+    // unreachable longer than GX_TRANSPORT_TIMEOUT (default 60s, 0 disables).
+    #startWatchdog() {
+        if (this.#watchdogInterval) {
+            return;
+        }
+
+        this.#watchdogInterval = setInterval(() => {
+            const limit = getTransportTimeout();
+            if (limit === 0) {
+                return;
+            }
+            if (this.#disconnectedSince === null) {
+                return;
+            }
+
+            const elapsed = Date.now() - this.#disconnectedSince;
+            if (elapsed >= limit) {
+                logger.error(
+                    `gx.connection: transport unreachable for ${Math.round(elapsed / 1000)}s (limit ${limit}ms), exiting`,
+                );
+                process.exit(1);
+            }
+        }, WATCHDOG_INTERVAL);
+
+        this.#watchdogInterval.unref?.();
+    }
+
+    /**
+     * Starts background logging of NATS status events for all connections.
+     * @returns {void}
+     */
+    monitorStatus() {
+        for (const conn of this.#connections) {
+            (async () => {
+                for await (const event of conn.status()) {
+                    if (event.type === "disconnect") {
+                        if (this.#disconnectedSince === null) {
+                            this.#disconnectedSince = Date.now();
+                        }
+                    } else if (event.type === "reconnect") {
+                        this.#disconnectedSince = null;
+                    }
+
+                    logger.debug("gx.connection.status", JSON.stringify(event));
+                }
+            })().catch((e) => logger.error("gx.connection.status:", e));
         }
     }
 
     /**
-     * Wait for the connection to be safely closed
+     * Resolves once all NATS connections have been fully closed, then stops the web server and
+     * exits the process (exit code 0 on graceful drain, 1 on unexpected closure).
+     *
+     * @returns {Promise<void>}
      */
     async waitUntilClosed() {
         // wait for all connections to be closed
-        await Promise.all(this.#connections.map(connection => connection.closed()));
+        await Promise.all(this.#connections.map((connection) => connection.closed()));
 
         this.#closed = true;
         logger.info("gx.connection.closed");
 
+        if (this.#watchdogInterval) {
+            clearInterval(this.#watchdogInterval);
+            this.#watchdogInterval = null;
+        }
+
         webserver.stop();
 
         await sleep(5000);
 
         logger.info("gx.terminate");
-        process.exit(1);
+        process.exit(this.#draining ? 0 : 1);
     }
 
     /**
-     * Wait for the connection to be fully established
+     * Resolves once the NATS connection pool is ready to publish and subscribe.
+     *
+     * @returns {Promise<void>}
      */
     async waitUntilReady() {
         while (!this.#ready) {
@@ -100,9 +173,9 @@ class Connection {
 
     /**
      * Publish JSON
-     * 
-     * @param {string} subject 
-     * @param {object} json 
+     *
+     * @param {string} subject
+     * @param {object} json
      * @returns void
      */
     async publish(subject, json) {
@@ -114,17 +187,17 @@ class Connection {
 
         // if payload is too big, convert it to Stream
         if (payload.length > this.getMaxPayloadSize()) {
-            payload = encode(Stream(JSON.stringify(json)));
+            payload = encode(Stream(Buffer.from(payload)));
         }
 
-        await this.#getConnection().publish(subject, payload);
+        await this.#getConnection().publish(encryptSubject(subject), encryptPayload(payload));
     }
 
     /**
      * Publish RAW
-     * 
-     * @param {string} subject 
-     * @param {string | Buffer} data 
+     *
+     * @param {string} subject
+     * @param {string | Buffer} data
      * @returns void
      */
     async publishRaw(subject, data) {
@@ -132,21 +205,24 @@ class Connection {
             return;
         }
 
-        await this.#getConnection().publish(subject, data);
+        await this.#getConnection().publish(
+            encryptSubject(subject),
+            encryptPayload(data != null ? Buffer.from(data) : Buffer.alloc(0)),
+        );
     }
 
     /**
      * Request/Reply pattern on top of pub/sub
-     * 
-     * @param {string} subject 
-     * @param {object} json 
-     * @param {object} options 
+     *
+     * @param {string} subject
+     * @param {object} json
+     * @param {object} options
      * @returns any
      */
     async request(subject, json, opts = {}) {
         const options = {
             ...defaultRequestOptions,
-            ...opts
+            ...opts,
         };
 
         const respondTo = `gx2.r.${picoid(16)}`;
@@ -159,24 +235,40 @@ class Connection {
         }
 
         const nc = this.#getConnection();
-        let response = await nc.subscribe(respondTo, { max: 1, ...options });
+        const response = await nc.subscribe(encryptSubject(respondTo), { max: 1, ...options });
 
-        await nc.publish(subject, payload);
+        await nc.publish(encryptSubject(subject), encryptPayload(payload));
 
         const event = await getFirstItemFromAsyncIterable(response);
-        return decode(event.data);
+        return decode(decryptPayload(event.data));
     }
 
+    /**
+     * Subscribes to a NATS subject and returns an async-iterable subscription. If payload
+     * encryption is enabled each message is transparently decrypted before being yielded.
+     *
+     * @param {string} subject - NATS subject to subscribe to.
+     * @param {object} [options] - NATS subscription options (e.g. `queue`, `max`).
+     * @returns {Promise<AsyncIterable>} Subscription iterable.
+     */
     async subscribe(subject, options) {
-        return this.#getConnection().subscribe(subject, options);
+        return wrapSubscription(await this.#getConnection().subscribe(encryptSubject(subject), options));
     }
 
-    async unsubscribe(subscription) {
+    /**
+     * Cancels an active subscription.
+     *
+     * @param {AsyncIterable} subscription - Subscription returned by {@link subscribe}.
+     * @returns {void}
+     */
+    unsubscribe(subscription) {
         subscription.unsubscribe();
     }
 
     /**
-     * 
+     * Returns the maximum NATS message payload size in bytes as reported by the server.
+     * Falls back to 512 KB if the connection info is not yet available.
+     *
      * @returns {number}
      */
     getMaxPayloadSize() {
@@ -184,25 +276,44 @@ class Connection {
         return nc?.info?.max_payload || 1024 * 512;
     }
 
+    /**
+     * Returns `true` after all NATS connections have been fully closed.
+     *
+     * @returns {boolean}
+     */
     isClosed() {
         return this.#closed;
     }
 
+    /**
+     * Drains all active NATS connections, flushing pending messages before closing them.
+     *
+     * @returns {Promise<void>}
+     */
     async drain() {
         this.#draining = true;
 
-        await Promise.all(this.#connections.map(connection => connection.drain()));
+        await Promise.all(this.#connections.map((connection) => connection.drain()));
     }
-
 }
 
+/**
+ * Singleton {@link Connection} instance shared across the process. Started automatically on
+ * module load; callers should use `connection.waitUntilReady()` before publishing or subscribing.
+ *
+ * @type {Connection}
+ */
 export const connection = new Connection();
-connection.start();
+connection.start().catch((e) => {
+    logger.error("gx.connection.start:", e);
+    process.exit(1);
+});
 
+/**
+ * Initiates a graceful shutdown by draining all NATS connections.
+ *
+ * @returns {void}
+ */
 export const stopConnection = () => {
-    if (!connection) {
-        return;
-    }
-
     connection.drain();
 };

package/src/Crypto.js

@@ -0,0 +1,117 @@
+import { createCipheriv, createDecipheriv, createHash, createHmac, randomBytes } from "crypto";
+
+const _secret = process.env.GX_SECRET || null;
+
+// Subject key is derived separately so HMAC-subject and AES-payload never share key material.
+const _subjectKey = _secret
+    ? createHash("sha256")
+          .update(_secret + "\x00subject")
+          .digest()
+    : null;
+
+/**
+ * AES-256-GCM key derived from `GX_SECRET`, or `null` when encryption is disabled.
+ * Used internally by {@link encryptPayload} and {@link decryptPayload}.
+ *
+ * @type {Buffer|null}
+ */
+export const _payloadKey = _secret
+    ? createHash("sha256")
+          .update(_secret + "\x00payload")
+          .digest()
+    : null;
+
+/**
+ * Encrypts `data` with AES-256-GCM using {@link _payloadKey}. Returns `data` unchanged when
+ * encryption is disabled. The output format is `[12-byte IV][16-byte auth tag][ciphertext]`.
+ *
+ * @param {Buffer|null} data - Plaintext bytes to encrypt.
+ * @returns {Buffer}
+ */
+export function encryptPayload(data) {
+    if (!_payloadKey) {
+        return data;
+    }
+    const buf = data != null ? Buffer.from(data) : Buffer.alloc(0);
+    const iv = randomBytes(12);
+    const cipher = createCipheriv("aes-256-gcm", _payloadKey, iv);
+    const encrypted = cipher.update(buf);
+    cipher.final();
+    const out = Buffer.allocUnsafe(12 + 16 + encrypted.length);
+    iv.copy(out, 0);
+    cipher.getAuthTag().copy(out, 12);
+    encrypted.copy(out, 28);
+    return out;
+}
+
+/**
+ * Decrypts a buffer produced by {@link encryptPayload}. Returns `data` unchanged when
+ * encryption is disabled. Expects the layout `[12-byte IV][16-byte auth tag][ciphertext]`.
+ *
+ * @param {Buffer} data - Encrypted bytes to decrypt.
+ * @returns {Buffer}
+ */
+export function decryptPayload(data) {
+    if (!_payloadKey) {
+        return data;
+    }
+    const buf = Buffer.from(data);
+    const decipher = createDecipheriv("aes-256-gcm", _payloadKey, buf.subarray(0, 12));
+    decipher.setAuthTag(buf.subarray(12, 28));
+    const decrypted = decipher.update(buf.subarray(28));
+    decipher.final();
+    return decrypted;
+}
+
+/**
+ * Encrypts each dot-separated segment of a NATS subject using HMAC-SHA256, truncated to 32 hex
+ * characters. Wildcard tokens (`*`, `>`) are passed through unchanged so NATS subscription
+ * semantics are preserved. Returns the subject unchanged when encryption is disabled.
+ *
+ * @param {string} subject - Plain NATS subject string (e.g. `"gx2.service.abc"`).
+ * @returns {string} Encrypted subject string.
+ */
+export function encryptSubject(subject) {
+    if (!_subjectKey) {
+        return subject;
+    }
+
+    return subject
+        .split(".")
+        .map((seg) =>
+            seg === "*" || seg === ">" ? seg : createHmac("sha256", _subjectKey).update(seg).digest("hex").slice(0, 32),
+        )
+        .join(".");
+}
+
+/**
+ * Wraps a NATS subscription so that every incoming message's `data` field is transparently
+ * decrypted before being yielded. Returns the subscription unchanged when encryption is
+ * disabled.
+ *
+ * @param {object} sub - NATS subscription object with `[Symbol.asyncIterator]`, `drain`, and `unsubscribe`.
+ * @returns {object} Wrapped subscription with the same interface.
+ */
+export function wrapSubscription(sub) {
+    if (!_payloadKey) {
+        return sub;
+    }
+
+    return {
+        [Symbol.asyncIterator]() {
+            const iter = sub[Symbol.asyncIterator]();
+            return {
+                async next() {
+                    const { value, done } = await iter.next();
+                    if (done) {
+                        return { value, done };
+                    }
+
+                    return { value: { ...value, data: decryptPayload(value.data) }, done: false };
+                },
+            };
+        },
+        drain: () => sub.drain(),
+        unsubscribe: () => sub.unsubscribe(),
+    };
+}