infinispan 0.13.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,106 +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:
-
-```bash
-$ ./run-testsuite.sh
-```
+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.
 
-To run tests continuously execute:
+To test against a specific Infinispan version:
 
 ```bash
-$ ./node_modules/.bin/jasmine-node spec --autotest --watch lib --captureExceptions
+INFINISPAN_VERSION=16.1.3 npm run test:docker
 ```
 
-To run individual tests execute:
+### Manual container lifecycle
 
-```bash
-$ node node_modules/jasmine-node/lib/jasmine-node/cli.js spec/infinispan_local_spec.js --captureExceptions
-```
-
-To help with testing, you can quickly run the smoke tests via:
+For iterative development, start containers once and run tests repeatedly:
 
 ```bash
-$ ./smoke-tests.sh
+npm run docker:up
+npm test
+# ... make changes ...
+npm test
+npm run docker:down
 ```
 
-Both testsuite and smoke tests can be run with older protocol versions, e.g.
+### Individual tests
 
-```bash
-$ protocol=2.5 ./smoke-tests.sh
-```
-
-## Note for Mac Users:
-You might experience MPING issues running an Infinispan cluster.
+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:
 
-    $ ./node_modules/.bin/jasmine-node spec-manual --captureExceptions
-
+```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.
@@ -164,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/jasmine-node/lib/jasmine-node/cli.js spec/codec_spec.js
-
-Or:
-
-    node --inspect-brk node_modules/jasmine-node/lib/jasmine-node/cli.js 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).