Struct WebSocketClient

pub struct WebSocketClient { /* private fields */ }

Tendermint RPC client that provides access to all RPC functionality (including Event subscription) over a WebSocket connection.

The WebSocketClient itself is effectively just a handle to its driver The driver is the component of the client that actually interacts with the remote RPC over the WebSocket connection. The WebSocketClient can therefore be cloned into different asynchronous contexts, effectively allowing for asynchronous access to the driver.

It is the caller’s responsibility to spawn an asynchronous task in which to execute the WebSocketClientDriver::run method. See the example below.

Dropping Subscriptions will automatically terminate them (the WebSocketClientDriver detects a disconnected channel and removes the subscription from its internal routing table). When all subscriptions to a particular query have disconnected, the driver will automatically issue an unsubscribe request to the remote RPC endpoint.

Timeouts

The WebSocket client connection times out after 30 seconds if it does not receive anything at all from the server. This will automatically return errors to all active subscriptions and terminate them.

This is not configurable at present.

Keep-Alive

The WebSocket client implements a keep-alive mechanism whereby it sends a PING message to the server every 27 seconds, matching the PING cadence of the Tendermint server (see this code for details).

This is not configurable at present.

Examples

use tendermint::abci::Transaction;
use tendermint_rpc::{WebSocketClient, SubscriptionClient, Client};
use tendermint_rpc::query::EventType;
use futures::StreamExt;

#[tokio::main]
async fn main() {
    let (client, driver) = WebSocketClient::new("ws://127.0.0.1:26657/websocket")
        .await
        .unwrap();
    let driver_handle = tokio::spawn(async move { driver.run().await });

    // Standard client functionality
    let tx = format!("some-key=some-value");
    client.broadcast_tx_async(Transaction::from(tx.into_bytes())).await.unwrap();

    // Subscription functionality
    let mut subs = client.subscribe(EventType::NewBlock.into())
        .await
        .unwrap();

    // Grab 5 NewBlock events
    let mut ev_count = 5_i32;

    while let Some(res) = subs.next().await {
        let ev = res.unwrap();
        println!("Got event: {:?}", ev);
        ev_count -= 1;
        if ev_count < 0 {
            break;
        }
    }

    // Signal to the driver to terminate.
    client.close().unwrap();
    // Await the driver's termination to ensure proper connection closure.
    let _ = driver_handle.await.unwrap();
}

Implementations

impl WebSocketClient

pub async fn new<U>(url: U) -> Result<(Self, WebSocketClientDriver), Error>

where U: TryInto<WebSocketClientUrl, Error = Error>,

Construct a new WebSocket-based client connecting to the given Tendermint node’s RPC endpoint.

Supports both ws:// and wss:// protocols.

pub async fn new_with_config<U>( url: U, config: WebSocketConfig, ) -> Result<(Self, WebSocketClientDriver), Error>

where U: TryInto<WebSocketClientUrl, Error = Error>,

Construct a new WebSocket-based client connecting to the given Tendermint node’s RPC endpoint.

Supports both ws:// and wss:// protocols.

pub fn builder(url: WebSocketClientUrl) -> Builder

Initiate a builder for a WebSocket-based client connecting to the given Tendermint node’s RPC endpoint.

Supports both ws:// and wss:// protocols.

Trait Implementations

impl Client for WebSocketClient

fn perform<'life0, 'async_trait, R>( &'life0 self, request: R, ) -> Pin<Box<dyn Future<Output = Result<R::Output, Error>> + Send + 'async_trait>>

where R: SimpleRequest + 'async_trait, Self: 'async_trait, 'life0: 'async_trait,

Perform a request against the RPC endpoint.

fn block<'life0, 'async_trait, H>( &'life0 self, height: H, ) -> Pin<Box<dyn Future<Output = Result<Response, Error>> + Send + 'async_trait>>

where H: Into<Height> + Send + 'async_trait, Self: 'async_trait, 'life0: 'async_trait,

/block: get block at a given height.

fn block_by_hash<'life0, 'async_trait>( &'life0 self, hash: Hash, ) -> Pin<Box<dyn Future<Output = Result<Response, Error>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

/block_by_hash: get block by hash.

fn latest_block<'life0, 'async_trait>( &'life0 self, ) -> Pin<Box<dyn Future<Output = Result<Response, Error>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

/block: get the latest block.

fn block_results<'life0, 'async_trait, H>( &'life0 self, height: H, ) -> Pin<Box<dyn Future<Output = Result<Response, Error>> + Send + 'async_trait>>

where H: Into<Height> + Send + 'async_trait, Self: 'async_trait, 'life0: 'async_trait,

/block_results: get ABCI results for a block at a particular height.

fn latest_block_results<'life0, 'async_trait>( &'life0 self, ) -> Pin<Box<dyn Future<Output = Result<Response, Error>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

/block_results: get ABCI results for the latest block.

fn block_search<'life0, 'async_trait>( &'life0 self, query: Query, page: u32, per_page: u8, order: Order, ) -> Pin<Box<dyn Future<Output = Result<Response, Error>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

/block_search: search for blocks by BeginBlock and EndBlock events.

fn header<'life0, 'async_trait, H>( &'life0 self, height: H, ) -> Pin<Box<dyn Future<Output = Result<Response, Error>> + Send + 'async_trait>>

where H: Into<Height> + Send + 'async_trait, Self: 'async_trait, 'life0: 'async_trait,

/header: get block header at a given height.

fn header_by_hash<'life0, 'async_trait>( &'life0 self, hash: Hash, ) -> Pin<Box<dyn Future<Output = Result<Response, Error>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

/header_by_hash: get block by hash.

fn tx<'life0, 'async_trait>( &'life0 self, hash: Hash, prove: bool, ) -> Pin<Box<dyn Future<Output = Result<Response, Error>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

/tx: find transaction by hash.

fn tx_search<'life0, 'async_trait>( &'life0 self, query: Query, prove: bool, page: u32, per_page: u8, order: Order, ) -> Pin<Box<dyn Future<Output = Result<Response, Error>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

/tx_search: search for transactions with their results.

fn broadcast_tx_commit<'life0, 'async_trait, T>( &'life0 self, tx: T, ) -> Pin<Box<dyn Future<Output = Result<Response, Error>> + Send + 'async_trait>>

where T: Into<Vec<u8>> + Send + 'async_trait, Self: 'async_trait, 'life0: 'async_trait,

/broadcast_tx_commit: broadcast a transaction, returning the response from DeliverTx.

fn abci_info<'life0, 'async_trait>( &'life0 self, ) -> Pin<Box<dyn Future<Output = Result<Info, Error>> + Send + 'async_trait>>

where Self: Sync + 'async_trait, 'life0: 'async_trait,

/abci_info: get information about the ABCI application.

fn abci_query<'life0, 'async_trait, V>( &'life0 self, path: Option<String>, data: V, height: Option<Height>, prove: bool, ) -> Pin<Box<dyn Future<Output = Result<AbciQuery, Error>> + Send + 'async_trait>>

where V: Into<Vec<u8>> + Send + 'async_trait, Self: Sync + 'async_trait, 'life0: 'async_trait,

/abci_query: query the ABCI application

fn blockchain<'life0, 'async_trait, H>( &'life0 self, min: H, max: H, ) -> Pin<Box<dyn Future<Output = Result<Response, Error>> + Send + 'async_trait>>

where H: Into<Height> + Send + 'async_trait, Self: Sync + 'async_trait, 'life0: 'async_trait,

/blockchain: get block headers for min <= height <= max.

fn broadcast_tx_async<'life0, 'async_trait, T>( &'life0 self, tx: T, ) -> Pin<Box<dyn Future<Output = Result<Response, Error>> + Send + 'async_trait>>

where T: Into<Vec<u8>> + Send + 'async_trait, Self: Sync + 'async_trait, 'life0: 'async_trait,

/broadcast_tx_async: broadcast a transaction, returning immediately.

fn broadcast_tx_sync<'life0, 'async_trait, T>( &'life0 self, tx: T, ) -> Pin<Box<dyn Future<Output = Result<Response, Error>> + Send + 'async_trait>>

where T: Into<Vec<u8>> + Send + 'async_trait, Self: Sync + 'async_trait, 'life0: 'async_trait,

/broadcast_tx_sync: broadcast a transaction, returning the response from CheckTx.

fn commit<'life0, 'async_trait, H>( &'life0 self, height: H, ) -> Pin<Box<dyn Future<Output = Result<Response, Error>> + Send + 'async_trait>>

where H: Into<Height> + Send + 'async_trait, Self: Sync + 'async_trait, 'life0: 'async_trait,

/commit: get block commit at a given height.

fn consensus_params<'life0, 'async_trait, H>( &'life0 self, height: H, ) -> Pin<Box<dyn Future<Output = Result<Response, Error>> + Send + 'async_trait>>

where H: Into<Height> + Send + 'async_trait, Self: Sync + 'async_trait, 'life0: 'async_trait,

/consensus_params: get current consensus parameters at the specified height.

fn consensus_state<'life0, 'async_trait>( &'life0 self, ) -> Pin<Box<dyn Future<Output = Result<Response, Error>> + Send + 'async_trait>>

where Self: Sync + 'async_trait, 'life0: 'async_trait,

/consensus_state: get current consensus state

fn validators<'life0, 'async_trait, H>( &'life0 self, height: H, paging: Paging, ) -> Pin<Box<dyn Future<Output = Result<Response, Error>> + Send + 'async_trait>>

where H: Into<Height> + Send + 'async_trait, Self: Sync + 'async_trait, 'life0: 'async_trait,

/validators: get validators a given height.

fn latest_consensus_params<'life0, 'async_trait>( &'life0 self, ) -> Pin<Box<dyn Future<Output = Result<Response, Error>> + Send + 'async_trait>>

where Self: Sync + 'async_trait, 'life0: 'async_trait,

/consensus_params: get the latest consensus parameters.

fn latest_commit<'life0, 'async_trait>( &'life0 self, ) -> Pin<Box<dyn Future<Output = Result<Response, Error>> + Send + 'async_trait>>

where Self: Sync + 'async_trait, 'life0: 'async_trait,

/commit: get the latest block commit

fn health<'life0, 'async_trait>( &'life0 self, ) -> Pin<Box<dyn Future<Output = Result<(), Error>> + Send + 'async_trait>>

where Self: Sync + 'async_trait, 'life0: 'async_trait,

/health: get node health.

fn genesis<'life0, 'async_trait, AppState>( &'life0 self, ) -> Pin<Box<dyn Future<Output = Result<Genesis<AppState>, Error>> + Send + 'async_trait>>

where AppState: Debug + Serialize + DeserializeOwned + Send + 'async_trait, Self: Sync + 'async_trait, 'life0: 'async_trait,

/genesis: get genesis file.

fn genesis_chunked<'life0, 'async_trait>( &'life0 self, chunk: u64, ) -> Pin<Box<dyn Future<Output = Result<Response, Error>> + Send + 'async_trait>>

where Self: Sync + 'async_trait, 'life0: 'async_trait,

fn genesis_chunked_stream<'life0, 'async_trait>( &'life0 self, ) -> Pin<Box<dyn Future<Output = Pin<Box<dyn Stream<Item = Result<Vec<u8>, Error>> + '_>>> + Send + 'async_trait>>

where Self: Sync + 'async_trait, 'life0: 'async_trait,

/genesis_chunked: get genesis file in multiple chunks.

fn net_info<'life0, 'async_trait>( &'life0 self, ) -> Pin<Box<dyn Future<Output = Result<Response, Error>> + Send + 'async_trait>>

where Self: Sync + 'async_trait, 'life0: 'async_trait,

/net_info: obtain information about P2P and other network connections.

fn status<'life0, 'async_trait>( &'life0 self, ) -> Pin<Box<dyn Future<Output = Result<Response, Error>> + Send + 'async_trait>>

where Self: Sync + 'async_trait, 'life0: 'async_trait,

/status: get Tendermint status including node info, pubkey, latest block hash, app hash, block height and time.

fn broadcast_evidence<'life0, 'async_trait>( &'life0 self, e: Evidence, ) -> Pin<Box<dyn Future<Output = Result<Response, Error>> + Send + 'async_trait>>

where Self: Sync + 'async_trait, 'life0: 'async_trait,

/broadcast_evidence: broadcast an evidence.

fn wait_until_healthy<'life0, 'async_trait, T>( &'life0 self, timeout: T, ) -> Pin<Box<dyn Future<Output = Result<(), Error>> + Send + 'async_trait>>

where T: Into<Duration> + Send + 'async_trait, Self: Sync + 'async_trait, 'life0: 'async_trait,

Poll the /health endpoint until it returns a successful result or the given timeout has elapsed.

impl Clone for WebSocketClient

fn clone(&self) -> WebSocketClient

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for WebSocketClient

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl SubscriptionClient for WebSocketClient

fn subscribe<'life0, 'async_trait>( &'life0 self, query: Query, ) -> Pin<Box<dyn Future<Output = Result<Subscription, Error>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

/subscribe: subscribe to receive events produced by the given query.

fn unsubscribe<'life0, 'async_trait>( &'life0 self, query: Query, ) -> Pin<Box<dyn Future<Output = Result<(), Error>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

/unsubscribe: unsubscribe from events relating to the given query.

fn close(self) -> Result<(), Error>

Subscription clients will usually have long-running underlying transports that will need to be closed at some point.