rpc: event subscription management for RPC client

CHANGELOG.md

@@ -8,13 +8,41 @@
 - Separate protobuf types from Rust domain types using the DomainType trait ([#535])
 - Changed validator sorting order to sort by voting power. ([#506])
 
+### BREAKING CHANGES:
+
+- `[rpc]` The entire RPC client interface has been refactored. The
+ `Client` struct has now been replaced by an `HttpClient` struct, which
+ implements all of the RPC methods except those relating to event
+ subscription. To access this struct, you now need to enable both the
+ `client` and `transport_http` features when using the `tendermint-rpc`
+ crate. ([#516])
+
+### IMPROVEMENTS:
+
+- `[rpc]` A `WebSocketSubscriptionClient` is now provided to facilitate event
+ subscription for a limited range of RPC events over a WebSocket connection.
+ See the [Tendermint `/subscribe` endpoint's](https://docs.tendermint.com/master/rpc/#/Websocket/subscribe)
+ and the `tendermint-rpc` crate's docs for more details.
+ To access this struct you need to enable both the `client`, `subscription`
+ and `transport_websocket` features when using the `tendermint-rpc` crate.
+ ([#516])
+- `[rpc]` A `MockClient` and `MockSubscriptionClient` struct are available for use in
+ instances where you may want to interact with the Tendermint RPC from your
+ tests without integrating with an actual node. To access these structs you
+ need to enable the `client`, `subscription` and `transport_mock` features
+ when using the `tendermint-rpc` crate. If you only want to use the
+ `MockClient` struct, just enable features `client` and `transport_mock`.
+ See the crate docs for more details.
+ ([#516])
+
 [#524]: https://github.com/informalsystems/tendermint-rs/issues/524
 [#526]: https://github.com/informalsystems/tendermint-rs/issues/526
 [#498]: https://github.com/informalsystems/tendermint-rs/issues/498
 [#463]: https://github.com/informalsystems/tendermint-rs/issues/463
 [#504]: https://github.com/informalsystems/tendermint-rs/issues/504
 [#535]: https://github.com/informalsystems/tendermint-rs/issues/535
 [#506]: https://github.com/informalsystems/tendermint-rs/issues/506
+[#516]: https://github.com/informalsystems/tendermint-rs/pull/516
 
 ## v0.16.0
 

light-client/Cargo.toml

@@ -28,7 +28,7 @@ secp256k1 = ["tendermint/secp256k1", "tendermint-rpc/secp256k1"]
 
 [dependencies]
 tendermint = { version = "0.16.0", path = "../tendermint" }
-tendermint-rpc = { version = "0.16.0", path = "../rpc", default-features = false }
+tendermint-rpc = { version = "0.16.0", path = "../rpc", features = ["client", "transport_http"] }
 
 anomaly = { version = "0.2.0", features = ["serializer"] }
 contracts = "0.4.0"

light-client/src/components/io.rs

@@ -2,9 +2,11 @@
 
 use contracts::{contract_trait, post};
 use serde::{Deserialize, Serialize};
-use thiserror::Error;
-
+#[cfg(feature = "rpc-client")]
 use tendermint_rpc as rpc;
+#[cfg(feature = "rpc-client")]
+use tendermint_rpc::Client;
+use thiserror::Error;
 
 use crate::types::{Height, LightBlock, PeerId};
 
@@ -29,6 +31,7 @@ impl From<Height> for AtHeight {
 /// I/O errors
 #[derive(Clone, Debug, Error, PartialEq, Serialize, Deserialize)]
 pub enum IoError {
+ #[cfg(feature = "rpc-client")]
  /// Wrapper for a `tendermint::rpc::Error`.
  #[error(transparent)]
  IoError(#[from] rpc::Error),
@@ -128,7 +131,7 @@ mod prod {
  peer: PeerId,
  height: AtHeight,
  ) -> Result<TMSignedHeader, IoError> {
- let rpc_client = self.rpc_client_for(peer);
+ let rpc_client = self.rpc_client_for(peer)?;
 
  let res = block_on(
  async {
@@ -161,7 +164,7 @@ mod prod {
  };
 
  let res = block_on(
- self.rpc_client_for(peer).validators(height),
+ self.rpc_client_for(peer)?.validators(height),
  peer,
  self.timeout,
  )?;
@@ -172,10 +175,11 @@ mod prod {
  }
  }
 
+ // TODO(thane): Generalize over client transport (instead of using HttpClient directly).
  #[pre(self.peer_map.contains_key(&peer))]
- fn rpc_client_for(&self, peer: PeerId) -> rpc::Client {
+ fn rpc_client_for(&self, peer: PeerId) -> Result<rpc::HttpClient, IoError> {
  let peer_addr = self.peer_map.get(&peer).unwrap().to_owned();
- rpc::Client::new(peer_addr)
+ Ok(rpc::HttpClient::new(peer_addr).map_err(IoError::from)?)
  }
  }
 

light-client/src/evidence.rs

@@ -26,6 +26,7 @@ mod prod {
  use contracts::pre;
  use std::collections::HashMap;
  use tendermint_rpc as rpc;
+ use tendermint_rpc::Client;
 
  /// Production implementation of the EvidenceReporter component, which reports evidence to full
  /// nodes via RPC.
@@ -38,7 +39,7 @@ mod prod {
  impl EvidenceReporter for ProdEvidenceReporter {
  #[pre(self.peer_map.contains_key(&peer))]
  fn report(&self, e: Evidence, peer: PeerId) -> Result<Hash, IoError> {
- let res = block_on(self.rpc_client_for(peer).broadcast_evidence(e));
+ let res = block_on(self.rpc_client_for(peer)?.broadcast_evidence(e));
 
  match res {
  Ok(response) => Ok(response.hash),
@@ -56,9 +57,9 @@ mod prod {
  }
 
  #[pre(self.peer_map.contains_key(&peer))]
- fn rpc_client_for(&self, peer: PeerId) -> rpc::Client {
+ fn rpc_client_for(&self, peer: PeerId) -> Result<rpc::HttpClient, IoError> {
  let peer_addr = self.peer_map.get(&peer).unwrap().to_owned();
- rpc::Client::new(peer_addr)
+ Ok(rpc::HttpClient::new(peer_addr).map_err(IoError::from)?)
  }
  }
 

light-node/Cargo.toml

@@ -18,7 +18,7 @@ description = """
  The Tendermint light-node wraps the light-client crate into a command-line
  interface tool.
  It can be used to initialize and start a standalone light client daemon and
- exposes a JSONRPC endpoint from which you can query the current state of the
+ exposes a JSON-RPC endpoint from which you can query the current state of the
  light node.
  """
 

light-node/README.md

@@ -6,7 +6,7 @@ See the [repo root] for build status, license, rust version, etc.
 # Light-Node
 
 The [Tendermint] light-node wraps the [light-client] crate into a command-line interface tool. 
-It can be used as a standalone light client daemon and exposes a JSONRPC endpoint 
+It can be used as a standalone light client daemon and exposes a JSON-RPC endpoint 
 from which you can query the current state of the light node. 
 
 ## Getting Started
@@ -103,7 +103,7 @@ Or on a specific sub-command, e.g.:
 $ cargo run -- help start
  ```
 
-### JSONRPC Endpoint(s)
+### JSON-RPC Endpoint(s)
 
 When you have a light-node running you can query its current state via:
 ```

light-node/src/lib.rs

@@ -2,7 +2,7 @@
 //!
 //! The Tendermint light-node wraps the light-client crate into a command-line interface tool.
 //!
-//! It can be used to initialize and start a standalone light client daemon and exposes a JSONRPC
+//! It can be used to initialize and start a standalone light client daemon and exposes a JSON-RPC
 //! endpoint from which you can query the current state of the light node.
 
 // Tip: Deny warnings with `RUSTFLAGS="-D warnings"` environment variable in CI

light-node/src/rpc.rs

@@ -1,4 +1,4 @@
-//! JSONRPC Server and Client for the light-node RPC endpoint.
+//! JSON-RPC Server and Client for the light-node RPC endpoint.
 use jsonrpc_core::IoHandler;
 use jsonrpc_http_server::{AccessControlAllowOrigin, DomainsValidation, ServerBuilder};
 

rpc/Cargo.toml

@@ -15,7 +15,7 @@ authors = [
 ]
 
 description = """
- tenndermint-rpc contains the core types returned by a Tendermint node's RPC endpoint.
+ tendermint-rpc contains the core types returned by a Tendermint node's RPC endpoint.
  All networking related features are feature guarded to keep the dependencies small in
  cases where only the core types are needed.
  """
@@ -24,9 +24,13 @@ description = """
 all-features = true
 
 [features]
-default = ["client"]
-client = ["async-tungstenite", "futures", "http", "hyper", "tokio"]
-secp256k1 = ["tendermint/secp256k1"]
+default = []
+client = [ "async-trait", "futures" ]
+secp256k1 = [ "tendermint/secp256k1" ]
+subscription = [ "tokio" ]
+transport_http = [ "http", "hyper", "tokio" ]
+transport_mock = [ "tokio" ]
+transport_websocket = [ "async-tungstenite", "tokio" ]
 
 [dependencies]
 bytes = "0.5"
@@ -38,8 +42,9 @@ tendermint = { version = "0.16.0", path = "../tendermint" }
 thiserror = "1"
 uuid = { version = "0.8", default-features = false }
 
-async-tungstenite = { version="0.5", features = ["tokio-runtime"], optional = true }
+async-tungstenite = { version="0.8", features = ["tokio-runtime"], optional = true }
+async-trait = { version = "0.1", optional = true }
 futures = { version = "0.3", optional = true }
 http = { version = "0.2", optional = true }
 hyper = { version = "0.13", optional = true }
-tokio = { version = "0.2", features = ["macros"], optional = true }
+tokio = { version = "0.2", features = ["macros", "fs", "sync"], optional = true }

rpc/README.md

@@ -7,7 +7,7 @@ See the [repo root] for build status, license, rust version, etc.
 
 A rust implementation of the core types returned by a Tendermint node's RPC 
 endpoint. 
-These can be used to deserialize JSONRPC responses.
+These can be used to deserialize JSON-RPC responses.
 All networking related features will be feature guarded to keep the dependencies small 
 in cases where only the core types are needed.