Crate robust_provider 

Robust, retrying wrapper around Alloy providers.

This module exposes RobustProvider, a small wrapper around Alloy’s RootProvider that adds:

• bounded per-call timeouts
• exponential backoff retries
• transparent failover between a primary and one or more fallback providers
• more robust WebSocket block subscriptions with automatic reconnection

Use RobustProviderBuilder to construct a provider with sensible defaults and optional fallbacks, or implement the IntoRobustProvider and IntoRootProvider traits to support custom providers.

How it works

All RPC calls performed through RobustProvider are wrapped in a total timeout and retried with exponential backoff up to max_retries. If the primary provider keeps failing, the call is retried against the configured fallback providers in the order they were added. For subscriptions, RobustSubscription also tracks lag, switches to fallbacks on repeated failure, and periodically attempts to reconnect to the primary provider.

Examples

Creating a robust WebSocket provider with a fallback:

use alloy::providers::{Provider, ProviderBuilder};
use robust_provider::RobustProviderBuilder;
use std::time::Duration;
use tokio_stream::StreamExt;

let ws = ProviderBuilder::new().connect("ws://localhost:8545").await?;
let ws_fallback = ProviderBuilder::new().connect("ws://localhost:8456").await?;

let robust = RobustProviderBuilder::new(ws)
    .fallback(ws_fallback)
    .call_timeout(Duration::from_secs(30))
    .subscription_timeout(Duration::from_secs(120))
    .build()
    .await?;

// Make RPC calls with automatic retries and fallback
let block_number = robust.get_block_number().await?;
println!("Current block: {}", block_number);

// Create subscriptions that automatically reconnect on failure
let sub = robust.subscribe_blocks().await?;
let mut stream = sub.into_stream();
while let Some(response) = stream.next().await {
    match response {
        Ok(block) => println!("New block: {:?}", block),
        Err(e) => println!("Got error: {:?}", e),
    }
}

You can also convert existing providers using IntoRobustProvider

Modules

macros

Macros

block_not_found_doc

Documentation string for BlockNotFound errors, for use in robust_rpc! macro calls.

Structs

RobustProvider

Provider wrapper with built-in retry and timeout mechanisms.

RobustProviderBuilder

Builder for constructing a RobustProvider.

RobustSubscription

A robust subscription wrapper that automatically handles provider failover and periodic reconnection attempts to the primary provider.

RobustSubscriptionStream

Enums

Error

Errors that can occur when using super::RobustProvider.

FailoverError

Low-level error related to RPC calls and failover logic.

Constants

DEFAULT_CALL_TIMEOUT

Default timeout used by RobustProvider

DEFAULT_MAX_RETRIES

Default maximum number of retry attempts.

DEFAULT_MIN_DELAY

Default base delay between retries.

DEFAULT_POLL_INTERVAL

Default polling interval for HTTP subscriptions.

DEFAULT_RECONNECT_INTERVAL

Default time interval between primary provider reconnection attempts

DEFAULT_SUBSCRIPTION_BUFFER_CAPACITY

Default subscription channel size.

DEFAULT_SUBSCRIPTION_TIMEOUT

Default timeout for subscriptions

Traits

IntoRobustProvider

Conversion trait for types that can be turned into a RobustProvider.

IntoRootProvider

Conversion trait for types that can be turned into an Alloy RootProvider.