Node-OPCUA Server Discovery

Common errors

• Error: Certificate validation failed for endpoint 'opc.tcp://localhost:4840'

  cause The client (or discovery server) does not trust the server's (or discovery server's) certificate, or the certificate's application URI/DNS name does not match the endpoint URL.
  fix Ensure the server's certificate is in the client's trusted certificates store, and vice versa. Verify that the `applicationUri` in the certificate matches the server's configured URI and that DNS names/IPs in the certificate match the endpoint URL used for connection. Regenerate certificates if necessary, ensuring proper hostnames/IPs.

• Error: read ECONNRESET

  cause This typically indicates a network connectivity issue or a premature termination of the connection, often due to firewalls, incorrect endpoint URLs, or server-side certificate validation failures leading to an immediate disconnect.
  fix Check network connectivity between client and server, including firewall rules on both ends (port 4840 for LDS, default 4840 or custom for OPC UA servers). Verify the endpoint URL is correct and accessible. Review server logs for errors related to connection establishment or certificate rejection.

• TypeError: Cannot read properties of undefined (reading 'start')

  cause The `OPCUADiscoveryServer` instance was not properly initialized before attempting to call its `start()` method, likely due to missing or incorrect constructor arguments.
  fix Ensure the `OPCUADiscoveryServer` constructor is called with all required options, including `port`, `serverInfo`, and `certificateManager`. Double-check the types and availability of these properties before passing them to the constructor.

Warnings

• breaking Version `2.168.0` significantly refactored core packages, migrating from `async` and `lodash` to native modern JavaScript patterns. While primarily internal, changes to the 'more robust typed event system' may introduce breaking changes to existing event listeners or custom extensions relying on previous internal event structures.
  Fix: Review and update any custom event handlers or modules that might be interacting with the internal event system or relying on `async`/`lodash` utilities directly. Consult `node-opcua`'s main documentation for updated event patterns.
• gotcha Beginning with `v2.165.0`, `node-opcua` introduced enhanced 'Advertised Endpoints' support for Docker, NAT, or proxy deployments. Incorrectly configuring advertised endpoints can lead to discovery failures where clients cannot connect to the server's actual network location.
  Fix: For servers running behind network address translation (NAT), Docker port-mapping, or reverse proxies, ensure the `advertisedEndpoints` option is correctly configured with the publicly accessible endpoint URLs. Validate these URLs from the client's perspective.
• gotcha Changes in OPC UA 1.05 compliance and DataType handling (v2.163.0) can impact applications dealing with complex or custom information models. While providing performance improvements, previous non-compliant type handling might now be stricter.
  Fix: If your application uses custom OPC UA DataTypes or relies on specific encoding/decoding behaviors, thoroughly test against `v2.163.0` and later versions. Ensure your information models strictly adhere to OPC UA 1.05 specifications. Re-evaluate any custom extension object or variant handling.
• gotcha The `node-opcua` ecosystem relies heavily on X.509 certificates for secure communication. Misconfiguration or missing certificates (e.g., self-signed certificates for the discovery server itself, or trusted certificates for registering servers) are common sources of connection errors.
  Fix: Always ensure your `OPCUADiscoveryServer` instance has a valid `CertificateManager` configured with appropriate certificates. For client-server communication via discovery, ensure that both the discovery server and the registered OPC UA servers have trusted certificates configured on both sides.

Install

• npm install node-opcua-server-discovery npm
• yarn add node-opcua-server-discovery yarn
• pnpm add node-opcua-server-discovery pnpm

Imports

• OPCUADiscoveryServer
  wrong:

  const OPCUADiscoveryServer = require('node-opcua-server-discovery');

  correct:

  import { OPCUADiscoveryServer } from 'node-opcua-server-discovery';

  The `node-opcua` ecosystem primarily uses ES Modules and TypeScript. While CommonJS might work in some older Node.js contexts, ESM is the recommended and best-supported import method.
• DiscoveryServerOptions

  import type { DiscoveryServerOptions } from 'node-opcua-server-discovery';

  Import types separately using `import type` for clarity and to ensure type-only imports are correctly handled by TypeScript compilers and bundlers.
• CertificateManager

  import { CertificateManager } from 'node-opcua-pki';

  While not directly from `server-discovery`, certificate management is crucial for OPC UA security. `node-opcua-pki` is a closely related and often required dependency for configuring secure discovery services.

Quickstart

This code snippet demonstrates how to initialize and start an OPC UA Local Discovery Server (LDS) using `node-opcua-server-discovery`. It includes essential steps for certificate management, defining server information, and graceful shutdown. This LDS can then be used by other OPC UA servers to register themselves, and by clients to discover available services.

import { OPCUADiscoveryServer } from 'node-opcua-server-discovery';
import { CertificateManager } from 'node-opcua-pki';
import path from 'path';
import os from 'os';

async function startDiscoveryServer() {
  const pkiFolder = path.join(os.tmpdir(), "pki_for_discovery");
  const certificateManager = new CertificateManager({ pki: pkiFolder });
  await certificateManager.initialize();

  // Ensure a self-signed certificate is available for the discovery server
  await certificateManager.createSelfSignedCertificate({
    applicationUri: 'urn:MyNodeOPCUADiscoveryServer',
    applicationName: { text: 'My Node-OPCUA Discovery Server', locale: 'en-US' },
    dns: [os.hostname(), 'localhost'],
    ip: [], // Add your server's IP if necessary
    startDate: new Date(),
    endDate: new Date(Date.now() + 365 * 24 * 60 * 60 * 1000) // 1 year validity
  });

  const discoveryServer = new OPCUADiscoveryServer({
    port: 4840,
    serverInfo: {
      applicationUri: 'urn:MyNodeOPCUADiscoveryServer',
      applicationName: { text: 'My Node-OPCUA Discovery Server', locale: 'en-US' },
      productUri: 'https://github.com/node-opcua/node-opcua',
    },
    certificateManager: certificateManager,
    // Optional: Specify server endpoints for the discovery server itself
    // For example, if running behind NAT/Docker with advertised endpoints
    // advertisedEndpoints: ['opc.tcp://my-public-host:4840']
  });

  await discoveryServer.start();
  console.log(`OPC UA Discovery Server started on port ${discoveryServer.port}.`);
  console.log(`PKI folder: ${pkiFolder}`);

  process.on('SIGINT', async () => {
    console.log('Stopping discovery server...');
    await discoveryServer.shutdown();
    console.log('Discovery server stopped.');
    process.exit(0);
  });
}

startDiscoveryServer().catch(err => {
  console.error('Failed to start discovery server:', err);
  process.exit(1);
});