Skip to content

Commit

Permalink
Merge pull request #8 from tcharding/06-17-docs
Browse files Browse the repository at this point in the history
regtest: Try to fix docs
  • Loading branch information
tcharding authored Jun 17, 2024
2 parents 04cae1e + ef2a501 commit bc2870f
Show file tree
Hide file tree
Showing 8 changed files with 33 additions and 50 deletions.
2 changes: 1 addition & 1 deletion Cargo-minimal.lock
Original file line number Diff line number Diff line change
Expand Up @@ -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",
Expand Down
2 changes: 1 addition & 1 deletion Cargo-recent.lock
Original file line number Diff line number Diff line change
Expand Up @@ -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",
Expand Down
5 changes: 5 additions & 0 deletions regtest/CHANGELOG.md
Original file line number Diff line number Diff line change
@@ -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).
Expand Down
4 changes: 2 additions & 2 deletions regtest/Cargo.toml
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
[package]
name = "bitcoind-json-rpc-regtest"
version = "0.2.0"
version = "0.2.1"
authors = ["Riccardo Casatta <riccardo@casatta.it>", "Tobin C. Harding <me@tobin.cc>"]
license = "MIT"
repository = "https://github.com/tcharding/rust-bitcoind-json-rpc"
Expand Down Expand Up @@ -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]
Expand Down
57 changes: 14 additions & 43 deletions regtest/README.md
Original file line number Diff line number Diff line change
@@ -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.
Expand All @@ -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:

Expand All @@ -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)
Expand Down Expand Up @@ -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.
10 changes: 8 additions & 2 deletions regtest/src/client_versions.rs
Original file line number Diff line number Diff line change
@@ -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};
Expand Down Expand Up @@ -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};
1 change: 1 addition & 0 deletions regtest/src/lib.rs
Original file line number Diff line number Diff line change
Expand Up @@ -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,
Expand Down
2 changes: 1 addition & 1 deletion regtest/src/versions.rs
Original file line number Diff line number Diff line change
Expand Up @@ -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";

0 comments on commit bc2870f

Please sign in to comment.