From 38f722e5accecf9b49d86e43f077ea9e02dc6973 Mon Sep 17 00:00:00 2001 From: "Tobin C. Harding" Date: Mon, 17 Jun 2024 15:06:13 +1000 Subject: [PATCH 1/5] Update lock files I did a bad thing and pushed patches to master then cut a release of `bitcoind-json-rpc-client` without using a PR, and forgot to update lock files - so here it is. --- Cargo-minimal.lock | 2 +- Cargo-recent.lock | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/Cargo-minimal.lock b/Cargo-minimal.lock index e0b74a2..483ada6 100644 --- a/Cargo-minimal.lock +++ b/Cargo-minimal.lock @@ -86,7 +86,7 @@ dependencies = [ [[package]] name = "bitcoind-json-rpc-client" -version = "0.2.0" +version = "0.2.1" dependencies = [ "bitcoin", "bitcoind-json-rpc-types", diff --git a/Cargo-recent.lock b/Cargo-recent.lock index e0b74a2..483ada6 100644 --- a/Cargo-recent.lock +++ b/Cargo-recent.lock @@ -86,7 +86,7 @@ dependencies = [ [[package]] name = "bitcoind-json-rpc-client" -version = "0.2.0" +version = "0.2.1" dependencies = [ "bitcoin", "bitcoind-json-rpc-types", From c191fdb1dba3070a469774eb194f0ee7f22f4a82 Mon Sep 17 00:00:00 2001 From: "Tobin C. Harding" Date: Mon, 17 Jun 2024 14:13:15 +1000 Subject: [PATCH 2/5] regtest: Fix typos in cfg Its "features" not "feadures", fix multiple instances of the typo. --- regtest/src/client_versions.rs | 2 +- regtest/src/versions.rs | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/regtest/src/client_versions.rs b/regtest/src/client_versions.rs index 2fc9ddd..e64ab32 100644 --- a/regtest/src/client_versions.rs +++ b/regtest/src/client_versions.rs @@ -68,6 +68,6 @@ pub use bitcoind_json_rpc_client::{client_sync::v18::{Client, AddressType}, json pub use bitcoind_json_rpc_client::{client_sync::v17::{Client, AddressType}, json::v17 as json}; // To make --no-default-features work we have to enable some feature, use most recent version same as for default. -#[cfg(all(not(feature = "26_0"), not(feature = "25_2"), not(feature = "25_1"), not(feature = "25_0"), not(feature = "24_2"),not(feadure = "24_1"), not(feature = "24_0_1"), not(feature = "23_2"), not(feature = "23_1"), not(feature = "23_0"), not(feature = "22_1"), not(feature = "22_0"), not(feature = "0_21_2"), not(feature = "0_20_2"), not(feature = "0_19_1"), not(feature = "0_18_1"), not(feature = "0_17_1")))] +#[cfg(all(not(feature = "26_0"), not(feature = "25_2"), not(feature = "25_1"), not(feature = "25_0"), not(feature = "24_2"),not(feature = "24_1"), not(feature = "24_0_1"), not(feature = "23_2"), not(feature = "23_1"), not(feature = "23_0"), not(feature = "22_1"), not(feature = "22_0"), not(feature = "0_21_2"), not(feature = "0_20_2"), not(feature = "0_19_1"), not(feature = "0_18_1"), not(feature = "0_17_1")))] #[allow(unused_imports)] // Not all users need the json types. pub use bitcoind_json_rpc_client::{client_sync::v26::{Client, AddressType}, json::v26 as json}; diff --git a/regtest/src/versions.rs b/regtest/src/versions.rs index 46587f5..1c5767c 100644 --- a/regtest/src/versions.rs +++ b/regtest/src/versions.rs @@ -50,6 +50,6 @@ pub const VERSION: &str = "0.18.1"; pub const VERSION: &str = "0.17.1"; // To make --no-default-features work we have to enable some feature, use most recent version same as for default. -#[cfg(all(not(feature = "26_0"), not(feature = "25_2"), not(feature = "25_1"), not(feature = "25_0"), not(feature = "24_2"),not(feadure = "24_1"), not(feature = "24_0_1"), not(feature = "23_2"), not(feature = "23_1"), not(feature = "23_0"), not(feature = "22_1"), not(feature = "22_0"), not(feature = "0_21_2"), not(feature = "0_20_2"), not(feature = "0_19_1"), not(feature = "0_18_1"), not(feature = "0_17_1")))] +#[cfg(all(not(feature = "26_0"), not(feature = "25_2"), not(feature = "25_1"), not(feature = "25_0"), not(feature = "24_2"),not(feature = "24_1"), not(feature = "24_0_1"), not(feature = "23_2"), not(feature = "23_1"), not(feature = "23_0"), not(feature = "22_1"), not(feature = "22_0"), not(feature = "0_21_2"), not(feature = "0_20_2"), not(feature = "0_19_1"), not(feature = "0_18_1"), not(feature = "0_17_1")))] #[allow(dead_code)] // for --no-default-features pub const VERSION: &str = "26.0"; From febf24fe75cc7d89db3ace91b915e630dbc03df3 Mon Sep 17 00:00:00 2001 From: "Tobin C. Harding" Date: Mon, 17 Jun 2024 14:29:48 +1000 Subject: [PATCH 3/5] regtest: Update readme The readme is stale because it is the one we grabbed when importing `bitcoind`. Since this crate is currently being release under a different name remove the stale docs that are specific to `bitcoind`. --- regtest/README.md | 57 ++++++++++++----------------------------------- 1 file changed, 14 insertions(+), 43 deletions(-) diff --git a/regtest/README.md b/regtest/README.md index 74752ff..a5366a2 100644 --- a/regtest/README.md +++ b/regtest/README.md @@ -1,7 +1,3 @@ -[![MIT license](https://img.shields.io/github/license/RCasatta/bitcoind)](https://github.com/RCasatta/bitcoind/blob/master/LICENSE) -[![Crates](https://img.shields.io/crates/v/bitcoind.svg)](https://crates.io/crates/bitcoind) -[![Docs](https://img.shields.io/badge/docs.rs-bitcoind-green)](https://docs.rs/bitcoind) - # Bitcoind Utility to run a regtest bitcoind process, useful in integration testing environment. @@ -19,8 +15,7 @@ for bitcoin core 25.1, starting a regtest node is as simple as that: ``` The build script will automatically download the bitcoin core version 25.1 from [bitcoin core](https://bitcoincore.org), -verify the hashes and place it in the build directory for this crate. If you wish to download from an -alternate location, for example locally for CI, use the `BITCOIND_DOWNLOAD_ENDPOINT` env var. +verify the binary hash and place it in the build directory for this crate. When you don't use the auto-download feature you have the following options: @@ -37,22 +32,15 @@ if let Ok(exe_path) = bitcoind::exe_path() { Startup options could be configured via the [`Conf`] struct using [`BitcoinD::with_conf`] or [`BitcoinD::from_downloaded_with_conf`] -## Issues with traditional approach - -I used integration testing based on external bash script launching needed external processes, there -are many issues with this approach like: - -* External script may interfere with local development environment [1](https://github.com/rust-bitcoin/rust-bitcoincore-rpc/blob/200fc8247c1896709a673b82a89ca0da5e7aa2ce/integration_test/run.sh#L9) -* Use of a single huge test to test everything [2](https://github.com/rust-bitcoin/rust-bitcoincore-rpc/blob/200fc8247c1896709a673b82a89ca0da5e7aa2ce/integration_test/src/main.rs#L122-L203) -* If test are separated, a failing test may fail to leave a clean situation, causing other test to fail (because of the initial situation, not a real failure) -* bash script are hard, especially support different OS and versions - ## Features - * It waits until bitcoind daemon become ready to accept RPC commands - * `bitcoind` use a temporary directory as datadir. You can specify the root of your temp directories so that you have node's datadir in a RAM disk (eg `/dev/shm`) - * Free ports are asked to the OS. Since you can't reserve the given port, a low probability race condition is still possible, for this reason the process is tried to be spawn 3 times with different ports. - * The process is killed when the struct goes out of scope no matter how the test finishes + * Waits until bitcoind daemon becomes ready to accept RPC commands + * `bitcoind` uses a temporary directory as datadir. You can specify the root of your temp + directories so that you have the node's datadir in a RAM disk (eg `/dev/shm`) + * Free ports are requested from the OS. Since you can't reserve the given port, a low probability + race condition is still possible, for this reason the process attempts spawning 3 times with + different ports. + * The process is killed when the struct goes out of scope no matter how the test finishes. * Allows easy spawning of dependent processes like: - [electrs](https://github.com/RCasatta/electrsd) - [cln](https://github.com/RCasatta/lightningd) @@ -85,28 +73,11 @@ Pinning in `Cargo.toml` is avoided because it could cause compilation issues dow ## Nix -For reproducibility reasons, Nix build scripts cannot hit the internet, but the -auto-download feature does exactly that. To successfully build under Nix the -user must provide the tarball locally and specify its location via the -`BITCOIND_TARBALL_FILE` env var. - -Another option is to specify the `BITCOIND_SKIP_DOWNLOAD` env var and provide the -executable via the `PATH`. - -Alternatively, use the dep without auto-download feature. - -## Used by - -* [firma](https://github.com/RCasatta/firma/) -* [payjoin](https://github.com/Kixunil/payjoin) -* [rust-miniscript](https://github.com/rust-bitcoin/rust-miniscript/tree/4a3ba11c2fd5063be960741d557f3f7a28041e1f/bitcoind-tests) - -### Via bdk dependency - -* [gun](https://github.com/LLFourn/gun) +For reproducibility reasons, Nix build scripts cannot hit the internet, but the auto-download +feature does exactly that. To successfully build under Nix the user must provide the tarball locally +and specify its location via the `BITCOIND_TARBALL_FILE` env var. -### Via electrsd dependency: +Another option is to specify the `BITCOIND_SKIP_DOWNLOAD` env var and provide the executable via the +`PATH`. -* [bdk](https://github.com/bitcoindevkit/bdk) -* [BEWallet](https://github.com/LeoComandini/BEWallet) -* [gdk rust](https://github.com/Blockstream/gdk/blob/master/subprojects/gdk_rust/) +Alternatively, use the dep without the auto-download feature. From 21acb0ef2815fb0f9ded0299d4565fcf0bab3c8b Mon Sep 17 00:00:00 2001 From: "Tobin C. Harding" Date: Mon, 17 Jun 2024 14:48:53 +1000 Subject: [PATCH 4/5] regtest: Attempt to fix Client docs The crate is not typical in that it expects at least one of the "verison number" features to be enabled. This does not play nicely with the docs.rs build. In an effort to make things at least uderstandable add do a few things: - inline the `Client` and `json` docs - configure docs.rs build to enable 26_0 - Add a big fat note to hopefully alleviate the misleading "Available on crate feature 26_0 only." --- regtest/Cargo.toml | 2 +- regtest/src/client_versions.rs | 8 +++++++- regtest/src/lib.rs | 1 + 3 files changed, 9 insertions(+), 2 deletions(-) diff --git a/regtest/Cargo.toml b/regtest/Cargo.toml index 11f8d9b..498e6f9 100644 --- a/regtest/Cargo.toml +++ b/regtest/Cargo.toml @@ -65,7 +65,7 @@ anyhow = "1.0.66" [package.metadata.docs.rs] -features = ["download", "doc"] +features = ["download", "doc", "26_0"] rustdoc-args = ["--cfg", "docsrs"] [patch.crates-io.bitcoind-json-rpc-client] diff --git a/regtest/src/client_versions.rs b/regtest/src/client_versions.rs index e64ab32..ae854c1 100644 --- a/regtest/src/client_versions.rs +++ b/regtest/src/client_versions.rs @@ -1,4 +1,10 @@ // All features uses 26_0 +/// The version specific client and json types. +/// +/// **THIS IS AVAILABLE FOR ALL VERSION NUMBER FEATURES** (eg `25_0`, `24_2` etc). This crate is +/// unusual in that it expects exactly one version number feature to be selected, docs.rs is not set +/// up to handle such oddity. +/// #[cfg(feature = "26_0")] #[allow(unused_imports)] // Not all users need the json types. pub use bitcoind_json_rpc_client::{client_sync::v26::{Client, AddressType}, json::v26 as json}; @@ -67,7 +73,7 @@ pub use bitcoind_json_rpc_client::{client_sync::v18::{Client, AddressType}, json #[allow(unused_imports)] // Not all users need the json types. pub use bitcoind_json_rpc_client::{client_sync::v17::{Client, AddressType}, json::v17 as json}; -// To make --no-default-features work we have to enable some feature, use most recent version same as for default. +// To make --no-default-features work we have to re-export a the types, use most recent version same as we do for all features. #[cfg(all(not(feature = "26_0"), not(feature = "25_2"), not(feature = "25_1"), not(feature = "25_0"), not(feature = "24_2"),not(feature = "24_1"), not(feature = "24_0_1"), not(feature = "23_2"), not(feature = "23_1"), not(feature = "23_0"), not(feature = "22_1"), not(feature = "22_0"), not(feature = "0_21_2"), not(feature = "0_20_2"), not(feature = "0_19_1"), not(feature = "0_18_1"), not(feature = "0_17_1")))] #[allow(unused_imports)] // Not all users need the json types. pub use bitcoind_json_rpc_client::{client_sync::v26::{Client, AddressType}, json::v26 as json}; diff --git a/regtest/src/lib.rs b/regtest/src/lib.rs index cadb9a3..e54a469 100644 --- a/regtest/src/lib.rs +++ b/regtest/src/lib.rs @@ -21,6 +21,7 @@ use tempfile::TempDir; pub use {anyhow, tempfile, which}; #[rustfmt::skip] // Keep pubic re-exports separate. +#[doc(inline)] pub use self::{ client_versions::{json, Client, AddressType}, versions::VERSION, From ef2a5013433a6caa14b2e3db0e8224e1c94fc4f7 Mon Sep 17 00:00:00 2001 From: "Tobin C. Harding" Date: Mon, 17 Jun 2024 15:10:02 +1000 Subject: [PATCH 5/5] regtest: Bump version to 0.2.1 In preparation for doing a point release bump the version and add a changelog. --- regtest/CHANGELOG.md | 5 +++++ regtest/Cargo.toml | 2 +- 2 files changed, 6 insertions(+), 1 deletion(-) diff --git a/regtest/CHANGELOG.md b/regtest/CHANGELOG.md index 46f7294..94d465a 100644 --- a/regtest/CHANGELOG.md +++ b/regtest/CHANGELOG.md @@ -1,3 +1,8 @@ +# 0.2.1 - 2024-06-17 + +Do various little fixes to try and make the docs on `Client` more legible, specifically to alleviate +confusion around the flag on `docs.rs` that says "Available on crate feature 26_0 only." + # 0.2.0 - 2024-06-13 - Use Bitcoin Core 0.17.1 (0.17.2 seems to not exist and have been a mistake). diff --git a/regtest/Cargo.toml b/regtest/Cargo.toml index 498e6f9..9efb936 100644 --- a/regtest/Cargo.toml +++ b/regtest/Cargo.toml @@ -1,6 +1,6 @@ [package] name = "bitcoind-json-rpc-regtest" -version = "0.2.0" +version = "0.2.1" authors = ["Riccardo Casatta ", "Tobin C. Harding "] license = "MIT" repository = "https://github.com/tcharding/rust-bitcoind-json-rpc"