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

@@ -23,7 +23,7 @@ crate-type = ["cdylib", "rlib"]
 
 [features]
 default = ["rpc-client"]
-rpc-client = ["tendermint-rpc/client"]
+rpc-client = ["tendermint-rpc/client", "tendermint-rpc/transport_http"]
 secp256k1 = ["tendermint/secp256k1", "tendermint-rpc/secp256k1"]
 
 [dependencies]

light-client/src/components/io.rs

@@ -4,6 +4,9 @@ use contracts::{contract_trait, post};
 use serde::{Deserialize, Serialize};
 use thiserror::Error;
 
+#[cfg(feature = "rpc-client")]
+use tendermint_rpc::Client;
+
 use tendermint_rpc as rpc;
 
 use crate::types::{Height, LightBlock, PeerId};
@@ -31,7 +34,7 @@ impl From<Height> for AtHeight {
 pub enum IoError {
     /// Wrapper for a `tendermint::rpc::Error`.
     #[error(transparent)]
-    IoError(#[from] rpc::Error),
+    RpcError(#[from] rpc::Error),
 
     /// Given height is invalid
     #[error("invalid height: {0}")]
@@ -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 {
@@ -143,7 +146,7 @@ mod prod {
 
             match res {
                 Ok(response) => Ok(response.signed_header),
-                Err(err) => Err(IoError::IoError(err)),
+                Err(err) => Err(IoError::RpcError(err)),
             }
         }
 
@@ -161,21 +164,22 @@ mod prod {
             };
 
             let res = block_on(
-                self.rpc_client_for(peer).validators(height),
+                self.rpc_client_for(peer)?.validators(height),
                 peer,
                 self.timeout,
             )?;
 
             match res {
                 Ok(response) => Ok(TMValidatorSet::new(response.validators)),
-                Err(err) => Err(IoError::IoError(err)),
+                Err(err) => Err(IoError::RpcError(err)),
             }
         }
 
+        // 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,11 +39,11 @@ 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),
-                Err(err) => Err(IoError::IoError(err)),
+                Err(err) => Err(IoError::RpcError(err)),
             }
         }
     }
@@ -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.