node-opcua-client-browser 2.177.0

package/source/create_browser_client.ts

@@ -0,0 +1,105 @@
+/**
+ * @module node-opcua-client-browser
+ *
+ * Thin helper that constructs an `OPCUAClient` (from `node-opcua-client`)
+ * pre-wired with the browser WebSocket transport factory and, when no
+ * credentials are supplied, an in-memory certificate/key pair provider so
+ * no disk paths are touched.
+ *
+ * All other `OPCUAClient` configuration passes through unchanged — callers
+ * configure session timeouts, reconnection strategies, security policies,
+ * etc. exactly as they would for the Node client.
+ *
+ * @example
+ * ```ts
+ * import { createBrowserClient, AttributeIds, MessageSecurityMode, SecurityPolicy } from "node-opcua-client-browser";
+ *
+ * const client = createBrowserClient({
+ *     endpointMustExist: false,
+ *     securityMode: MessageSecurityMode.None,
+ *     securityPolicy: SecurityPolicy.None,
+ * });
+ * await client.connect("opc.ws://localhost:4840");
+ * const session = await client.createSession();
+ * const dv = await session.read({ nodeId: "ns=1;s=Counter", attributeId: AttributeIds.Value });
+ * await session.close();
+ * await client.disconnect();
+ * ```
+ */
+
+import { InMemoryCertificateKeyPairProvider, InMemoryCertificateStore } from "node-opcua-common";
+import { OPCUAClient, type OPCUAClientOptions } from "node-opcua-client";
+import type { Certificate, PrivateKey } from "node-opcua-crypto/web";
+
+import { browserWsTransportFactory } from "./client_ws_transport";
+
+/**
+ * Options accepted by {@link createBrowserClient}. Superset of
+ * {@link OPCUAClientOptions}; the browser-specific defaults described above
+ * apply unless the caller overrides them.
+ */
+export interface CreateBrowserClientOptions extends OPCUAClientOptions {
+    /**
+     * Pre-built client certificate chain (DER). When combined with
+     * `clientPrivateKey`, it is loaded into an
+     * `InMemoryCertificateKeyPairProvider` so the owning `OPCUAClient`
+     * needs no disk cert files.
+     *
+     * If you already pass `certificateKeyPairProvider`, this option is
+     * ignored.
+     */
+    clientCertificate?: Certificate | Certificate[];
+
+    /**
+     * Pre-built client private key. Paired with `clientCertificate` to
+     * populate the in-memory provider.
+     *
+     * If you already pass `certificateKeyPairProvider`, this option is
+     * ignored.
+     */
+    clientPrivateKey?: PrivateKey;
+}
+
+/**
+ * Construct an `OPCUAClient` with browser-appropriate defaults.
+ *
+ * - `transportFactory` defaults to `browserWsTransportFactory` so the
+ *   underlying secure channel opens a WebSocket. Callers can override by
+ *   passing a different `transportFactory`.
+ * - `certificateKeyPairProvider` defaults to an
+ *   `InMemoryCertificateKeyPairProvider`, populated with
+ *   `clientCertificate` / `clientPrivateKey` when those are supplied.
+ *   When they are NOT supplied, the provider is constructed empty —
+ *   callers are expected to await `ensureCertificateExists(...)` on the
+ *   returned client's credentials before connecting with a non-None
+ *   security policy.
+ * - `clientCertificateManager` defaults to an `InMemoryCertificateStore`
+ *   (auto-accept unknown peer certs). Callers can override by passing
+ *   their own `clientCertificateManager` (e.g. one backed by IndexedDB
+ *   or OPFS).
+ */
+export function createBrowserClient(options: CreateBrowserClientOptions = {} as CreateBrowserClientOptions): OPCUAClient {
+    const { clientCertificate, clientPrivateKey, ...clientOptions } = options;
+
+    // Default to the browser WS transport factory unless the caller supplies one.
+    if (!clientOptions.transportFactory) {
+        clientOptions.transportFactory = browserWsTransportFactory;
+    }
+
+    // Default to an in-memory cert/key provider unless the caller supplies one.
+    // If the caller provided a client cert + private key, pre-populate the
+    // provider so the owning client can reach them without further async setup.
+    if (!clientOptions.certificateKeyPairProvider) {
+        const chain = clientCertificate
+            ? (Array.isArray(clientCertificate) ? clientCertificate : [clientCertificate])
+            : undefined;
+        clientOptions.certificateKeyPairProvider = new InMemoryCertificateKeyPairProvider(chain, clientPrivateKey);
+    }
+
+    // Default to an in-memory trust store unless the caller supplies one.
+    if (!clientOptions.clientCertificateManager) {
+        clientOptions.clientCertificateManager = new InMemoryCertificateStore({ autoAcceptUnknown: true });
+    }
+
+    return OPCUAClient.create(clientOptions);
+}

package/source/index.ts

@@ -0,0 +1,49 @@
+/*!
+ * The MIT License (MIT)
+ * Copyright (c) 2022-2025  Sterfive SAS - 833264583 RCS ORLEANS - France (https://www.sterfive.com)
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy of
+ * this software and associated documentation files (the "Software"), to deal in
+ * the Software without restriction, including without limitation the rights to
+ * use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
+ * the Software, and to permit persons to whom the Software is furnished to do so,
+ * subject to the following conditions:
+ *
+ *   The above copyright notice and this permission notice shall be included in all
+ *   copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+ * FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+ * COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+ * IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+ * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+ */
+/**
+ * @module node-opcua-client-browser
+ *
+ * Browser entry point for `node-opcua-client`. Exposes the OPC UA WebSocket
+ * transport (`ClientWS_transport`, `browserWsTransportFactory`,
+ * `parseWsEndpointUrl`).
+ *
+ * Target environments: modern evergreen browsers (Chromium, Firefox, WebKit).
+ * The transport uses the OPC UA WebSocket mapping per Part 6 §7.5
+ * (`opcua+uacp` subprotocol, one UACP chunk per binary frame).
+ *
+ * NOTE: `createBrowserClient` is temporarily NOT re-exported from this
+ * barrel. Its `OPCUAClient` import drags in `node-opcua-client`, which
+ * still transitively pulls Node-only modules (`node:crypto`, `node:fs`,
+ * `node:dns`, `@ster5/global-mutex`, `multicast-dns`, …) at bundle
+ * time. The full plan to make those packages browser-safe lives at
+ * `C:\Users\etien\.claude\plans\run-pnpm-filter-node-opcua-client-browse-vivid-sparkle.md`.
+ * The Node-side helper itself is still built and unit-tested — its 8
+ * mocha cases in `test/unit/test_create_browser_client.ts` import it
+ * directly from `../../dist`. Re-export will be restored in Step 5 of
+ * the plan once Steps 1–4 land.
+ */
+
+export * from "./client_ws_transport";
+export * as uacp from "./uacp";
+export { type WebSocketLike, WsSocketAdapter } from "./ws_socket_adapter";
+
+export const VERSION = "2.172.0";

package/source/uacp.ts

@@ -0,0 +1,22 @@
+/**
+ * @module node-opcua-client-browser
+ * @internal
+ *
+ * UACP primitives usable in the browser.
+ *
+ * These are thin re-exports of the byte-level encoders/decoders from
+ * `node-opcua-transport`. Those modules are pure-JS (only `node:events` is
+ * pulled in, which Vite polyfills automatically) and are therefore safe to
+ * bundle for the browser. Consolidating them here gives us a single point of
+ * audit if a future release of `node-opcua-transport` introduces a Node-only
+ * import.
+ */
+
+export {
+    AcknowledgeMessage,
+    HelloMessage,
+    TCPErrorMessage,
+    packTcpMessage,
+    readRawMessageHeader,
+    type TransportSettingsOptions
+} from "node-opcua-transport";

package/source/ws_socket_adapter.ts

@@ -0,0 +1,219 @@
+/**
+ * @module node-opcua-client-browser
+ * @internal
+ *
+ * WebSocket → {@link ISocketLike} adapter.
+ *
+ * {@link TCP_transport} in `node-opcua-transport` expects an `ISocketLike` that
+ * emits `data`, `close`, `end`, `error`, `timeout` events and provides
+ * `write`, `end`, `destroy`, `setKeepAlive`, `setNoDelay`, `setTimeout`.
+ *
+ * This adapter turns a browser `WebSocket` (or the `ws` package used during
+ * unit tests) into that shape so the full HEL/ACK + chunk-assembly machinery
+ * in `TCP_transport` can be reused without change.
+ *
+ * Framing per OPC UA Part 6 §7.5: each outgoing UACP chunk is sent as exactly
+ * one binary WebSocket message. Incoming binary messages are concatenated via
+ * the `TCP_transport` packet-assembler, so even if a peer (e.g. `websockify`)
+ * splits a chunk across multiple frames, the assembler re-combines them.
+ * Text frames are ignored with a warning.
+ */
+
+import { EventEmitter } from "events";
+import type { ISocketLike } from "node-opcua-transport";
+
+/**
+ * Minimal structural type that matches both the browser `WebSocket` global and
+ * the `ws` package's Node implementation.
+ */
+export interface WebSocketLike {
+    readonly readyState: number;
+    binaryType: string;
+    send(data: ArrayBuffer | ArrayBufferView): void;
+    close(code?: number, reason?: string): void;
+
+    // Browser event model (setter-based)
+    onopen: ((this: WebSocketLike, ev: unknown) => void) | null;
+    onclose: ((this: WebSocketLike, ev: { code?: number; reason?: string }) => void) | null;
+    onerror: ((this: WebSocketLike, ev: unknown) => void) | null;
+    onmessage: ((this: WebSocketLike, ev: { data: unknown }) => void) | null;
+}
+
+// WebSocket readyState constants (avoid importing the DOM lib to stay Node-side compatible)
+const WS_OPEN = 1;
+const WS_CLOSING = 2;
+const WS_CLOSED = 3;
+
+function toBuffer(data: unknown): Buffer | null {
+    if (!data) return null;
+    if (typeof Buffer !== "undefined" && Buffer.isBuffer(data)) return data as Buffer;
+    if (data instanceof ArrayBuffer) return Buffer.from(new Uint8Array(data));
+    if (ArrayBuffer.isView(data)) {
+        const view = data as ArrayBufferView;
+        return Buffer.from(view.buffer, view.byteOffset, view.byteLength);
+    }
+    // Blob path: the transport's HEL/ACK uses `binaryType = "arraybuffer"`,
+    // so this should never hit. Fail loud if it does.
+    return null;
+}
+
+/**
+ * Wrap a {@link WebSocketLike} as an {@link ISocketLike}. The returned socket
+ * forwards `data` events once the WS is open, and cleans up the WS listeners
+ * on `destroy` or `end`.
+ *
+ * The WebSocket must already be instantiated (i.e. `new WebSocket(url, protocols)`).
+ * The caller drives this by the time `_install_socket` is called; we just bind.
+ */
+export class WsSocketAdapter extends EventEmitter implements ISocketLike {
+    public remoteAddress?: string;
+    public remotePort?: number;
+    public destroyed = false;
+
+    private _timeoutHandle: ReturnType<typeof setTimeout> | null = null;
+    private _timeoutMs = 0;
+    private _timeoutCb: (() => void) | null = null;
+
+    constructor(private readonly ws: WebSocketLike, url?: string) {
+        super();
+
+        if (url) {
+            try {
+                const u = new URL(url);
+                this.remoteAddress = u.hostname;
+                this.remotePort = u.port ? Number(u.port) : undefined;
+            } catch {
+                /* ignore – URL parse already happened in connect() */
+            }
+        }
+
+        ws.binaryType = "arraybuffer";
+
+        const emitError = (err: Error) => {
+            this.emit("error", err);
+        };
+
+        ws.onopen = () => {
+            this.emit("connect");
+        };
+
+        ws.onmessage = (ev: { data: unknown }) => {
+            // Reset inactivity timer if any
+            this._resetTimeout();
+
+            const buf = toBuffer(ev.data);
+            if (!buf) {
+                // Text frame or unknown type: ignore with a warning, per spec
+                // eslint-disable-next-line no-console
+                console.warn("[ClientWS_transport] ignoring non-binary WebSocket frame");
+                return;
+            }
+            this.emit("data", buf);
+        };
+
+        ws.onerror = () => {
+            // Browser WebSocket errors carry no useful detail. Translate into a
+            // generic Error so downstream log messages still make sense.
+            emitError(new Error("WebSocket error"));
+        };
+
+        ws.onclose = (ev: { code?: number; reason?: string }) => {
+            this._clearTimeout();
+            // `hadError` is best-effort: anything other than 1000 (normal) is
+            // treated as an error path.
+            const hadError = !!ev && typeof ev.code === "number" && ev.code !== 1000;
+            this.emit("end");
+            this.emit("close", hadError);
+        };
+    }
+
+    public write(data: string | Buffer, callback?: (err?: Error | null) => undefined | undefined): void {
+        if (this.destroyed || this.ws.readyState >= WS_CLOSING) {
+            callback?.(new Error("WebSocket is not open"));
+            return;
+        }
+        try {
+            if (typeof data === "string") {
+                // UACP chunks are always binary; if we somehow got a string,
+                // encode to UTF-8.
+                this.ws.send(new TextEncoder().encode(data));
+            } else {
+                // Send as ArrayBufferView so the WS layer keeps it as one binary frame.
+                const u8 = data instanceof Uint8Array ? data : new Uint8Array(data);
+                // `send()` accepts ArrayBuffer or ArrayBufferView; use the view so the
+                // underlying buffer isn't copied unnecessarily.
+                this.ws.send(u8);
+            }
+            callback?.();
+        } catch (err) {
+            callback?.(err as Error);
+        }
+    }
+
+    public end(): void {
+        this._clearTimeout();
+        if (this.ws.readyState === WS_OPEN) {
+            try {
+                this.ws.close(1000, "normal closure");
+            } catch {
+                /* swallow */
+            }
+        }
+    }
+
+    public destroy(_err?: Error): void {
+        this.destroyed = true;
+        this._clearTimeout();
+        if (this.ws.readyState < WS_CLOSED) {
+            try {
+                this.ws.close(1001, "going away");
+            } catch {
+                /* swallow */
+            }
+        }
+        // Detach handlers so no late events fire into a destroyed transport.
+        try {
+            this.ws.onopen = null;
+            this.ws.onclose = null;
+            this.ws.onerror = null;
+            this.ws.onmessage = null;
+        } catch {
+            /* swallow */
+        }
+    }
+
+    // These three are no-ops for WebSocket – keep-alive and nodelay are handled
+    // by the browser / underlying TCP stack; we expose them so TCP_transport's
+    // setup sequence runs unchanged.
+    public setKeepAlive(_enable?: boolean, _initialDelay?: number): this {
+        return this;
+    }
+    public setNoDelay(_noDelay?: boolean): this {
+        return this;
+    }
+
+    public setTimeout(timeout: number, callback?: () => void): this {
+        this._timeoutMs = timeout;
+        this._timeoutCb = callback ?? null;
+        this._resetTimeout();
+        return this;
+    }
+
+    private _resetTimeout(): void {
+        this._clearTimeout();
+        if (this._timeoutMs > 0 && this._timeoutCb) {
+            const cb = this._timeoutCb;
+            this._timeoutHandle = setTimeout(() => {
+                this.emit("timeout");
+                cb();
+            }, this._timeoutMs);
+        }
+    }
+
+    private _clearTimeout(): void {
+        if (this._timeoutHandle !== null) {
+            clearTimeout(this._timeoutHandle);
+            this._timeoutHandle = null;
+        }
+    }
+}