@iota/client-load-balancer
v1.0.2
Published
IOTA JavaScript Client Load Balancer
Downloads
10
Readme
About
The Client Load Balancer is a utility package for sending commands to a list of nodes instead of just a single provider.
This package is compatible with the IOTA JavaScript client library and mam.client.js.
There is a separate branch https://github.com/iotaledger/client-load-balancer/tree/no-mam which contains a version of this library for use with mam.js. This branch removes all the MAM specific methods and references as mam.js
utilises the regular composeAPI
for its communications.
Features include:
Snapshot aware option which tries alternate nodes if getTrytes returns all 9s for result.
Node list walk strategies:
Linear - Walks the list of nodes sequentially
Random - Randomly picks a node from the list
Custom - Create your own walk strategy
Success mode for when an operation completes successfully:
Keep - Keep using the same node until it fails.
Next - Always step to the next node.
Fail mode for when a node does not respond or returns error:
Single - Fails the whole call after a single failure.
All - Tries all the nodes until one succeeds.
Timeout for non-responsive nodes.
Blacklist limit, nodes failing a number of times are longer used until all nodes exhausted.
Settings available on a per node or global level:
- Minimum weight magnitude
- Depth
- AttachToTangle
- TimeoutMs
This is beta software, so there may be performance and stability issues. Please report any issues in our issue tracker.
Prerequisites
To use the Client Load Balancer in your own applications, you need Node.js installed on your device.
To check if you have Node.js installed, run the following command:
node -v
If Node.js is installed, you should see the version that's installed.
Installation
To install this package, use one of the following commands:
npm install iotaledger/client-load-balancer
yarn add iotaledger/client-load-balancer
Getting started
To jump in now, see the following code sample:
const { composeAPI, FailMode, RandomWalkStrategy, SuccessMode } = require('@iota/client-load-balancer');
(async function () {
try {
const api = composeAPI({
nodeWalkStrategy: new RandomWalkStrategy(
[
{
"provider": "https://altnodes.devnet.iota.org:443",
"depth": 3,
"mwm": 9
},
{
"provider": "https://nodes.devnet.iota.org:443",
"depth": 3,
"mwm": 9
}
]
),
successMode: SuccessMode.next,
failMode: FailMode.all,
timeoutMs: 5000,
tryNodeCallback: (node) => {
console.log(`Trying node ${node.provider}`);
},
failNodeCallback: (node, err) => {
console.log(`Failed node ${node.provider}, ${err.message}`);
}
});
const res = await api.getNodeInfo();
console.log("App Name:", res.appName);
console.log("App Version:", res.appVersion);
} catch (err) {
console.error(`Error: ${err.message}`);
}
})();
Will output:
Trying node https://nodes.devnet.iota.org:443
App Name: IRI Testnet
App Version: 1.5.6-RELEASE
MWM and Depth
The mwm
and depth
parameters can be set at multiple levels within the configuration. You can specify them at a node level, but they are optional.
{
provider: "https://altnodes.devnet.iota.org:443",
depth?: 3,
mwm?: 9
}
If you don't specify them for each node you can set them at the top level load balancer settings.
const api = composeAPI({
nodeWalkStrategy: ...,
depth?: 3,
mwm?: 9
});
Or you can just provide them when calling the regular methods that require them.
const iota = composeAPI(loadBalancerSettings);
const trytes = await iota.prepareTransfers(seed, transfers, options);
await iota.sendTrytes(trytes, 3, 9);
If you want methods like sendTrytes
to use the values from the configuration just pass undefined
instead, in JavaScript
you can skip the parameters altogether but TypeScript
will require some values, hence undefined
.
In this case of undefined
parameters the code will first look at the configuration for the node that it is currently using, if that does not provide values it uses the load balancer settings. If they are not provided the defaults are depth=3
and mwm=9
await iota.sendTrytes(trytes, undefined, undefined);
API Reference
See the JavaScript API reference.
Supporting the project
If you want to contribute, consider submitting a bug report, feature request or a pull request.
See our contributing guidelines for more information.
Joining the discussion
If you want to get involved in the community, need help with getting set up, have any issues or just want to discuss IOTA, Distributed Registry Technology (DRT), and IoT with other people, feel free to join our Discord.