Crate reconnecting_jsonrpsee_ws_client

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

• MethodResult
  Method result.
• SubscriptionResult
  Subscription result.