cdk_http_client/
lib.rs

1//! HTTP client abstraction for CDK
2//!
3//! This crate provides an HTTP client wrapper that abstracts the underlying HTTP library.
4//! Using this crate allows other CDK crates to avoid direct dependencies on a specific backend.
5//! Backend selection is feature-based: enable a native backend with `bitreq`
6//! (default) or `reqwest`. The features are additive — when both are enabled,
7//! `reqwest` takes precedence (see "Backend selection" below).
8//! The default `bitreq` backend supports HTTP proxy URLs only. SOCKS proxy schemes
9//! such as `socks5h` are supported only when this crate is built with the `reqwest`
10//! feature.
11//!
12//! # Backend selection
13//!
14//! CDK library crates depend on HTTP capability, while this crate owns the concrete
15//! backend choice. The `bitreq` backend is the default: any CDK crate that pulls in
16//! HTTP support turns it on automatically. `cdk-common/http` enables `bitreq`, and
17//! `cdk`'s `wallet` and `mint` features depend on it, so applications get a working
18//! client out of the box — including with `cdk --no-default-features --features wallet`.
19//!
20//! The backend features are additive: enabling both `bitreq` and `reqwest`
21//! resolves to `reqwest` (a strict superset that adds SOCKS proxy and
22//! invalid-certificate support), so feature unification across a dependency graph
23//! never conflicts. To use `reqwest`, add an explicit dependency on this crate with
24//! the `reqwest` feature — it takes precedence wherever it is enabled:
25//!
26//! ```toml
27//! [dependencies]
28//! cdk = { version = "0.17.0", features = ["wallet"] }
29//! cdk-http-client = { version = "0.17.0", features = ["reqwest"] }
30//! ```
31//!
32//! When depending on this crate directly with `--no-default-features`, at least one
33//! backend must be selected, or compilation fails with a clear error. To exercise the
34//! `reqwest` backend in workspace checks:
35//!
36//! ```bash
37//! cargo check -p cdk -p cdk-http-client --features cdk-http-client/reqwest
38//! ```
39//!
40//! # Example
41//!
42//! ```no_run
43//! use cdk_http_client::{HttpClient, Response};
44//! use serde::Deserialize;
45//!
46//! #[derive(Deserialize)]
47//! struct ApiResponse {
48//!     message: String,
49//! }
50//!
51//! async fn example() -> Response<ApiResponse> {
52//!     let client = HttpClient::new();
53//!     client.fetch("https://api.example.com/data").await
54//! }
55//! ```
56
57mod backends;
58mod client;
59#[cfg(all(feature = "bip353", not(target_arch = "wasm32")))]
60mod dns;
61mod error;
62mod request;
63mod response;
64mod transport;
65pub mod ws;
66
67#[cfg(all(
68    feature = "bitreq",
69    not(feature = "reqwest"),
70    not(target_arch = "wasm32")
71))]
72pub use backends::BitreqRequestBuilder;
73#[cfg(all(feature = "reqwest", not(target_arch = "wasm32")))]
74pub use backends::ReqwestRequestBuilder;
75#[cfg(target_arch = "wasm32")]
76pub use backends::WasmRequestBuilder;
77pub use client::{fetch, HttpClient, HttpClientBuilder};
78pub use error::HttpError;
79pub use request::RequestBuilder;
80pub use response::{RawResponse, Response};
81#[cfg(any(target_arch = "wasm32", feature = "bitreq", feature = "reqwest"))]
82pub use transport::Async;
83#[cfg(all(
84    feature = "bitreq",
85    not(feature = "reqwest"),
86    not(target_arch = "wasm32")
87))]
88pub use transport::BitreqTransport;
89#[cfg(all(feature = "reqwest", not(target_arch = "wasm32")))]
90pub use transport::ReqwestTransport;
91#[cfg(all(feature = "tor", not(target_arch = "wasm32")))]
92pub use transport::TorAsync;
93pub use transport::Transport;
cdk_http_client/lib.rs

cdk_http_client/
lib.rs
