infinispan 0.14.0 → 0.15.0

package/.githooks/commit-msg

@@ -0,0 +1,9 @@
+#!/usr/bin/env bash
+
+REGEX='^\[#[0-9]+\]\s[A-Z].*\n?(\n(\*\s.*\n)+)?$'
+if ! grep -qE "$REGEX" "$1"; then
+    echo "Commit message format is incorrect. Run the following command:" >&2
+    echo "  git config commit.template .gitmessage" >&2
+    echo "and retry" >&2
+    exit 1
+fi

package/.githooks/configure-hooks

@@ -0,0 +1,7 @@
+#!/usr/bin/env bash
+
+BASEDIR=$(dirname "$0")/..
+BASEDIR_RESOLVED=$(realpath "$BASEDIR")
+
+git config get --local core.hooksPath || git config set --local core.hooksPath "$BASEDIR_RESOLVED"/.githooks
+git config get --local commit.template || git config set --local commit.template "$BASEDIR_RESOLVED"/.gitmessage

package/.githooks/configure-hooks.bat

@@ -0,0 +1,15 @@
+@echo off
+
+set "DIRNAME=%~dp0%"
+pushd "%DIRNAME%.."
+set "BASEDIR_RESOLVED=%CD%"
+popd
+
+git config get --local core.hooksPath
+if ERRORLEVEL 1 (
+   git config set --local core.hooksPath "%BASEDIR_RESOLVED%/.githooks
+)
+git config get --local commit.template
+if ERRORLEVEL 1 (
+   git config set --local commit.template "%BASEDIR_RESOLVED%/.gitmessage
+)

package/.gitmessage

@@ -0,0 +1,7 @@
+# [#nnnnn] Title, summary, imperative, start upper case, don't end with a period
+# No more than 50 chars. #### 50 chars is here:  #
+# Remember blank line between title and body.
+
+# Body: Explain *what* and *why* (not *how*)
+# Wrap at 72 chars. ################################## which is here:  #
+

package/AI-CODE.md

@@ -0,0 +1,86 @@
+# JS Client Code Instructions
+
+## Tech Stack
+* **Runtime:** Node.js 24 LTS
+* **Language:** JavaScript (ES6+) with TypeScript definition files (`types/index.d.ts`)
+* **Protocol:** Hot Rod binary protocol — versions 2.2, 2.5, 2.9, 3.0, 4.0, 4.1
+* **Test framework:** Jasmine 6
+* **Linting:** ESLint (ES2022, single quotes, semicolons required, JSDoc required)
+* **Docs:** JSDoc for API docs, AsciiDoc for user documentation
+
+## Project Structure
+
+```
+index.js                  # Entry point — re-exports lib/infinispan.js
+lib/
+  infinispan.js           # Main client API (connect, CRUD, listeners, queries, scripts)
+  io.js                   # Transport layer (TCP sockets, topology, failover, consistent hashing)
+  protocols.js            # Hot Rod protocol encode/decode for all supported versions
+  codec.js                # Binary codec (VInt, VLong, strings, Protobuf, JSON)
+  listeners.js            # Remote/local event listener management
+  functional.js           # Functional combinators (lift, actions, pipeline, partial application)
+  utils.js                # Logging, MurmurHash3, ReplayableBuffer, address normalization
+  uri.js                  # Hot Rod URI parsing (hotrod:// and hotrods:// schemes)
+  sasl/                   # SASL authentication mechanisms
+    factory.js            #   Mechanism registry and negotiation
+    plain.js              #   PLAIN
+    digest.js             #   DIGEST-MD5
+    scram.js              #   SCRAM-SHA-1/256/384/512
+    external.js           #   EXTERNAL (TLS cert)
+    oauthbearer.js        #   OAUTHBEARER
+spec/                     # Tests
+  *_spec.js               #   Test suites
+  utils/testing.js        #   Shared test utilities and assertion helpers
+  configs/                #   Infinispan server XML configurations for test scenarios
+types/                    # TypeScript type definitions
+documentation/            # AsciiDoc user documentation
+scripts/                  # Build and test tooling
+```
+
+## Build and Test Commands
+* **Install dependencies:** `npm install`
+* **Lint:** `npm run lint`
+* **Run tests (with containers):** `npm run test:docker`
+* **Run tests (containers already running):** `npm test`
+* **Start test containers:** `npm run docker:up`
+* **Stop test containers:** `npm run docker:down`
+* **Run a single spec:** `npx jasmine spec/infinispan_local_spec.js`
+* **Generate SSL certificates:** `npm run ssl:generate`
+* **Generate API docs:** `npm run docs:api`
+* **Override server version:** `INFINISPAN_VERSION=16.1.3 npm run test:docker`
+
+## Architecture Notes
+
+* **Consistent hashing:** Keys are routed to owning servers using MurmurHash3. Topology updates from the server adjust the hash ring automatically.
+* **Multiplexing:** Multiple in-flight requests share a single TCP connection per server, routed by message ID.
+* **State threading in codec:** The codec layer uses a functional "lift" pattern where encode/decode functions return `{answer, state}` tuples for immutable state management through the pipeline.
+* **Failover:** Automatic retry with round-robin fallback to other cluster members. Cross-site failover supported via `clusters` option and `switchToCluster()`.
+
+## Development Standards
+* **Style:** Use `var` for variable declarations (not `const`/`let`) to match existing codebase.
+* **Module pattern:** All modules wrap code in an IIFE: `(function() { ... }.call(this));`
+* **JSDoc:** Required for all public functions. Use `@param`, `@returns`, `@since` tags.
+* **Testing:** Tests use Promise chains with `spec/utils/testing.js` helpers. Follow the pattern:
+  ```javascript
+  var t = require('./utils/testing');
+  it('should do something', function(done) {
+    t.client(t.local, t.authOpts)
+      .then(t.assert(t.put('key', 'value')))
+      .then(t.assert(t.get('key'), t.toBe('value')))
+      .then(t.assert(t.disconnect()))
+      .then(function() { done(); }, t.failed(done));
+  });
+  ```
+* **Commit logs:** Commit logs must always start with `[#nnnnn] Summary`.
+* **Git branches:** Branches should be named `issueid/issue_summary` and use `origin/main` as the upstream.
+
+## Development Platform
+* **Repository:** https://github.com/infinispan/js-client
+* **Issues:** Use GitHub Issues with appropriate labels.
+* **License:** Apache-2.0
+
+## Related Projects
+
+* **Infinispan server:** The Infinispan server source code is in ../infinispan
+* **Operator:** The Infinispan Operator source code is in ../infinispan-operator
+* **Console:** The Infinispan Console source code is in ../infinispan-console

package/README.md

@@ -1,13 +1,18 @@
 # Hot Rod JS Client
 
+[![npm version](https://img.shields.io/npm/v/infinispan)](https://www.npmjs.com/package/infinispan)
+[![License](https://img.shields.io/npm/l/infinispan)](https://github.com/infinispan/js-client/blob/main/LICENSE)
+[![CI](https://github.com/infinispan/js-client/actions/workflows/ci.yml/badge.svg)](https://github.com/infinispan/js-client/actions/workflows/ci.yml)
+[![Node.js](https://img.shields.io/node/v/infinispan)](https://www.npmjs.com/package/infinispan)
+[![npm downloads](https://img.shields.io/npm/dm/infinispan)](https://www.npmjs.com/package/infinispan)
+
 `infinispan` is an asynchronous event-driven Infinispan client for Node.js.
 The results of the asynchronous operations are represented using
 [Promise](https://www.promisejs.org) instances. Amongst many advantages,
 promises make it easy to transform/chain multiple asynchronous invocations
 and they improve error handling by making it easy to centralise it.
 
-The client is under heavy development but here's a summary of its
-current capabilities:
+Here's a summary of its current capabilities:
 
 * `infinispan` client can be constructed with a single server address or
 multiple servers addresses. When passing multiple addresses, it will iterate
@@ -54,100 +59,91 @@ The client is normally connected to one of the sites, but if its members fail to
 
 Find installation, configuration, and example usage in the Hot Rod JS Client Guide at [infinispan.org/documentation](https://infinispan.org/documentation/).
 
-You can also build the Hot Rod JS Client Guide as follows:
-
-1. Clone the source repository.
-```bash
-$ git clone git@github.com:infinispan/js-client.git
-```
+You can also build the Hot Rod JS Client Guide locally:
 
-2. Build the HTML from the asciidoc source.
 ```bash
-$ asciidoctor documentation/asciidoc/titles/js_client.asciidoc
+npm run docs:user
 ```
 
-3. Open `documentation/asciidoc/titles/js_client.html` in any browser.
+Open `out/docs/index.html` in any browser.
 
 # API docs
 
 Review [Hot Rod JS client API documentation](http://docs.jboss.org/infinispan/hotrod-clients/javascript/1.0/apidocs/module-infinispan.html).
 
-You can also build API docs from the source repository as follows:
+To generate API docs locally:
 
-1. Generate JSDoc formatted API docs.
 ```bash
-$ npm install jsdoc
-$ ./node_modules/.bin/jsdoc lib/*.js
+npm run docs:api
 ```
 
-2. Open `open out/index.html` in any browser.
+Open `out/index.html` in any browser.
 
 # Testing
 
-Before executing any tests, Infinispan Server instances need to be started
-up so that testsuite can run against those. To ease this process, a script
-has been created in the root directory to start all the expected server
-instances.
+Tests run against Infinispan Server instances in Docker containers.
 
-Go to the root of the repo and execute:
+## Prerequisites
 
-```bash
-$ npm install
-```
+- Docker and Docker Compose
+- Java (for SSL certificate generation via `keytool`)
+- Node.js 24+
 
-Next, start the Infinispan Servers via:
+## Running tests
 
 ```bash
-$ ./run-servers.sh
+npm install
+npm run test:docker
 ```
 
-To run the testsuite once execute:
+This starts all required containers, generates SSL certificates if needed,
+waits for the cluster to form, runs the full test suite, and tears down
+the containers on exit.
 
-```bash
-$ ./run-testsuite.sh
-```
-
-To run individual tests execute:
+To test against a specific Infinispan version:
 
 ```bash
-$ npx jasmine spec/infinispan_local_spec.js
+INFINISPAN_VERSION=16.1.3 npm run test:docker
 ```
 
-To help with testing, you can quickly run the smoke tests via:
-
-```bash
-$ ./smoke-tests.sh
-```
+### Manual container lifecycle
 
-Both testsuite and smoke tests can be run with older protocol versions, e.g.
+For iterative development, start containers once and run tests repeatedly:
 
 ```bash
-$ protocol=2.5 ./smoke-tests.sh
+npm run docker:up
+npm test
+# ... make changes ...
+npm test
+npm run docker:down
 ```
 
-## Note for Mac Users:
-You might experience MPING issues running an Infinispan cluster.
+### Individual tests
+
+With containers running:
 
 ```bash
-13:37:15,561 ERROR (jgroups-5,server-two) [org.jgroups.protocols.MPING]
+npx jasmine spec/infinispan_local_spec.js
 ```
 
-If you run into the errors above, add the following to the routes of your host
+### SSL certificates
+
+Certificates are generated automatically on first test run. To regenerate:
 
 ```bash
-sudo route add -net 224.0.0.0/5 127.0.0.1
-sudo route add -net 232.0.0.0/5 192.168.1.3
+npm run ssl:generate
 ```
 
-# Manual stress tests
+## Manual stress tests
 
-The testsuite now contains manual stress tests that take several minutes to run.
+The testsuite contains manual stress tests that take several minutes to run.
 To run these tests, execute:
 
-    $ npx jasmine spec-manual/*_spec.js
-
+```bash
+npx jasmine spec-manual/*_spec.js
+```
 
-# Memory profiling
+## Memory profiling
 
 The source code comes with some programs that allow the client's memory consumption to be profiled.
 Those programs rely on having access to the global garbage collector.
@@ -158,38 +154,20 @@ Example:
 node --expose-gc memory-profiling/infinispan_memory_many_get.js
 ```
 
-So of programs might only report the memory usage before/after.
+Some programs might only report the memory usage before/after.
 Others might generate heap dumps which can be visualized using Google Chrome.
 Within Chrome, the Developer Tools UI contains a `Memory` tab where heap dumps can be loaded.
 
-
-# Debugging
+## Debugging
 
 To debug tests with IDE:
 
-    node --inspect-brk node_modules/.bin/jasmine spec/codec_spec.js
-
-Or:
-
-    node --inspect-brk node_modules/.bin/jasmine spec/infinispan_local_spec.js
+```bash
+node --inspect-brk node_modules/.bin/jasmine spec/codec_spec.js
+```
 
 And then start a remote Node.js debugger from IDE on port 9229.
 
-# Tests, servers and ports
-
-Here's some more detailed information on which tests interact with which servers and on which ports.
-On top of that, you can find information on which tests are always running as opposed to those that are started (and stopped) by the tests themselves.
-
-| Test          | Server Profile  | Ports (Auto/Manual)                     |
-| :------------ | :-------------: | :-------------------------------------- |
-| local spec    | local           | `11222` (A)                             |
-| expiry spec   | local           | `11222` (A)                             |
-| cluster spec  | clustered       | `11322` (A), `11332` (A), `11342` (A)   |
-| failover spec | clustered       | `11422` (M), `11432` (M), `11442` (M)   |
-| ssl spec      | local           | `11232` (A), `12242` (A), `12252` (A)   |
-| xsite spec    | earth, moon     | `11522` (earth, M), `11532` (moon, M)   |
-
 # Reporting an issue
 
-This project does not use Github issues.
-Instead, please report them via JIRA (project [HRJS](https://issues.jboss.org/projects/HRJS/summary)).
+Report issues via [GitHub Issues](https://github.com/infinispan/js-client/issues).

package/lib/codec.js

@@ -821,11 +821,48 @@
     protobuf.loadSync(path.join(`${__dirname}/protostream/message-wrapping.proto`),root); //loaded the wrappedMessage.proto to the root
     var QueryRequest = root.lookupType('org.infinispan.query.remote.client.QueryRequest');
     var QueryResponse = root.lookupType('org.infinispan.query.remote.client.QueryResponse');
+    var ContinuousQueryResult = root.lookupType('org.infinispan.query.remote.client.ContinuousQueryResult');
 
     return {
       QueryRequest,
-      QueryResponse
+      QueryResponse,
+      ContinuousQueryResult
     };
   }());
 
+  var CQ_RESULT_TYPES = ['leaving', 'joining', 'updated'];
+
+  /**
+   * Wrap a scalar value as a WrappedMessage byte array.
+   * @param {string|number|boolean} value - The value to wrap.
+   * @returns {Buffer} The encoded WrappedMessage bytes.
+   */
+  exports.wrapScalar = function(value) {
+    return WrappedMessage.encode(createWrappedMessage(value, _.identity)).finish();
+  };
+
+  /**
+   * Decode a ContinuousQueryResult from raw protobuf bytes.
+   * @param {Buffer} bytes - The raw ContinuousQueryResult bytes.
+   * @returns {Object} Decoded result with resultType, key, value, projection.
+   */
+  exports.decodeContinuousQueryResult = function(bytes) {
+    var msg = Query.ContinuousQueryResult.decode(bytes);
+    return {
+      resultType: CQ_RESULT_TYPES[msg.resultType] || 'leaving',
+      key: msg.key,
+      value: msg.value,
+      projection: msg.projection
+    };
+  };
+
+  /**
+   * Decode a WrappedMessage from raw bytes.
+   * @param {Buffer} bytes - The raw WrappedMessage bytes.
+   * @returns {Object} The decoded WrappedMessage object.
+   */
+  exports.decodeWrappedMessage = function(bytes) {
+    return WrappedMessage.decode(bytes);
+  };
+
 }.call(this));

package/lib/functional.js

@@ -193,6 +193,31 @@
     return _.extend.apply(null, construct({}, arguments));
   };
 
+  /**
+   * Deep merges multiple objects, with later arguments taking precedence.
+   * @returns {Object} A new merged object.
+   */
+  exports.deepMerge = function(/*args*/) {
+    var sources = _.toArray(arguments);
+    var result = {};
+    for (var i = 0; i < sources.length; i++) {
+      var src = sources[i];
+      if (!existy(src)) continue;
+      var keys = _.keys(src);
+      for (var k = 0; k < keys.length; k++) {
+        var key = keys[k];
+        var val = src[key];
+        if (!existy(val)) continue;
+        if (_.isObject(val) && !_.isArray(val) && _.isObject(result[key]) && !_.isArray(result[key])) {
+          result[key] = exports.deepMerge(result[key], val);
+        } else {
+          result[key] = val;
+        }
+      }
+    }
+    return result;
+  };
+
   exports.dispatch = function(/* funs */) {
     var funs = _.toArray(arguments);
     var size = funs.length;

package/lib/infinispan.js

@@ -13,6 +13,7 @@
   var f = require('./functional');
   var codec = require('./codec');
   var u = require('./utils');
+  var uri = require('./uri');
   var protocols = require('./protocols');
   var io = require('./io');
   var listeners = require('./listeners');
@@ -824,6 +825,58 @@
           return false;
         });
       },
+      /**
+       * Continuous query options.
+       *
+       * @typedef {Object} ContinuousQueryOptions
+       * @property {Object} [params] - Named parameter bindings for the Ickle query.
+       * @since 0.16
+       */
+      /**
+       * Register a continuous query that watches for cache changes
+       * matching the given Ickle query.
+       *
+       * @param {String} queryString Ickle query string.
+       * @param {ContinuousQueryOptions=} opts Optional CQ options.
+       * @returns {Promise<Object>}
+       * A promise completed with a ContinuousQuery handle.
+       * Use cq.on('joining', fn), cq.on('leaving', fn), cq.on('updated', fn)
+       * to receive events.
+       * @memberof Client#
+       * @since 0.16
+       */
+      addContinuousQuery: function(queryString, opts) {
+        var ctx = transport.context(SMALL);
+        logger.debugf('Invoke addContinuousQuery(msgId=%d,query=%s)', ctx.id, queryString);
+        return listen.addContinuousQueryListener(transport, ctx, queryString, opts);
+      },
+      /**
+       * Remove a continuous query.
+       *
+       * @param {Object} cq ContinuousQuery handle returned by addContinuousQuery.
+       * @returns {Promise}
+       * A promise completed when the continuous query has been removed.
+       * @memberof Client#
+       * @since 0.16
+       */
+      removeContinuousQuery: function(cq) {
+        var listenerId = cq.getListenerId();
+        var ctx = transport.context(SMALL);
+        logger.debugf('Invoke removeContinuousQuery(msgId=%d,listenerId=%s)', ctx.id, listenerId);
+        var conn = listen.findConnectionListener(listenerId);
+        if (!f.existy(conn))
+          return Promise.reject(
+            new Error(`No server connection for CQ listener (listenerId=${  listenerId  })`));
+
+        var remote = futurePinned(ctx, 0x27, p.encodeListenerId(listenerId), p.complete(p.hasSuccess), conn);
+        return remote.then(function (success) {
+          if (success) {
+            listen.removeListeners(listenerId);
+            return true;
+          }
+          return false;
+        });
+      },
       /**
        * Add script to server(s).
        *
@@ -1294,8 +1347,24 @@
    */
   /**
    * Infinispan client constructor taking an optional initial address,
-   * or multiple addresses, to which the client will try to connect to,
-   * as well as optional configuration settings.
+   * multiple addresses, or a Hot Rod URI string to which the client
+   * will try to connect, as well as optional configuration settings.
+   *
+   * @example
+   * // Connect with a Hot Rod URI
+   * client('hotrod://admin:password@localhost:11222')
+   *
+   * @example
+   * // URI with TLS and query parameters
+   * client('hotrods://admin:password@localhost:11222?trust_ca=/ca.pem')
+   *
+   * @example
+   * // URI with programmatic overrides
+   * client('hotrod://admin:password@localhost:11222', {authentication: {saslMechanism: 'SCRAM-SHA-256'}})
+   *
+   * @example
+   * // URI with multiple servers
+   * client('hotrod://admin:password@node1:11222,node2:11322')
    *
    * @example
    * client({port: 11222, host: 'localhost'})
@@ -1310,18 +1379,29 @@
    * client([{port: 11522, host: 'myhost'}, {port: 11622, host: 'myhost'}],
    *        {version: '2.2', cacheName: 'myCache'})
    *
-   * @param {(ServerAddress|ServerAddress[])} args
-   * Optional single or multiple addresses to which to connect. If none
-   * provided, the client will connect to localhost:11222 address by default.
+   * @param {(String|ServerAddress|ServerAddress[])} args
+   * A Hot Rod URI string (hotrod:// or hotrods://), a single server address,
+   * or an array of server addresses. If none provided, the client connects
+   * to localhost:11222 by default.
    * @param {ClientOptions=} options
-   * Optional configuration settings.
+   * Optional configuration settings. When a URI is provided, these settings
+   * override URI values.
    * @constructs Client
    * @returns {Promise<ReturnType<Client>>} A promise that resolves to a connected client.
    * @since 0.3
    */
   exports.client = function client(args, options) {
-    var merged = f.merge(Client.config, options);
-    var c = new Client(u.normalizeAddresses(args), merged);
+    var addrs, uriOpts;
+    if (uri.isHotrodURI(args)) {
+      var parsed = uri.parseHotrodURI(args);
+      addrs = parsed.servers;
+      uriOpts = parsed.options;
+    } else {
+      addrs = u.normalizeAddresses(args);
+      uriOpts = {};
+    }
+    var merged = f.deepMerge(Client.config, uriOpts, options || {});
+    var c = new Client(addrs, merged);
 
     return c.connect();
   };
@@ -1389,16 +1469,7 @@
       enabled: false,
       secureProtocol: 'TLS_client_method',
       trustCerts: [],
-      clientAuth: {
-        key: undefined,
-        passphrase: undefined,
-        cert: undefined
-      },
-      sniHostName: undefined,
-      cryptoStore: {
-        path: undefined,
-        passphrase: undefined
-      }
+      sniHostName: undefined
     },
     dataFormat : {
       keyType: 'text/plain',

package/lib/io.js

@@ -1116,6 +1116,9 @@
       f.actions(p.stepsHeaderBody(ctx, 0x23, p.sasl(transport.authOpts(), holder), undefined), codec.bytesEncoded)(ctx);
       var result = transport.writeCommandPinned(ctx, p.decodeSasl, conn);
       return result.then(function (r) {
+        if (r.complete) {
+          return r;
+        }
         ctx = u.context(16);
         ctx.topologyId = topologyId;
         holder.challenge = r.response;
@@ -1123,7 +1126,6 @@
         return transport.writeCommandPinned(ctx, p.decodeSasl, conn).then(function (r) {
           return r;
         });
-        return r;
       });
     }