jsgar 4.5.2 → 4.6.0

package/dist/gar.umd.js

@@ -1,8 +1,8 @@
 (function (global, factory) {
-    typeof exports === 'object' && typeof module !== 'undefined' ? module.exports = factory() :
-    typeof define === 'function' && define.amd ? define(factory) :
-    (global = typeof globalThis !== 'undefined' ? globalThis : global || self, global.GARClient = factory());
-})(this, (function () { 'use strict';
+    typeof exports === 'object' && typeof module !== 'undefined' ? factory(exports) :
+    typeof define === 'function' && define.amd ? define(['exports'], factory) :
+    (global = typeof globalThis !== 'undefined' ? globalThis : global || self, factory(global.GARClient = {}));
+})(this, (function (exports) { 'use strict';
 
     /**
      * A client implementation for the Generic Active Records (GAR) protocol using WebSockets.
@@ -30,6 +30,155 @@
     // - In Node.js, dynamically imports 'ws' and assigns globalThis.WebSocket
     // All client code references the constructor via helper methods, not a top-level binding.
 
+    // AF_UNIX local-transport optimization (mirrors ipc/gar.cpp). When the endpoint
+    // resolves to an IP bound to a local interface, the GAR server is also listening
+    // on an abstract-namespace AF_UNIX socket at "\0gar.endpoint.<port>". Routing the
+    // WebSocket through that path bypasses the kernel TCP loopback stack — avoiding
+    // EDR/Falcon-style instrumentation overhead — while preserving the wire protocol.
+    //
+    // Browser environments have no raw socket access, so this is Node.js-only. The
+    // 'ws' library lets us inject a pre-connected net.Socket (or TLS-wrapped) via
+    // the createConnection option in the constructor.
+    //
+    // Set TRS_DISABLE_AF_UNIX=1 (also accepts true/on/yes, case-insensitive) to opt
+    // out and force the regular TCP path. Useful when capturing GAR traffic with
+    // tcpdump/wireshark on the loopback interface, which only sees TCP.
+
+    function _garAfUnixDisabled() {
+        const v = (typeof process !== 'undefined' && process.env)
+            ? process.env.TRS_DISABLE_AF_UNIX : undefined;
+        if (!v) return false;
+        return ['1', 'true', 'on', 'yes'].includes(v.toLowerCase());
+    }
+
+    let _garNetMod = null;
+    let _garTlsMod = null;
+    let _garOsMod = null;
+    let _garDnsMod = null;
+
+    async function _garLoadNodeModules() {
+        if (_garNetMod) return true;
+        const isNode = typeof process !== 'undefined' && process.versions && process.versions.node;
+        if (!isNode) return false;
+        try {
+            const { createRequire } = await import('node:module');
+            const req = createRequire(process.cwd() + '/');
+            _garNetMod = req('net');
+            _garTlsMod = req('tls');
+            _garOsMod = req('os');
+            _garDnsMod = req('dns');
+            return true;
+        } catch {
+            return false;
+        }
+    }
+
+    function _garLocalIPv4Set() {
+        const set = new Set(['127.0.0.1']);
+        const ifaces = _garOsMod.networkInterfaces();
+        for (const name of Object.keys(ifaces)) {
+            for (const addr of ifaces[name] || []) {
+                if (addr.family === 'IPv4' || addr.family === 4) set.add(addr.address);
+            }
+        }
+        return set;
+    }
+
+    // Returns the optimal GAR endpoint string for |inetEndpoint|: if the URL's
+    // host resolves locally on this machine, returns the AF_UNIX form
+    // "unix:gar.endpoint.<port>"; otherwise echoes the input. Mirrors
+    // `trsutil --optimal-endpoint`. Async because DNS lookup in Node is async-only.
+    // Respects TRS_DISABLE_AF_UNIX. Does not probe the AF_UNIX listener — caller
+    // (or jsgar's connect path) handles fallback if it's unreachable.
+    async function optimalEndpoint(inetEndpoint) {
+        if (_garAfUnixDisabled()) return inetEndpoint;
+        if (!(await _garLoadNodeModules())) return inetEndpoint;
+        let parsed;
+        try { parsed = new URL(inetEndpoint); } catch { return inetEndpoint; }
+        const host = parsed.hostname;
+        const port = parsed.port;
+        if (!host || !port) return inetEndpoint;
+        let ip;
+        try {
+            if (_garNetMod.isIP(host)) {
+                ip = host;
+            } else {
+                const r = await _garDnsMod.promises.lookup(host, { family: 4 });
+                ip = r.address;
+            }
+        } catch { return inetEndpoint; }
+        if (ip.startsWith('127.') || _garLocalIPv4Set().has(ip)) {
+            return `unix:gar.endpoint.${port}`;
+        }
+        return inetEndpoint;
+    }
+
+    // Returns the abstract-namespace AF_UNIX path (a string starting with \u0000)
+    // for the given GAR WebSocket endpoint if (a) it resolves to a local IPv4 and
+    // (b) the abstract listener at the matching name is reachable. Otherwise null.
+    async function _garUnixAbstractPathForEndpoint(wsEndpoint) {
+        if (_garAfUnixDisabled()) return null;
+        if (!(await _garLoadNodeModules())) return null;
+        let parsed;
+        try {
+            parsed = new URL(wsEndpoint);
+        } catch {
+            return null;
+        }
+        const host = parsed.hostname;
+        const port = parsed.port;
+        if (!host || !port) return null;
+
+        let ip;
+        try {
+            if (_garNetMod.isIP(host)) {
+                ip = host;
+            } else {
+                const r = await _garDnsMod.promises.lookup(host, { family: 4 });
+                ip = r.address;
+            }
+        } catch {
+            return null;
+        }
+
+        // Loopback short-circuit; otherwise check against the host's interface IPs.
+        // (Less precise than RTM_GETROUTE used by the C++ side, but covers the
+        // practical "is this destination on this machine?" question for our use.)
+        if (!ip.startsWith('127.')) {
+            if (!_garLocalIPv4Set().has(ip)) return null;
+        }
+
+        const abstractPath = '\u0000gar.endpoint.' + port;
+        // Reachability probe: AF_UNIX local connect either succeeds immediately or
+        // fails immediately with ECONNREFUSED/ENOENT.
+        const reachable = await new Promise((resolve) => {
+            let done = false;
+            const finish = (ok) => {
+                if (done) return;
+                done = true;
+                try { sock.destroy(); } catch { /* ignore */ }
+                resolve(ok);
+            };
+            const sock = _garNetMod.createConnection({ path: abstractPath });
+            sock.once('connect', () => finish(true));
+            sock.once('error', () => finish(false));
+            setTimeout(() => finish(false), 500);
+        });
+        return reachable ? abstractPath : null;
+    }
+
+    function _garMakeUnixCreateConnectionFn(abstractPath, useSSL, sniHost, allowSelfSigned) {
+        return () => {
+            const unixSocket = _garNetMod.createConnection({ path: abstractPath });
+            if (!useSSL) return unixSocket;
+            return _garTlsMod.connect({
+                socket: unixSocket,
+                servername: sniHost,
+                rejectUnauthorized: !allowSelfSigned,
+            });
+        };
+    }
+
     class GARClient {
         /**
          * Initialize the GAR client.
@@ -74,7 +223,7 @@
             this.localKeyMap = new Map();
             this.invalidatedKeyIds = new Set();
             this.recordMap = new Map();
-            this._activeOwnership = { msg_ref: 0, ownership_action: 'None', skip_ownership_checks: false, client_key_id: 0 };
+            this._activeOwnership = { msg_ref: 0, ownership_action: 'None', skip_ownership_checks: false, require_existing: false, client_key_id: 0 };
 
             this.running = false;
             this.heartbeatIntervalId = null;
@@ -142,7 +291,7 @@
             this.invalidatedKeyIds.clear();
 
             // Active ownership state
-            this._activeOwnership = { msg_ref: 0, ownership_action: 'None', skip_ownership_checks: false, client_key_id: 0 };
+            this._activeOwnership = { msg_ref: 0, ownership_action: 'None', skip_ownership_checks: false, require_existing: false, client_key_id: 0 };
 
             // Heartbeat grace period flags
             this._initialGracePeriod = false;
@@ -169,13 +318,35 @@
                     const WS = await this._ensureWebSocketCtor();
                     const isNode = typeof process !== 'undefined' && process.versions && process.versions.node;
 
-                    this.log('INFO', `Connecting to WebSocket server at ${this.wsEndpoint}`);
+                    // Prefer AF_UNIX abstract-namespace transport for local destinations.
+                    // Falls back to TCP automatically (next reconnect iteration) if the
+                    // listener disappears between probe and real connect.
+                    let unixAbstractPath = null;
+                    let sniHost = null;
+                    if (isNode) {
+                        unixAbstractPath = await _garUnixAbstractPathForEndpoint(this.wsEndpoint);
+                        if (unixAbstractPath) {
+                            try { sniHost = new URL(this.wsEndpoint).hostname; } catch { /* ignore */ }
+                        }
+                    }
+
+                    this.log('INFO', `Connecting to WebSocket server at ${this.wsEndpoint}${unixAbstractPath ? ' (via AF_UNIX)' : ''}`);
 
                     const connectionPromise = new Promise((resolve, reject) => {
                         let websocket;
-                        if (this.allowSelfSignedCertificate && isNode) {
+                        const useSSL = this.wsEndpoint.toLowerCase().startsWith('wss://');
+                        const wsOpts = {};
+                        if (this.allowSelfSignedCertificate && isNode && useSSL) {
                             // Node.js 'ws' supports options for TLS; browsers do not.
-                            websocket = new WS(this.wsEndpoint, ['gar-protocol'], { rejectUnauthorized: false });
+                            wsOpts.rejectUnauthorized = false;
+                        }
+                        if (unixAbstractPath) {
+                            wsOpts.createConnection = _garMakeUnixCreateConnectionFn(
+                                unixAbstractPath, useSSL, sniHost, this.allowSelfSignedCertificate
+                            );
+                        }
+                        if (Object.keys(wsOpts).length > 0) {
+                            websocket = new WS(this.wsEndpoint, ['gar-protocol'], wsOpts);
                         } else {
                             websocket = new WS(this.wsEndpoint, ['gar-protocol']);
                         }
@@ -1145,12 +1316,13 @@
          * @param {number} [options.msgRef=0] - Message reference for correlating recoverable error responses.
          * @param {string} [options.ownershipAction='None'] - 'None' (check only), 'Acquire', or 'Release'.
          * @param {boolean} [options.skipOwnershipChecks=false] - Bypass ownership validation.
+         * @param {boolean} [options.requireExisting=false] - Only write to existing keys; do not create new keys.
          * @param {number} [options.clientKeyId=0] - The g::Client key ID for ownership. 0 uses the connection key.
          */
-        updateActiveOwnership({ msgRef = 0, ownershipAction = 'None', skipOwnershipChecks = false, clientKeyId = 0 } = {}) {
-            const newOwnership = { msg_ref: msgRef, ownership_action: ownershipAction, skip_ownership_checks: skipOwnershipChecks, client_key_id: clientKeyId };
+        updateActiveOwnership({ msgRef = 0, ownershipAction = 'None', skipOwnershipChecks = false, requireExisting = false, clientKeyId = 0 } = {}) {
+            const newOwnership = { msg_ref: msgRef, ownership_action: ownershipAction, skip_ownership_checks: skipOwnershipChecks, require_existing: requireExisting, client_key_id: clientKeyId };
             const cur = this._activeOwnership;
-            if (newOwnership.msg_ref !== cur.msg_ref || newOwnership.ownership_action !== cur.ownership_action || newOwnership.skip_ownership_checks !== cur.skip_ownership_checks || newOwnership.client_key_id !== cur.client_key_id) {
+            if (newOwnership.msg_ref !== cur.msg_ref || newOwnership.ownership_action !== cur.ownership_action || newOwnership.skip_ownership_checks !== cur.skip_ownership_checks || newOwnership.require_existing !== cur.require_existing || newOwnership.client_key_id !== cur.client_key_id) {
                 this._activeOwnership = newOwnership;
                 this.sendMessage({ message_type: 'ActiveOwnership', value: newOwnership });
             }
@@ -1516,6 +1688,9 @@
         }
     }
 
-    return GARClient;
+    exports.default = GARClient;
+    exports.optimalEndpoint = optimalEndpoint;
+
+    Object.defineProperty(exports, '__esModule', { value: true });
 
 }));

package/gar.js

@@ -24,6 +24,155 @@
 // - In Node.js, dynamically imports 'ws' and assigns globalThis.WebSocket
 // All client code references the constructor via helper methods, not a top-level binding.
 
+// AF_UNIX local-transport optimization (mirrors ipc/gar.cpp). When the endpoint
+// resolves to an IP bound to a local interface, the GAR server is also listening
+// on an abstract-namespace AF_UNIX socket at "\0gar.endpoint.<port>". Routing the
+// WebSocket through that path bypasses the kernel TCP loopback stack — avoiding
+// EDR/Falcon-style instrumentation overhead — while preserving the wire protocol.
+//
+// Browser environments have no raw socket access, so this is Node.js-only. The
+// 'ws' library lets us inject a pre-connected net.Socket (or TLS-wrapped) via
+// the createConnection option in the constructor.
+//
+// Set TRS_DISABLE_AF_UNIX=1 (also accepts true/on/yes, case-insensitive) to opt
+// out and force the regular TCP path. Useful when capturing GAR traffic with
+// tcpdump/wireshark on the loopback interface, which only sees TCP.
+
+function _garAfUnixDisabled() {
+    const v = (typeof process !== 'undefined' && process.env)
+        ? process.env.TRS_DISABLE_AF_UNIX : undefined;
+    if (!v) return false;
+    return ['1', 'true', 'on', 'yes'].includes(v.toLowerCase());
+}
+
+let _garNetMod = null;
+let _garTlsMod = null;
+let _garOsMod = null;
+let _garDnsMod = null;
+
+async function _garLoadNodeModules() {
+    if (_garNetMod) return true;
+    const isNode = typeof process !== 'undefined' && process.versions && process.versions.node;
+    if (!isNode) return false;
+    try {
+        const { createRequire } = await import('node:module');
+        const req = createRequire(process.cwd() + '/');
+        _garNetMod = req('net');
+        _garTlsMod = req('tls');
+        _garOsMod = req('os');
+        _garDnsMod = req('dns');
+        return true;
+    } catch {
+        return false;
+    }
+}
+
+function _garLocalIPv4Set() {
+    const set = new Set(['127.0.0.1']);
+    const ifaces = _garOsMod.networkInterfaces();
+    for (const name of Object.keys(ifaces)) {
+        for (const addr of ifaces[name] || []) {
+            if (addr.family === 'IPv4' || addr.family === 4) set.add(addr.address);
+        }
+    }
+    return set;
+}
+
+// Returns the optimal GAR endpoint string for |inetEndpoint|: if the URL's
+// host resolves locally on this machine, returns the AF_UNIX form
+// "unix:gar.endpoint.<port>"; otherwise echoes the input. Mirrors
+// `trsutil --optimal-endpoint`. Async because DNS lookup in Node is async-only.
+// Respects TRS_DISABLE_AF_UNIX. Does not probe the AF_UNIX listener — caller
+// (or jsgar's connect path) handles fallback if it's unreachable.
+async function optimalEndpoint(inetEndpoint) {
+    if (_garAfUnixDisabled()) return inetEndpoint;
+    if (!(await _garLoadNodeModules())) return inetEndpoint;
+    let parsed;
+    try { parsed = new URL(inetEndpoint); } catch { return inetEndpoint; }
+    const host = parsed.hostname;
+    const port = parsed.port;
+    if (!host || !port) return inetEndpoint;
+    let ip;
+    try {
+        if (_garNetMod.isIP(host)) {
+            ip = host;
+        } else {
+            const r = await _garDnsMod.promises.lookup(host, { family: 4 });
+            ip = r.address;
+        }
+    } catch { return inetEndpoint; }
+    if (ip.startsWith('127.') || _garLocalIPv4Set().has(ip)) {
+        return `unix:gar.endpoint.${port}`;
+    }
+    return inetEndpoint;
+}
+
+// Returns the abstract-namespace AF_UNIX path (a string starting with \u0000)
+// for the given GAR WebSocket endpoint if (a) it resolves to a local IPv4 and
+// (b) the abstract listener at the matching name is reachable. Otherwise null.
+async function _garUnixAbstractPathForEndpoint(wsEndpoint) {
+    if (_garAfUnixDisabled()) return null;
+    if (!(await _garLoadNodeModules())) return null;
+    let parsed;
+    try {
+        parsed = new URL(wsEndpoint);
+    } catch {
+        return null;
+    }
+    const host = parsed.hostname;
+    const port = parsed.port;
+    if (!host || !port) return null;
+
+    let ip;
+    try {
+        if (_garNetMod.isIP(host)) {
+            ip = host;
+        } else {
+            const r = await _garDnsMod.promises.lookup(host, { family: 4 });
+            ip = r.address;
+        }
+    } catch {
+        return null;
+    }
+
+    // Loopback short-circuit; otherwise check against the host's interface IPs.
+    // (Less precise than RTM_GETROUTE used by the C++ side, but covers the
+    // practical "is this destination on this machine?" question for our use.)
+    if (!ip.startsWith('127.')) {
+        if (!_garLocalIPv4Set().has(ip)) return null;
+    }
+
+    const abstractPath = '\u0000gar.endpoint.' + port;
+    // Reachability probe: AF_UNIX local connect either succeeds immediately or
+    // fails immediately with ECONNREFUSED/ENOENT.
+    const reachable = await new Promise((resolve) => {
+        let done = false;
+        const finish = (ok) => {
+            if (done) return;
+            done = true;
+            try { sock.destroy(); } catch { /* ignore */ }
+            resolve(ok);
+        };
+        const sock = _garNetMod.createConnection({ path: abstractPath });
+        sock.once('connect', () => finish(true));
+        sock.once('error', () => finish(false));
+        setTimeout(() => finish(false), 500);
+    });
+    return reachable ? abstractPath : null;
+}
+
+function _garMakeUnixCreateConnectionFn(abstractPath, useSSL, sniHost, allowSelfSigned) {
+    return () => {
+        const unixSocket = _garNetMod.createConnection({ path: abstractPath });
+        if (!useSSL) return unixSocket;
+        return _garTlsMod.connect({
+            socket: unixSocket,
+            servername: sniHost,
+            rejectUnauthorized: !allowSelfSigned,
+        });
+    };
+}
+
 class GARClient {
     /**
      * Initialize the GAR client.
@@ -68,7 +217,7 @@ class GARClient {
         this.localKeyMap = new Map();
         this.invalidatedKeyIds = new Set();
         this.recordMap = new Map();
-        this._activeOwnership = { msg_ref: 0, ownership_action: 'None', skip_ownership_checks: false, client_key_id: 0 };
+        this._activeOwnership = { msg_ref: 0, ownership_action: 'None', skip_ownership_checks: false, require_existing: false, client_key_id: 0 };
 
         this.running = false;
         this.heartbeatIntervalId = null;
@@ -136,7 +285,7 @@ class GARClient {
         this.invalidatedKeyIds.clear();
 
         // Active ownership state
-        this._activeOwnership = { msg_ref: 0, ownership_action: 'None', skip_ownership_checks: false, client_key_id: 0 };
+        this._activeOwnership = { msg_ref: 0, ownership_action: 'None', skip_ownership_checks: false, require_existing: false, client_key_id: 0 };
 
         // Heartbeat grace period flags
         this._initialGracePeriod = false;
@@ -163,13 +312,35 @@ class GARClient {
                 const WS = await this._ensureWebSocketCtor();
                 const isNode = typeof process !== 'undefined' && process.versions && process.versions.node;
 
-                this.log('INFO', `Connecting to WebSocket server at ${this.wsEndpoint}`);
+                // Prefer AF_UNIX abstract-namespace transport for local destinations.
+                // Falls back to TCP automatically (next reconnect iteration) if the
+                // listener disappears between probe and real connect.
+                let unixAbstractPath = null;
+                let sniHost = null;
+                if (isNode) {
+                    unixAbstractPath = await _garUnixAbstractPathForEndpoint(this.wsEndpoint);
+                    if (unixAbstractPath) {
+                        try { sniHost = new URL(this.wsEndpoint).hostname; } catch { /* ignore */ }
+                    }
+                }
+
+                this.log('INFO', `Connecting to WebSocket server at ${this.wsEndpoint}${unixAbstractPath ? ' (via AF_UNIX)' : ''}`);
 
                 const connectionPromise = new Promise((resolve, reject) => {
                     let websocket;
-                    if (this.allowSelfSignedCertificate && isNode) {
+                    const useSSL = this.wsEndpoint.toLowerCase().startsWith('wss://');
+                    const wsOpts = {};
+                    if (this.allowSelfSignedCertificate && isNode && useSSL) {
                         // Node.js 'ws' supports options for TLS; browsers do not.
-                        websocket = new WS(this.wsEndpoint, ['gar-protocol'], { rejectUnauthorized: false });
+                        wsOpts.rejectUnauthorized = false;
+                    }
+                    if (unixAbstractPath) {
+                        wsOpts.createConnection = _garMakeUnixCreateConnectionFn(
+                            unixAbstractPath, useSSL, sniHost, this.allowSelfSignedCertificate
+                        );
+                    }
+                    if (Object.keys(wsOpts).length > 0) {
+                        websocket = new WS(this.wsEndpoint, ['gar-protocol'], wsOpts);
                     } else {
                         websocket = new WS(this.wsEndpoint, ['gar-protocol']);
                     }
@@ -1139,12 +1310,13 @@ class GARClient {
      * @param {number} [options.msgRef=0] - Message reference for correlating recoverable error responses.
      * @param {string} [options.ownershipAction='None'] - 'None' (check only), 'Acquire', or 'Release'.
      * @param {boolean} [options.skipOwnershipChecks=false] - Bypass ownership validation.
+     * @param {boolean} [options.requireExisting=false] - Only write to existing keys; do not create new keys.
      * @param {number} [options.clientKeyId=0] - The g::Client key ID for ownership. 0 uses the connection key.
      */
-    updateActiveOwnership({ msgRef = 0, ownershipAction = 'None', skipOwnershipChecks = false, clientKeyId = 0 } = {}) {
-        const newOwnership = { msg_ref: msgRef, ownership_action: ownershipAction, skip_ownership_checks: skipOwnershipChecks, client_key_id: clientKeyId };
+    updateActiveOwnership({ msgRef = 0, ownershipAction = 'None', skipOwnershipChecks = false, requireExisting = false, clientKeyId = 0 } = {}) {
+        const newOwnership = { msg_ref: msgRef, ownership_action: ownershipAction, skip_ownership_checks: skipOwnershipChecks, require_existing: requireExisting, client_key_id: clientKeyId };
         const cur = this._activeOwnership;
-        if (newOwnership.msg_ref !== cur.msg_ref || newOwnership.ownership_action !== cur.ownership_action || newOwnership.skip_ownership_checks !== cur.skip_ownership_checks || newOwnership.client_key_id !== cur.client_key_id) {
+        if (newOwnership.msg_ref !== cur.msg_ref || newOwnership.ownership_action !== cur.ownership_action || newOwnership.skip_ownership_checks !== cur.skip_ownership_checks || newOwnership.require_existing !== cur.require_existing || newOwnership.client_key_id !== cur.client_key_id) {
             this._activeOwnership = newOwnership;
             this.sendMessage({ message_type: 'ActiveOwnership', value: newOwnership });
         }
@@ -1511,3 +1683,4 @@ class GARClient {
 }
 
 export default GARClient;
+export { optimalEndpoint };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jsgar",
-  "version": "4.5.2",
+  "version": "4.6.0",
   "description": "A Javascript client for the GAR protocol",
   "type": "module",
   "main": "dist/gar.umd.js",
@@ -36,7 +36,7 @@
     "@eslint/json": "^0.13.2",
     "@rollup/plugin-commonjs": "^24.0.0",
     "@rollup/plugin-node-resolve": "^15.0.0",
-    "eslint": "^9.38.0",
+    "eslint": "^9.39.4",
     "globals": "^16.0.0",
     "rollup": "^3.0.0"
   }