Crate reconnecting_jsonrpsee_ws_client

Expand description

§reconnecting-jsonrpsee-ws-client

Wrapper crate over the jsonrpsee ws client, which automatically reconnects under the hood; without that, one has to restart it. It supports a few retry strategies, such as exponential backoff, but it’s also possible to use custom strategies as long as it implements Iterator<Item = Duration>.

By default, the library is re-transmitting pending calls and re-establishing subscriptions that were closed until it’s successful when the connection was terminated, but it’s also possible to disable that and manage it yourself.

For instance, you may not want to re-subscribe to a subscription that has side effects or retries at all. Then the library exposes request_with_policy and subscribe_with_policy to support that

async fn run() {
   use reconnecting_jsonrpsee_ws_client::{Client, CallRetryPolicy, rpc_params};

   let client = Client::builder().build("ws://127.0.0.1:9944".to_string()).await.unwrap();
   let mut sub = client
       .subscribe_with_policy(
           "subscribe_lo".to_string(),
           rpc_params![],
           "unsubscribe_lo".to_string(),
           // Do not re-subscribe if the connection is closed.
           CallRetryPolicy::Retry,
       )
       .await
       .unwrap();
}

The tricky part is subscriptions, which may lose a few notifications when it’s re-connecting, it’s not possible to know which ones.

Lost subscription notifications may be very important to know in some cases, and then this library is not recommended to use.

There is one way to determine how long a reconnection takes:

async fn run() {
    use reconnecting_jsonrpsee_ws_client::{Client, CallRetryPolicy, rpc_params};

    let client = Client::builder().build("ws://127.0.0.1:9944".to_string()).await.unwrap();
    
    // Print when the RPC client starts to reconnect.
    tokio::spawn(async move {
       loop {
        client.reconnect_started().await;
        let now = std::time::Instant::now();
        client.reconnected().await;
        println!(
           "RPC client reconnection took `{} seconds`",
           now.elapsed().as_secs()
        );
       }
    });
}

Macros§

rpc_params: Convert the given values to a crate::params::ArrayParams as expected by a jsonrpsee Client (http or websocket).

Structs§

Client: JSON-RPC client that reconnects automatically and may loose subscription notifications when it reconnects.
ClientBuilder: Builder for Client.
ExponentialBackoff: A retry strategy driven by exponential back-off.
FibonacciBackoff: A retry strategy driven by the fibonacci series.
FixedInterval: A retry strategy driven by a fixed interval.
HeaderMap: A set of HTTP headers
PingConfig: Configuration for WebSocket ping/pong mechanism and it may be used to disconnect an inactive connection.
RpcParams: Serialized JSON-RPC params.
Subscription: Represent a single subscription.

Enums§

CallRetryPolicy: How to handle when a subscription or method call when the connection was closed.
Disconnect: An error that indicates the subscription was disconnected and may reconnect.
Error: Error that can occur when for a RPC call or subscription.
IdKind: JSON-RPC request object id data type.
RpcError: Error type.
SubscriptionId: Id of a subscription, communicated by the server.

Type Aliases§