reconnecting-jsonrpsee-ws-client 使用指南

介绍

reconnecting-jsonrpsee-ws-client 是一个 Rust 库，提供了自动重连功能的 JSON-RPC WebSocket 客户端实现。它基于 jsonrpsee 库构建，主要解决了 WebSocket 连接不稳定时的自动恢复问题。

主要特性：

• 自动处理 WebSocket 连接断开和重连
• 内置 JSON-RPC 2.0 协议支持
• 提供异步 API 接口
• 可配置的重连策略

安装

在 Cargo.toml 中添加依赖：

[dependencies]
reconnecting-jsonrpsee-ws-client = "0.1"
tokio = { version = "1.0", features = ["full"] }

基本使用方法

创建客户端

use reconnecting_jsonrpsee_ws_client::ClientBuilder;

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    let client = ClientBuilder::default()
        .build("wss://example.com/ws")
        .await?;
    
    Ok(())
}

发送 JSON-RPC 请求

let response: String = client.request("get_status", None).await?;
println!("Server status: {}", response);

处理通知

use jsonrpsee::core::client::Subscription;

let mut subscription: Subscription<String> = client.subscribe("subscribe_updates", None, "updates").await?;

while let Some(update) = subscription.next().await {
    println!("Received update: {:?}", update);
}

高级配置

自定义重连策略

use std::time::Duration;
use reconnecting_jsonrpsee-ws-client::ReconnectOptions;

let options = ReconnectOptions::new()
    .with_retry_policy(ReconnectOptions::retry_policy().with_max_retries(10))
    .with_delay(Duration::from_secs(5));

let client = ClientBuilder::default()
    .set_reconnect_options(options)
    .build("wss://example.com/ws")
    .await?;

自定义请求超时

use std::time::Duration;

let client = ClientBuilder::default()
    .request_timeout(Duration::from_secs(30))
    .build("wss://example.com/ws")
    .await?;

完整示例

以下是基于上述内容的完整示例代码：

use reconnecting_jsonrpsee_ws_client::ClientBuilder;
use jsonrpsee::core::client::Subscription;
use std::time::Duration;
use anyhow::Context;

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    // 创建带有自定义配置的客户端
    let client = ClientBuilder::default()
        .request_timeout(Duration::from_secs(10))
        // 配置重连策略：最大重试10次，每次间隔5秒
        .set_reconnect_options(
            ReconnectOptions::new()
                .with_retry_policy(ReconnectOptions::retry_policy().with_max_retries(10))
                .with_delay(Duration::from_secs(5))
        )
        .build("wss://example.com/ws")
        .await
        .context("Failed to create WebSocket client")?;

    // 发送请求获取服务器状态
    match client.request("get_status", None).await {
        Ok(status) => println!("Server status: {}", status),
        Err(e) => eprintln!("Failed to get server status: {}", e),
    }

    // 发送请求获取服务器版本
    let version: String = client.request("get_version", None).await?;
    println!("Server version: {}", version);

    // 订阅日志通知
    let mut sub: Subscription<String> = client.subscribe("subscribe_logs", None, "logs").await?;
    
    // 在单独的tokio任务中处理订阅消息
    tokio::spawn(async move {
        while let Some(log) = sub.next().await {
            match log {
                Ok(log) => println!("New log entry: {}", log),
                Err(e) => eprintln!("Error in subscription: {}", e),
            }
        }
    });

    // 保持主线程运行，直到收到Ctrl+C信号
    tokio::signal::ctrl_c().await?;
    println!("Shutting down...");
    
    Ok(())
}

错误处理

该库返回的错误类型实现了 std::error::Error trait，可以使用 anyhow 或 thiserror 等库进行错误处理。

match client.request("some_method", None).await {
    Ok(result) => println!("Success: {:?}", result),
    Err(e) => eprintln!("Error: {}", e),
}

注意事项

1. 确保 Tokio 运行时已正确初始化
2. WebSocket URL 应以 ws:// 或 wss:// 开头
3. 对于生产环境，建议配置合理的重连策略和超时时间
4. 订阅处理通常需要在单独的 Tokio 任务中运行
5. 使用 anyhow 或 thiserror 可以更好地处理嵌套错误

这个库特别适合需要长期保持 WebSocket 连接并处理 JSON-RPC 协议的场景，如区块链节点连接、实时数据监控等应用。