Multi-node failover

Pass multiple Kubo RPC URLs to init(). Meshkit checks every node at startup and routes each operation to the first healthy one in priority order.

Basic setup

import { init } from '@ipfs-meshkit/meshkit';

const { meshkit } = await init({
  nodes: [
    'http://127.0.0.1:5001',           // primary (tried first)
    'https://backup.example.com:5001', // failover
  ],
});

console.log(meshkit.activeNodes);
// ['http://127.0.0.1:5001', 'https://backup.example.com:5001']

Local + remote failover

Combine a local daemon with a remote backup:

import { init, setupGracefulShutdown } from '@ipfs-meshkit/meshkit';

const { meshkit, localNode } = await init({
  localNode: true,
  nodes: ['https://backup.example.com:5001'],
});

setupGracefulShutdown(localNode);

The local node is prepended automatically and becomes the primary.

Authentication headers

If your Kubo node has RPC auth configured, pass headers to all nodes:

const { meshkit } = await init({
  nodes: ['https://kubo.example.com:5001'],
  headers: { Authorization: 'Bearer your-token' },
});

How failover works

• At init(), Meshkit calls the RPC health endpoint on every node concurrently.
• Unreachable or unhealthy nodes are dropped from the active list.
• upload, retrieve, pin, resolveName, and resolveAndRetrieve try nodes in order; the first success is returned.
• publishName, generateKey, and listKeys always use the primary node (index 0) because they require keystore access.
• If all nodes fail, a MeshkitError is thrown with .causes containing each node's error.

Checking active nodes

console.log(meshkit.activeNodes);
// readonly string[] — healthy nodes at init, in priority order

Note: activeNodes reflects health at init time. It does not update dynamically if a node goes down after startup.