Crate pivx_throttled_jsonrpc 

Throttled JSON-RPC Client

A macro-based JSON-RPC client generator with built-in rate limiting, concurrency control, and request batching.

Features

• Declarative API: Define your RPC client with a simple macro syntax
• Rate Limiting: Control requests-per-second (RPS) to avoid overwhelming servers
• Concurrency Control: Limit simultaneous in-flight requests
• Request Batching: Efficiently batch multiple RPC calls
• Flexible Response Types: Support for both single-type and enum variant responses

Throttling Behavior

This library provides synchronous/blocking throttling using std::thread::sleep:

Rate Limiting (RPS)

• When: rps > 0
• How: Enforces minimum time 1/rps seconds between consecutive requests
• Behavior: Thread sleeps if previous request was too recent
• Scope: Global across all threads using the same client instance

Concurrency Limiting

• When: max_concurrency > 0
• How: Limits number of simultaneous in-flight requests
• Behavior: Thread blocks (via Condvar) until a slot is available
• Scope: Global across all threads using the same client instance

Important Notes

• This is a blocking/synchronous client - threads will sleep/block
• For async workloads, consider wrapping calls in tokio::task::spawn_blocking
• Timeouts are controlled by the underlying reqwest client (default: 30s connect, no read timeout)

Example

use throttled_json_rpc::jsonrpc_client;

jsonrpc_client!(pub struct MyRpcClient {
    single:
        /// Get block hash by height
        pub fn getblockhash(&self, height: u64) -> Result<String>;
    enum:
});

let client = MyRpcClient::new(
    "http://localhost:8332".to_string(),
    Some("rpcuser".to_string()),
    Some("rpcpass".to_string()),
    5,    // max 5 concurrent requests
    10,   // max 10 requests per second
    0,    // no batching (0 = disabled)
);

let block_hash = client.getblockhash(100)?;
println!("Block hash: {}", block_hash);

Macros

jsonrpc_client

Enums

RpcError

Error types for JSON-RPC operations