@hiero-ledger/sdk 2.76.0 → 2.78.0-beta.1

package/src/channel/Channel.js

@@ -1,7 +1,8 @@
 // SPDX-License-Identifier: Apache-2.0
 
-import * as HieroProto from "@hashgraph/proto";
+import * as HieroProto from "@hiero-ledger/proto";
 import * as utf8 from "../encoding/utf8.js";
+import { DEFAULT_GRPC_DEADLINE } from "../constants/ClientConstants.js";
 
 const { proto } = HieroProto;
 
@@ -12,8 +13,9 @@ const { proto } = HieroProto;
 export default class Channel {
     /**
      * @protected
+     * @param {number} [grpcDeadline] - The gRPC deadline in milliseconds
      */
-    constructor() {
+    constructor(grpcDeadline = DEFAULT_GRPC_DEADLINE) {
         /**
          * @protected
          * @type {?HieroProto.proto.CryptoService}
@@ -73,6 +75,28 @@ export default class Channel {
          * @type {?HieroProto.proto.AddressBookService}
          */
         this._addressBook = null;
+
+        /**
+         * @protected
+         * @type {number}
+         */
+        this._grpcDeadline = grpcDeadline;
+    }
+
+    /**
+     * Set the gRPC deadline for this channel
+     * @param {number} deadline - The deadline in milliseconds, or null to clear
+     */
+    setGrpcDeadline(deadline) {
+        this._grpcDeadline = deadline;
+    }
+
+    /**
+     * Get the gRPC deadline for this channel
+     * @returns {number}
+     */
+    get grpcDeadline() {
+        return this._grpcDeadline;
     }
 
     /**

package/src/channel/NativeChannel.js

@@ -4,19 +4,31 @@ import * as base64 from "../encoding/base64.native.js";
 import HttpError from "../http/HttpError.js";
 import HttpStatus from "../http/HttpStatus.js";
 import { SDK_NAME, SDK_VERSION } from "../version.js";
+import GrpcServiceError from "../grpc/GrpcServiceError.js";
+import GrpcStatus from "../grpc/GrpcStatus.js";
 
 export default class NativeChannel extends Channel {
     /**
      * @param {string} address
+     * @param {number=} grpcDeadline
      */
-    constructor(address) {
-        super();
+    constructor(address, grpcDeadline) {
+        super(grpcDeadline);
 
         /**
          * @type {string}
          * @private
          */
         this._address = address;
+
+        /**
+         * 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;
     }
 
     /**
@@ -27,6 +39,89 @@ export default class NativeChannel extends Channel {
         // do nothing
     }
 
+    /**
+     * 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.
+     *
+     * @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
+        }
+
+        const shouldUseHttps = !(
+            this._address.includes("localhost") ||
+            this._address.includes("127.0.0.1")
+        );
+
+        const address = shouldUseHttps
+            ? `https://${this._address}`
+            : `http://${this._address}`;
+
+        // Calculate remaining time until deadline
+        const timeoutMs = deadline.getTime() - Date.now();
+        if (timeoutMs <= 0) {
+            throw new GrpcServiceError(GrpcStatus.Timeout);
+        }
+
+        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-text",
+                    "x-user-agent": `${SDK_NAME}/${SDK_VERSION}`,
+                    "x-grpc-web": "1",
+                },
+                body: base64.encode(new Uint8Array(0)), // Empty body for health check
+                signal: abortController.signal,
+            });
+
+            clearTimeout(timeoutId);
+
+            // Check if response is successful (200) and has gRPC headers
+            if (response.status === 200) {
+                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 or no gRPC headers present
+            // This means the proxy might not be configured correctly or not running
+            throw new GrpcServiceError(GrpcStatus.Unavailable);
+        } catch (error) {
+            clearTimeout(timeoutId);
+
+            if (error instanceof Error && error.name === "AbortError") {
+                throw new GrpcServiceError(GrpcStatus.Timeout);
+            }
+
+            if (error instanceof GrpcServiceError) {
+                throw error;
+            }
+
+            // Network error - server is not reachable
+            throw new GrpcServiceError(GrpcStatus.Unavailable);
+        }
+    }
+
     /**
      * @override
      * @protected
@@ -36,7 +131,16 @@ export default class NativeChannel 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 {
+                // Wait for connection to be ready (similar to gRPC waitForReady)
+                await this._waitForReady(deadline);
+
                 const data = base64.encode(
                     new Uint8Array(encodeRequest(requestData)),
                 );
@@ -121,6 +225,11 @@ export default class NativeChannel extends Channel {
 
                 callback(null, unaryResponse);
             } catch (error) {
+                if (error instanceof GrpcServiceError) {
+                    callback(error, null);
+                    return;
+                }
+
                 callback(/** @type {Error} */ (error), null);
             }
         };

package/src/channel/NodeChannel.js

@@ -14,16 +14,15 @@ export default class NodeChannel extends Channel {
     /**
      * @internal
      * @param {string} address
-     * @param {number=} maxExecutionTime
+     * @param {number=} grpcDeadline
      */
-    constructor(address, maxExecutionTime) {
-        super();
+    constructor(address, grpcDeadline) {
+        super(grpcDeadline);
 
         /** @type {Client | null} */
         this._client = null;
 
         this.address = address;
-        this.maxExecutionTime = maxExecutionTime;
 
         const { ip, port } = this.parseAddress(address);
         this.nodeIp = ip;
@@ -146,9 +145,7 @@ export default class NodeChannel extends Channel {
             this._initializeClient()
                 .then(() => {
                     const deadline = new Date();
-                    const milliseconds = this.maxExecutionTime
-                        ? this.maxExecutionTime
-                        : 10000;
+                    const milliseconds = this.grpcDeadline;
                     deadline.setMilliseconds(
                         deadline.getMilliseconds() + milliseconds,
                     );

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,27 +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 {
-                // Check if address already contains a scheme
-                const hasScheme =
-                    this._address.startsWith("http://") ||
-                    this._address.startsWith("https://");
-
-                let address;
-                if (hasScheme) {
-                    // Use the address as-is if it already has a scheme
-                    address = this._address;
-                } else {
-                    // Only prepend scheme if none exists
-                    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);
 
-                    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
@@ -80,6 +241,7 @@ export default class WebChannel extends Channel {
                         HttpStatus._fromValue(response.status),
                     );
                     callback(error, null);
+                    return;
                 }
 
                 // Check headers for gRPC errors
@@ -93,6 +255,7 @@ export default class WebChannel extends Channel {
                     );
                     error.message = grpcMessage;
                     callback(error, null);
+                    return;
                 }
 
                 const responseBuffer = await response.arrayBuffer();
@@ -100,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);
     }
 
     /**