@hiero-ledger/sdk 2.75.0 → 2.77.0

package/src/channel/WebChannel.js

@@ -10,15 +10,185 @@ import Channel, { encodeRequest, decodeUnaryResponse } from "./Channel.js";
 export default class WebChannel extends Channel {
     /**
      * @param {string} address
+     * @param {number=} grpcDeadline
      */
-    constructor(address) {
-        super();
+    constructor(address, grpcDeadline) {
+        super(grpcDeadline);
 
         /**
          * @type {string}
          * @private
          */
         this._address = address;
+
+        // Set the gRPC deadline using the base class method
+
+        /**
+         * Flag indicating if the connection is ready (health check has passed)
+         * Set to true after the first successful health check
+         *
+         * @type {boolean}
+         * @private
+         */
+        this._isReady = false;
+
+        /**
+         * Promise that resolves when the health check is complete
+         * Used to prevent multiple concurrent health checks
+         *
+         * @type {Promise<void>|null}
+         * @private
+         */
+        this._healthCheckPromise = null;
+    }
+
+    /**
+     * Determines whether to use HTTPS based on the address
+     * @param {string} address - The address to check
+     * @returns {boolean} - True if HTTPS should be used, false for HTTP
+     * @private
+     */
+    _shouldUseHttps(address) {
+        return !(
+            address.includes("localhost") || address.includes("127.0.0.1")
+        );
+    }
+
+    /**
+     * Builds the full URL with appropriate scheme (http/https)
+     * @param {string} address - The base address
+     * @returns {string} - The full URL with scheme
+     * @private
+     */
+    _buildUrl(address) {
+        // Check if address already contains a scheme
+        const hasScheme =
+            address.startsWith("http://") || address.startsWith("https://");
+
+        if (hasScheme) {
+            // Use the address as-is if it already has a scheme
+            return address;
+        } else {
+            // Only prepend scheme if none exists
+            const shouldUseHttps = this._shouldUseHttps(address);
+            return shouldUseHttps ? `https://${address}` : `http://${address}`;
+        }
+    }
+
+    /**
+     * Check if the gRPC-Web proxy is reachable and healthy
+     * Performs a POST request and verifies the response has gRPC-Web headers,
+     * which indicates the proxy is running and processing gRPC requests.
+     * Results are cached per address for the entire lifecycle.
+     * Uses promise-based synchronization to prevent multiple concurrent health checks.
+     *
+     * @param {Date} deadline - Deadline for the health check
+     * @returns {Promise<void>}
+     * @private
+     */
+    async _waitForReady(deadline) {
+        // Check if we've already validated this address
+        if (this._isReady) {
+            return; // Health check already passed for this address
+        }
+
+        // If a health check is already in progress, wait for it to complete
+        if (this._healthCheckPromise) {
+            return this._healthCheckPromise;
+        }
+
+        // Start a new health check and store the promise
+        this._healthCheckPromise = this._performHealthCheck(deadline);
+
+        try {
+            await this._healthCheckPromise;
+        } finally {
+            // Clear the promise when done (success or failure)
+            this._healthCheckPromise = null;
+        }
+    }
+
+    /**
+     * Performs the actual health check request
+     * @param {Date} deadline - Deadline for the health check
+     * @returns {Promise<void>}
+     * @private
+     */
+    async _performHealthCheck(deadline) {
+        const address = this._buildUrl(this._address);
+
+        // Calculate remaining time until deadline
+        const timeoutMs = deadline.getTime() - Date.now();
+        if (timeoutMs <= 0) {
+            throw new GrpcServiceError(
+                GrpcStatus.Timeout,
+                ALL_WEB_NETWORK_NODES?.[this._address]?.toString(),
+            );
+        }
+
+        const abortController = new AbortController();
+        const timeoutId = setTimeout(() => abortController.abort(), timeoutMs);
+
+        try {
+            // Make a POST request to verify the gRPC-Web proxy is running
+            // We use a minimal gRPC-Web compatible request
+            //eslint-disable-next-line n/no-unsupported-features/node-builtins
+            const response = await fetch(address, {
+                method: "POST",
+                headers: {
+                    "content-type": "application/grpc-web+proto",
+                    "x-user-agent": `${SDK_NAME}/${SDK_VERSION}`,
+                    "x-grpc-web": "1",
+                },
+                body: new Uint8Array(0), // Empty body for health check
+                signal: abortController.signal,
+            });
+
+            clearTimeout(timeoutId);
+
+            // Check if response is successful (200) or indicates a redirect (3xx)
+            // 3xx status codes indicate the resource has moved, which is valid for proxies
+            if (
+                response.ok ||
+                (response.status >= 300 && response.status < 400)
+            ) {
+                const grpcStatus = response.headers.get("grpc-status");
+                const grpcMessage = response.headers.get("grpc-message");
+
+                // If gRPC headers exist, the proxy is running and processing requests
+                if (grpcStatus != null || grpcMessage != null) {
+                    // Mark this connection as ready
+                    this._isReady = true;
+                    return; //  Healthy - gRPC-Web proxy is responding
+                }
+            }
+
+            // If we get here, either status isn't 200/3xx or no gRPC headers present
+            // This means the proxy might not be configured correctly or not running
+            throw new GrpcServiceError(
+                GrpcStatus.Unavailable,
+                ALL_WEB_NETWORK_NODES?.[this._address]?.toString(),
+            );
+        } catch (error) {
+            clearTimeout(timeoutId);
+
+            if (error instanceof Error && error.name === "AbortError") {
+                throw new GrpcServiceError(
+                    GrpcStatus.Timeout,
+                    ALL_WEB_NETWORK_NODES?.[this._address]?.toString(),
+                );
+            }
+
+            if (error instanceof GrpcServiceError) {
+                throw error;
+            }
+
+            // Network error - server is not reachable
+            throw new GrpcServiceError(
+                GrpcStatus.Unavailable,
+                ALL_WEB_NETWORK_NODES?.[this._address]?.toString(),
+            );
+        }
     }
 
     /**
@@ -38,15 +208,18 @@ export default class WebChannel extends Channel {
     _createUnaryClient(serviceName) {
         // eslint-disable-next-line @typescript-eslint/no-misused-promises
         return async (method, requestData, callback) => {
+            // Calculate deadline for connection check
+            const deadline = new Date();
+            const milliseconds = this._grpcDeadline;
+
+            deadline.setMilliseconds(deadline.getMilliseconds() + milliseconds);
+
             try {
-                const shouldUseHttps = !(
-                    this._address.includes("localhost") ||
-                    this._address.includes("127.0.0.1")
-                );
+                // Wait for connection to be ready (similar to gRPC waitForReady)
+                await this._waitForReady(deadline);
 
-                const address = shouldUseHttps
-                    ? `https://${this._address}`
-                    : `http://${this._address}`;
+                // Build the full URL with appropriate scheme
+                const address = this._buildUrl(this._address);
                 // this will be executed in a browser environment so eslint is
                 // disabled for the fetch call
                 //eslint-disable-next-line n/no-unsupported-features/node-builtins
@@ -68,6 +241,7 @@ export default class WebChannel extends Channel {
                         HttpStatus._fromValue(response.status),
                     );
                     callback(error, null);
+                    return;
                 }
 
                 // Check headers for gRPC errors
@@ -81,6 +255,7 @@ export default class WebChannel extends Channel {
                     );
                     error.message = grpcMessage;
                     callback(error, null);
+                    return;
                 }
 
                 const responseBuffer = await response.arrayBuffer();
@@ -88,6 +263,11 @@ export default class WebChannel extends Channel {
 
                 callback(null, unaryResponse);
             } catch (error) {
+                if (error instanceof GrpcServiceError) {
+                    callback(error, null);
+                    return;
+                }
+
                 const err = new GrpcServiceError(
                     // retry on grpc web errors
                     GrpcStatus._fromValue(18),

package/src/client/Client.js

@@ -12,6 +12,10 @@ import FileId from "../file/FileId.js";
 import Logger from "../logger/Logger.js"; // eslint-disable-line
 import { convertToNumber } from "../util.js";
 import AddressBookQuery from "../network/AddressBookQuery.js";
+import {
+    DEFAULT_GRPC_DEADLINE,
+    DEFAULT_REQUEST_TIMEOUT,
+} from "../constants/ClientConstants.js";
 
 /**
  * @typedef {import("../channel/Channel.js").default} Channel
@@ -40,6 +44,8 @@ import AddressBookQuery from "../network/AddressBookQuery.js";
  * @property {boolean} [scheduleNetworkUpdate]
  * @property {number} [shard]
  * @property {number} [realm]
+ * @property {number} [grpcDeadline]
+ * @property {number} [requestTimeout]
  */
 
 /**
@@ -127,7 +133,10 @@ export default class Client {
         this._defaultRegenerateTransactionId = true;
 
         /** @private */
-        this._requestTimeout = null;
+        this._requestTimeout = DEFAULT_REQUEST_TIMEOUT;
+
+        /** @private */
+        this._grpcDeadline = DEFAULT_GRPC_DEADLINE;
 
         /**
          * @type {boolean}
@@ -156,6 +165,23 @@ export default class Client {
             this._realm = props.realm;
         }
 
+        if (props != null && props.grpcDeadline != null) {
+            this.setGrpcDeadline(props.grpcDeadline);
+        }
+
+        if (props != null && props.requestTimeout != null) {
+            this.setRequestTimeout(props.requestTimeout);
+        }
+
+        // Validate that requestTimeout is larger than grpcDeadline after both are set
+        if (this._requestTimeout <= this._grpcDeadline) {
+            console.warn(
+                `DEPRECATION WARNING: requestTimeout (${this._requestTimeout}ms) should be larger than grpcDeadline (${this._grpcDeadline}ms). ` +
+                    `This configuration may cause operations to fail unexpectedly. ` +
+                    `This will throw an error in the next major version. Please adjust your timeout values.`,
+            );
+        }
+
         /** @internal */
         /** @type {NodeJS.Timeout} */
         this._timer;
@@ -675,21 +701,65 @@ export default class Client {
     }
 
     /**
-     * @param {number} requestTimeout - Number of milliseconds
+     * Set the total request timeout for complete operations.
+     *
+     * @param {number} requestTimeout - Maximum time in milliseconds for complete Transaction/Query operations
      * @returns {this}
      */
     setRequestTimeout(requestTimeout) {
+        if (requestTimeout <= 0) {
+            throw new Error("requestTimeout must be a positive number");
+        }
+        if (requestTimeout <= this._grpcDeadline) {
+            console.warn(
+                `DEPRECATION WARNING: requestTimeout (${requestTimeout}ms) should be larger than grpcDeadline (${this._grpcDeadline}ms). ` +
+                    `This configuration may cause operations to fail unexpectedly. ` +
+                    `This will throw an error in the next major version. Please adjust your timeout values.`,
+            );
+        }
         this._requestTimeout = requestTimeout;
         return this;
     }
 
     /**
-     * @returns {?number}
+     * Get the total request timeout for complete operations.
+     *
+     * @returns {number} Maximum time in milliseconds for complete Transaction/Query operations
      */
     get requestTimeout() {
         return this._requestTimeout;
     }
 
+    /**
+     * Set the global gRPC deadline for all requests.
+     *
+     * @param {number} grpcDeadline - Maximum time in milliseconds for a single gRPC request
+     * @returns {this}
+     */
+    setGrpcDeadline(grpcDeadline) {
+        if (grpcDeadline <= 0) {
+            throw new Error("grpcDeadline must be a positive number");
+        }
+        if (grpcDeadline >= this._requestTimeout) {
+            console.warn(
+                `DEPRECATION WARNING: grpcDeadline (${grpcDeadline}ms) should be smaller than requestTimeout (${this._requestTimeout}ms). ` +
+                    `This configuration may cause operations to fail unexpectedly. ` +
+                    `This will throw an error in the next major version. Please adjust your timeout values.`,
+            );
+        }
+        this._grpcDeadline = grpcDeadline;
+        return this;
+    }
+
+    /**
+     * Get the global gRPC deadline for all requests.
+     *
+     * @returns {number} Maximum time in milliseconds for a single gRPC request
+     */
+    get grpcDeadline() {
+        return this._grpcDeadline;
+    }
+
     /**
      * @returns {number}
      */
@@ -794,7 +864,9 @@ export default class Client {
      * @returns {(address: string) => ChannelT}
      */
     _createNetworkChannel() {
-        throw new Error("not implemented");
+        return () => {
+            throw new Error("not implemented");
+        };
     }
 
     /**
@@ -802,7 +874,9 @@ export default class Client {
      * @returns {(address: string) => MirrorChannelT}
      */
     _createMirrorNetworkChannel() {
-        throw new Error("not implemented");
+        return () => {
+            throw new Error("not implemented");
+        };
     }
 
     /**

package/src/client/NativeClient.js

@@ -307,7 +307,7 @@ export default class NativeClient extends Client {
      * @returns {(address: string) => NativeChannel}
      */
     _createNetworkChannel() {
-        return (address) => new NativeChannel(address);
+        return (address) => new NativeChannel(address, this.grpcDeadline);
     }
 
     /**

package/src/client/NodeClient.js

@@ -35,9 +35,6 @@ export default class NodeClient extends Client {
     constructor(props) {
         super(props);
 
-        /** @private */
-        this._maxExecutionTime = 10000;
-
         if (props != null) {
             if (typeof props.network === "string") {
                 this._setNetworkFromName(props.network);
@@ -267,12 +264,16 @@ export default class NodeClient extends Client {
 
     /**
      * Available only for NodeClient
-     *
+     * Legacy method maintained for backward compatibility.
+     * This method now calls setGrpcDeadline internally to ensure proper validation.
+     * @deprecated Use setGrpcDeadline instead.
      * @param {number} maxExecutionTime
      * @returns {this}
      */
     setMaxExecutionTime(maxExecutionTime) {
-        this._maxExecutionTime = maxExecutionTime;
+        // Use the parent class setGrpcDeadline method to ensure proper validation
+        // This ensures that maxExecutionTime follows the same validation rules as grpcDeadline
+        this.setGrpcDeadline(maxExecutionTime);
         return this;
     }
 
@@ -358,7 +359,7 @@ export default class NodeClient extends Client {
      * @returns {(address: string, cert?: string) => NodeChannel}
      */
     _createNetworkChannel() {
-        return (address) => new NodeChannel(address, this._maxExecutionTime);
+        return (address) => new NodeChannel(address, this.grpcDeadline);
     }
 
     /**

package/src/client/WebClient.js

@@ -27,52 +27,45 @@ export default class WebClient extends Client {
      */
     constructor(props) {
         super(props);
+
         if (props != null) {
             if (typeof props.network === "string") {
-                switch (props.network) {
+                this._setNetworkFromName(props.network);
+            } else if (props.network != null) {
+                Client._validateNetworkConsistency(props.network);
+
+                const { shard, realm } = Client._extractShardRealm(
+                    props.network,
+                );
+
+                // Shard and realm are inferred from the network, so we need to set them here
+                // to ensure that the client is properly configured.
+                this._shard = shard;
+                this._realm = realm;
+
+                this.setNetwork(props.network);
+            }
+
+            if (typeof props.mirrorNetwork === "string") {
+                switch (props.mirrorNetwork) {
                     case "mainnet":
-                        this.setNetwork(WebNetwork.MAINNET);
                         this.setMirrorNetwork(WebMirrorNetwork.MAINNET);
-                        this.setLedgerId(LedgerId.MAINNET);
                         break;
 
                     case "testnet":
-                        this.setNetwork(WebNetwork.TESTNET);
-                        this.setLedgerId(LedgerId.TESTNET);
                         this.setMirrorNetwork(WebMirrorNetwork.TESTNET);
                         break;
 
                     case "previewnet":
-                        this.setNetwork(WebNetwork.PREVIEWNET);
-                        this.setLedgerId(LedgerId.PREVIEWNET);
                         this.setMirrorNetwork(WebMirrorNetwork.PREVIEWNET);
                         break;
 
-                    case "local-node":
-                        this.setNetwork(WebNetwork.LOCAL_NODE);
-                        this.setLedgerId(LedgerId.LOCAL_NODE);
-                        this.setMirrorNetwork(WebMirrorNetwork.LOCAL_NODE);
-                        break;
-
                     default:
-                        throw new Error(
-                            // eslint-disable-next-line @typescript-eslint/restrict-template-expressions
-                            `unknown network: ${props.network}`,
-                        );
+                        this.setMirrorNetwork([props.mirrorNetwork]);
+                        break;
                 }
-            } else if (props.network != null) {
-                Client._validateNetworkConsistency(props.network);
-
-                const { shard, realm } = Client._extractShardRealm(
-                    props.network,
-                );
-
-                // Shard and realm are inferred from the network, so we need to set them here
-                // to ensure that the client is properly configured.
-                this._shard = shard;
-                this._realm = realm;
-
-                this.setNetwork(props.network);
+            } else if (props.mirrorNetwork != null) {
+                this.setMirrorNetwork(props.mirrorNetwork);
             }
         }
     }
@@ -249,6 +242,19 @@ export default class WebClient extends Client {
                     break;
             }
         } else {
+            // Check for deprecation warnings for network endpoints with schemes
+            for (const [key] of Object.entries(network)) {
+                if (key.startsWith("https://") || key.startsWith("http://")) {
+                    console.warn(
+                        '[Deprecation Notice] Hiero SDK: Network endpoint "' +
+                            key +
+                            '" includes a URL scheme (e.g. "https://"). ' +
+                            "This format was accepted in earlier versions but is now deprecated. " +
+                            'Please remove the scheme and use "host:port" instead (e.g. "node00.swirldslabs.com:443"). ' +
+                            "Support for scheme-prefixed endpoints will be removed in a future major release.",
+                    );
+                }
+            }
             this._network.setNetwork(network);
         }
     }
@@ -282,6 +288,46 @@ export default class WebClient extends Client {
         return this;
     }
 
+    /**
+     * @private
+     * @param {string} name
+     * @returns {this}
+     */
+    _setNetworkFromName(name) {
+        switch (name) {
+            case "mainnet":
+                this.setNetwork(WebNetwork.MAINNET);
+                this.setMirrorNetwork(WebMirrorNetwork.MAINNET);
+                this.setLedgerId(LedgerId.MAINNET);
+                break;
+
+            case "testnet":
+                this.setNetwork(WebNetwork.TESTNET);
+                this.setMirrorNetwork(WebMirrorNetwork.TESTNET);
+                this.setLedgerId(LedgerId.TESTNET);
+                break;
+
+            case "previewnet":
+                this.setNetwork(WebNetwork.PREVIEWNET);
+                this.setMirrorNetwork(WebMirrorNetwork.PREVIEWNET);
+                this.setLedgerId(LedgerId.PREVIEWNET);
+                break;
+
+            case "local-node":
+                this.setNetwork(WebNetwork.LOCAL_NODE);
+                this.setMirrorNetwork(WebMirrorNetwork.LOCAL_NODE);
+                this.setLedgerId(LedgerId.LOCAL_NODE);
+                break;
+
+            default:
+                throw new Error(
+                    // eslint-disable-next-line @typescript-eslint/restrict-template-expressions
+                    `unknown network: ${name}`,
+                );
+        }
+        return this;
+    }
+
     /**
      * @override
      * @returns {Promise<this>}
@@ -331,7 +377,7 @@ export default class WebClient extends Client {
      * @returns {(address: string) => WebChannel}
      */
     _createNetworkChannel() {
-        return (address) => new WebChannel(address);
+        return (address) => new WebChannel(address, this.grpcDeadline);
     }
 
     /**