Struct tendermint_rpc::WebSocketClient

pub struct WebSocketClient { /* fields omitted */ }

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 (see the new method). 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 driver's 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("tcp://127.0.0.1:26657".parse().unwrap())
        .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(address: Address) -> Result<(Self, WebSocketClientDriver)>

Construct a WebSocket client. Immediately attempts to open a WebSocket connection to the node with the given address.

On success, this returns both a client handle (a WebSocketClient instance) as well as the WebSocket connection driver. The execution of this driver becomes the responsibility of the client owner, and must be executed in a separate asynchronous context to the client to ensure it doesn't block the client.

pub fn close(self) -> Result<()>

Signals to the driver that it must terminate.

Trait Implementations

impl Client for WebSocketClient

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

Perform a request against the RPC endpoint

#[must_use]pub fn abci_info<'life0, 'async_trait>(
    &'life0 self
) -> Pin<Box<dyn Future<Output = Result<AbciInfo>> + Send + 'async_trait>> where
    'life0: 'async_trait,
    Self: Sync + 'async_trait, 

/abci_info: get information about the ABCI application.

#[must_use]pub fn abci_query<'life0, 'async_trait, V>(
    &'life0 self,
    path: Option<Path>,
    data: V,
    height: Option<Height>,
    prove: bool
) -> Pin<Box<dyn Future<Output = Result<AbciQuery>> + Send + 'async_trait>> where
    V: Into<Vec<u8>> + Send,
    V: 'async_trait,
    'life0: 'async_trait,
    Self: Sync + 'async_trait, 

/abci_query: query the ABCI application

#[must_use]pub fn block<'life0, 'async_trait, H>(
    &'life0 self,
    height: H
) -> Pin<Box<dyn Future<Output = Result<Response>> + Send + 'async_trait>> where
    H: Into<Height> + Send,
    H: 'async_trait,
    'life0: 'async_trait,
    Self: Sync + 'async_trait, 

/block: get block at a given height.

#[must_use]pub fn latest_block<'life0, 'async_trait>(
    &'life0 self
) -> Pin<Box<dyn Future<Output = Result<Response>> + Send + 'async_trait>> where
    'life0: 'async_trait,
    Self: Sync + 'async_trait, 

/block: get the latest block.

#[must_use]pub fn block_results<'life0, 'async_trait, H>(
    &'life0 self,
    height: H
) -> Pin<Box<dyn Future<Output = Result<Response>> + Send + 'async_trait>> where
    H: Into<Height> + Send,
    H: 'async_trait,
    'life0: 'async_trait,
    Self: Sync + 'async_trait, 

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

#[must_use]pub fn latest_block_results<'life0, 'async_trait>(
    &'life0 self
) -> Pin<Box<dyn Future<Output = Result<Response>> + Send + 'async_trait>> where
    'life0: 'async_trait,
    Self: Sync + 'async_trait, 

/block_results: get ABCI results for the latest block.

#[must_use]pub fn blockchain<'life0, 'async_trait, H>(
    &'life0 self,
    min: H,
    max: H
) -> Pin<Box<dyn Future<Output = Result<Response>> + Send + 'async_trait>> where
    H: Into<Height> + Send,
    H: 'async_trait,
    'life0: 'async_trait,
    Self: Sync + 'async_trait, 

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

#[must_use]pub fn broadcast_tx_async<'life0, 'async_trait>(
    &'life0 self,
    tx: Transaction
) -> Pin<Box<dyn Future<Output = Result<Response>> + Send + 'async_trait>> where
    'life0: 'async_trait,
    Self: Sync + 'async_trait, 

/broadcast_tx_async: broadcast a transaction, returning immediately.

#[must_use]pub fn broadcast_tx_sync<'life0, 'async_trait>(
    &'life0 self,
    tx: Transaction
) -> Pin<Box<dyn Future<Output = Result<Response>> + Send + 'async_trait>> where
    'life0: 'async_trait,
    Self: Sync + 'async_trait, 

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

#[must_use]pub fn broadcast_tx_commit<'life0, 'async_trait>(
    &'life0 self,
    tx: Transaction
) -> Pin<Box<dyn Future<Output = Result<Response>> + Send + 'async_trait>> where
    'life0: 'async_trait,
    Self: Sync + 'async_trait, 

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

#[must_use]pub fn commit<'life0, 'async_trait, H>(
    &'life0 self,
    height: H
) -> Pin<Box<dyn Future<Output = Result<Response>> + Send + 'async_trait>> where
    H: Into<Height> + Send,
    H: 'async_trait,
    'life0: 'async_trait,
    Self: Sync + 'async_trait, 

/commit: get block commit at a given height.

#[must_use]pub fn consensus_state<'life0, 'async_trait>(
    &'life0 self
) -> Pin<Box<dyn Future<Output = Result<Response>> + Send + 'async_trait>> where
    'life0: 'async_trait,
    Self: Sync + 'async_trait, 

/consensus_state: get current consensus state

#[must_use]pub fn validators<'life0, 'async_trait, H>(
    &'life0 self,
    height: H
) -> Pin<Box<dyn Future<Output = Result<Response>> + Send + 'async_trait>> where
    H: Into<Height> + Send,
    H: 'async_trait,
    'life0: 'async_trait,
    Self: Sync + 'async_trait, 

/validators: get validators a given height.

#[must_use]pub fn latest_commit<'life0, 'async_trait>(
    &'life0 self
) -> Pin<Box<dyn Future<Output = Result<Response>> + Send + 'async_trait>> where
    'life0: 'async_trait,
    Self: Sync + 'async_trait, 

/commit: get the latest block commit

#[must_use]pub fn health<'life0, 'async_trait>(
    &'life0 self
) -> Pin<Box<dyn Future<Output = Result<()>> + Send + 'async_trait>> where
    'life0: 'async_trait,
    Self: Sync + 'async_trait, 

/health: get node health.

#[must_use]pub fn genesis<'life0, 'async_trait>(
    &'life0 self
) -> Pin<Box<dyn Future<Output = Result<Genesis>> + Send + 'async_trait>> where
    'life0: 'async_trait,
    Self: Sync + 'async_trait, 

/genesis: get genesis file.

#[must_use]pub fn net_info<'life0, 'async_trait>(
    &'life0 self
) -> Pin<Box<dyn Future<Output = Result<Response>> + Send + 'async_trait>> where
    'life0: 'async_trait,
    Self: Sync + 'async_trait, 

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

#[must_use]pub fn status<'life0, 'async_trait>(
    &'life0 self
) -> Pin<Box<dyn Future<Output = Result<Response>> + Send + 'async_trait>> where
    'life0: 'async_trait,
    Self: Sync + 'async_trait, 

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

#[must_use]pub fn broadcast_evidence<'life0, 'async_trait>(
    &'life0 self,
    e: Evidence
) -> Pin<Box<dyn Future<Output = Result<Response>> + Send + 'async_trait>> where
    'life0: 'async_trait,
    Self: Sync + 'async_trait, 

/broadcast_evidence: broadcast an evidence.

#[must_use]pub 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>> + Send + 'async_trait>> where
    'life0: 'async_trait,
    Self: Sync + 'async_trait, 

/tx_search: search for transactions with their results.

impl Clone for WebSocketClient

pub fn clone(&self) -> WebSocketClient

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Debug for WebSocketClient

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

Formats the value using the given formatter.

impl SubscriptionClient for WebSocketClient

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

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

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

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