@tier0/opcua-client 0.1.0 → 0.2.0

package/BENCHMARK.md

@@ -69,7 +69,7 @@ The native queue integration test also intentionally uses capacity 5 and batch s
 
 ## OperationLimits and NodeId cache optimization
 
-The P1 optimization reads the four standard server limits in one request and adds a bounded per-connection native parsed-NodeId cache. The 5,000-point standalone test recorded 5,011 cache entries, 65,001 hits, 5,011 misses, zero bypasses, and approximately 92.8% hit rate. Browse improved from 2,143 ms to 1,991 ms in the recorded local run; Read P50 remained 301 ms and Write P50 remained within local-run variance at 376 ms.
+The P1 optimization originally read four standard OperationLimits in one request and added a bounded per-connection native parsed-NodeId cache. It now also reads the optional `MaxMonitoredItemsPerSubscription` server capability. The 5,000-point standalone test recorded 5,011 cache entries, 65,001 hits, 5,011 misses, zero bypasses, and approximately 92.8% hit rate. Browse improved from 2,143 ms to 1,991 ms in the recorded local run; Read P50 remained 301 ms and Write P50 remained within local-run variance at 376 ms.
 
 The optimized Node-RED Flow results were:
 
@@ -80,4 +80,55 @@ The optimized Node-RED Flow results were:
 
 Against the immediately preceding P0 runs, 5,000-point Node-RED CPU changed from 2,050 ms to 1,990 ms and peak RSS from 143.1 MB to 139.1 MB. The 10,000-point CPU changed from 2,570 ms to 2,120 ms. The 10,000-point P1 run followed the sustained 5,000-point run in the same Node-RED process, so its 155.3 MB peak is a warmed-process regression value and should not be compared directly with the fresh-process memory baseline.
 
-The native integration fixture also advertises all four OperationLimits as 7 and verifies that the client reads those exact values. Its cache capacity is intentionally reduced to 32; the test remains bounded at 32 entries and reports 118 FIFO evictions while Browse, Read, Write, Subscribe, and cleanup all pass.
+The native integration fixture advertises the four OperationLimits as 7 and leaves `MaxMonitoredItemsPerSubscription` unspecified, which the client reports as 0 before applying its configured fallback. Its cache capacity is intentionally reduced to 32; the test remains bounded at 32 entries and reports 118 FIFO evictions while Browse, Read, Write, Subscribe, and cleanup all pass.
+
+## Multi-Subscription sharding and timed aggregation
+
+The 2026-08-06 real Node-RED smoke run forced the 100-point set into four Subscriptions by setting `maxItemsPerSubscription=25`. Browse, batch Read, batch Write, subscription creation, and the selectable Browse output all ran through a deployed Flow and a real OPC UA fixture.
+
+- Subscription creation: 72 ms for 100 MonitoredItems across 4 Subscriptions.
+- Two complete write rounds: 200 notifications delivered, 0 dropped, final values converged for 100/100 points.
+- Combined native queues: maximum depth 200 and capacity 200,000 across the four Subscriptions.
+- Node-RED process: 134.9 MB peak RSS and 130 ms sampled CPU for the complete smoke run.
+
+The outage run stopped and restarted the real fixture after subscription creation. The Subscribe node invalidated the old shard set and recovered exactly four Subscriptions containing 100/100 desired points. Subsequent writes again converged 100/100 final values with zero queue drops. Rebuild notifications can include current server values, so final per-point convergence and the recovered Subscription/MonitoredItem counts are the correctness gates rather than an exact raw notification count.
+
+The scale acceptance then used 5,000 points with `maxItemsPerSubscription=1000`. The deployed Node-RED Flow created exactly five Subscriptions in 478 ms, browsed 5,000 variables in 2,047 ms, read them in 321 ms, and completed each 5,000-point write round in 324 ms. The native queues delivered all 15,000 notifications with zero drops; final values converged for 5,000/5,000 points. Peak Node-RED RSS was 150.0 MB.
+
+The matching outage run rebuilt exactly five Subscriptions containing 5,000/5,000 desired points after the server restarted. It again delivered 15,000/15,000 native notifications with zero drops and converged every final value. The owner command queue completed 42/42 commands with maximum depth 4, zero rejection, and zero timeout; peak Node-RED RSS was 151.6 MB.
+
+## Single-owner native command queue
+
+The 2026-08-06 concurrency run used a real 3,000-point OPC UA fixture and submitted four Browse, four 200-point Read, and four 200-point Write operations concurrently. Including Connect, the native owner thread completed 13/13 commands with zero rejection and a maximum command queue depth of 4. A 1 ms JavaScript timer advanced 4,604 times during the run, confirming that the Node.js event loop remained responsive while the native owner serialized OPC UA work.
+
+The overload run reduced command queue capacity to 1. Queue depth never exceeded 1; seven commands were rejected immediately as full and one queued command was safely removed after its one-second queue timeout. The diagnostic counters reported two completed commands, eight total rejections, and one timeout. Native notification queue, reconnect, and real Node-RED four-Subscription recovery tests continued to pass after the ownership change.
+
+## 20,000-point sustained Node-RED pressure run
+
+The 2026-08-06 capacity run deployed the real nodes into Node-RED with 20,000 writable OPC UA variables, three complete Read rounds, four 5,000-item Subscriptions, and five complete Write rounds.
+
+| Metric | Result |
+| --- | ---: |
+| Browse 20,000 variables | 7,948 ms |
+| Read P50 / P95 | 1,236 / 1,559 ms |
+| Write P50 / P95 | 1,493 / 1,917 ms |
+| Create 20,000 MonitoredItems / 4 Subscriptions | 1,639 ms |
+| Native notifications | 120,000 / 120,000 delivered |
+| Final value convergence | 20,000 / 20,000 points |
+| Notification drops | 0 |
+| Maximum notification queue depth | 7,978 / 320,000 capacity |
+| Maximum native callback lag | 5.24 ms |
+| Owner commands | 367 / 367 completed, 0 rejected, 0 timed out |
+| Node-RED peak RSS | 342.9 MB |
+| Node-RED sampled CPU | 7,000 ms |
+| Complete run | 34.3 s |
+
+The collector observed 100,500 changes after its subscription-status gate, while native diagnostics recorded all 120,000 initial and write notifications. As in the smaller runs, notifications may arrive before the collector initializes its counter; zero native drops and convergence of every point to the final write value are the correctness gates. Phase sampling and an isolated external-writer run were subsequently used to locate and reduce the transient memory peak.
+
+## 20,000-point memory isolation and CSV Write optimization
+
+The same deployed Flow was tested with a separate native client generating the five write rounds. Node-RED still browsed 20,000 variables, rendered the 20,040-node editor tree, read all points, created four 5,000-item Subscriptions, collected notifications, and verified final convergence. Moving only write-payload construction outside Node-RED reduced its peak RSS to 170.27 MB. The phase peak during Subscribe creation was 166.47 MB and the peak during 100,000 external writes plus notification handling was 170.27 MB. All 120,000 native notifications were delivered with zero drops and 20,000/20,000 final convergence. This isolates the collection path from the CSV Write path and shows that subscription setup and notification delivery were not responsible for the earlier 342-362 MB peaks.
+
+Write CSV parsing was then changed from multiple whole-payload arrays and object copies to a single line scan that constructs compact final write descriptors. Two mixed Node-RED runs, each producing CSV and executing all 100,000 writes inside the Flow, recorded stable peaks of 226.73 MB and 226.06 MB. The immediately preceding fresh-process repeat peaked at 362.29 MB, so the repeatable peak reduction was approximately 37.6%. The optimized repeat recorded Write P50/P95 of 1,410/1,769 ms, delivered 120,000/120,000 native notifications with zero drops, and converged 20,000/20,000 final values. These are process-RSS engineering measurements; allocator and garbage-collector behavior still require production baselines on the target Node-RED image.
+
+The 20,000-point outage acceptance stopped and restarted the real OPC UA fixture after the initial four Subscriptions were created. The Subscribe node rebuilt exactly four Subscriptions with 20,000/20,000 MonitoredItems and zero failures. Two subsequent complete write rounds plus the rebuilt initial values delivered 60,000/60,000 native notifications with zero drops and final convergence for all 20,000 points. Recovery-phase RSS peaked at 175.04 MB and the complete run at 184.5 MB. The recovery status explicitly reported `rebuilt=true` and `dataGapPossible=true` because a server-side subscription rebuild cannot guarantee changes that occurred during the outage.

package/README.md

@@ -6,9 +6,9 @@ High-scale OPC UA client nodes for Node-RED, backed by open62541 and designed fo
 
 - `tier0-opcua-connection`: shared client session and credentials.
 - `tier0-opcua-browse`: recursive Browse plus a searchable, selectable address-space tree.
-- `tier0-opcua-read`: scalar-compatible batch Read with a manual/imported point list.
-- `tier0-opcua-write`: scalar-compatible batch Write with a manual/imported point list.
-- `tier0-opcua-subscribe`: one Subscription with many MonitoredItems.
+- `tier0-opcua-read`: scalar/array batch Read with optional IndexRange and a manual/imported point list.
+- `tier0-opcua-write`: scalar/array/matrix batch Write with optional IndexRange and a manual/imported point list.
+- `tier0-opcua-subscribe`: one or more automatically sharded Subscriptions with many MonitoredItems.
 
 The OPC UA server remains a separate service. This package contains client and collection nodes only.
 
@@ -35,13 +35,18 @@ Browse output can be wired directly into Read or Subscribe. In the Read and Writ
 
 Subscription commands are `replace`, `add`, `remove`, and `clear`. Read and Write split large arrays into configurable service batches; they do not loop over scalar OPC UA requests.
 
-Subscription notifications use a bounded native C++ queue and cross into JavaScript in batches. The default mode preserves all changes, batches up to 500 values, and caps pending changes at 10,000. Queue options are:
+Subscription notifications use a bounded native C++ queue and cross into JavaScript in batches. In Node-RED batch mode, changes from every server Subscription are merged and emitted when 500 values are ready or the default 50 ms flush window expires. Queue options are:
 
-- `callbackBatchSize`: maximum changes per C++ to JavaScript callback.
+- `callbackBatchSize`: maximum changes per native callback and Node-RED output message.
+- `callbackFlushIntervalMs`: maximum wait for a partially filled Node-RED output batch (default 50 ms).
 - `callbackQueueSize`: hard native queue capacity.
 - `queueMode`: `all` preserves pending changes; `latest` coalesces by MonitoredItem.
 - `overflowPolicy`: `drop-oldest` or `drop-newest` when the hard capacity is reached.
-- `outputMode`: `batch` sends one Node-RED message per native batch; `single` preserves one message per change compatibility.
+- `outputMode`: `batch` aggregates changes across Subscriptions; `single` preserves one message per change compatibility.
+
+`timestampMode` defaults to `source`, avoiding an unnecessary server timestamp on every high-rate notification. Advanced settings can request `both`, `server`, or `neither`. Notification outputs contain the changing value/status/timestamp plus useful custom point metadata such as `alias`; monitoring configuration that is constant for the lifetime of the item is not repeated on every change.
+
+Large point sets are automatically split across server Subscriptions. `maxItemsPerSubscription` defaults to 5,000 and acts as the fallback safety limit. When the server advertises `MaxMonitoredItemsPerSubscription`, the node uses the smaller limit. Status messages expose `subscriptionCount`, `subscriptionIds`, `desired`, `monitored`, and `failed`.
 
 Every batch includes queue diagnostics in `msg.opcua.queue`, including depth, capacity, maximum depth, enqueued, delivered, dropped, coalesced, batch sequence, and maximum queue lag. Queue overflow is also reported through the node status and warning log; it is never silent.
 
@@ -51,15 +56,23 @@ Each connection reads the server's standard OperationLimits in one OPC UA Read r
 
 Parsed NodeIds are cached per connection in native code. The default capacity is 100,000 entries and is configurable as `NodeId cache size` on the Connection node. The cache uses bounded FIFO eviction, is cleared naturally on reconnect, and can be disabled with capacity `0`. Read and Write batch outputs expose live data through `msg.opcua.clientDiagnostics`; library users can call `client.getDiagnostics()`. Diagnostics include OperationLimits plus cache size, capacity, hits, misses, bypasses, and evictions.
 
+## Native client ownership and command queue
+
+Each Connection owns one native C++ thread. That thread creates and closes the `UA_Client`, executes Connect, Browse, Read, Write, and Subscription commands, and runs `UA_Client_run_iterate`. Node.js async workers only submit commands and wait for their results, so concurrent Flow messages never access one open62541 client from multiple threads.
+
+The native command queue defaults to 256 pending commands and is configurable as `Command queue` under advanced Connection settings. Queue capacity is hard: overload is rejected with an explicit error. A command that remains queued longer than the configured OPC UA request timeout is removed safely; an already-running service call is allowed to finish under open62541's request timeout. Closing a Connection stops accepting work, rejects pending commands, and performs OPC UA cleanup on the owner thread.
+
+`client.getDiagnostics().commandQueue` reports `depth`, `capacity`, `maxDepth`, `active`, `enqueued`, `completed`, `rejected`, and `timedOut`.
+
 ## Connection and subscription recovery
 
 The native client reports secure-channel, session, connectivity-check, and subscription-inactivity transitions to a JavaScript connection supervisor. Recoverable channel interruptions keep the native client alive. Terminal failures replace the native client and retry with exponential backoff, 20% jitter, and the configured maximum interval. Operations fail fast with `OPCUA_RECONNECTING` while the connection is unavailable instead of building an unbounded request queue.
 
-Subscribe nodes retain a desired point map independently from the live server subscription. After reconnection they serialize reconciliation, validate the old subscription, rebuild it when the server session was lost, and recreate missing MonitoredItems in service-sized batches. A recovery status message has `msg.opcua.operation = "subscription-status"`, `recovered`, `rebuilt`, `reason`, and `dataGapPossible`. `dataGapPossible` is true after a subscription rebuild because values may have changed while the server was unavailable.
+Subscribe nodes retain a desired point map independently from live server Subscriptions. After reconnection they serialize reconciliation, validate every old Subscription, rebuild the complete shard set when the server session was lost, and recreate each MonitoredItem once in service-sized batches. A recovery status message has `msg.opcua.operation = "subscription-status"`, `recovered`, `rebuilt`, `reason`, and `dataGapPossible`. `dataGapPossible` is true after a subscription rebuild because values may have changed while the server was unavailable.
 
 Connection diagnostics also expose the current channel/session state and supervisor counters: client generation, reconnect attempts/successes, terminal replacements, and last recovery duration.
 
-Read CSV point lists require a `nodeId` header. Write CSV uses `nodeId,value,dataType`; `dataType` is optional when the Write node supplies a default. Other supported descriptor columns include `alias`, `samplingInterval`, `queueSize`, `deadbandType`, and `deadbandValue`.
+Read CSV point lists require a `nodeId` header. Write CSV uses `nodeId,value,dataType`; `dataType` is optional when the Write node supplies a default. Large Write CSV payloads are scanned once directly into compact native-write descriptors, avoiding several full-size intermediate point lists. Duplicate NodeIds retain the last row. Other supported descriptor columns include `alias`, `samplingInterval`, `queueSize`, `deadbandType`, and `deadbandValue`.
 
 ```csv
 nodeId,value,dataType
@@ -67,6 +80,29 @@ ns=2;s=Line1.Speed,1200,Double
 ns=2;s=Line1.Enabled,true,Boolean
 ```
 
+## Arrays and IndexRange
+
+Read and Write descriptors accept the standard OPC UA `indexRange` field. The
+legacy `range` spelling is normalized to `indexRange`. One-dimensional examples
+are `0` and `2:5`; matrix ranges use a comma, for example `0:1,2:3`. Invalid or
+descending ranges are rejected before an OPC UA service call.
+
+Write values may be scalar JavaScript values, arrays, or rectangular nested
+arrays. Nested arrays are converted to OPC UA matrix dimensions; ragged or empty
+arrays are rejected. A direct array payload is treated as the value when the
+message or Write node identifies one target NodeId. A configured single
+`useInput` point behaves the same way. Set `msg.opcua.pointList = true` only when
+an array payload must be forced to mean a dynamic list of point descriptors.
+
+```json
+{
+  "topic": "ns=2;s=Recipe.Steps",
+  "indexRange": "4:6",
+  "dataType": "Double",
+  "payload": [12.5, 13.0, 13.5]
+}
+```
+
 An incoming point list takes priority over the point list saved in the node. Existing flows that stored a single static NodeId are migrated into the visible list when their editor is opened. A migrated Write item keeps using its incoming `msg.payload`; imported Write rows normally carry `nodeId`, `value`, and optional `dataType`.
 
 ## Browse tree selection
@@ -77,20 +113,73 @@ The selected Variable descriptors are saved with the Browse node. Each input mes
 
 Node editors show only the standard settings by default. Connection security/timeouts/cache, Browse limits/paging, Read/Write batching/output, and Subscribe queue/deadband tuning remain available under a closed **Advanced settings** section. Existing flows retain their stored advanced values.
 
-## Build
+## Secure connections
+
+Connection nodes support `None/None` and `Sign` or `SignAndEncrypt` with
+`Basic256Sha256`. Secure connections require a client certificate, its private
+key, and at least one trusted Server or CA certificate. Trust is strict: an
+empty trust list is rejected instead of silently accepting every Server
+certificate. Optional CRL files can be supplied as a newline-separated list.
+Password-protected PEM private keys use the separate Node-RED credential field,
+so the password is not stored in the normal Flow configuration.
+
+The client Application URI can be configured when the URI embedded in the
+client certificate differs from the open62541 default. Username authentication
+uses the selected secure endpoint and its advertised UserTokenPolicy.
+
+The Connection editor can call `GetEndpoints`, filters the response to the
+implemented policies, and selects an endpoint compatible with Anonymous or
+Username authentication. Certificate, private-key, trust-list, and CRL entries
+are filesystem paths visible to the Node-RED runtime.
+
+## Offline installation
+
+The published package contains a prebuilt `linux-x64-musl` native addon for the
+Node-RED Alpine image, the pinned open62541 v1.4.16 source archive, and its
+`node-addon-api` build dependency. The same Node-API binary is verified on Node
+20.19.6 and Node 22.22.2. Installing the tarball on the supported target does
+not contact npm or GitHub and does not invoke a compiler:
 
-Linux build prerequisites are a C/C++ compiler, CMake, Python, and Git.
+```bash
+npm install ./tier0-opcua-client-0.1.0.tgz --offline
+```
+
+The loader uses the bundled native addon directly. Set
+`OPCUA_CLIENT_FORCE_BUILD=1` only to force a source rebuild. Unsupported
+platforms fall back to the bundled open62541 source and therefore still require
+a local C/C++ toolchain, CMake, Python, Node headers, and OpenSSL development
+files. No network is needed for open62541 itself.
+
+Create the supported prebuild and package on Linux with:
+
+```bash
+npm ci --ignore-scripts
+npm run build:offline-prebuild -- --nodedir=/usr/local
+npm pack
+```
+
+See `THIRD_PARTY_NOTICES.md` for the bundled open62541 and node-addon-api
+licenses.
+
+## Source build
+
+Linux build prerequisites are a C/C++ compiler, CMake, Python, Git, and the
+OpenSSL development package.
 
 ```bash
 npm install
 npm test
 ```
 
-`npm install` builds the pinned open62541 release first and then compiles the N-API addon. To rebuild only the native layer after changing C++ code, run `npm run build`.
+When no compatible prebuild is available, `npm install` builds the bundled
+open62541 release and then compiles the N-API addon. To rebuild only the native
+layer after changing C++ code, run `npm run build`.
 
 The open62541 build is static and position-independent so the resulting N-API addon does not need a runtime open62541 shared library.
 
-Security mode `None` is supported in the first implementation slice. Sign and SignAndEncrypt are visible in the connection model but require an encryption-enabled open62541 build and certificate trust-store integration before production use.
+The pinned open62541 build uses its OpenSSL encryption backend. The initial
+secure policy scope intentionally excludes deprecated Basic128Rsa15 and
+Basic256 policies.
 
 ## Native integration test
 
@@ -102,9 +191,34 @@ python3 -m venv .build/test-venv
 PATH="$PWD/.build/test-venv/bin:$PATH" npm run test:native
 ```
 
+The Python fixture is used for the general native suite but does not implement
+OPC UA IndexRange semantics. Build the included open62541 test Server to verify
+real partial array reads and writes:
+
+```bash
+npm run build:test-server
+OPCUA_TEST_SERVER_BINARY="$PWD/build/open62541-test-server" \
+node test/native.integration.js
+```
+
+Run the secure integration test against a real Server after placing its
+certificate in the trust list:
+
+```bash
+OPCUA_SECURE_ENDPOINT=opc.tcp://server:4840 \
+OPCUA_CLIENT_CERTIFICATE=/pki/client.der \
+OPCUA_CLIENT_PRIVATE_KEY=/pki/client-key.pem \
+OPCUA_TRUSTED_CERTIFICATES=/pki/server.der \
+npm run test:secure
+```
+
+Set `OPCUA_USERNAME` and `OPCUA_PASSWORD` when the selected Endpoint uses a
+Username identity token. `OPCUA_CLIENT_APPLICATION_URI` must match the URI in
+the client certificate when it differs from the default.
+
 ## Stress test
 
-The stress test starts a real writable OPC UA server, browses the complete address space, performs repeated batched reads and writes, creates one Subscription containing all MonitoredItems, verifies change delivery for every point, and reports latency, throughput, memory, CPU, and event-loop delay.
+The stress test starts a real writable OPC UA server, browses the complete address space, performs repeated batched reads and writes, creates subscriptions containing all MonitoredItems, verifies change delivery for every point, and reports latency, throughput, memory, CPU, and event-loop delay.
 
 ```bash
 OPCUA_STRESS_POINTS=5000 \
@@ -127,7 +241,7 @@ To inject a real server outage after subscription creation, restart the fixture,
 OPCUA_NODERED_POINTS=1000 npm run test:nodered:reconnect
 ```
 
-See [BENCHMARK.md](BENCHMARK.md) for the recorded 1,000, 5,000, sustained 5,000, and 10,000 point baselines.
+See [BENCHMARK.md](BENCHMARK.md) for the recorded 1,000, 5,000, 10,000, and sustained 20,000 point baselines.
 
 ## Scale defaults
 
@@ -135,7 +249,10 @@ See [BENCHMARK.md](BENCHMARK.md) for the recorded 1,000, 5,000, sustained 5,000,
 - Attribute read batch: 200 points.
 - Read/Write service batch: 500 points.
 - MonitoredItem creation batch: 500 points.
+- Subscription capacity fallback: 5,000 MonitoredItems (automatically reduced by the server limit).
+- Node-RED batch flush: 500 changes or 50 ms.
 - Subscription callback queue: 10,000 pending changes.
 - Parsed NodeId cache: 100,000 entries per connection.
+- Native command queue: 256 pending commands per connection.
 
 Configured service batches are automatically clamped to the server's advertised OperationLimits.

package/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,20 @@
+# Third-party notices
+
+## open62541
+
+This package contains open62541 v1.4.16 in source and executable form.
+open62541 is licensed under the Mozilla Public License 2.0.
+
+- Project: https://github.com/open62541/open62541
+- Source version: https://github.com/open62541/open62541/tree/v1.4.16
+- License copy: `vendor/open62541-LICENSE`
+- Bundled source: `vendor/open62541-v1.4.16.tar.gz`
+
+The open62541 source is not modified by this package. The native Node.js addon
+links the open62541 static library with this package's separate C++ binding.
+
+## node-addon-api
+
+This package bundles node-addon-api for offline source-build fallback.
+node-addon-api is licensed under the MIT License; its package includes its own
+license file.

package/binding.gyp

@@ -17,7 +17,7 @@
       "cflags_cc!": ["-fno-exceptions"],
       "cflags_cc": ["-std=c++20"],
       "conditions": [
-        ["OS=='linux'", {"libraries": ["-lpthread", "-lm"]}]
+        ["OS=='linux'", {"libraries": ["-lpthread", "-lm", "-lssl", "-lcrypto"]}]
       ]
     }
   ]

package/lib/client.js

@@ -3,6 +3,7 @@
 const { EventEmitter } = require('events');
 const { chunks } = require('./points');
 const { loadAddon } = require('./native');
+const { normalizeConnectionOptions } = require('./security');
 
 function normalizeNotificationBatch(notification) {
   if (notification && Array.isArray(notification.changes)) {
@@ -31,6 +32,7 @@ class OpcUaClient extends EventEmitter {
     this.options = { ...options };
     this.handle = null;
     this.connecting = null;
+    this.replacing = null;
     this.closed = false;
     this.connectionState = 'idle';
     this.connectionToken = 0;
@@ -58,6 +60,11 @@ class OpcUaClient extends EventEmitter {
 
   async connect() {
     if (this.closed) throw new Error('OPC UA client is closed');
+    if (this.replacing) {
+      const error = new Error('OPC UA client is replacing a failed connection');
+      error.code = 'OPCUA_RECONNECTING';
+      throw error;
+    }
     if (this.handle != null) {
       if (this.connectionState === 'connected') return this.handle;
       const error = new Error(`OPC UA client is ${this.connectionState}`);
@@ -78,13 +85,14 @@ class OpcUaClient extends EventEmitter {
   }
 
   async #connect() {
+    const options = normalizeConnectionOptions(this.options);
     const addon = loadAddon();
     const token = ++this.connectionToken;
     this.connectionState = 'connecting';
     let handle;
     try {
       handle = await addon.connectAsync(
-        this.options,
+        options,
         (state) => this.#onNativeState(token, state)
       );
     } catch (error) {
@@ -138,6 +146,10 @@ class OpcUaClient extends EventEmitter {
     if (connecting) {
       try { await connecting; } catch {}
     }
+    const replacing = this.replacing;
+    if (replacing) {
+      try { await replacing; } catch {}
+    }
     const handle = this.handle;
     this.handle = null;
     if (handle != null) {
@@ -258,8 +270,17 @@ class OpcUaClient extends EventEmitter {
     if (state.connected) {
       this.reconnectAttempt = 0;
       this.#refreshDiagnostics();
-    } else if (state.terminal) {
-      void this.#replaceTerminalClient(token, state);
+    } else if (state.terminal && !this.replacing) {
+      const replacing = this.#replaceTerminalClient(token, state);
+      this.replacing = replacing;
+      void replacing.then(
+        () => {
+          if (this.replacing === replacing) this.replacing = null;
+        },
+        () => {
+          if (this.replacing === replacing) this.replacing = null;
+        }
+      );
     }
   }
 
@@ -268,12 +289,13 @@ class OpcUaClient extends EventEmitter {
     this.connectionToken += 1;
     this.supervisorDiagnostics.terminalReplacements += 1;
     const handle = this.handle;
-    this.handle = null;
-    this.connectionState = 'failed';
+    this.connectionState = 'replacing';
     if (handle != null) {
       try { await loadAddon().disconnectAsync(handle); } catch {}
     }
+    if (this.handle === handle) this.handle = null;
     if (!this.closed) {
+      this.connectionState = 'failed';
       const error = new Error(`OPC UA connection failed: ${state.statusCode || 'Unknown'}`);
       error.code = 'OPCUA_CONNECTION_FAILED';
       this.emit('fault', error);
@@ -282,7 +304,7 @@ class OpcUaClient extends EventEmitter {
   }
 
   #scheduleReconnect() {
-    if (this.closed || this.reconnectTimer || this.connecting) return;
+    if (this.closed || this.handle != null || this.reconnectTimer || this.connecting) return;
     const base = Math.max(100, Number(this.options.reconnectInterval) || 5000);
     const maximum = Math.max(base, Number(this.options.maxReconnectInterval) || 30000);
     const exponential = Math.min(maximum, base * (2 ** this.reconnectAttempt));
@@ -318,4 +340,23 @@ class OpcUaClient extends EventEmitter {
   }
 }
 
-module.exports = { OpcUaClient, effectiveBatchSize, normalizeNotificationBatch };
+async function discoverEndpoints(options) {
+  const source = typeof options === 'string' ? { endpoint: options } : { ...options };
+  const endpoint = String(source.endpoint || '').trim();
+  if (!endpoint) {
+    const error = new Error('OPC UA endpoint is required');
+    error.code = 'OPCUA_INVALID_SECURITY_CONFIGURATION';
+    throw error;
+  }
+  return loadAddon().discoverEndpointsAsync({
+    endpoint,
+    requestTimeout: Number(source.requestTimeout) || 10000,
+  });
+}
+
+module.exports = {
+  OpcUaClient,
+  discoverEndpoints,
+  effectiveBatchSize,
+  normalizeNotificationBatch,
+};

package/lib/native.js

@@ -1,5 +1,8 @@
 'use strict';
 
+const path = require('node:path');
+const { prebuildKey, resolvePrebuilt } = require('./prebuild');
+
 let injectedAddon;
 let loadedAddon;
 
@@ -7,17 +10,29 @@ function loadAddon() {
   if (injectedAddon) return injectedAddon;
   if (loadedAddon) return loadedAddon;
 
-  try {
-    loadedAddon = require('../build/Release/opcua_open62541.node');
-    return loadedAddon;
-  } catch (error) {
-    const wrapped = new Error(
-      `Native open62541 addon is unavailable: ${error.message}. ` +
-      'Run npm run build:open62541 && npm run build.'
-    );
-    wrapped.cause = error;
-    throw wrapped;
+  const packageRoot = path.resolve(__dirname, '..');
+  const candidates = [
+    process.env.OPCUA_OPEN62541_ADDON,
+    resolvePrebuilt(packageRoot),
+    path.join(packageRoot, 'build', 'Release', 'opcua_open62541.node'),
+  ].filter(Boolean);
+  let lastError;
+  for (const candidate of candidates) {
+    try {
+      loadedAddon = require(candidate);
+      return loadedAddon;
+    } catch (error) {
+      lastError = error;
+    }
   }
+
+  const wrapped = new Error(
+    `Native open62541 addon is unavailable for ${prebuildKey()}: ` +
+    `${lastError?.message || 'no addon candidate found'}. ` +
+    'Run npm run build:offline-prebuild to build this platform.'
+  );
+  wrapped.cause = lastError;
+  throw wrapped;
 }
 
 function setAddonForTests(addon) {