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", 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 11f8d9b..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" @@ -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/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. diff --git a/regtest/src/client_versions.rs b/regtest/src/client_versions.rs index 2fc9ddd..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. -#[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")))] +// 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, 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";