@tier0/opcua-client 0.1.0 → 0.4.0

package/nodes/connection.html

@@ -2,27 +2,76 @@
   .opcua-advanced { margin: 8px 0 12px; }
   .opcua-advanced summary { cursor: pointer; font-weight: 600; padding: 6px 0; }
   .opcua-standard-note { margin: 0 0 10px 105px; color: var(--red-ui-form-text-color, #666); font-size: 0.9em; }
+  .opcua-discovery-result { margin: 6px 0 8px 105px; max-width: 70%; }
+  .opcua-discovery-result select { width: 100%; }
+  .opcua-security-path { width: calc(70% - 88px) !important; }
+  .opcua-security-list { display: inline-block; width: 70%; vertical-align: top; }
+  .opcua-security-list textarea { width: 100%; box-sizing: border-box; }
+  .opcua-security-upload { margin-top: 4px; }
+  .opcua-hidden-file { display: none !important; }
 </style>
 <script type="text/html" data-template-name="tier0-opcua-connection">
   <div class="form-row"><label for="node-config-input-endpoint">Endpoint</label><input type="text" id="node-config-input-endpoint" placeholder="opc.tcp://127.0.0.1:4840"></div>
+  <div class="form-row"><label></label><button type="button" class="red-ui-button" id="node-config-input-discoverEndpoints">Discover endpoints</button> <button type="button" class="red-ui-button" id="node-config-input-testConnection">Test connection</button></div>
+  <div class="opcua-discovery-result" id="node-config-input-discoveryResult" style="display:none"><select id="node-config-input-discoveredEndpoint"></select></div>
+  <div class="opcua-standard-note" id="node-config-input-testResult"></div>
   <div class="form-row"><label for="node-config-input-securityMode">Security</label><select id="node-config-input-securityMode"><option value="None">None</option><option value="Sign">Sign</option><option value="SignAndEncrypt">SignAndEncrypt</option></select></div>
-  <div class="opcua-standard-note">Standard defaults include automatic reconnect, connectivity checks, and a bounded NodeId cache.</div>
+  <div class="opcua-standard-note">Standard defaults include automatic reconnect, connectivity checks, and bounded command/NodeId queues.</div>
   <details class="opcua-advanced">
     <summary>Security and advanced connection settings</summary>
-    <div class="form-row"><label for="node-config-input-securityPolicy">Policy</label><select id="node-config-input-securityPolicy"><option value="None">None</option><option value="Basic256Sha256">Basic256Sha256</option><option value="Aes128Sha256RsaOaep">Aes128Sha256RsaOaep</option><option value="Aes256Sha256RsaPss">Aes256Sha256RsaPss</option></select></div>
+    <div class="form-row"><label for="node-config-input-securityPolicy">Policy</label><select id="node-config-input-securityPolicy"><option value="None">None</option><option value="Basic256Sha256">Basic256Sha256</option></select></div>
     <div class="form-row"><label for="node-config-input-user">User</label><input type="text" id="node-config-input-user"></div>
     <div class="form-row"><label for="node-config-input-password">Password</label><input type="password" id="node-config-input-password"></div>
-    <div class="form-row"><label for="node-config-input-certificate">Certificate</label><input type="text" id="node-config-input-certificate"></div>
-    <div class="form-row"><label for="node-config-input-privateKey">Private key</label><input type="text" id="node-config-input-privateKey"></div>
+    <div class="form-row opcua-secure-field"><label for="node-config-input-certificate">Client certificate</label><input type="text" class="opcua-security-path" id="node-config-input-certificate" placeholder="Upload or enter /path/to/client.der"> <button type="button" class="red-ui-button" id="node-config-upload-certificate"><i class="fa fa-upload"></i> Upload</button><input type="file" class="opcua-hidden-file" id="node-config-file-certificate" accept=".der,.pem,.crt,.cer"></div>
+    <div class="form-row opcua-secure-field"><label for="node-config-input-privateKey">Client private key</label><input type="text" class="opcua-security-path" id="node-config-input-privateKey" placeholder="Upload or enter /path/to/client-key.pem"> <button type="button" class="red-ui-button" id="node-config-upload-privateKey"><i class="fa fa-upload"></i> Upload</button><input type="file" class="opcua-hidden-file" id="node-config-file-privateKey" accept=".der,.pem,.key"></div>
+    <div class="form-row opcua-secure-field"><label for="node-config-input-privateKeyPassword">Key password</label><input type="password" id="node-config-input-privateKeyPassword"></div>
+    <div class="form-row opcua-secure-field"><label for="node-config-input-applicationUri">Application URI</label><input type="text" id="node-config-input-applicationUri" placeholder="Must match the client certificate"></div>
+    <div class="form-row opcua-secure-field"><label for="node-config-input-trustedCertificates">Trusted certificates</label><div class="opcua-security-list"><textarea id="node-config-input-trustedCertificates" rows="3" placeholder="Upload files or enter one Server/CA path per line"></textarea><button type="button" class="red-ui-button opcua-security-upload" id="node-config-upload-trustedCertificates"><i class="fa fa-upload"></i> Upload files</button><input type="file" multiple class="opcua-hidden-file" id="node-config-file-trustedCertificates" accept=".der,.pem,.crt,.cer"></div></div>
+    <div class="form-row opcua-secure-field"><label for="node-config-input-revocationList">Revocation list</label><div class="opcua-security-list"><textarea id="node-config-input-revocationList" rows="2" placeholder="Upload files or enter one optional CRL path per line"></textarea><button type="button" class="red-ui-button opcua-security-upload" id="node-config-upload-revocationList"><i class="fa fa-upload"></i> Upload files</button><input type="file" multiple class="opcua-hidden-file" id="node-config-file-revocationList" accept=".der,.pem,.crl"></div></div>
+    <div class="opcua-standard-note opcua-secure-field">Uploaded files are stored under the Node-RED user directory. Runtime-visible paths may still be entered directly.</div>
     <div class="form-row"><label for="node-config-input-requestedSessionTimeout">Session timeout</label><input type="number" id="node-config-input-requestedSessionTimeout"></div>
     <div class="form-row"><label for="node-config-input-requestTimeout">Request timeout</label><input type="number" id="node-config-input-requestTimeout"></div>
     <div class="form-row"><label for="node-config-input-connectivityCheckInterval">Connectivity check</label><input type="number" id="node-config-input-connectivityCheckInterval"></div>
     <div class="form-row"><label for="node-config-input-reconnectInterval">Reconnect interval</label><input type="number" id="node-config-input-reconnectInterval"></div>
     <div class="form-row"><label for="node-config-input-maxReconnectInterval">Max reconnect</label><input type="number" id="node-config-input-maxReconnectInterval"></div>
     <div class="form-row"><label for="node-config-input-nodeIdCacheSize">NodeId cache</label><input type="number" id="node-config-input-nodeIdCacheSize"></div>
+    <div class="form-row"><label for="node-config-input-commandQueueSize">Command queue</label><input type="number" id="node-config-input-commandQueueSize"></div>
+    <div class="form-row"><label for="node-config-input-allowParallelSession">Parallel Session</label><input type="checkbox" id="node-config-input-allowParallelSession" style="width:auto"></div>
+    <div class="opcua-standard-note">Leave disabled and reuse one Connection configuration for one Session. Enable only when a separate Session with equivalent settings is intentional.</div>
   </details>
   <div class="form-row"><label for="node-config-input-name">Name</label><input type="text" id="node-config-input-name"></div>
 </script>
+<script type="text/html" data-help-name="tier0-opcua-connection">
+  <section lang="zh-CN">
+    <h3>连接（Connection）</h3>
+    <p>创建并维护共享的 OPC UA SecureChannel 和 Session，供 Browse、Read、Write、Subscribe 节点复用。配置节点本身没有消息输入或输出。</p>
+    <h4>主要配置</h4>
+    <ul>
+      <li><b>Endpoint</b>：服务器地址，例如 <code>opc.tcp://192.168.1.10:4840</code>。</li>
+      <li><b>Discover endpoints</b>：读取服务器公开的安全模式、安全策略和用户认证方式。</li>
+      <li><b>Test connection</b>：使用当前配置建立临时连接并验证认证。</li>
+      <li><b>Security</b>：支持 None、Sign、SignAndEncrypt；安全模式、策略和认证方式必须与服务器 Endpoint 匹配。</li>
+      <li><b>证书</b>：安全连接可上传或指定客户端证书、私钥、信任证书和 CRL。Application URI 应与客户端证书一致。</li>
+    </ul>
+    <h4>建议</h4>
+    <p>一个 Connection 配置对应一条客户端 Session。多个业务节点应复用同一个 Connection，避免为相同 Endpoint 重复创建 Session。节点内置自动重连、连通性检查以及有界命令队列。</p>
+  </section>
+  <hr>
+  <section lang="en">
+    <h3>Connection</h3>
+    <p>Creates and maintains a shared OPC UA SecureChannel and Session for Browse, Read, Write, and Subscribe nodes. The configuration node itself has no message input or output.</p>
+    <h4>Main settings</h4>
+    <ul>
+      <li><b>Endpoint</b>: Server URL, for example <code>opc.tcp://192.168.1.10:4840</code>.</li>
+      <li><b>Discover endpoints</b>: Reads advertised security modes, policies, and user token types.</li>
+      <li><b>Test connection</b>: Opens a temporary connection with the current settings and validates authentication.</li>
+      <li><b>Security</b>: Supports None, Sign, and SignAndEncrypt. Mode, policy, and identity must match an advertised endpoint.</li>
+      <li><b>Certificates</b>: Secure connections can upload or reference a client certificate, private key, trust list, and CRLs. The Application URI should match the client certificate.</li>
+    </ul>
+    <h4>Recommendation</h4>
+    <p>One Connection configuration owns one client Session. Reuse it across nodes targeting the same server instead of creating duplicate Sessions. Automatic reconnect, connectivity checks, and a bounded command queue are enabled.</p>
+  </section>
+</script>
 <script type="text/javascript">
   RED.nodes.registerType('tier0-opcua-connection', {
     category: 'config',
@@ -30,15 +79,253 @@
       endpoint: { value: '', required: true },
       securityMode: { value: 'None' }, securityPolicy: { value: 'None' },
       user: { value: '' }, certificate: { value: '' }, privateKey: { value: '' },
+      applicationUri: { value: '' }, trustedCertificates: { value: '' }, revocationList: { value: '' },
       requestedSessionTimeout: { value: 60000, validate: RED.validators.number() },
       requestTimeout: { value: 10000, validate: RED.validators.number() },
       connectivityCheckInterval: { value: 5000, validate: RED.validators.number() },
       reconnectInterval: { value: 5000, validate: RED.validators.number() },
       maxReconnectInterval: { value: 30000, validate: RED.validators.number() },
       nodeIdCacheSize: { value: 100000, validate: RED.validators.number() },
+      commandQueueSize: { value: 256, validate: RED.validators.number() },
+      allowParallelSession: { value: false },
       name: { value: '' }
     },
-    credentials: { password: { type: 'password' } },
-    label: function () { return this.name || this.endpoint || 'tier0-opcua-connection'; }
+    credentials: {
+      password: { type: 'password' },
+      privateKeyPassword: { type: 'password' }
+    },
+    label: function () { return this.name || this.endpoint || 'tier0-opcua-connection'; },
+    oneditprepare: function () {
+      const connectionId = this.id;
+      const mode = $('#node-config-input-securityMode');
+      const policy = $('#node-config-input-securityPolicy');
+      const result = $('#node-config-input-discoveryResult');
+      const discovered = $('#node-config-input-discoveredEndpoint');
+      const policyName = function (uri) {
+        return String(uri || '').split('#').pop() || 'None';
+      };
+      const updateSecurityFields = function () {
+        const secure = mode.val() !== 'None';
+        $('.opcua-secure-field').toggle(secure);
+        if (!secure) policy.val('None');
+        else if (policy.val() === 'None') policy.val('Basic256Sha256');
+      };
+      mode.on('change', updateSecurityFields);
+      updateSecurityFields();
+
+      const maxSecurityFileSize = 2 * 1024 * 1024;
+      const uploadSecurityFile = function (file, kind) {
+        return new Promise(function (resolve, reject) {
+          if (!connectionId) {
+            reject(new Error('Save the Connection node once before uploading security files'));
+            return;
+          }
+          if (file.size > maxSecurityFileSize) {
+            reject(new Error(`${file.name} exceeds the 2 MiB security file limit`));
+            return;
+          }
+          const reader = new FileReader();
+          reader.onerror = function () {
+            reject(new Error(`Cannot read ${file.name}`));
+          };
+          reader.onload = function () {
+            const encoded = String(reader.result || '');
+            const separator = encoded.indexOf(',');
+            if (separator < 0) {
+              reject(new Error(`Cannot encode ${file.name}`));
+              return;
+            }
+            $.ajax({
+              url: 'opcua-client/security-files',
+              method: 'POST',
+              contentType: 'application/json',
+              data: JSON.stringify({
+                connectionId,
+                kind,
+                fileName: file.name,
+                contentBase64: encoded.slice(separator + 1)
+              })
+            }).done(function (response) {
+              resolve(response.file);
+            }).fail(function (xhr) {
+              reject(new Error(xhr.responseJSON?.error || `Cannot upload ${file.name}`));
+            });
+          };
+          reader.readAsDataURL(file);
+        });
+      };
+
+      const bindSecurityUpload = function (buttonSelector, fileSelector, targetSelector, kind, append) {
+        const button = $(buttonSelector);
+        const fileInput = $(fileSelector);
+        const target = $(targetSelector);
+        button.on('click', function () { fileInput.trigger('click'); });
+        fileInput.on('change', function () {
+          const input = this;
+          const files = Array.from(input.files || []);
+          if (!files.length) return;
+          button.prop('disabled', true);
+          files.reduce(function (chain, file) {
+            return chain.then(function () {
+              return uploadSecurityFile(file, kind);
+            }).then(function (uploaded) {
+              if (!append) {
+                target.val(uploaded.path);
+                return;
+              }
+              const paths = String(target.val() || '').split(/\r?\n|;/)
+                .map(function (entry) { return entry.trim(); })
+                .filter(Boolean);
+              if (paths.indexOf(uploaded.path) < 0) paths.push(uploaded.path);
+              target.val(paths.join('\n'));
+            });
+          }, Promise.resolve()).then(function () {
+            RED.notify(`${files.length} OPC UA security file(s) uploaded`, 'success');
+          }).catch(function (error) {
+            RED.notify(error.message || String(error), 'error');
+          }).then(function () {
+            input.value = '';
+            button.prop('disabled', false);
+          });
+        });
+      };
+
+      bindSecurityUpload('#node-config-upload-certificate', '#node-config-file-certificate',
+        '#node-config-input-certificate', 'clientCertificate', false);
+      bindSecurityUpload('#node-config-upload-privateKey', '#node-config-file-privateKey',
+        '#node-config-input-privateKey', 'privateKey', false);
+      bindSecurityUpload('#node-config-upload-trustedCertificates',
+        '#node-config-file-trustedCertificates', '#node-config-input-trustedCertificates',
+        'trustedCertificate', true);
+      bindSecurityUpload('#node-config-upload-revocationList',
+        '#node-config-file-revocationList', '#node-config-input-revocationList',
+        'revocationList', true);
+
+      const connectionSettings = function () {
+        return {
+          connectionId,
+          endpoint: String($('#node-config-input-endpoint').val() || '').trim(),
+          securityMode: mode.val(),
+          securityPolicy: policy.val(),
+          user: $('#node-config-input-user').val(),
+          password: $('#node-config-input-password').val(),
+          certificate: $('#node-config-input-certificate').val(),
+          privateKey: $('#node-config-input-privateKey').val(),
+          privateKeyPassword: $('#node-config-input-privateKeyPassword').val(),
+          applicationUri: $('#node-config-input-applicationUri').val(),
+          trustedCertificates: $('#node-config-input-trustedCertificates').val(),
+          revocationList: $('#node-config-input-revocationList').val(),
+          requestedSessionTimeout: $('#node-config-input-requestedSessionTimeout').val(),
+          requestTimeout: $('#node-config-input-requestTimeout').val(),
+          connectivityCheckInterval: $('#node-config-input-connectivityCheckInterval').val(),
+          reconnectInterval: $('#node-config-input-reconnectInterval').val(),
+          maxReconnectInterval: $('#node-config-input-maxReconnectInterval').val(),
+          nodeIdCacheSize: $('#node-config-input-nodeIdCacheSize').val(),
+          commandQueueSize: $('#node-config-input-commandQueueSize').val()
+        };
+      };
+
+      $('#node-config-input-discoverEndpoints').on('click', function () {
+        const button = $(this);
+        const endpoint = String($('#node-config-input-endpoint').val() || '').trim();
+        if (!endpoint) {
+          RED.notify('Enter an OPC UA endpoint first', 'warning');
+          return;
+        }
+        button.prop('disabled', true).text('Discovering...');
+        $.ajax({
+          url: 'opcua-client/endpoints',
+          method: 'POST',
+          contentType: 'application/json',
+          data: JSON.stringify({
+            endpoint,
+            requestTimeout: Number($('#node-config-input-requestTimeout').val()) || 10000
+          })
+        }).done(function (response) {
+          const allEndpoints = Array.isArray(response.endpoints) ? response.endpoints : [];
+          const identityType = String($('#node-config-input-user').val() || '').trim()
+            ? 'Username' : 'Anonymous';
+          const supported = allEndpoints.filter(function (item) {
+            const itemPolicy = policyName(item.securityPolicyUri);
+            return itemPolicy === 'None' || itemPolicy === 'Basic256Sha256';
+          });
+          const matchingIdentity = supported.filter(function (item) {
+            return (item.userIdentityTokens || []).some(function (token) {
+              return token.tokenType === identityType;
+            });
+          });
+          const endpoints = matchingIdentity.length ? matchingIdentity : supported;
+          discovered.empty();
+          endpoints.sort(function (left, right) {
+            return Number(right.securityLevel || 0) - Number(left.securityLevel || 0);
+          }).forEach(function (item, index) {
+            const identities = (item.userIdentityTokens || []).map(function (token) {
+              return token.tokenType;
+            }).filter(function (value, tokenIndex, values) {
+              return values.indexOf(value) === tokenIndex;
+            }).join(', ');
+            $('<option></option>')
+              .val(String(index))
+              .text(`${item.securityMode} / ${policyName(item.securityPolicyUri)} / ${identities || 'No identity token'}`)
+              .data('endpoint', item)
+              .appendTo(discovered);
+          });
+          if (!endpoints.length) {
+            RED.notify('The server returned no supported None or Basic256Sha256 endpoint', 'warning');
+            result.hide();
+            return;
+          }
+          if (!matchingIdentity.length) {
+            RED.notify(`No endpoint advertises ${identityType}; showing other supported endpoints`, 'warning');
+          }
+          result.show();
+          discovered.trigger('change');
+        }).fail(function (xhr) {
+          RED.notify(xhr.responseJSON?.error || 'Endpoint discovery failed', 'error');
+          result.hide();
+        }).always(function () {
+          button.prop('disabled', false).text('Discover endpoints');
+        });
+      });
+
+      discovered.on('change', function () {
+        const selected = discovered.find(':selected').data('endpoint');
+        if (!selected) return;
+        const selectedPolicy = policyName(selected.securityPolicyUri);
+        mode.val(selected.securityMode);
+        if (selectedPolicy === 'None' || selectedPolicy === 'Basic256Sha256') {
+          policy.val(selectedPolicy);
+        }
+        updateSecurityFields();
+      });
+
+      $('#node-config-input-testConnection').on('click', function () {
+        const button = $(this);
+        const testResult = $('#node-config-input-testResult');
+        const settings = connectionSettings();
+        if (!settings.endpoint) {
+          RED.notify('Enter an OPC UA endpoint first', 'warning');
+          return;
+        }
+        button.prop('disabled', true).text('Testing...');
+        testResult.text('');
+        $.ajax({
+          url: 'opcua-client/test-connection',
+          method: 'POST',
+          contentType: 'application/json',
+          data: JSON.stringify(settings)
+        }).done(function (response) {
+          const connection = response.connection || {};
+          testResult.text(`Connected: ${connection.securityMode || settings.securityMode} / ${policyName(connection.securityPolicyUri)}`);
+          RED.notify('OPC UA connection test succeeded', 'success');
+        }).fail(function (xhr) {
+          const message = xhr.responseJSON?.error || 'OPC UA connection test failed';
+          testResult.text(message);
+          RED.notify(message, 'error');
+        }).always(function () {
+          button.prop('disabled', false).text('Test connection');
+        });
+      });
+    }
   });
 </script>

package/nodes/connection.js

@@ -1,42 +1,178 @@
 'use strict';
 
-const { OpcUaClient } = require('../lib/client');
+const { OpcUaClient, discoverEndpoints } = require('../lib/client');
+const { ConnectionRegistry } = require('../lib/connection-registry');
+const { SecurityFileStore } = require('../lib/security-file-store');
+
+function pathList(value) {
+  const source = Array.isArray(value) ? value : String(value || '').split(/\r?\n|;/);
+  return source.map((entry) => String(entry || '').trim()).filter(Boolean);
+}
+
+function clientOptions(config, credentials = {}) {
+  return {
+    endpoint: config.endpoint,
+    securityMode: config.securityMode || 'None',
+    securityPolicy: config.securityPolicy || 'None',
+    user: config.user || '',
+    password: credentials.password || '',
+    certificate: config.certificate || '',
+    privateKey: config.privateKey || '',
+    privateKeyPassword: credentials.privateKeyPassword || '',
+    applicationUri: config.applicationUri || '',
+    trustedCertificates: pathList(config.trustedCertificates),
+    revocationList: pathList(config.revocationList),
+    requestedSessionTimeout: Number(config.requestedSessionTimeout) || 60000,
+    requestTimeout: Number(config.requestTimeout) || 10000,
+    connectivityCheckInterval: Number.isFinite(Number(config.connectivityCheckInterval))
+      ? Math.max(0, Math.floor(Number(config.connectivityCheckInterval)))
+      : 5000,
+    reconnectInterval: Number(config.reconnectInterval) || 5000,
+    maxReconnectInterval: Number(config.maxReconnectInterval) || 30000,
+    nodeIdCacheSize: Number.isFinite(Number(config.nodeIdCacheSize))
+      ? Math.max(0, Math.floor(Number(config.nodeIdCacheSize)))
+      : 100000,
+    commandQueueSize: Number.isFinite(Number(config.commandQueueSize))
+      ? Math.max(1, Math.floor(Number(config.commandQueueSize)))
+      : 256,
+  };
+}
 
 module.exports = function registerConnectionNode(RED) {
+  const connectionRegistry = new ConnectionRegistry();
+  const securityFileStore = new SecurityFileStore({ userDir: RED.settings?.userDir });
+
+  RED.httpAdmin.post(
+    '/opcua-client/security-files',
+    RED.auth.needsPermission('opcua-client.security-files.write'),
+    async (req, res) => {
+      try {
+        const file = await securityFileStore.save(req.body || {});
+        res.send({ file });
+      } catch (error) {
+        const status = error?.code === 'OPCUA_SECURITY_FILE_TOO_LARGE'
+          ? 413
+          : String(error?.code || '').startsWith('OPCUA_SECURITY_FILE_') ? 400 : 500;
+        res.status(status).send({
+          error: error.message || String(error),
+          code: error.code || 'OPCUA_SECURITY_FILE_UPLOAD_FAILED',
+        });
+      }
+    }
+  );
+
+  RED.httpAdmin.post(
+    '/opcua-client/endpoints',
+    RED.auth.needsPermission('opcua-client.discovery'),
+    async (req, res) => {
+      try {
+        const endpoints = await discoverEndpoints({
+          endpoint: req.body?.endpoint,
+          requestTimeout: req.body?.requestTimeout,
+        });
+        res.send({ endpoints });
+      } catch (error) {
+        res.status(error?.code === 'OPCUA_RECONNECTING' ? 503 : 400).send({
+          error: error.message || String(error),
+          code: error.code || 'OPCUA_DISCOVERY_FAILED',
+        });
+      }
+    }
+  );
+
+  RED.httpAdmin.post(
+    '/opcua-client/test-connection',
+    RED.auth.needsPermission('opcua-client.test'),
+    async (req, res) => {
+      const body = req.body || {};
+      const deployed = body.connectionId ? RED.nodes.getNode(String(body.connectionId)) : null;
+      const deployedOptions = deployed?.client?.options || {};
+      const suppliedPassword = body.password && body.password !== '__PWRD__'
+        ? String(body.password) : deployedOptions.password;
+      const suppliedPrivateKeyPassword = body.privateKeyPassword &&
+        body.privateKeyPassword !== '__PWRD__'
+        ? String(body.privateKeyPassword) : deployedOptions.privateKeyPassword;
+      const options = {
+        ...deployedOptions,
+        ...clientOptions(body, {
+          password: suppliedPassword,
+          privateKeyPassword: suppliedPrivateKeyPassword,
+        }),
+      };
+      const client = new OpcUaClient(options);
+      client.on('fault', () => {});
+      try {
+        await client.connect();
+        const diagnostics = client.getDiagnostics();
+        const state = client.getState();
+        await client.disconnect();
+        res.send({
+          connected: true,
+          state,
+          connection: diagnostics.connection || {},
+          operationLimits: diagnostics.operationLimits || {},
+        });
+      } catch (error) {
+        try { await client.disconnect(); } catch {}
+        res.status(400).send({
+          connected: false,
+          error: error.message || String(error),
+          code: error.code || 'OPCUA_CONNECTION_TEST_FAILED',
+        });
+      }
+    }
+  );
+
   function OpcUaConnectionNode(config) {
     RED.nodes.createNode(this, config);
     const node = this;
 
-    node.client = new OpcUaClient({
-      endpoint: config.endpoint,
-      securityMode: config.securityMode || 'None',
-      securityPolicy: config.securityPolicy || 'None',
-      user: config.user || '',
-      password: node.credentials?.password || '',
-      certificate: config.certificate || '',
-      privateKey: config.privateKey || '',
-      requestedSessionTimeout: Number(config.requestedSessionTimeout) || 60000,
-      requestTimeout: Number(config.requestTimeout) || 10000,
-      connectivityCheckInterval: Number.isFinite(Number(config.connectivityCheckInterval))
-        ? Math.max(0, Math.floor(Number(config.connectivityCheckInterval)))
-        : 5000,
-      reconnectInterval: Number(config.reconnectInterval) || 5000,
-      maxReconnectInterval: Number(config.maxReconnectInterval) || 30000,
-      nodeIdCacheSize: Number.isFinite(Number(config.nodeIdCacheSize))
-        ? Math.max(0, Math.floor(Number(config.nodeIdCacheSize)))
-        : 100000,
+    const options = clientOptions(config, node.credentials);
+    const registration = connectionRegistry.register(options);
+    node.client = new OpcUaClient(options);
+    node.getConnectionGovernance = () => ({
+      ...registration.diagnostics(),
+      allowParallelSession: config.allowParallelSession === true,
     });
+    node.getDiagnostics = () => ({
+      ...node.client.getDiagnostics(),
+      connectionGovernance: node.getConnectionGovernance(),
+    });
+
+    if (registration.duplicate && config.allowParallelSession !== true) {
+      node.warn(
+        `Equivalent OPC UA Connection configuration detected for ${options.endpoint}; ` +
+        'this creates an additional Session. Reuse the existing Connection configuration ' +
+        'or enable "Allow parallel Session" when isolation is intentional.'
+      );
+    }
 
-    node.client.on('fault', (error) => node.warn(`OPC UA connection fault: ${error.message}`));
-    node.client.on('state', (state) => {
+    const onFault = (error) => node.warn(`OPC UA connection fault: ${error.message}`);
+    const onState = (state) => {
       if (state.state === 'failed') node.warn(`OPC UA connection failed: ${state.statusCode}`);
-    });
-    node.on('close', async (done) => {
+    };
+    node.client.on('fault', onFault);
+    node.client.on('state', onState);
+    node.on('close', async (removed, done) => {
+      if (typeof removed === 'function') {
+        done = removed;
+        removed = false;
+      }
+      node.client.off('fault', onFault);
+      node.client.off('state', onState);
+      registration.unregister();
       try {
         await node.client.disconnect();
       } catch (error) {
         node.warn(`OPC UA disconnect failed: ${error.message}`);
       }
+      if (removed) {
+        try {
+          await securityFileStore.removeConnection(config.id);
+        } catch (error) {
+          node.warn(`OPC UA managed security file cleanup failed: ${error.message}`);
+        }
+      }
       done();
     });
   }
@@ -44,6 +180,7 @@ module.exports = function registerConnectionNode(RED) {
   RED.nodes.registerType('tier0-opcua-connection', OpcUaConnectionNode, {
     credentials: {
       password: { type: 'password' },
+      privateKeyPassword: { type: 'password' },
     },
   });
 };

package/nodes/read.html

@@ -36,14 +36,51 @@
   </div>
   <details class="opcua-advanced">
     <summary>Advanced settings</summary>
+    <div class="form-row"><label for="node-input-indexRange">Index range</label><input type="text" id="node-input-indexRange" placeholder="For example 0:9 or 0:1,2:3"></div>
     <div class="form-row"><label for="node-input-batchSize">Batch size</label><input type="number" id="node-input-batchSize"></div>
     <div class="form-row"><label for="node-input-outputMode">Output</label><select id="node-input-outputMode"><option value="batch">Batch</option><option value="split">One message per point</option></select></div>
+    <div class="form-row"><label for="node-input-resultDetail">Result detail</label><select id="node-input-resultDetail"><option value="compact">Compact</option><option value="value">Value only</option><option value="full">Full metadata</option></select></div>
   </details>
   <div class="form-row"><label for="node-input-name">Name</label><input type="text" id="node-input-name"></div>
 </script>
 <script type="text/html" data-help-name="tier0-opcua-read">
-  <p>Add NodeIds to the point list or import JSON/CSV. Imported points are parsed and shown in the same list.</p>
-  <p>CSV requires a <code>nodeId</code> header. A JSON/CSV point list may also arrive dynamically in <code>msg.payload</code>.</p>
+  <section lang="zh-CN">
+    <h3>读取（Read）</h3>
+    <p>每收到一条输入消息执行一次 OPC UA Read。它不是定时器；读取频率由上游 Inject、Function 或其他节点的触发频率决定。</p>
+    <h4>输入</h4>
+    <ul>
+      <li>可在编辑器中添加 NodeId，或导入 JSON/CSV 点表；CSV 必须包含 <code>nodeId</code> 列。</li>
+      <li>也可通过 <code>msg.payload</code> 或 <code>msg.items</code> 动态传入点表。</li>
+      <li>单点读取可使用节点配置、<code>msg.nodeId</code> 或 <code>msg.topic</code>。</li>
+      <li><code>indexRange</code> 可读取数组或矩阵的指定范围。</li>
+    </ul>
+    <h4>输出</h4>
+    <ul>
+      <li><b>Compact</b>：NodeId/alias、值、状态码和源时间戳，推荐用于采集。</li>
+      <li><b>Value only</b>：批量时按点表顺序输出值数组，单点时输出标量。</li>
+      <li><b>Full metadata</b>：同时输出完整点表描述和客户端诊断，适合排障。</li>
+    </ul>
+    <p>大点表会按照 Batch size 和服务器 OperationLimits 自动拆分为批量服务请求，不会逐点建立连接。</p>
+  </section>
+  <hr>
+  <section lang="en">
+    <h3>Read</h3>
+    <p>Executes one OPC UA Read for each input message. It is not a timer; the upstream Inject, Function, or other node controls the read frequency.</p>
+    <h4>Input</h4>
+    <ul>
+      <li>Add NodeIds in the editor or import a JSON/CSV point list. CSV requires a <code>nodeId</code> column.</li>
+      <li>A dynamic point list may arrive in <code>msg.payload</code> or <code>msg.items</code>.</li>
+      <li>A single point may come from the node setting, <code>msg.nodeId</code>, or <code>msg.topic</code>.</li>
+      <li>Use <code>indexRange</code> to read part of an array or matrix.</li>
+    </ul>
+    <h4>Output</h4>
+    <ul>
+      <li><b>Compact</b>: NodeId/alias, value, status code, and source timestamp. Recommended for collection flows.</li>
+      <li><b>Value only</b>: A value array in point-list order for batch reads, or a scalar for one point.</li>
+      <li><b>Full metadata</b>: Full point descriptors and client diagnostics for troubleshooting.</li>
+    </ul>
+    <p>Large point lists are split according to Batch size and server OperationLimits. The node does not create one connection per point.</p>
+  </section>
 </script>
 <script type="text/javascript">
   RED.nodes.registerType('tier0-opcua-read', {
@@ -51,8 +88,10 @@
     defaults: {
       connection: { value: '', type: 'tier0-opcua-connection', required: true },
       nodeId: { value: '' }, pointList: { value: '' }, pointListFileName: { value: '' },
+      indexRange: { value: '' },
       batchSize: { value: 500, validate: RED.validators.number() },
-      outputMode: { value: 'batch' }, name: { value: '' }
+      outputMode: { value: 'batch' }, resultDetail: { value: 'compact' },
+      name: { value: '' }
     },
     oneditprepare: function () {
       const points = new Map();