jsonrpsee-tcp

The jsonrpsee framework only provides HTTP and WebSocket server implementations by default. reth/ipc provides IPC server and client implementations. For scenarios that require TCP server implementation, this library provides both TCP server and client implementations.

Features

• ✅ TCP server implementation
• ✅ TCP client implementation
• ✅ Support for both synchronous and asynchronous method registration
• ✅ Support for subscriptions
• ✅ Full JSON-RPC 2.0 protocol support
• ✅ Built on tokio async runtime

Installation

Add the dependency to your Cargo.toml:

[dependencies]
jsonrpsee-tcp = "0.1.0"
jsonrpsee = "0.24"
tokio = { version = "1.0", features = ["full"] }

Usage Examples

Server

use jsonrpsee::types::Params;
use jsonrpsee_tcp::server::Builder;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let server = Builder::new()
        .register_method("say_hello", |params: Params, _ctx: &()| {
            let name: String = params.one()?;
            Ok(format!("Hello, {}!", name))
        })?
        .register_method("add", |params: Params, _ctx: &()| {
            let params: (i32, i32) = params.parse()?;
            Ok(params.0 + params.1)
        })?
        .build("127.0.0.1:9944".parse()?)
        .await?;

    println!("TCP server listening on {}", server.local_addr());
    server.run().await?;
    Ok(())
}

Client

use jsonrpsee_tcp::client::Client;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = Client::connect("127.0.0.1:9944".parse()?).await?;

    // Call methods
    let response: String = client.request("say_hello", vec!["World"]).await?;
    println!("Response: {}", response);

    let sum: i32 = client.request("add", vec![5, 3]).await?;
    println!("Sum: {}", sum);

    Ok(())
}

Subscriptions

use jsonrpsee::core::server::SubscriptionMessage;
use jsonrpsee::types::Params;
use jsonrpsee_tcp::server::Builder;
use tokio::time::{interval, Duration};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let server = Builder::new()
        .register_subscription(
            "subscribe_hello",
            "hello",
            "unsubscribe_hello",
            |_params, pending, _ctx, _ext| async move {
                let sink = match pending.accept().await {
                    Ok(sink) => sink,
                    Err(_) => return,
                };
                
                let mut interval = interval(Duration::from_secs(2));
                let mut counter = 0;
                
                loop {
                    interval.tick().await;
                    counter += 1;
                    
                    let message = format!("Hello #{}", counter);
                    if sink.send(SubscriptionMessage::from(message)).await.is_err() {
                        break;
                    }
                    
                    if counter >= 10 {
                        break;
                    }
                }
            },
        )?
        .build("127.0.0.1:9945".parse()?)
        .await?;

    server.run().await?;
    Ok(())
}

Running Examples

Start the server:

cargo run --example server

Run the client in another terminal:

cargo run --example client

Or test using the nc command:

nc localhost 9944
{"jsonrpc":"2.0","method":"say_hello","params":["World"],"id":1}

You can also run the subscription example:

cargo run --example subscription_server

API Documentation

Server API

• Builder::new() - Create a new server builder
• Builder::register_method() - Register a synchronous method
• Builder::register_async_method() - Register an asynchronous method
• Builder::register_subscription() - Register a subscription
• Builder::register_subscription_raw() - Register a subscription (raw version)
• Builder::merge() - Merge another RpcModule
• Builder::build() - Build and start the server
• Server::run() - Run the server and accept connections

Client API

• Client::connect() - Connect to a TCP server
• Client::request() - Send a JSON-RPC request
• Client::request_no_params() - Send a request without parameters

Protocol

Uses the standard JSON-RPC 2.0 protocol, with each request and response separated by a newline character (\n).

Request format:

{"jsonrpc":"2.0","method":"method_name","params":[...], "id":1}

Response format:

{"jsonrpc":"2.0","result":"...", "id":1}

Error response:

{"jsonrpc":"2.0","error":{"code":-32603,"message":"Internal error"},"id":1}

License

MIT