node-opcua-transport 2.170.0 → 2.173.0

package/source/client_tcp_transport.ts

@@ -8,28 +8,27 @@ import { types } from "node:util";
 import chalk from "chalk";
 
 import { assert } from "node-opcua-assert";
-import { BinaryStream } from "node-opcua-binary-stream";
-import { readMessageHeader } from "node-opcua-chunkmanager";
-import { checkDebugFlag, make_debugLog, make_errorLog, make_warningLog } from "node-opcua-debug";
+import { checkDebugFlag, make_debugLog, make_errorLog } from "node-opcua-debug";
 import type { ErrorCallback } from "node-opcua-status-code";
-import { AcknowledgeMessage } from "./AcknowledgeMessage";
-import { HelloMessage } from "./HelloMessage";
-import { TCPErrorMessage } from "./TCPErrorMessage";
-import { getFakeTransport, type ISocketLike, TCP_transport } from "./tcp_transport";
-import { decodeMessage, packTcpMessage, parseEndpointUrl } from "./tools";
-import { doTraceHelloAck } from "./utils";
+
+import { ClientTransportBase } from "./client_transport_base";
+import type { TransportSettingsOptions } from "./i_client_transport";
+import { getFakeTransport, type ISocketLike } from "./tcp_transport";
+import { parseEndpointUrl } from "./tools";
 
 const doDebug = checkDebugFlag(__filename);
 const debugLog = make_debugLog(__filename);
-const warningLog = make_warningLog(__filename);
 const errorLog = make_errorLog(__filename);
 const gHostname = os.hostname();
 
+// Re-exported for source-level backwards compatibility: this type used to live in this file.
+export type { TransportSettingsOptions };
+
 function createClientSocket(endpointUrl: string, timeout: number): ISocketLike {
     // create a socket based on Url
     const ep = parseEndpointUrl(endpointUrl);
-    const port = parseInt(ep.port!, 10);
-    const hostname = ep.hostname!;
+    const port = parseInt(ep.port  || "4840", 10);
+    const hostname = ep.hostname;
 
     let socket: ISocketLike;
     switch (ep.protocol) {
@@ -53,29 +52,6 @@ function createClientSocket(endpointUrl: string, timeout: number): ISocketLike {
         }
     }
 }
-export interface ClientTCP_transport {
-    on(eventName: "chunk", eventHandler: (messageChunk: Buffer) => void): this;
-    on(eventName: "close", eventHandler: (err: Error | null) => void): this;
-    on(eventName: "connection_break", eventHandler: (err: Error | null) => void): this;
-    on(eventName: "connect", eventHandler: () => void): this;
-
-    once(eventName: "chunk", eventHandler: (messageChunk: Buffer) => void): this;
-    once(eventName: "close", eventHandler: (err: Error | null) => void): this;
-    once(eventName: "connection_break", eventHandler: (err: Error | null) => void): this;
-    once(eventName: "connect", eventHandler: () => void): this;
-
-    emit(eventName: "chunk", messageChunk: Buffer): boolean;
-    emit(eventName: "close", err?: Error | null): boolean;
-    emit(eventName: "connection_break", err?: Error | null): boolean;
-    emit(eventName: "connect"): boolean;
-}
-
-export interface TransportSettingsOptions {
-    maxChunkCount?: number;
-    maxMessageSize?: number;
-    receiveBufferSize?: number;
-    sendBufferSize?: number;
-}
 
 /**
  * a ClientTCP_transport connects to a remote server socket and
@@ -112,50 +88,7 @@ export interface TransportSettingsOptions {
  *
  *
  */
-// biome-ignore lint/suspicious/noUnsafeDeclarationMerging: typed EventEmitter events - extending parent's event map in subclass hierarchy
-export class ClientTCP_transport extends TCP_transport {
-    public static defaultMaxChunk = 0; // 0 - no limits
-    public static defaultMaxMessageSize = 0; // 0 - no limits
-    public static defaultReceiveBufferSize = 1024 * 64 * 10;
-    public static defaultSendBufferSize = 1024 * 64 * 10; // 8192 min,
-
-    public endpointUrl: string;
-    public serverUri: string;
-    public numberOfRetry: number;
-    public parameters?: AcknowledgeMessage;
-
-    private _counter: number;
-    private _helloSettings: {
-        maxChunkCount: number;
-        maxMessageSize: number;
-        receiveBufferSize: number;
-        sendBufferSize: number;
-    };
-    constructor(transportSettings?: TransportSettingsOptions) {
-        super();
-        this.endpointUrl = "";
-        this.serverUri = "";
-        this._counter = 0;
-        this.numberOfRetry = 0;
-
-        // initially before HEL/ACK
-        this.maxChunkCount = 1;
-        this.maxMessageSize = 4 * 1024;
-        this.receiveBufferSize = 4 * 1024;
-
-        transportSettings = transportSettings || {};
-        this._helloSettings = {
-            maxChunkCount: transportSettings.maxChunkCount || ClientTCP_transport.defaultMaxChunk,
-            maxMessageSize: transportSettings.maxMessageSize || ClientTCP_transport.defaultMaxMessageSize,
-            receiveBufferSize: transportSettings.receiveBufferSize || ClientTCP_transport.defaultReceiveBufferSize,
-            sendBufferSize: transportSettings.sendBufferSize || ClientTCP_transport.defaultSendBufferSize
-        };
-    }
-
-    public getTransportSettings(): TransportSettingsOptions {
-        return this._helloSettings;
-    }
-
+export class ClientTCP_transport extends ClientTransportBase {
     public dispose(): void {
         /* c8 ignore next */
         doDebug && debugLog(" ClientTCP_transport disposed");
@@ -170,7 +103,8 @@ export class ClientTCP_transport extends TCP_transport {
         doDebug && debugLog(chalk.cyan(`ClientTCP_transport#connect(endpointUrl = ${endpointUrl})`));
         let socket: ISocketLike | null = null;
         try {
-            const _ep = parseEndpointUrl(endpointUrl);
+            // validate the URL upfront so a parse error is reported synchronously
+            parseEndpointUrl(endpointUrl);
             socket = createClientSocket(endpointUrl, this.timeout);
 
             socket.setTimeout(this.timeout >> 1, () => {
@@ -184,34 +118,6 @@ export class ClientTCP_transport extends TCP_transport {
             return;
         }
 
-        /**
-         *
-         */
-        const _on_socket_error_after_connection = (err: Error) => {
-            /* c8 ignore next */
-            doDebug && debugLog(" _on_socket_error_after_connection ClientTCP_transport Socket Error", err.message);
-
-            // EPIPE : EPIPE (Broken pipe): A write on a pipe, socket, or FIFO for which there is no process to read the
-            // data. Commonly encountered at the net and http layers, indicative that the remote side of the stream
-            // being written to has been closed.
-
-            // ECONNRESET (Connection reset by peer): A connection was forcibly closed by a peer. This normally results
-            // from a loss of the connection on the remote socket due to a timeout or reboot. Commonly encountered
-            // via the http and net module
-
-            //  socket termination could happen:
-            //   * when the socket times out (lost of connection, network outage, etc...)
-            //   * or, when the server abruptly disconnects the socket ( in case of invalid communication for instance)
-            if (err.message.match(/ECONNRESET|EPIPE|premature socket termination/)) {
-                /**
-                 * @event connection_break
-                 *
-                 */
-                doDebug && debugLog("connection_break after reconnection", endpointUrl);
-                this.emit("connection_break", err);
-            }
-        };
-
         const _on_socket_connect = () => {
             /* c8 ignore next */
             doDebug && debugLog("entering _on_socket_connect");
@@ -223,13 +129,12 @@ export class ClientTCP_transport extends TCP_transport {
                     if (!this._socket) {
                         return callback(new Error("Abandoned"));
                     }
-                    // install error handler to detect connection break
-                    this._socket.on("error", _on_socket_error_after_connection);
+                    // install the post-connect "connection break" detector inherited from ClientTransportBase
+                    this._install_post_connect_error_handler(endpointUrl);
                     /**
                      * notify the observers that the transport is connected (the socket is connected and the the HEL/ACK
                      * transaction has been done)
                      * @event connect
-                     *
                      */
                     this.emit("connect");
                 } else {
@@ -269,110 +174,4 @@ export class ClientTCP_transport extends TCP_transport {
         this._socket?.once("end", _on_socket_end_for_connect);
         this._socket?.once("connect", _on_socket_connect);
     }
-
-    private _handle_ACK_response(messageChunk: Buffer, callback: ErrorCallback) {
-        const _stream = new BinaryStream(messageChunk);
-        const messageHeader = readMessageHeader(_stream);
-        let err: Error | null = null;
-        /* c8 ignore next */
-        if (messageHeader.isFinal !== "F") {
-            err = new Error(" invalid ACK message");
-            return callback(err);
-        }
-
-        let responseClass: typeof AcknowledgeMessage | typeof TCPErrorMessage;
-        let response: AcknowledgeMessage | TCPErrorMessage;
-
-        if (messageHeader.msgType === "ERR") {
-            responseClass = TCPErrorMessage;
-            _stream.rewind();
-            response = decodeMessage(_stream, responseClass) as TCPErrorMessage;
-
-            err = new Error(`ACK: ERR received ${response.statusCode.toString()} : ${response.reason}`);
-            (err as any).statusCode = response.statusCode;
-            // c8 ignore next
-            doTraceHelloAck && warningLog("receiving ERR instead of Ack", response.toString());
-
-            callback(err);
-        } else {
-            responseClass = AcknowledgeMessage;
-            _stream.rewind();
-            response = decodeMessage(_stream, responseClass) as AcknowledgeMessage;
-
-            this.parameters = response;
-            this.setLimits(response);
-
-            // c8 ignore next
-            doTraceHelloAck && warningLog("receiving Ack\n", response.toString());
-
-            callback();
-        }
-    }
-
-    private _send_HELLO_request() {
-        /* c8 ignore next */
-        doDebug && debugLog("entering _send_HELLO_request");
-
-        assert(this._socket);
-        assert(Number.isFinite(this.protocolVersion));
-        assert(this.endpointUrl.length > 0, " expecting a valid endpoint url");
-
-        const { maxChunkCount, maxMessageSize, receiveBufferSize, sendBufferSize } = this._helloSettings;
-
-        // Write a message to the socket as soon as the client is connected,
-        // the server will receive it as message from the client
-        const helloMessage = new HelloMessage({
-            endpointUrl: this.endpointUrl,
-            protocolVersion: this.protocolVersion,
-            maxChunkCount,
-            maxMessageSize,
-            receiveBufferSize,
-            sendBufferSize
-        });
-        // c8 ignore next
-        doTraceHelloAck && warningLog(`sending Hello\n ${helloMessage.toString()} `);
-
-        const messageChunk = packTcpMessage("HEL", helloMessage);
-        this._write_chunk(messageChunk);
-    }
-
-    private _on_ACK_response(externalCallback: ErrorCallback, err: Error | null, data?: Buffer) {
-        /* c8 ignore next */
-        doDebug && debugLog("entering _on_ACK_response");
-
-        assert(typeof externalCallback === "function");
-        assert(this._counter === 0, "Ack response should only be received once !");
-        this._counter += 1;
-
-        if (err || !data) {
-            if (this._socket) {
-                const s = this._socket;
-                this._socket = null;
-                s.destroy();
-            }
-            externalCallback(err || new Error("no data"));
-        } else {
-            this._handle_ACK_response(data, externalCallback);
-        }
-    }
-
-    private _perform_HEL_ACK_transaction(callback: ErrorCallback) {
-        /* c8 ignore next */
-        if (!this._socket) {
-            return callback(new Error("No socket available to perform HEL/ACK transaction"));
-        }
-        assert(this._socket, "expecting a valid socket to send a message");
-        assert(typeof callback === "function");
-        this._counter = 0;
-        /* c8 ignore next */
-        doDebug && debugLog("entering _perform_HEL_ACK_transaction");
-
-        this._install_one_time_message_receiver((err: Error | null, data?: Buffer) => {
-            /* c8 ignore next */
-            doDebug && debugLog("before  _on_ACK_response ", err ? err.message : "");
-
-            this._on_ACK_response(callback, err, data);
-        });
-        this._send_HELLO_request();
-    }
 }

package/source/client_transport_base.ts

@@ -0,0 +1,238 @@
+/**
+ * @module node-opcua-transport
+ *
+ * Transport-agnostic base class for client-side OPC UA transports.
+ *
+ * Owns the UACP HEL/ACK handshake, the negotiated transport settings, and the
+ * post-connect connection-break detector. Concrete subclasses (`ClientTCP_transport`,
+ * `ClientWS_transport`, ...) implement only the socket-creation step in `connect()`.
+ *
+ * Browser-safe: does not import `node:net`, `node:os`, `node:util`, or any other
+ * Node-only built-in beyond what `TCP_transport` already inherits from `node:events`.
+ */
+
+import { assert } from "node-opcua-assert";
+import { BinaryStream } from "node-opcua-binary-stream";
+import { readMessageHeader } from "node-opcua-chunkmanager";
+import { checkDebugFlag, make_debugLog, make_warningLog } from "node-opcua-debug";
+import type { ErrorCallback } from "node-opcua-status-code";
+
+import { AcknowledgeMessage } from "./AcknowledgeMessage";
+import { HelloMessage } from "./HelloMessage";
+import type { TransportSettingsOptions } from "./i_client_transport";
+import { TCPErrorMessage } from "./TCPErrorMessage";
+import { TCP_transport } from "./tcp_transport";
+import { decodeMessage, packTcpMessage } from "./tools";
+import { doTraceHelloAck } from "./utils";
+
+// Use a string category instead of `__filename` so the module loads in
+// browsers without a Node-style filename global.
+const doDebug = checkDebugFlag("ClientTransportBase");
+const debugLog = make_debugLog("ClientTransportBase");
+const warningLog = make_warningLog("ClientTransportBase");
+
+export interface ClientTransportBase {
+    on(eventName: "chunk", eventHandler: (messageChunk: Buffer) => void): this;
+    on(eventName: "close", eventHandler: (err: Error | null) => void): this;
+    on(eventName: "connection_break", eventHandler: (err: Error | null) => void): this;
+    on(eventName: "connect", eventHandler: () => void): this;
+
+    once(eventName: "chunk", eventHandler: (messageChunk: Buffer) => void): this;
+    once(eventName: "close", eventHandler: (err: Error | null) => void): this;
+    once(eventName: "connection_break", eventHandler: (err: Error | null) => void): this;
+    once(eventName: "connect", eventHandler: () => void): this;
+
+    emit(eventName: "chunk", messageChunk: Buffer): boolean;
+    emit(eventName: "close", err?: Error | null): boolean;
+    emit(eventName: "connection_break", err?: Error | null): boolean;
+    emit(eventName: "connect"): boolean;
+}
+
+// biome-ignore lint/suspicious/noUnsafeDeclarationMerging: companion to the interface above
+export abstract class ClientTransportBase extends TCP_transport {
+    public static defaultMaxChunk = 0; // 0 - no limits
+    public static defaultMaxMessageSize = 0; // 0 - no limits
+    public static defaultReceiveBufferSize = 1024 * 64 * 10;
+    public static defaultSendBufferSize = 1024 * 64 * 10; // 8192 min,
+
+    public endpointUrl: string;
+    public serverUri: string;
+    public numberOfRetry: number;
+    public parameters?: AcknowledgeMessage;
+
+    private _counter: number;
+    private _helloSettings: {
+        maxChunkCount: number;
+        maxMessageSize: number;
+        receiveBufferSize: number;
+        sendBufferSize: number;
+    };
+
+    constructor(transportSettings?: TransportSettingsOptions) {
+        super();
+        this.endpointUrl = "";
+        this.serverUri = "";
+        this._counter = 0;
+        this.numberOfRetry = 0;
+
+        // initially before HEL/ACK
+        this.maxChunkCount = 1;
+        this.maxMessageSize = 4 * 1024;
+        this.receiveBufferSize = 4 * 1024;
+
+        transportSettings = transportSettings || {};
+        this._helloSettings = {
+            maxChunkCount: transportSettings.maxChunkCount || ClientTransportBase.defaultMaxChunk,
+            maxMessageSize: transportSettings.maxMessageSize || ClientTransportBase.defaultMaxMessageSize,
+            receiveBufferSize: transportSettings.receiveBufferSize || ClientTransportBase.defaultReceiveBufferSize,
+            sendBufferSize: transportSettings.sendBufferSize || ClientTransportBase.defaultSendBufferSize
+        };
+    }
+
+    public getTransportSettings(): TransportSettingsOptions {
+        return this._helloSettings;
+    }
+
+    public dispose(): void {
+        /* c8 ignore next */
+        doDebug && debugLog(" ClientTransportBase disposed");
+
+        super.dispose();
+    }
+
+    /**
+     * Connect to `endpointUrl` and perform the UACP HEL/ACK handshake.
+     * Concrete subclasses are responsible for opening the underlying socket
+     * (TCP, WebSocket, ...) and then driving the inherited HEL/ACK machinery.
+     */
+    public abstract connect(endpointUrl: string, callback: ErrorCallback): void;
+
+    /**
+     * Install the post-connect "connection break" detector. Subclasses call this
+     * once the underlying socket is open and the HEL/ACK transaction has succeeded.
+     *
+     * Detects ECONNRESET / EPIPE / premature socket termination on the live socket
+     * and re-emits them as `connection_break` so reconnection logic upstream can
+     * react.
+     */
+    protected _install_post_connect_error_handler(endpointUrl: string): void {
+        if (!this._socket) return;
+        this._socket.on("error", (err: Error) => {
+            // EPIPE : a write on a pipe/socket/FIFO with no reader.
+            // ECONNRESET : connection forcibly closed by the peer (timeout, reboot, ...).
+            // "premature socket termination" : abrupt close mid-message.
+            if (err.message.match(/ECONNRESET|EPIPE|premature socket termination/)) {
+                /* c8 ignore next */
+                doDebug && debugLog("connection_break after reconnection", endpointUrl);
+                this.emit("connection_break", err);
+            }
+        });
+    }
+
+    protected _perform_HEL_ACK_transaction(callback: ErrorCallback): void {
+        /* c8 ignore next */
+        if (!this._socket) {
+            callback(new Error("No socket available to perform HEL/ACK transaction"));
+            return;
+        }
+        assert(this._socket, "expecting a valid socket to send a message");
+        assert(typeof callback === "function");
+        this._counter = 0;
+        /* c8 ignore next */
+        doDebug && debugLog("entering _perform_HEL_ACK_transaction");
+
+        this._install_one_time_message_receiver((err: Error | null, data?: Buffer) => {
+            /* c8 ignore next */
+            doDebug && debugLog("before  _on_ACK_response ", err ? err.message : "");
+
+            this._on_ACK_response(callback, err, data);
+        });
+        this._send_HELLO_request();
+    }
+
+    private _send_HELLO_request(): void {
+        /* c8 ignore next */
+        doDebug && debugLog("entering _send_HELLO_request");
+
+        assert(this._socket);
+        assert(Number.isFinite(this.protocolVersion));
+        assert(this.endpointUrl.length > 0, " expecting a valid endpoint url");
+
+        const { maxChunkCount, maxMessageSize, receiveBufferSize, sendBufferSize } = this._helloSettings;
+
+        const helloMessage = new HelloMessage({
+            endpointUrl: this.endpointUrl,
+            protocolVersion: this.protocolVersion,
+            maxChunkCount,
+            maxMessageSize,
+            receiveBufferSize,
+            sendBufferSize
+        });
+        // c8 ignore next
+        doTraceHelloAck && warningLog(`sending Hello\n ${helloMessage.toString()} `);
+
+        const messageChunk = packTcpMessage("HEL", helloMessage);
+        this._write_chunk(messageChunk);
+    }
+
+    private _on_ACK_response(externalCallback: ErrorCallback, err: Error | null, data?: Buffer): void {
+        /* c8 ignore next */
+        doDebug && debugLog("entering _on_ACK_response");
+
+        assert(typeof externalCallback === "function");
+        assert(this._counter === 0, "Ack response should only be received once !");
+        this._counter += 1;
+
+        if (err || !data) {
+            if (this._socket) {
+                const s = this._socket;
+                this._socket = null;
+                s.destroy();
+            }
+            externalCallback(err || new Error("no data"));
+        } else {
+            this._handle_ACK_response(data, externalCallback);
+        }
+    }
+
+    private _handle_ACK_response(messageChunk: Buffer, callback: ErrorCallback): void {
+        const _stream = new BinaryStream(messageChunk);
+        const messageHeader = readMessageHeader(_stream);
+        let err: Error | null = null;
+        /* c8 ignore next */
+        if (messageHeader.isFinal !== "F") {
+            err = new Error(" invalid ACK message");
+             callback(err);
+             return;
+        }
+
+        let responseClass: typeof AcknowledgeMessage | typeof TCPErrorMessage;
+        let response: AcknowledgeMessage | TCPErrorMessage;
+
+        if (messageHeader.msgType === "ERR") {
+            responseClass = TCPErrorMessage;
+            _stream.rewind();
+            response = decodeMessage(_stream, responseClass) as TCPErrorMessage;
+
+            err = new Error(`ACK: ERR received ${response.statusCode.toString()} : ${response.reason}`);
+            // biome-ignore lint/suspicious/noExplicitAny: legacy diagnostic field tacked onto Error
+            (err as any).statusCode = response.statusCode;
+            // c8 ignore next
+            doTraceHelloAck && warningLog("receiving ERR instead of Ack", response.toString());
+
+            callback(err);
+        } else {
+            responseClass = AcknowledgeMessage;
+            _stream.rewind();
+            response = decodeMessage(_stream, responseClass) as AcknowledgeMessage;
+
+            this.parameters = response;
+            this.setLimits(response);
+
+            // c8 ignore next
+            doTraceHelloAck && warningLog("receiving Ack\n", response.toString());
+
+            callback();
+        }
+    }
+}

package/source/default_client_transport_factory.ts

@@ -0,0 +1,19 @@
+/**
+ * @module node-opcua-transport
+ */
+
+import { ClientTCP_transport, type TransportSettingsOptions } from "./client_tcp_transport";
+import type { IClientTransport, IClientTransportFactory } from "./i_client_transport";
+
+/**
+ * The default client-transport factory, which returns a {@link ClientTCP_transport}.
+ *
+ * This is the implicit factory used by {@link ClientSecureChannelLayer} when no
+ * `transportFactory` option is provided, preserving the historical (Node-only)
+ * behavior byte-for-byte.
+ */
+export const defaultClientTransportFactory: IClientTransportFactory = {
+    create(settings?: TransportSettingsOptions): IClientTransport {
+        return new ClientTCP_transport(settings) as IClientTransport;
+    }
+};

package/source/i_client_transport.ts

@@ -0,0 +1,134 @@
+/**
+ * @module node-opcua-transport
+ */
+
+import type { AcknowledgeMessage } from "./AcknowledgeMessage";
+
+/**
+ * Options used to construct a client transport. Passed through {@link IClientTransportFactory.create}
+ * and applied to the UACP HEL message during the handshake.
+ */
+export interface TransportSettingsOptions {
+    maxChunkCount?: number;
+    maxMessageSize?: number;
+    receiveBufferSize?: number;
+    sendBufferSize?: number;
+}
+
+/**
+ * The minimal surface that {@link ClientSecureChannelLayer} (and anything else acting as
+ * a secure-channel client) uses from a transport. {@link ClientTCP_transport} already
+ * satisfies this interface; browser transports (e.g. a WebSocket-based one) must also
+ * satisfy it to be pluggable via {@link IClientTransportFactory}.
+ *
+ * This interface is intentionally the smallest superset of what the existing
+ * `ClientTCP_transport` exposes and that the secure-channel layer actually consumes,
+ * so adding new transports does not require replicating Node-specific machinery.
+ */
+export interface IClientTransport {
+    // ──────────────────────────────────────────────────────────────
+    // mutable configuration / runtime state
+    // ──────────────────────────────────────────────────────────────
+
+    /** diagnostic name, useful in debug logs */
+    readonly name: string;
+
+    /** OPC UA UACP protocol version advertised in HEL */
+    protocolVersion: number;
+
+    /** overall timeout applied to the underlying socket / connection lifecycle */
+    timeout: number;
+
+    /** number of times the owning channel has retried. Advisory; bumped by callers. */
+    numberOfRetry: number;
+
+    /** endpoint URL the transport was connected to (set by `connect`) */
+    endpointUrl: string;
+
+    /** URI reported by the local application to the peer */
+    serverUri: string;
+
+    // ──────────────────────────────────────────────────────────────
+    // HEL/ACK negotiated values (populated after successful connect)
+    // ──────────────────────────────────────────────────────────────
+
+    readonly parameters?: AcknowledgeMessage;
+
+    readonly receiveBufferSize: number;
+    readonly sendBufferSize: number;
+    readonly maxChunkCount: number;
+    readonly maxMessageSize: number;
+
+    // ──────────────────────────────────────────────────────────────
+    // diagnostics
+    // ──────────────────────────────────────────────────────────────
+
+    readonly bytesRead: number;
+    readonly bytesWritten: number;
+    readonly chunkReadCount: number;
+    readonly chunkWrittenCount: number;
+
+    // ──────────────────────────────────────────────────────────────
+    // lifecycle
+    // ──────────────────────────────────────────────────────────────
+
+    /** connect to `endpointUrl` and perform the UACP HEL/ACK handshake */
+    connect(endpointUrl: string, callback: (err?: Error | null) => void): void;
+
+    /** gracefully disconnect; invokes `callback` when the underlying connection is closed */
+    disconnect(callback: (err?: Error | null) => void): void;
+
+    /** forcibly release resources (close the connection if still open) */
+    dispose(): void;
+
+    /** write a single UACP chunk to the transport */
+    write(chunk: Buffer, callback?: (err?: Error | null) => undefined): void;
+
+    /** emit an ERR back to the peer and destroy the underlying connection */
+    prematureTerminate(err: Error, statusCode: import("node-opcua-status-code").StatusCode): void;
+
+    /** simulate a connection break (used by reconnection logic in tests) */
+    forceConnectionBreak(): void;
+
+    /** `true` when the underlying connection is open and usable */
+    isValid(): boolean;
+
+    /** `true` when `disconnect()` has started or the connection is gone */
+    isDisconnecting(): boolean;
+
+    /** return the effective transport settings (`maxChunkCount` etc.) */
+    getTransportSettings(): TransportSettingsOptions;
+
+    // ──────────────────────────────────────────────────────────────
+    // typed events (mirrors ClientTCP_transport's declaration merge)
+    // ──────────────────────────────────────────────────────────────
+
+    on(eventName: "chunk", eventHandler: (messageChunk: Buffer) => void): this;
+    on(eventName: "close", eventHandler: (err: Error | null) => void): this;
+    on(eventName: "connection_break", eventHandler: (err: Error | null) => void): this;
+    on(eventName: "connect", eventHandler: () => void): this;
+
+    once(eventName: "chunk", eventHandler: (messageChunk: Buffer) => void): this;
+    once(eventName: "close", eventHandler: (err: Error | null) => void): this;
+    once(eventName: "connection_break", eventHandler: (err: Error | null) => void): this;
+    once(eventName: "connect", eventHandler: () => void): this;
+
+    removeListener(eventName: "chunk", eventHandler: (messageChunk: Buffer) => void): this;
+    removeListener(eventName: "close", eventHandler: (err: Error | null) => void): this;
+    removeListener(eventName: "connection_break", eventHandler: (err: Error | null) => void): this;
+    removeListener(eventName: "connect", eventHandler: () => void): this;
+}
+
+/**
+ * A factory that produces an {@link IClientTransport}. Injected into
+ * {@link ClientSecureChannelLayerOptions.transportFactory} to swap the default Node TCP
+ * transport for an alternative (for example, a browser WebSocket transport or a tracing
+ * proxy wrapped around the default).
+ */
+export interface IClientTransportFactory {
+    /**
+     * Create a new transport. Called once per secure-channel open; the factory must not
+     * return the same instance twice.
+     */
+    create(settings?: TransportSettingsOptions): IClientTransport;
+}