postchain-client 2.1.3 → 2.1.5

package/README.md

@@ -43,6 +43,8 @@ Create a Chromia client instance and configures it according to your needs.
 - `settings` (Object): A set of network settings to customize the behavior of the Chromia client.
   - `nodeUrlPool` (Optional): An array of URLs representing the nodes the client will send requests to. Use this if you know the specific nodes that will handle the client requests. These nodes can either be local nodes or belong to the same cluster as the targeted blockchain.
   - `directoryNodeUrlPool` (Optional): An array of URLs representing nodes in the system cluster, where the directory chain is located. The client will automatically discover every node running the targeted application by querying the directory chain. This can be useful when the client needs to automatically adapt to updates to the nodes within the cluster where the blockchain is located."
+  - `blockedNodeUrlSubstrings` (Optional): Opt-in node URL filtering. If configured, URLs containing any listed substring are excluded (case-insensitive). By default this is disabled, so existing behavior is unchanged.
+  - `nodeUrlFilter` (Optional): Opt-in custom predicate `(url: string) => boolean` used to accept/reject node URLs. If both `blockedNodeUrlSubstrings` and `nodeUrlFilter` are set, a URL is used only when it passes both filters.
   - `blockchainRid` (Optional): Resource Identifier (Rid) of the targeted blockchain. This is a unique identifier for the specific blockchain.
   - `blockchainIid` (Optional): Instance Identifier (Iid) of the targeted blockchain. The directory chain always has Iid 0.
   - `statusPollInterval` (Optional): Interval (in milliseconds) at which the client will poll the status after posting a transaction.
@@ -54,6 +56,12 @@ Create a Chromia client instance and configures it according to your needs.
     - `unreachableDuration` (Optional): Duration (in milliseconds) that an endpoint should remain unreachable before reattempting. Defaults to 30000 ms.
   - `useStickyNode`(Optional): A boolean that will make sure that on succefull requests to a node, the client will continue using this node unless it starts failing.
 
+### Optional node URL filtering (opt-in)
+
+Node URL filtering is disabled by default for backward compatibility. Existing users do not need to change anything.
+
+If you opt in by configuring `blockedNodeUrlSubstrings` and/or `nodeUrlFilter`, filtering is applied consistently to direct node pools, directory node pools, and directory-discovered blockchain API URLs before failover candidates are used.
+
 ### Returns
 
 A promise that resolves to the configured Chromia client instance.

package/built/cjs/index.js

@@ -1120,7 +1120,7 @@ var utils$1 = {};
 var errors = {};
 
 Object.defineProperty(errors, "__esModule", { value: true });
-errors.GetBridFromChainException = errors.SerializedTransactionFormatException = errors.InvalidTxRidException = errors.UnexpectedStatusError = errors.TxRejectedError = errors.GetTransactionRidException = errors.InvalidTransactionFormatException = errors.DirectoryNodeUrlPoolException = errors.BlockchainUrlUndefinedException = errors.MissingNodeUrlError = errors.MissingBlockchainIdentifierError = errors.MissingPubKeyError = void 0;
+errors.GetBridFromChainException = errors.SerializedTransactionFormatException = errors.InvalidTxRidException = errors.UnexpectedStatusError = errors.TxRejectedError = errors.GetTransactionRidException = errors.InvalidTransactionFormatException = errors.FilteredNodeUrlPoolEmptyError = errors.DirectoryNodeUrlPoolException = errors.BlockchainUrlUndefinedException = errors.MissingNodeUrlError = errors.MissingBlockchainIdentifierError = errors.MissingPubKeyError = void 0;
 const customError_1 = customError;
 const formatter_1$1 = formatter;
 class MissingPubKeyError extends customError_1.CustomError {
@@ -1154,6 +1154,12 @@ class DirectoryNodeUrlPoolException extends customError_1.CustomError {
     }
 }
 errors.DirectoryNodeUrlPoolException = DirectoryNodeUrlPoolException;
+class FilteredNodeUrlPoolEmptyError extends customError_1.CustomError {
+    constructor(poolName) {
+        super(`All node URLs were filtered out for pool "${poolName}". Update node URL filters or pool configuration.`, 400);
+    }
+}
+errors.FilteredNodeUrlPoolEmptyError = FilteredNodeUrlPoolEmptyError;
 class InvalidTransactionFormatException extends customError_1.CustomError {
     constructor() {
         super(`The transaction is not in the right format`, 400);
@@ -2481,23 +2487,9 @@ function requireUtils$1 () {
 		                responseTimeout: settings.responseTimeout,
 		            });
 		        }))();
-		        return {
-		            endpointPool,
-		            nodeManager: nodeManager,
-		            blockchainRid: blockchainRidToUse,
-		            merkleHashVersion: (_e = settings.merkleHashVersion) !== null && _e !== void 0 ? _e : constants_1.MERKLE_HASH_VERSIONS.UNSET,
-		            dappStatusPolling: setStatusPolling(settings.dappStatusPolling),
-		            clusterAnchoringStatusPolling: setStatusPolling(settings.clusterAnchoringStatusPolling),
-		            systemAnchoringStatusPolling: setStatusPolling(settings.systemAnchoringStatusPolling),
-		            retryTransactionPolling: setRetryTransactionPolling(settings.retryTransactionPolling),
-		            failoverStrategy: ((_f = settings.failOverConfig) === null || _f === void 0 ? void 0 : _f.strategy) || exports.defaultFailoverConfig.strategy,
-		            attemptsPerEndpoint: ((_g = settings.failOverConfig) === null || _g === void 0 ? void 0 : _g.attemptsPerEndpoint) || exports.defaultFailoverConfig.attemptsPerEndpoint,
-		            attemptInterval: ((_h = settings.failOverConfig) === null || _h === void 0 ? void 0 : _h.attemptInterval) || exports.defaultFailoverConfig.attemptInterval,
-		            unreachableDuration: ((_j = settings.failOverConfig) === null || _j === void 0 ? void 0 : _j.unreachableDuration) || exports.defaultFailoverConfig.unreachableDuration,
-		            directoryChainRid: settings.directoryChainRid || directoryChainRid,
-		            connectTimeout: settings.connectTimeout,
-		            responseTimeout: settings.responseTimeout,
-		        };
+		        return Object.assign(Object.assign(Object.assign({ endpointPool, nodeManager: nodeManager }, (settings.blockedNodeUrlSubstrings !== undefined
+		            ? { blockedNodeUrlSubstrings: settings.blockedNodeUrlSubstrings }
+		            : {})), (settings.nodeUrlFilter !== undefined ? { nodeUrlFilter: settings.nodeUrlFilter } : {})), { blockchainRid: blockchainRidToUse, merkleHashVersion: (_e = settings.merkleHashVersion) !== null && _e !== void 0 ? _e : constants_1.MERKLE_HASH_VERSIONS.UNSET, dappStatusPolling: setStatusPolling(settings.dappStatusPolling), clusterAnchoringStatusPolling: setStatusPolling(settings.clusterAnchoringStatusPolling), systemAnchoringStatusPolling: setStatusPolling(settings.systemAnchoringStatusPolling), retryTransactionPolling: setRetryTransactionPolling(settings.retryTransactionPolling), failoverStrategy: ((_f = settings.failOverConfig) === null || _f === void 0 ? void 0 : _f.strategy) || exports.defaultFailoverConfig.strategy, attemptsPerEndpoint: ((_g = settings.failOverConfig) === null || _g === void 0 ? void 0 : _g.attemptsPerEndpoint) || exports.defaultFailoverConfig.attemptsPerEndpoint, attemptInterval: ((_h = settings.failOverConfig) === null || _h === void 0 ? void 0 : _h.attemptInterval) || exports.defaultFailoverConfig.attemptInterval, unreachableDuration: ((_j = settings.failOverConfig) === null || _j === void 0 ? void 0 : _j.unreachableDuration) || exports.defaultFailoverConfig.unreachableDuration, directoryChainRid: settings.directoryChainRid || directoryChainRid, connectTimeout: settings.connectTimeout, responseTimeout: settings.responseTimeout });
 		    });
 		}
 		function getMerkleHashVersionFromDapp(config) {
@@ -2523,7 +2515,7 @@ function requireUtils$1 () {
 		    return true;
 		}
 		function nodeDiscovery(_a) {
-		    return __awaiter(this, arguments, void 0, function* ({ nodeManager, directoryEndpointPool, failOverConfig, blockchainRid, blockchainIid, connectTimeout, responseTimeout, }) {
+		    return __awaiter(this, arguments, void 0, function* ({ nodeManager, directoryEndpointPool, blockedNodeUrlSubstrings, nodeUrlFilter, failOverConfig, blockchainRid, blockchainIid, connectTimeout, responseTimeout, }) {
 		        if (directoryEndpointPool.length === 0) {
 		            throw new errors_2.DirectoryNodeUrlPoolException();
 		        }
@@ -2559,7 +2551,11 @@ function requireUtils$1 () {
 		            nodeUrlPool: (0, exports.getUrlsFromEndpoints)(directoryEndpointPool),
 		            blockchainRid: directoryBRID,
 		        });
-		        return yield getBlockchainApiUrls(D1Client, (0, formatter_1.ensureBuffer)(blockchainRidToUse));
+		        const discoveredNodes = yield getBlockchainApiUrls(D1Client, (0, formatter_1.ensureBuffer)(blockchainRidToUse));
+		        return applyNodeUrlFilters(discoveredNodes, {
+		            blockedNodeUrlSubstrings,
+		            nodeUrlFilter,
+		        }, "discoveredNodeUrlPool");
 		    });
 		}
 		function getBlockchainApiUrls(directoryClient, blockchainRid) {
@@ -2702,14 +2698,21 @@ function requireUtils$1 () {
 		    return __awaiter(this, void 0, void 0, function* () {
 		        var _a;
 		        if (settings.directoryNodeUrlPool) {
+		            const directoryNodeUrlsOrNull = applyNodeUrlFilters(ensureArray(settings.directoryNodeUrlPool), settings, "directoryNodeUrlPool");
+		            if (directoryNodeUrlsOrNull === null) {
+		                throw new errors_2.DirectoryNodeUrlPoolException();
+		            }
+		            const directoryNodeUrls = directoryNodeUrlsOrNull;
 		            // If directoryNodeUrlPool is provided, use nodeDiscovery
 		            const nodeManager = (0, nodeManager_1.createNodeManager)({
-		                nodeUrls: ensureArray(settings.directoryNodeUrlPool),
+		                nodeUrls: directoryNodeUrls,
 		                unavailableDuration: (_a = settings.failOverConfig) === null || _a === void 0 ? void 0 : _a.unreachableDuration,
 		            });
 		            const discoveredNodes = yield nodeDiscovery({
 		                nodeManager,
-		                directoryEndpointPool: (0, exports.createEndpointObjects)(ensureArray(settings.directoryNodeUrlPool)),
+		                directoryEndpointPool: (0, exports.createEndpointObjects)(directoryNodeUrls),
+		                blockedNodeUrlSubstrings: settings.blockedNodeUrlSubstrings,
+		                nodeUrlFilter: settings.nodeUrlFilter,
 		                failOverConfig: settings.failOverConfig,
 		                blockchainRid: settings.blockchainRid,
 		                blockchainIid: settings.blockchainIid,
@@ -2720,11 +2723,11 @@ function requireUtils$1 () {
 		        }
 		        else if (typeof settings.nodeUrlPool === "string") {
 		            // If nodeUrlPool is a string, convert it to an array
-		            return [settings.nodeUrlPool];
+		            return applyNodeUrlFilters([settings.nodeUrlPool], settings, "nodeUrlPool");
 		        }
 		        else if (Array.isArray(settings.nodeUrlPool)) {
 		            // If nodeUrlPool is already an array, use it as-is
-		            return settings.nodeUrlPool;
+		            return applyNodeUrlFilters(settings.nodeUrlPool, settings, "nodeUrlPool");
 		        }
 		        else {
 		            // Default to an empty array if no valid configuration is provided
@@ -2732,11 +2735,37 @@ function requireUtils$1 () {
 		        }
 		    });
 		}
-		function getSystemClient(directoryNodeUrlPool, directoryChainRid) {
+		function applyNodeUrlFilters(nodeUrls, settings, poolName) {
+		    var _a;
+		    if (nodeUrls === null) {
+		        return null;
+		    }
+		    const hasBlockedSubstringsFilter = Array.isArray(settings.blockedNodeUrlSubstrings) &&
+		        settings.blockedNodeUrlSubstrings.length > 0;
+		    const hasNodeUrlFilter = typeof settings.nodeUrlFilter === "function";
+		    if (!hasBlockedSubstringsFilter && !hasNodeUrlFilter) {
+		        return nodeUrls;
+		    }
+		    const blockedSubstrings = ((_a = settings.blockedNodeUrlSubstrings) !== null && _a !== void 0 ? _a : [])
+		        .map(substring => substring.toLowerCase())
+		        .filter(substring => substring.length > 0);
+		    const filteredNodeUrls = nodeUrls.filter(url => {
+		        const isBlockedBySubstring = blockedSubstrings.some(substring => url.toLowerCase().includes(substring));
+		        const passesCustomFilter = settings.nodeUrlFilter ? settings.nodeUrlFilter(url) : true;
+		        return !isBlockedBySubstring && passesCustomFilter;
+		    });
+		    if (filteredNodeUrls.length === 0) {
+		        throw new errors_2.FilteredNodeUrlPoolEmptyError(poolName);
+		    }
+		    return filteredNodeUrls;
+		}
+		function getSystemClient(directoryNodeUrlPool, directoryChainRid, blockedNodeUrlSubstrings, nodeUrlFilter) {
 		    return __awaiter(this, void 0, void 0, function* () {
 		        return yield (0, blockchainClient_1.createClient)({
 		            directoryNodeUrlPool,
 		            blockchainRid: directoryChainRid,
+		            blockedNodeUrlSubstrings,
+		            nodeUrlFilter,
 		        });
 		    });
 		}
@@ -2865,16 +2894,16 @@ function requireUtils$1 () {
 		}
 		function getAnchoringClientAndSystemChainRid(client) {
 		    return __awaiter(this, void 0, void 0, function* () {
-		        const directoryClient = yield getSystemClient((0, exports.getUrlsFromEndpoints)(client.config.endpointPool), client.config.directoryChainRid);
+		        const directoryClient = yield getSystemClient((0, exports.getUrlsFromEndpoints)(client.config.endpointPool), client.config.directoryChainRid, client.config.blockedNodeUrlSubstrings, client.config.nodeUrlFilter);
 		        const anchoringClient = yield (0, IccfProofTxMaterialBuilder_1.getAnchoringClient)(directoryClient, client.config.blockchainRid);
 		        const systemAnchoringChainRidBuffer = yield getSystemAnchoringChain(directoryClient);
 		        const systemAnchoringChainBridString = systemAnchoringChainRidBuffer.toString("hex");
 		        return { anchoringClient, systemAnchoringChainBridString };
 		    });
 		}
-		function getSystemAnchoringTransaction(dappClientEndpointPool, anchoredTxRid, anchoringClient, systemAnchoringChainRid, systemAnchoringStatusPolling, merkleHashVersion) {
+		function getSystemAnchoringTransaction(dappClientEndpointPool, anchoredTxRid, anchoringClient, systemAnchoringChainRid, systemAnchoringStatusPolling, merkleHashVersion, blockedNodeUrlSubstrings, nodeUrlFilter) {
 		    return __awaiter(this, void 0, void 0, function* () {
-		        const systemAnchoringChainClient = yield getSystemClient((0, exports.getUrlsFromEndpoints)(dappClientEndpointPool), systemAnchoringChainRid);
+		        const systemAnchoringChainClient = yield getSystemClient((0, exports.getUrlsFromEndpoints)(dappClientEndpointPool), systemAnchoringChainRid, blockedNodeUrlSubstrings, nodeUrlFilter);
 		        const clusterAnchoringProof = yield anchoringClient.getConfirmationProof(anchoredTxRid);
 		        const clusterBlockRid = (0, utils_1.calculateBlockRID)(clusterAnchoringProof, merkleHashVersion);
 		        const systemAnchoringTransactionConfirmation = yield (0, utils_1.awaitGetAnchoringTransactionForBlockRid)(systemAnchoringChainClient, (0, formatter_1.toBuffer)(anchoringClient.config.blockchainRid), clusterBlockRid, systemAnchoringStatusPolling);
@@ -3250,6 +3279,8 @@ function requireIccfProofTxMaterialBuilder () {
 	                blockchainRid: (0, formatter_1.ensureString)(sourceBlockchainRid),
 	                merkleHashVersion: merkleHashVersion,
 	                useStickyNode: true,
+	                blockedNodeUrlSubstrings: directoryClient.config.blockedNodeUrlSubstrings,
+	                nodeUrlFilter: directoryClient.config.nodeUrlFilter,
 	            });
 	        }
 	        else {
@@ -3258,6 +3289,8 @@ function requireIccfProofTxMaterialBuilder () {
 	                blockchainRid: (0, formatter_1.ensureString)(sourceBlockchainRid),
 	                merkleHashVersion: merkleHashVersion,
 	                useStickyNode: true,
+	                blockedNodeUrlSubstrings: directoryClient.config.blockedNodeUrlSubstrings,
+	                nodeUrlFilter: directoryClient.config.nodeUrlFilter,
 	            });
 	        }
 	        const txProof = yield clientConfiguredToSource.getConfirmationProof(txToProveRid);
@@ -4036,7 +4069,7 @@ function requireBlockchainClient () {
 	                    }
 	                    result.status = enums_1.AnchoringStatus.ClusterAnchored;
 	                    result.clusterAnchoredTx = anchoringTransactionValidation.data;
-	                    const systemAnchoredTransaction = yield (0, utils_1.getSystemAnchoringTransaction)(config.endpointPool, anchoringTransactionValidation.data.txRid, anchoringClient, systemAnchoringChainRid, config.systemAnchoringStatusPolling, config.merkleHashVersion);
+	                    const systemAnchoredTransaction = yield (0, utils_1.getSystemAnchoringTransaction)(config.endpointPool, anchoringTransactionValidation.data.txRid, anchoringClient, systemAnchoringChainRid, config.systemAnchoringStatusPolling, config.merkleHashVersion, config.blockedNodeUrlSubstrings, config.nodeUrlFilter);
 	                    if (!systemAnchoredTransaction) {
 	                        return result;
 	                    }
@@ -4266,7 +4299,7 @@ function requireBlockchainClient () {
 	                        callback === null || callback === void 0 ? void 0 : callback(error, null);
 	                        throw error;
 	                    }
-	                    const systemAnchoringTransactionTransaction = yield (0, utils_1.getSystemAnchoringTransaction)(config.endpointPool, anchoredTxRid, anchoringClient, systemAnchoringChainRid, config.systemAnchoringStatusPolling, config.merkleHashVersion);
+	                    const systemAnchoringTransactionTransaction = yield (0, utils_1.getSystemAnchoringTransaction)(config.endpointPool, anchoredTxRid, anchoringClient, systemAnchoringChainRid, config.systemAnchoringStatusPolling, config.merkleHashVersion, config.blockedNodeUrlSubstrings, config.nodeUrlFilter);
 	                    return systemAnchoringTransactionTransaction;
 	                });
 	            },
@@ -4339,6 +4372,8 @@ function requireBlockchainClient () {
 	                    blockchainRid: client.config.blockchainRid,
 	                    merkleHashVersion: client.config.merkleHashVersion,
 	                    useStickyNode: true,
+	                    blockedNodeUrlSubstrings: client.config.blockedNodeUrlSubstrings,
+	                    nodeUrlFilter: client.config.nodeUrlFilter,
 	                });
 	                return stickyNodeClient;
 	            });