node24-jmx25 0.0.0-stage → 0.8.0-dev

package/LICENSE

@@ -0,0 +1,190 @@
+                              Apache License
+                        Version 2.0, January 2004
+                     http://www.apache.org/licenses/
+
+TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+1. Definitions.
+
+   "License" shall mean the terms and conditions for use, reproduction,
+   and distribution as defined by Sections 1 through 9 of this document.
+
+   "Licensor" shall mean the copyright owner or entity authorized by
+   the copyright owner that is granting the License.
+
+   "Legal Entity" shall mean the union of the acting entity and all
+   other entities that control, are controlled by, or are under common
+   control with that entity. For the purposes of this definition,
+   "control" means (i) the power, direct or indirect, to cause the
+   direction or management of such entity, whether by contract or
+   otherwise, or (ii) ownership of fifty percent (50%) or more of the
+   outstanding shares, or (iii) beneficial ownership of such entity.
+
+   "You" (or "Your") shall mean an individual or Legal Entity
+   exercising permissions granted by this License.
+
+   "Source" form shall mean the preferred form for making modifications,
+   including but not limited to software source code, documentation
+   source, and configuration files.
+
+   "Object" form shall mean any form resulting from mechanical
+   transformation or translation of a Source form, including but
+   not limited to compiled object code, generated documentation,
+   and conversions to other media types.
+
+   "Work" shall mean the work of authorship, whether in Source or
+   Object form, made available under the License, as indicated by a
+   copyright notice that is included in or attached to the work
+   (an example is provided in the Appendix below).
+
+   "Derivative Works" shall mean any work, whether in Source or Object
+   form, that is based on (or derived from) the Work and for which the
+   editorial revisions, annotations, elaborations, or other modifications
+   represent, as a whole, an original work of authorship. For the purposes
+   of this License, Derivative Works shall not include works that remain
+   separable from, or merely link (or bind by name) to the interfaces of,
+   the Work and Derivative Works thereof.
+
+   "Contribution" shall mean any work of authorship, including
+   the original version of the Work and any modifications or additions
+   to that Work or Derivative Works thereof, that is intentionally
+   submitted to Licensor for inclusion in the Work by the copyright owner
+   or by an individual or Legal Entity authorized to submit on behalf of
+   the copyright owner. For the purposes of this definition, "submitted"
+   means any form of electronic, verbal, or written communication sent
+   to the Licensor or its representatives, including but not limited to
+   communication on electronic mailing lists, source code control systems,
+   and issue tracking systems that are managed by, or on behalf of, the
+   Licensor for the purpose of discussing and improving the Work, but
+   excluding communication that is conspicuously marked or otherwise
+   designated in writing by the copyright owner as "Not a Contribution."
+
+   "Contributor" shall mean Licensor and any individual or Legal Entity
+   on behalf of whom a Contribution has been received by Licensor and
+   subsequently incorporated within the Work.
+
+2. Grant of Copyright License. Subject to the terms and conditions of
+   this License, each Contributor hereby grants to You a perpetual,
+   worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+   copyright license to reproduce, prepare Derivative Works of,
+   publicly display, publicly perform, sublicense, and distribute the
+   Work and such Derivative Works in Source or Object form.
+
+3. Grant of Patent License. Subject to the terms and conditions of
+   this License, each Contributor hereby grants to You a perpetual,
+   worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+   (except as stated in this section) patent license to make, have made,
+   use, offer to sell, sell, import, and otherwise transfer the Work,
+   where such license applies only to those patent claims licensable
+   by such Contributor that are necessarily infringed by their
+   Contribution(s) alone or by combination of their Contribution(s)
+   with the Work to which such Contribution(s) was submitted. If You
+   institute patent litigation against any entity (including a
+   cross-claim or counterclaim in a lawsuit) alleging that the Work
+   or a Contribution incorporated within the Work constitutes direct
+   or contributory patent infringement, then any patent licenses
+   granted to You under this License for that Work shall terminate
+   as of the date such litigation is filed.
+
+4. Redistribution. You may reproduce and distribute copies of the
+   Work or Derivative Works thereof in any medium, with or without
+   modifications, and in Source or Object form, provided that You
+   meet the following conditions:
+
+   (a) You must give any other recipients of the Work or
+       Derivative Works a copy of this License; and
+
+   (b) You must cause any modified files to carry prominent notices
+       stating that You changed the files; and
+
+   (c) You must retain, in the Source form of any Derivative Works
+       that You distribute, all copyright, patent, trademark, and
+       attribution notices from the Source form of the Work,
+       excluding those notices that do not pertain to any part of
+       the Derivative Works; and
+
+   (d) If the Work includes a "NOTICE" text file as part of its
+       distribution, then any Derivative Works that You distribute must
+       include a readable copy of the attribution notices contained
+       within such NOTICE file, excluding those notices that do not
+       pertain to any part of the Derivative Works, in at least one
+       of the following places: within a NOTICE text file distributed
+       as part of the Derivative Works; within the Source form or
+       documentation, if provided along with the Derivative Works; or,
+       within a display generated by the Derivative Works, if and
+       wherever such third-party notices normally appear. The contents
+       of the NOTICE file are for informational purposes only and
+       do not modify the License. You may add Your own attribution
+       notices within Derivative Works that You distribute, alongside
+       or as an addendum to the NOTICE text from the Work, provided
+       that such additional attribution notices cannot be construed
+       as modifying the License.
+
+   You may add Your own copyright statement to Your modifications and
+   may provide additional or different license terms and conditions
+   for use, reproduction, or distribution of Your modifications, or
+   for any such Derivative Works as a whole, provided Your use,
+   reproduction, and distribution of the Work otherwise complies with
+   the conditions stated in this License.
+
+5. Submission of Contributions. Unless You explicitly state otherwise,
+   any Contribution intentionally submitted for inclusion in the Work
+   by You to the Licensor shall be under the terms and conditions of
+   this License, without any additional terms or conditions.
+   Notwithstanding the above, nothing herein shall supersede or modify
+   the terms of any separate license agreement you may have executed
+   with Licensor regarding such Contributions.
+
+6. Trademarks. This License does not grant permission to use the trade
+   names, trademarks, service marks, or product names of the Licensor,
+   except as required for reasonable and customary use in describing the
+   origin of the Work and reproducing the content of the NOTICE file.
+
+7. Disclaimer of Warranty. Unless required by applicable law or
+   agreed to in writing, Licensor provides the Work (and each
+   Contributor provides its Contributions) on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+   implied, including, without limitation, any warranties or conditions
+   of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+   PARTICULAR PURPOSE. You are solely responsible for determining the
+   appropriateness of using or redistributing the Work and assume any
+   risks associated with Your exercise of permissions under this License.
+
+8. Limitation of Liability. In no event and under no legal theory,
+   whether in tort (including negligence), contract, or otherwise,
+   unless required by applicable law (such as deliberate and grossly
+   negligent acts) or agreed to in writing, shall any Contributor be
+   liable to You for damages, including any direct, indirect, special,
+   incidental, or consequential damages of any character arising as a
+   result of this License or out of the use or inability to use the
+   Work (including but not limited to damages for loss of goodwill,
+   work stoppage, computer failure or malfunction, or any and all
+   other commercial damages or losses), even if such Contributor
+   has been advised of the possibility of such damages.
+
+9. Accepting Warranty or Additional Liability. While redistributing
+   the Work or Derivative Works thereof, You may choose to offer,
+   and charge a fee for, acceptance of support, warranty, indemnity,
+   or other liability obligations and/or rights consistent with this
+   License. However, in accepting such obligations, You may act only
+   on Your own behalf and on Your sole responsibility, not on behalf
+   of any other Contributor, and only if You agree to indemnify,
+   defend, and hold each Contributor harmless for any liability
+   incurred by, or claims asserted against, such Contributor by reason
+   of your accepting any such warranty or additional liability.
+
+END OF TERMS AND CONDITIONS
+
+Copyright 2013-2015 Xabier de Zuazo
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.

package/README.md

@@ -1,3 +1,118 @@
-# Temporary Holding Version
+# node18-jmx
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Node.js client for reading and managing Java applications through JMX. The package runs a small Java sidecar and exchanges newline-delimited JSON messages with it over the child process's standard input and output.
+
+## Requirements
+
+- Node.js 24 LTS or later.
+- Java 25 or later at runtime.
+- Maven and JDK 25 to build the Java sidecar from a source checkout. Published npm packages include the built sidecar JAR.
+
+## Installation
+
+```sh
+npm install node24-jmx25
+```
+
+## Usage
+
+The public API exposes both an `async`/`await` surface and the historical callback form. Every operation returns a `Promise` and still invokes the optional trailing callback with the decoded value when the request succeeds.
+
+```js
+const jmx = require("node24-jmx25");
+
+async function main() {
+  const client = jmx.createClient({ host: "localhost", port: 3000 });
+  client.on("error", (error) => console.error(error));
+
+  await client.connect();
+  const memory = await client.getAttribute("java.lang:type=Memory", "HeapMemoryUsage");
+  console.log(memory.getSync("used"));
+  await client.disconnect();
+}
+
+main();
+```
+
+An explicit JMX service URL and credentials may be passed instead:
+
+```js
+const client = jmx.createClient({
+  service: "service:jmx:rmi://localhost:3000/jndi/rmi://localhost:3000/jmxrmi",
+  username: "monitor",
+  password: "secret"
+});
+```
+
+## Client API
+
+`createClient(options)` accepts:
+
+- `service`: full JMX service URL. If provided, `host` and `port` are ignored.
+- `host`: hostname (defaults to `localhost`).
+- `port`: JMX port (required when `service` is not provided).
+- `protocol`: JMX protocol (defaults to `rmi`).
+- `urlPath`: optional JMX URL path.
+- `username` and `password`: optional JMX credentials.
+- `classpath`: optional array of local Java classpath entries, needed when operation signatures use application-specific classes.
+- `requestTimeoutMs`: per-request timeout in milliseconds (default `30000`; `0` disables).
+- `stderrFailFastBytes`: cumulative size of JVM stderr output after which the sidecar is terminated and all pending requests reject with a flood error (default `1048576`; `0` disables the guard).
+- `debug`: a function `(label, payload) => void` that receives every protocol send and receive. Pass `true` or set `DEBUG=node24-jmx25` to log through `console.error` instead.
+
+The returned EventEmitter exposes:
+
+- `connect()` and `disconnect()` manage the sidecar and the JMX connection. Both return a `Promise`. `connect()` additionally emits the `connect` event on success.
+- `getAttribute(mbean, attribute, [callback])`
+- `getAttributes(mbean, attributes, [callback])`
+- `getDefaultDomain([callback])`
+- `getDomains([callback])`
+- `getMBeanCount([callback])`
+- `listMBeans([pattern,] [callback])`
+- `invoke(mbean, methodName, params, [signature,] [callback])`
+- `setAttribute(mbean, attribute, value, [className,] [callback])`
+- `addNotificationListener(mbean)` and `removeNotificationListener(subscriptionId)`
+- Events: `connect`, `disconnect`, `error`, `notification`.
+
+Promises reject with the Java error class name in `error.name`; the Java stack trace is attached as `error.javaStack` when the sidecar supplied one. If a callback is provided and the request succeeds, the callback receives the decoded value as its only argument.
+
+### Value decoding
+
+- Java `long` values that fit into `Number.MAX_SAFE_INTEGER` are returned as plain JavaScript numbers. Values outside that range are wrapped as `{ longValue: "<decimal>" }` to preserve exactness. The legacy pattern `value.longValue` keeps working for the wrapped form, and plain-number comparisons work for the common case.
+- `CompositeData` values are returned as a wrapper with `getSync(key)`, which throws when `key` is unknown. The wrapper also exposes `keys()` and serializes to its items on `JSON.stringify`.
+- `TabularData` collapses to an array of `CompositeData` rows.
+- Java `Map` values whose keys are all strings are returned as plain objects. Maps with non-string keys are returned as arrays of `[key, value]` pairs to avoid lossy key coercion.
+- Other Java objects are returned as `{ className, value }` where `value` is the result of `toString()`.
+- Java arrays and `Iterable` values are returned as JavaScript arrays.
+
+### Notifications
+
+```js
+const subscriptionId = await client.addNotificationListener("test.jmx:type=Counter");
+client.on("notification", (event) => {
+  console.log(event.notification.type, event.notification.message);
+});
+```
+
+Each `notification` payload includes `subscriptionId`, `mbean`, and `notification` with the decoded JMX `Notification` fields.
+
+## Building and testing from source
+
+```sh
+npm test
+```
+
+`npm test` builds the sidecar before running the tests. `npm pack` and `npm publish` also build it automatically through the `prepack` script. Maven downloads the pinned Jackson dependency during the build.
+
+Continuous integration is defined in [.github/workflows/ci.yml](.github/workflows/ci.yml) and runs the same build/test pipeline on every push and pull request.
+
+## Debug logging
+
+Set the environment variable `DEBUG=node24-jmx25` or pass `debug: true` to `createClient` to log each JSON-RPC request and response to `stderr`. For custom routing supply `debug: (label, payload) => void`.
+
+## Security
+
+JMX credentials are sent only through the sidecar's local process pipe and are not written to logs. The pipe content is visible to the user who owns the Node.js process, which includes core dumps and process-memory snapshots of either side; prefer short-lived credentials and restrict access to the host accordingly. Use authenticated, TLS-protected JMX connections when the JMX endpoint is reachable over a network, and restrict network access to JMX ports independently of this client.
+
+## License
+
+Apache-2.0. See [LICENSE](LICENSE).

package/index.js

@@ -0,0 +1,33 @@
+"use strict";
+
+const Client = require("./lib/client");
+
+/** Checks whether a classpath entry is empty or has an unsupported non-string value. */
+function isInvalidClasspathEntry(entry) {
+  return typeof entry !== "string" || entry.length === 0;
+}
+
+/** Validates client options and returns a client for the requested JMX service. */
+function createClient(options) {
+  if (!options || typeof options !== "object") {
+    throw new TypeError("options is required");
+  }
+  if (options.service !== undefined && typeof options.service !== "string") {
+    throw new TypeError("service must be a string");
+  }
+  if (options.classpath !== undefined
+      && (!Array.isArray(options.classpath) || options.classpath.some(isInvalidClasspathEntry))) {
+    throw new TypeError("classpath must be an array of Java classpath entries");
+  }
+  if (!options.service) {
+    const validPortInput = typeof options.port === "number"
+      || (typeof options.port === "string" && /^\d+$/.test(options.port));
+    const port = Number(options.port);
+    if (!validPortInput || !Number.isInteger(port) || port < 1 || port > 65535) {
+      throw new TypeError("a valid port is required when service is not supplied");
+    }
+  }
+  return new Client(options);
+}
+
+module.exports = { createClient };

package/lib/client.js

@@ -0,0 +1,544 @@
+"use strict";
+
+const { spawn } = require("node:child_process");
+const { EventEmitter } = require("node:events");
+const fs = require("node:fs");
+const path = require("node:path");
+const { fromWire, toWire } = require("./javaValues");
+
+const DEFAULT_REQUEST_TIMEOUT_MS = 30000;
+const STDERR_TAIL_BYTES = 8192;
+const DEFAULT_STDERR_FAIL_FAST_BYTES = 1048576;
+
+/** Creates a Node.js client that communicates with the Java JMX bridge over process pipes. */
+class Client extends EventEmitter {
+  /** Stores connection options and initializes sidecar lifecycle and request state. */
+  constructor(options) {
+    super();
+    this.options = options;
+    this.service = buildServiceUrl(options);
+    this.requestTimeoutMs = options.requestTimeoutMs !== undefined
+      ? Number(options.requestTimeoutMs)
+      : DEFAULT_REQUEST_TIMEOUT_MS;
+    this.stderrFailFastBytes = typeof options.stderrFailFastBytes === "number"
+      ? options.stderrFailFastBytes
+      : DEFAULT_STDERR_FAIL_FAST_BYTES;
+    this.stderrBytes = 0;
+    this.debug = resolveDebug(options.debug);
+    this.child = null;
+    this.connected = false;
+    this.closing = false;
+    this.nextId = 1;
+    this.pending = new Map();
+    this.notificationHandlers = new Map();
+    this.writeQueue = [];
+    this.pumping = false;
+    this.drainPending = false;
+    this.stdoutBuffer = "";
+    this.stderrBuffer = Buffer.alloc(0);
+    this.readyPromise = null;
+    this.resolveReady = null;
+    this.rejectReady = null;
+    this.resolveExit = null;
+    this.exitPromise = null;
+  }
+
+  /** Starts or reuses the bridge, connects it to JMX, and emits connect on success. */
+  async connect() {
+    if (this.connected) return;
+    try {
+      await this.ensureBridge();
+      await this.request("connect", {
+        service: this.service,
+        username: this.options.username,
+        password: this.options.password
+      });
+      this.connected = true;
+      this.emit("connect");
+    } catch (error) {
+      if (this.child && !this.connected) {
+        this.closing = true;
+        await this.stopBridge();
+        this.closing = false;
+      }
+      throw error;
+    }
+  }
+
+  /** Disconnects the JMX connector, closes the sidecar, and emits disconnect after shutdown. */
+  async disconnect() {
+    if (!this.child || this.closing) return;
+    this.closing = true;
+    const wasConnected = this.connected;
+    let failure;
+    try {
+      if (wasConnected) {
+        await this.request("disconnect", {});
+      }
+    } catch (error) {
+      failure = error;
+    } finally {
+      this.connected = false;
+      await this.stopBridge();
+      this.closing = false;
+    }
+    if (failure) this.safeEmitError(failure);
+    if (wasConnected) this.emit("disconnect");
+  }
+
+  /** Closes the sidecar input, waits for process exit, and clears its pending lifecycle state. */
+  async stopBridge() {
+    if (!this.child) return;
+    const child = this.child;
+    try { child.stdin.end(); } catch (_) { /* input already closed */ }
+    await this.exitPromise;
+    this.child = null;
+    this.readyPromise = null;
+    this.exitPromise = null;
+    this.stdoutBuffer = "";
+    this.stderrBuffer = Buffer.alloc(0);
+    this.stderrBytes = 0;
+    this.writeQueue.length = 0;
+    this.pumping = false;
+    this.drainPending = false;
+  }
+
+  /** Requests one MBean attribute. Returns a Promise and invokes the optional legacy callback. */
+  getAttribute(mbean, attribute, callback) {
+    return this.dispatch("getAttribute", { mbean, attribute }, callback);
+  }
+
+  /** Requests multiple MBean attributes. Returns a Promise and invokes the optional legacy callback. */
+  getAttributes(mbean, attributes, callback) {
+    return this.dispatch("getAttributes", { mbean, attributes }, callback);
+  }
+
+  /** Requests the connected server's default domain. */
+  getDefaultDomain(callback) {
+    return this.dispatch("getDefaultDomain", {}, callback);
+  }
+
+  /** Requests the connected server's domains. */
+  getDomains(callback) {
+    return this.dispatch("getDomains", {}, callback);
+  }
+
+  /** Requests the connected server's MBean count. */
+  getMBeanCount(callback) {
+    return this.dispatch("getMBeanCount", {}, callback);
+  }
+
+  /** Invokes an MBean operation while preserving the optional-signature callback overload. */
+  invoke(mbean, methodName, params, signatureOrCallback, callback) {
+    let signature = signatureOrCallback;
+    if (typeof signatureOrCallback === "function") {
+      callback = signatureOrCallback;
+      signature = undefined;
+    }
+    let values;
+    let types;
+    try {
+      values = params || [];
+      types = signature || values.map(inferJavaType);
+    } catch (error) {
+      return this.failPromise(error);
+    }
+    return this.dispatch("invoke", {
+      mbean,
+      methodName,
+      params: values.map(toWire),
+      signature: types
+    }, callback);
+  }
+
+  /** Lists canonical MBean names, optionally filtered by an ObjectName pattern. */
+  listMBeans(mbean, callback) {
+    if (typeof mbean === "function") {
+      callback = mbean;
+      mbean = undefined;
+    }
+    return this.dispatch("listMBeans", { mbean }, callback);
+  }
+
+  /** Sets an attribute and preserves the optional-class-name callback overload. */
+  setAttribute(mbean, attribute, value, classNameOrCallback, callback) {
+    let className = classNameOrCallback;
+    if (typeof classNameOrCallback === "function") {
+      callback = classNameOrCallback;
+      className = inferJavaType(value);
+    }
+    let encoded;
+    try {
+      encoded = toWire(value);
+    } catch (error) {
+      return this.failPromise(error);
+    }
+    return this.dispatch("setAttribute", {
+      mbean,
+      attribute,
+      value: encoded,
+      className: className || inferJavaType(value)
+    }, callback);
+  }
+
+  /** Subscribes to JMX notifications from an MBean and returns the subscription identifier. */
+  async addNotificationListener(mbean) {
+    if (typeof mbean !== "string" || mbean.length === 0) {
+      throw new TypeError("mbean must be a non-empty ObjectName string");
+    }
+    const subscriptionId = await this.request("addNotificationListener", { mbean });
+    this.notificationHandlers.set(subscriptionId, { mbean });
+    return subscriptionId;
+  }
+
+  /** Removes an active JMX notification subscription from both sides of the bridge. */
+  async removeNotificationListener(subscriptionId) {
+    this.notificationHandlers.delete(subscriptionId);
+    await this.request("removeNotificationListener", { subscriptionId });
+  }
+
+  /** Routes an operation through the bridge, decodes the result, and signals both API styles. */
+  async dispatch(method, params, callback) {
+    const result = await this.request(method, params);
+    const decoded = fromWire(result);
+    if (typeof callback === "function") callback(decoded);
+    return decoded;
+  }
+
+  /** Starts the packaged Java archive once and waits until its protocol is ready. */
+  ensureBridge() {
+    if (this.child) return this.readyPromise;
+    const jarPath = path.join(__dirname, "..", "java-bridge", "target", "jmx-bridge.jar");
+    if (!fs.existsSync(jarPath)) {
+      return Promise.reject(new Error("JMX bridge JAR is missing; run `npm run build:bridge` first"));
+    }
+    const javaCommand = process.env.JAVA_HOME
+      ? path.join(process.env.JAVA_HOME, "bin", process.platform === "win32" ? "java.exe" : "java")
+      : "java";
+    const classpath = [jarPath].concat(this.options.classpath || []).join(path.delimiter);
+    this.child = spawn(javaCommand, ["-cp", classpath, "com.insider515.jmx.JmxBridge"], {
+      stdio: ["pipe", "pipe", "pipe"],
+      windowsHide: true
+    });
+    this.stdoutBuffer = "";
+    this.stderrBuffer = Buffer.alloc(0);
+    this.stderrBytes = 0;
+    this.writeQueue.length = 0;
+    this.pumping = false;
+    this.drainPending = false;
+    this.child.stdout.setEncoding("utf8");
+    this.child.stdout.on("data", this.consumeStdout.bind(this));
+    this.child.stderr.on("data", this.captureStderr.bind(this));
+    this.child.stdin.on("error", this.handleProcessError.bind(this));
+    this.child.stdin.on("drain", this.handleStdinDrain.bind(this));
+    this.child.on("error", this.handleProcessError.bind(this));
+    this.child.on("close", this.handleProcessExit.bind(this));
+    this.exitPromise = new Promise(
+      /** Stores the process-exit resolver for disconnect cleanup. */
+      (resolve) => { this.resolveExit = resolve; }
+    );
+    this.readyPromise = new Promise(
+      /** Stores startup completion handlers until the Java bridge reports readiness. */
+      (resolve, reject) => {
+        this.resolveReady = resolve;
+        this.rejectReady = reject;
+      }
+    );
+    return this.readyPromise;
+  }
+
+  /** Parses sidecar output lines, handles readiness, notifications, and routes RPC responses. */
+  consumeStdout(chunk) {
+    this.stdoutBuffer += chunk;
+    let newline;
+    while ((newline = this.stdoutBuffer.indexOf("\n")) !== -1) {
+      const line = this.stdoutBuffer.slice(0, newline);
+      this.stdoutBuffer = this.stdoutBuffer.slice(newline + 1);
+      let message;
+      try {
+        message = JSON.parse(line);
+      } catch (error) {
+        const protocolError = new Error("Invalid JSON received from JMX bridge", { cause: error });
+        this.rejectPending(protocolError);
+        if (this.child) this.child.kill();
+        this.safeEmitError(protocolError);
+        return;
+      }
+      if (this.debug) this.debug("recv", redactForDebug(message));
+      if (message.event === "ready") {
+        if (this.resolveReady) this.resolveReady();
+        this.resolveReady = null;
+        this.rejectReady = null;
+        continue;
+      }
+      if (message.event === "notification") {
+        this.emit("notification", {
+          subscriptionId: message.subscriptionId,
+          mbean: message.mbean,
+          notification: fromWire(message.notification)
+        });
+        continue;
+      }
+      const id = message.id;
+      const pending = this.pending.get(id);
+      if (!pending) {
+        if (Number.isSafeInteger(id) && id > 0 && id < this.nextId) {
+          continue;
+        }
+        const protocolError = new Error("JMX bridge returned an unknown request identifier");
+        this.rejectPending(protocolError);
+        if (this.child) this.child.kill();
+        this.safeEmitError(protocolError);
+        return;
+      }
+      this.pending.delete(id);
+      if (message.error) {
+        const error = new Error(message.error.message);
+        error.name = message.error.name || "JmxBridgeError";
+        if (typeof message.error.stack === "string") error.javaStack = message.error.stack;
+        pending.reject(error);
+      } else {
+        pending.resolve(message.result);
+      }
+    }
+  }
+
+  /** Rejects process startup and outstanding requests when the Java process cannot start. */
+  handleProcessError(error) {
+    if (this.rejectReady) this.rejectReady(error);
+    this.rejectReady = null;
+    this.resolveReady = null;
+    this.rejectPending(error);
+  }
+
+  /** Rejects every unresolved bridge request after the process transport becomes unusable. */
+  rejectPending(error) {
+    for (const pending of this.pending.values()) pending.reject(error);
+    this.pending.clear();
+    for (const queued of this.writeQueue) queued.reject(error);
+    this.writeQueue.length = 0;
+    this.pumping = false;
+    this.drainPending = false;
+  }
+
+  /** Retains a bounded byte tail of JVM diagnostics and kills the sidecar when stderr flood exceeds the fail-fast cap. */
+  captureStderr(chunk) {
+    const buffer = typeof chunk === "string" ? Buffer.from(chunk, "utf8") : chunk;
+    const combined = Buffer.concat([this.stderrBuffer, buffer]);
+    this.stderrBuffer = combined.length > STDERR_TAIL_BYTES
+      ? combined.subarray(combined.length - STDERR_TAIL_BYTES)
+      : combined;
+    this.stderrBytes += buffer.length;
+    if (this.stderrFailFastBytes > 0 && this.stderrBytes > this.stderrFailFastBytes && this.child && !this.closing) {
+      const limit = this.stderrFailFastBytes;
+      const details = this.stderrBuffer.toString("utf8").trim();
+      const suffix = details ? `: ${details}` : "";
+      const floodError = new Error(
+        `JMX bridge stderr exceeded the fail-fast threshold of ${limit} bytes${suffix}`);
+      this.stderrBytes = 0;
+      this.rejectPending(floodError);
+      try { this.child.kill("SIGKILL"); } catch (_) { /* process already exiting */ }
+      this.safeEmitError(floodError);
+    }
+  }
+
+  /** Handles sidecar termination and reports unexpected exits to the public error event. */
+  handleProcessExit(code, signal) {
+    const details = this.stderrBuffer.toString("utf8").trim();
+    const suffix = details ? `: ${details}` : "";
+    const error = new Error(`JMX bridge exited unexpectedly (code ${code}, signal ${signal})${suffix}`);
+    if (this.rejectReady) this.rejectReady(error);
+    this.rejectReady = null;
+    this.resolveReady = null;
+    for (const pending of this.pending.values()) pending.reject(error);
+    this.pending.clear();
+    for (const queued of this.writeQueue) queued.reject(error);
+    this.writeQueue.length = 0;
+    this.pumping = false;
+    if (this.resolveExit) this.resolveExit();
+    this.resolveExit = null;
+    const wasUnexpected = !this.closing;
+    if (wasUnexpected) {
+      this.child = null;
+      this.readyPromise = null;
+      this.exitPromise = null;
+      this.stderrBuffer = Buffer.alloc(0);
+      this.stderrBytes = 0;
+      this.notificationHandlers.clear();
+    }
+    if (wasUnexpected && this.connected) {
+      this.connected = false;
+      this.safeEmitError(error);
+      this.emit("disconnect");
+    }
+  }
+
+  /** Sends one JSON-RPC request, enforces its optional timeout, and resolves the matching response. */
+  async request(method, params) {
+    if (!this.child) throw new Error("JMX bridge is not running");
+    if (this.readyPromise) await this.readyPromise;
+    if (!Number.isSafeInteger(this.nextId)) {
+      throw new RangeError("JMX bridge request identifier space is exhausted");
+    }
+    const id = this.nextId++;
+    const line = JSON.stringify({ id, method, params }) + "\n";
+    if (this.debug) this.debug("send", { id, method, params: redactForDebug(params) });
+    return new Promise(
+      /** Registers the response handlers and request timeout for one bridge call. */
+      (resolve, reject) => {
+        const entry = { settled: false, resolve: null, reject: null };
+        const timer = this.requestTimeoutMs > 0
+          ? setTimeout(
+              /** Rejects the pending request and removes it from the queue if it was still waiting to be sent. */
+              () => {
+                if (entry.settled) return;
+                entry.settled = true;
+                this.pending.delete(id);
+                this.removeQueuedWrite(id);
+                reject(new Error(`JMX bridge request timed out after ${this.requestTimeoutMs}ms (${method})`));
+              }, this.requestTimeoutMs)
+          : null;
+        entry.resolve = /* Resolves one bridge response and cancels its pending timeout. */ (value) => {
+          if (entry.settled) return;
+          entry.settled = true;
+          if (timer) clearTimeout(timer);
+          resolve(value);
+        };
+        entry.reject = /* Rejects one bridge response and cancels its pending timeout. */ (error) => {
+          if (entry.settled) return;
+          entry.settled = true;
+          if (timer) clearTimeout(timer);
+          reject(error);
+        };
+        this.pending.set(id, entry);
+        this.enqueueWrite(id, line).catch(/** Fails the pending request when the pipe write cannot be enqueued. */ (error) => {
+          if (entry.settled) return;
+          entry.settled = true;
+          this.pending.delete(id);
+          if (timer) clearTimeout(timer);
+          reject(error);
+        });
+      }
+    );
+  }
+
+  /** Removes a queued write by request id when the caller cancels before the sidecar reads it. */
+  removeQueuedWrite(id) {
+    const index = this.writeQueue.findIndex(
+      /** Finds the queued write matching the cancelled request id. */
+      (entry) => entry.id === id
+    );
+    if (index === -1) return false;
+    this.writeQueue.splice(index, 1);
+    return true;
+  }
+
+  /** Serializes writes to the sidecar through a drain-aware queue to prevent runaway buffering. */
+  enqueueWrite(id, line) {
+    return new Promise(
+      /** Adds the write to the serialized queue and starts the pump if idle. */
+      (resolve, reject) => {
+        this.writeQueue.push({ id, line, resolve, reject });
+        this.pumpWriteQueue();
+      }
+    );
+  }
+
+  /** Flushes queued writes to stdin while honoring the stream's drain backpressure signal. */
+  pumpWriteQueue() {
+    if (this.pumping || this.drainPending || this.writeQueue.length === 0 || !this.child) return;
+    this.pumping = true;
+    while (this.writeQueue.length > 0) {
+      const entry = this.writeQueue[0];
+      let canContinue;
+      try {
+        canContinue = this.child.stdin.write(entry.line);
+      } catch (error) {
+        this.writeQueue.shift();
+        entry.reject(error);
+        continue;
+      }
+      this.writeQueue.shift();
+      entry.resolve();
+      if (!canContinue) {
+        this.drainPending = true;
+        this.pumping = false;
+        return;
+      }
+    }
+    this.pumping = false;
+  }
+
+  /** Clears the drain-pending gate so queued writes can resume after the stream drains. */
+  handleStdinDrain() {
+    this.drainPending = false;
+    this.pumpWriteQueue();
+  }
+
+  /** Emits a bridge error only when a listener is attached so Node does not crash the process. */
+  safeEmitError(error) {
+    if (this.listenerCount("error") > 0) this.emit("error", error);
+  }
+
+  /** Produces a rejected Promise for synchronous validation failures in public methods. */
+  failPromise(error) {
+    return Promise.reject(error);
+  }
+}
+
+/** Infers the Java signature for values supported by the legacy API. */
+function inferJavaType(value) {
+  if (value && typeof value.longValue !== "undefined") return "long";
+  if (typeof value === "string") return "java.lang.String";
+  if (typeof value === "boolean") return "boolean";
+  if (typeof value === "number") {
+    return Number.isInteger(value) && value >= -2147483648 && value <= 2147483647 ? "int" : "double";
+  }
+  if (Array.isArray(value)) return "[Ljava.lang.String;";
+  throw new TypeError(`Cannot infer Java type for ${typeof value}; provide an explicit signature`);
+}
+
+/** Creates the service URL format produced by the original Java JMXServiceURL constructor. */
+function buildServiceUrl(options) {
+  if (typeof options.service === "string" && options.service.startsWith("service:jmx:")) {
+    return options.service;
+  }
+  if (typeof options.service === "string") {
+    throw new TypeError("service must be a JMX service URL");
+  }
+  const protocol = options.protocol || "rmi";
+  const host = options.host || "localhost";
+  const port = Number(options.port);
+  const pathName = options.urlPath || `/jndi/${protocol}://${host}:${port}/jmx${protocol}`;
+  return `service:jmx:${protocol}://${host}:${port}${pathName}`;
+}
+
+const SENSITIVE_KEYS = new Set(["password", "username", "credentials", "secret", "token"]);
+
+/** Returns a shallow copy of a protocol payload with credential-like fields replaced by a placeholder. */
+function redactForDebug(payload) {
+  if (!payload || typeof payload !== "object") return payload;
+  if (Array.isArray(payload)) return payload.map(redactForDebug);
+  const result = {};
+  for (const [key, value] of Object.entries(payload)) {
+    if (SENSITIVE_KEYS.has(key.toLowerCase())) {
+      result[key] = typeof value === "undefined" ? value : "<redacted>";
+    } else {
+      result[key] = redactForDebug(value);
+    }
+  }
+  return result;
+}
+
+/** Resolves the debug logger from a user hook or the DEBUG environment flag. */
+function resolveDebug(hook) {
+  if (typeof hook === "function") return hook;
+  if (hook === true) return console.error.bind(console, "[node24-jmx25]");
+  const flag = process.env.DEBUG;
+  if (typeof flag === "string" && /(^|,)\s*node24-jmx25(\s*,|$)|^\*$/.test(flag)) {
+    return console.error.bind(console, "[node24-jmx25]");
+  }
+  return null;
+}
+
+module.exports = Client;

package/lib/javaValues.js

@@ -0,0 +1,112 @@
+"use strict";
+
+/** Wraps a Java long value while retaining its exact decimal representation. */
+class JavaLong {
+  /** Stores the untruncated long value as a decimal string. */
+  constructor(value) {
+    this.longValue = value;
+  }
+
+  /** Returns the exact decimal value without converting it to a JavaScript number. */
+  toString() {
+    return this.longValue;
+  }
+}
+
+/** Wraps a JMX CompositeData value with the legacy synchronous lookup method. */
+class JavaCompositeData {
+  /** Stores decoded CompositeData items for callback consumers. */
+  constructor(items) {
+    this.items = items;
+  }
+
+  /** Returns one named CompositeData item, matching the node-java throw-on-missing-key contract. */
+  getSync(key) {
+    if (!Object.prototype.hasOwnProperty.call(this.items, key)) {
+      const error = new Error(`CompositeData has no item named ${JSON.stringify(key)}`);
+      error.name = "CompositeDataKeyError";
+      throw error;
+    }
+    return this.items[key];
+  }
+
+  /** Reports the available CompositeData key names. */
+  keys() {
+    return Object.keys(this.items);
+  }
+
+  /** Exposes the decoded items when the wrapper is serialized as a plain JSON value. */
+  toJSON() {
+    return this.items;
+  }
+}
+
+/** Converts JSON-tagged JMX values into their callback-facing Java-compatible wrappers. */
+function fromWire(value) {
+  if (Array.isArray(value)) {
+    return value.map(fromWire);
+  }
+  if (!value || typeof value !== "object") {
+    return value;
+  }
+  if (value.$jmxType === "Long") {
+    return new JavaLong(value.value);
+  }
+  if (value.$jmxType === "CompositeData") {
+    const items = {};
+    for (const [key, item] of Object.entries(value.items)) {
+      items[key] = fromWire(item);
+    }
+    return new JavaCompositeData(items);
+  }
+  if (value.$jmxType === "TabularData") {
+    return fromWire(value.rows);
+  }
+  if (value.$jmxType === "Map") {
+    const entries = {};
+    for (const [key, item] of Object.entries(value.entries)) {
+      entries[key] = fromWire(item);
+    }
+    return entries;
+  }
+  if (value.$jmxType === "MapTypedKeys") {
+    return value.pairs.map(
+      /** Decodes a map entry whose non-string key would otherwise be coerced by JSON. */
+      (pair) => [fromWire(pair[0]), fromWire(pair[1])]
+    );
+  }
+  if (value.$jmxType === "Object") {
+    return { className: value.className, value: value.value };
+  }
+  const result = {};
+  for (const [key, item] of Object.entries(value)) {
+    result[key] = fromWire(item);
+  }
+  return result;
+}
+
+/** Encodes supported Java-compatible wrappers and plain JSON values for IPC requests. */
+function toWire(value) {
+  if (Array.isArray(value)) {
+    return value.map(toWire);
+  }
+  if (value && typeof value === "object" && typeof value.longValue !== "undefined") {
+    return String(value.longValue);
+  }
+  if (value && typeof value === "object" && typeof value.toJSON === "function") {
+    return toWire(value.toJSON());
+  }
+  if (value && typeof value === "object") {
+    const result = {};
+    for (const [key, item] of Object.entries(value)) {
+      result[key] = toWire(item);
+    }
+    return result;
+  }
+  if (typeof value === "bigint") {
+    return value.toString();
+  }
+  return value;
+}
+
+module.exports = { fromWire, toWire, JavaLong, JavaCompositeData };

package/package.json

@@ -1,6 +1,42 @@
 {
   "name": "node24-jmx25",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.8.0-dev",
+  "description": "Bridge library to communicate with Java applications through JMX.",
+  "homepage": "https://github.com/Insider515/node18-jmx",
+  "bugs": "https://github.com/Insider515/node18-jmx/issues",
+  "main": "index.js",
+  "scripts": {
+    "build:bridge": "mvn -f java-bridge/pom.xml clean package",
+    "prepack": "npm run build:bridge",
+    "test": "npm run build:bridge && node --test test/*.test.js"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Insider515/node18-jmx.git"
+  },
+  "keywords": [
+    "jmx",
+    "java",
+    "jvm",
+    "bridge"
+  ],
+  "author": {
+    "name": "Xabier de Zuazo",
+    "email": "xabier@zuazo.org",
+    "url": "https://github.com/zuazo"
+  },
+  "license": "Apache-2.0",
+  "readmeFilename": "README.md",
+  "engines": {
+    "node": ">=24"
+  },
+  "files": [
+    "index.js",
+    "lib/client.js",
+    "lib/javaValues.js",
+    "java-bridge/target/jmx-bridge.jar",
+    "README.md",
+    "LICENSE"
+  ],
+  "devDependencies": {}
+}