Make corepc-client async

Edit the copy of the sync client created in the previous commit to be
async. Update the readme and cargo.toml files.

Add only small set of RPCs.

Author: jamillambert

client/Cargo.toml

@@ -19,6 +19,8 @@ rustdoc-args = ["--cfg", "docsrs"]
 [features]
 # Enable this feature to get a blocking JSON-RPC client.
 client-sync = ["jsonrpc", "jsonrpc/bitreq_http"]
+# Enable this feature to get an async JSON-RPC client.
+client-async = ["jsonrpc", "jsonrpc/bitreq_http_async", "jsonrpc/client_async"]
 
 [dependencies]
 bitcoin = { version = "0.32.0", default-features = false, features = ["std", "serde"] }

client/README.md

@@ -1,7 +1,16 @@
 # corepc-client
 
-Rust client for the Bitcoin Core daemon's JSON-RPC API. Currently this
-is only a blocking client and is intended to be used in integration testing.
+Rust client for the Bitcoin Core daemon's JSON-RPC API.
+
+This crate provides:
+
+- A blocking client intended for integration testing (`client-sync`).
+- An async client intended for production (`client-async`).
+
+## Features
+
+- `client-sync`: Blocking JSON-RPC client.
+- `client-async`: Async JSON-RPC client.
 
 ## Minimum Supported Rust Version (MSRV)
 

client/src/client_async/mod.rs

@@ -1,6 +1,6 @@
 // SPDX-License-Identifier: CC0-1.0
 
-//! JSON-RPC clients for testing against specific versions of Bitcoin Core.
+//! Async JSON-RPC clients for specific versions of Bitcoin Core.
 
 mod error;
 pub mod v17;
@@ -22,7 +22,7 @@ use std::fs::File;
 use std::io::{BufRead, BufReader};
 use std::path::PathBuf;
 
-pub use crate::client_sync::error::Error;
+pub use crate::client_async::error::Error;
 
 /// Crate-specific Result type.
 ///
@@ -44,49 +44,48 @@ impl Auth {
             Auth::None => Ok((None, None)),
             Auth::UserPass(u, p) => Ok((Some(u), Some(p))),
             Auth::CookieFile(path) => {
-                let line = BufReader::new(File::open(path)?)
-                    .lines()
-                    .next()
-                    .ok_or(Error::InvalidCookieFile)??;
+                let line = BufReader::new(File::open(path)?).lines().next().ok_or(
+                    Error::InvalidCookieFile,
+                )??;
                 let colon = line.find(':').ok_or(Error::InvalidCookieFile)?;
                 Ok((Some(line[..colon].into()), Some(line[colon + 1..].into())))
             }
         }
     }
 }
 
-/// Defines a `jsonrpc::Client` using `bitreq`.
+/// Defines a async `jsonrpc::Client` using `bitreq`.
 #[macro_export]
-macro_rules! define_jsonrpc_bitreq_client {
+macro_rules! define_jsonrpc_bitreq_async_client {
     ($version:literal) => {
         use std::fmt;
+        use $crate::client_async::{log_response, Auth, Result};
+        use $crate::client_async::error::Error;
 
-        use $crate::client_sync::{log_response, Auth, Result};
-        use $crate::client_sync::error::Error;
-
-        /// Client implements a JSON-RPC client for the Bitcoin Core daemon or compatible APIs.
+        /// Client implements an async JSON-RPC client for the Bitcoin Core daemon or compatible APIs.
         pub struct Client {
-            inner: jsonrpc::client::Client,
+            inner: jsonrpc::AsyncClient,
         }
 
         impl fmt::Debug for Client {
             fn fmt(&self, f: &mut fmt::Formatter) -> core::fmt::Result {
                 write!(
                     f,
-                    "corepc_client::client_sync::{}::Client({:?})", $version, self.inner
+                    "corepc_client::client_async::{}::Client({})",
+                    $version, self.url
                 )
             }
         }
 
         impl Client {
             /// Creates a client to a bitcoind JSON-RPC server without authentication.
             pub fn new(url: &str) -> Self {
-                let transport = jsonrpc::http::bitreq_http::Builder::new()
+                let transport = jsonrpc::bitreq_http_async::Builder::new()
                     .url(url)
                     .expect("jsonrpc v0.19, this function does not error")
                     .timeout(std::time::Duration::from_secs(60))
                     .build();
-                let inner = jsonrpc::client::Client::with_transport(transport);
+                let inner = jsonrpc::AsyncClient::with_transport(transport);
 
                 Self { inner }
             }
@@ -97,20 +96,19 @@ macro_rules! define_jsonrpc_bitreq_client {
                     return Err(Error::MissingUserPassword);
                 }
                 let (user, pass) = auth.get_user_pass()?;
-
-                let transport = jsonrpc::http::bitreq_http::Builder::new()
+                let transport = jsonrpc::bitreq_http_async::Builder::new()
                     .url(url)
                     .expect("jsonrpc v0.19, this function does not error")
                     .timeout(std::time::Duration::from_secs(60))
                     .basic_auth(user.unwrap(), pass)
                     .build();
-                let inner = jsonrpc::client::Client::with_transport(transport);
+                let inner = jsonrpc::AsyncClient::with_transport(transport);
 
                 Ok(Self { inner })
             }
 
             /// Call an RPC `method` with given `args` list.
-            pub fn call<T: for<'a> serde::de::Deserialize<'a>>(
+            pub async fn call<T: for<'a> serde::de::Deserialize<'a>>(
                 &self,
                 method: &str,
                 args: &[serde_json::Value],
@@ -121,7 +119,7 @@ macro_rules! define_jsonrpc_bitreq_client {
                     log::debug!(target: "corepc", "request: {} {}", method, serde_json::Value::from(args));
                 }
 
-                let resp = self.inner.send_request(req).map_err(Error::from);
+                let resp = self.inner.send_request(req).await.map_err(Error::from);
                 log_response(method, &resp);
                 Ok(resp?.result()?)
             }
@@ -138,14 +136,14 @@ macro_rules! define_jsonrpc_bitreq_client {
 ///
 /// - `$expected_versions`: An vector of expected server versions e.g., `[230100, 230200]`.
 #[macro_export]
-macro_rules! impl_client_check_expected_server_version {
+macro_rules! impl_async_client_check_expected_server_version {
     ($expected_versions:expr) => {
         impl Client {
             /// Checks that the JSON-RPC endpoint is for a `bitcoind` instance with the expected version.
-            pub fn check_expected_server_version(&self) -> Result<()> {
-                let server_version = self.server_version()?;
+            pub async fn check_expected_server_version(&self) -> Result<()> {
+                let server_version = self.server_version().await?;
                 if !$expected_versions.contains(&server_version) {
-                    return Err($crate::client_sync::error::UnexpectedServerVersionError {
+                    return Err($crate::client_async::error::UnexpectedServerVersionError {
                         got: server_version,
                         expected: $expected_versions.to_vec(),
                     })?;

client/src/client_async/v17/blockchain.rs

@@ -0,0 +1,108 @@
+// SPDX-License-Identifier: CC0-1.0
+
+//! Macros for implementing async JSON-RPC methods on a client.
+//!
+//! Specifically this is methods found under the `== Blockchain ==` section of the
+//! API docs of Bitcoin Core `v0.17`.
+//!
+//! All macros require `Client` to be in scope.
+//!
+//! See or use the `define_jsonrpc_bitreq_async_client!` macro to define a `Client`.
+
+/// Implements Bitcoin Core JSON-RPC API method `getblock`.
+#[macro_export]
+macro_rules! impl_async_client_v17__get_block {
+    () => {
+        impl Client {
+            /// Gets a block by blockhash.
+            pub async fn get_block(&self, hash: BlockHash) -> Result<Block> {
+                let json = self.get_block_verbose_zero(hash).await?;
+                Ok(json.block()?)
+            }
+
+            /// Gets a block by blockhash with verbose set to 0.
+            pub async fn get_block_verbose_zero(&self, hash: BlockHash) -> Result<GetBlockVerboseZero> {
+                self.call("getblock", &[into_json(hash)?, 0.into()]).await
+            }
+
+            /// Gets a block by blockhash with verbose set to 1.
+            pub async fn get_block_verbose_one(&self, hash: BlockHash) -> Result<GetBlockVerboseOne> {
+                self.call("getblock", &[into_json(hash)?, 1.into()]).await
+            }
+
+            /// Alias for getblock verbosity 1, matching bitcoincore-rpc naming.
+            pub async fn get_block_info(&self, hash: BlockHash) -> Result<GetBlockVerboseOne> {
+                self.get_block_verbose_one(hash).await
+            }
+        }
+    };
+}
+
+/// Implements Bitcoin Core JSON-RPC API method `getblockcount`.
+#[macro_export]
+macro_rules! impl_async_client_v17__get_block_count {
+    () => {
+        impl Client {
+            pub async fn get_block_count(&self) -> Result<GetBlockCount> {
+                self.call("getblockcount", &[]).await
+            }
+        }
+    };
+}
+
+/// Implements Bitcoin Core JSON-RPC API method `getblockhash`.
+#[macro_export]
+macro_rules! impl_async_client_v17__get_block_hash {
+    () => {
+        impl Client {
+            pub async fn get_block_hash(&self, height: u64) -> Result<GetBlockHash> {
+                self.call("getblockhash", &[into_json(height)?]).await
+            }
+        }
+    };
+}
+
+/// Implements Bitcoin Core JSON-RPC API method `getblockheader`.
+#[macro_export]
+macro_rules! impl_async_client_v17__get_block_header {
+    () => {
+        impl Client {
+            pub async fn get_block_header(&self, hash: &BlockHash) -> Result<GetBlockHeader> {
+                self.call("getblockheader", &[into_json(hash)?, into_json(false)?]).await
+            }
+
+            // This is the same as calling getblockheader with verbose==true.
+            pub async fn get_block_header_verbose(
+                &self,
+                hash: &BlockHash,
+            ) -> Result<GetBlockHeaderVerbose> {
+                self.call("getblockheader", &[into_json(hash)?]).await
+            }
+
+            /// Alias for getblockheader with verbose true.
+            pub async fn get_block_header_info(
+                &self,
+                hash: &BlockHash,
+            ) -> Result<GetBlockHeaderVerbose> {
+                self.get_block_header_verbose(hash).await
+            }
+        }
+    };
+}
+
+/// Implements Bitcoin Core JSON-RPC API method `getrawmempool`.
+#[macro_export]
+macro_rules! impl_async_client_v17__get_raw_mempool {
+    () => {
+        impl Client {
+            pub async fn get_raw_mempool(&self) -> Result<GetRawMempool> {
+                // Equivalent to self.call("getrawmempool", &[into_json(false)?])
+                self.call("getrawmempool", &[]).await
+            }
+
+            pub async fn get_raw_mempool_verbose(&self) -> Result<GetRawMempoolVerbose> {
+                self.call("getrawmempool", &[into_json(true)?]).await
+            }
+        }
+    };
+}

client/src/client_async/v17/mod.rs

@@ -0,0 +1,28 @@
+// SPDX-License-Identifier: CC0-1.0
+
+//! An async JSON-RPC client for Bitcoin Core `v0.17`.
+
+pub mod blockchain;
+pub mod network;
+pub mod raw_transactions;
+
+use bitcoin::{Block, BlockHash, Txid};
+
+use crate::client_async::into_json;
+use crate::types::v17::*;
+
+crate::define_jsonrpc_bitreq_async_client!("v17");
+crate::impl_async_client_check_expected_server_version!({ [170200] });
+
+// == Blockchain ==
+crate::impl_async_client_v17__get_block!();
+crate::impl_async_client_v17__get_block_count!();
+crate::impl_async_client_v17__get_block_hash!();
+crate::impl_async_client_v17__get_block_header!();
+crate::impl_async_client_v17__get_raw_mempool!();
+
+// == Network ==
+crate::impl_async_client_v17__get_network_info!();
+
+// == Rawtransactions ==
+crate::impl_async_client_v17__get_raw_transaction!();

client/src/client_async/v17/network.rs

@@ -0,0 +1,28 @@
+// SPDX-License-Identifier: CC0-1.0
+
+//! Macros for implementing async JSON-RPC methods on a client.
+//!
+//! Specifically this is methods found under the `== Network ==` section of the
+//! API docs of Bitcoin Core `v0.17`.
+//!
+//! All macros require `Client` to be in scope.
+//!
+//! See or use the `define_jsonrpc_bitreq_async_client!` macro to define a `Client`.
+
+/// Implements Bitcoin Core JSON-RPC API method `getnetworkinfo`.
+#[macro_export]
+macro_rules! impl_async_client_v17__get_network_info {
+    () => {
+        impl Client {
+            /// Returns the server version field of `GetNetworkInfo`.
+            pub async fn server_version(&self) -> Result<usize> {
+                let info = self.get_network_info().await?;
+                Ok(info.version)
+            }
+
+            pub async fn get_network_info(&self) -> Result<GetNetworkInfo> {
+                self.call("getnetworkinfo", &[]).await
+            }
+        }
+    };
+}

client/src/client_async/v17/raw_transactions.rs

@@ -0,0 +1,29 @@
+// SPDX-License-Identifier: CC0-1.0
+
+//! Macros for implementing async JSON-RPC methods on a client.
+//!
+//! Specifically this is methods found under the `== Rawtransactions ==` section of the
+//! API docs of Bitcoin Core `v0.17`.
+//!
+//! All macros require `Client` to be in scope.
+//!
+//! See or use the `define_jsonrpc_bitreq_async_client!` macro to define a `Client`.
+
+/// Implements Bitcoin Core JSON-RPC API method `getrawtransaction`.
+#[macro_export]
+macro_rules! impl_async_client_v17__get_raw_transaction {
+    () => {
+        impl Client {
+            pub async fn get_raw_transaction(&self, txid: bitcoin::Txid) -> Result<GetRawTransaction> {
+                self.call("getrawtransaction", &[into_json(&txid)?, false.into()]).await
+            }
+
+            pub async fn get_raw_transaction_verbose(
+                &self,
+                txid: Txid,
+            ) -> Result<GetRawTransactionVerbose> {
+                self.call("getrawtransaction", &[into_json(&txid)?, true.into()]).await
+            }
+        }
+    };
+}

client/src/client_async/v18/mod.rs

@@ -0,0 +1,24 @@
+// SPDX-License-Identifier: CC0-1.0
+
+//! An async JSON-RPC client for Bitcoin Core `v0.18`.
+
+use bitcoin::{Block, BlockHash, Txid};
+
+use crate::client_async::into_json;
+use crate::types::v18::*;
+
+crate::define_jsonrpc_bitreq_async_client!("v18");
+crate::impl_async_client_check_expected_server_version!({ [180100] });
+
+// == Blockchain ==
+crate::impl_async_client_v17__get_block!();
+crate::impl_async_client_v17__get_block_count!();
+crate::impl_async_client_v17__get_block_hash!();
+crate::impl_async_client_v17__get_block_header!();
+crate::impl_async_client_v17__get_raw_mempool!();
+
+// == Network ==
+crate::impl_async_client_v17__get_network_info!();
+
+// == Rawtransactions ==
+crate::impl_async_client_v17__get_raw_transaction!();