corepc/bitreq/src/lib.rs at f1a3a3046793fbd5166cde44d19d72892be4ce40 · rust-bitcoin/corepc · GitHub

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
//! # Bitreq
//!
//! Simple, minimal-dependency HTTP client.  The library has a very
//! minimal API, so you'll probably know everything you need to after
//! reading a few examples.
//!
//! Note: as a minimal library, bitreq has been written with the
//! assumption that servers are well-behaved. This should be fine for
//! nearly any HTTP(S) you find using standard HTTP(S) servers, but
//! some truly ancient servers may cause spurious failures, especially
//! while using pipelining.
//!
//! # Additional features
//!
//! Since the crate is supposed to be minimal in terms of
//! dependencies, only the `std` feature is enabled by default.
//! Additional functionality can be enabled by specifying features for
//! the `bitreq` dependency in `Cargo.toml`:
//!
//! ```toml
//! [dependencies]
//! bitreq = { version = "0.2.0", features = ["https"] }
//! ```
//!
//! Below is the list of all available features.
//!
//! ## `https` or `https-rustls`
//!
//! This feature uses the (very good)
//! [`rustls`](https://crates.io/crates/rustls) crate to secure the
//! connection when needed. It uses `webpki-roots` to load certificate
//! authorities to trust.
//!
//! Note that if no HTTPS feature is enabled (and none are by default),
//! requests to urls that start with `https://` will fail and return an
//! [`HttpsFeatureNotEnabled`](enum.Error.html#variant.HttpsFeatureNotEnabled)
//! error. `https` was the name of this feature until the other https
//! feature variants were added, and is now an alias for
//! `https-rustls`.
//!
//! ## `https-rustls-probe`
//!
//! Like `https-rustls`, but uses the
//! [`rustls-native-certs`](https://crates.io/crates/rustls-native-certs)
//! crate to auto-detect certificate authorities installed in common
//! locations.
//!
//! ## `https-native-tls`
//!
//! Uses the [`native-tls`](https://crates.io/crates/native-tls) crate
//! to secure the connection when needed. This loads the system-native
//! TLS library rather than a Rust-specific one.
//!
//! ## `async`
//!
//! This feature enables asynchronous HTTP requests using tokio. It provides
//! [`send_async()`](struct.Request.html#method.send_async) and
//! [`send_lazy_async()`](struct.Request.html#method.send_lazy_async) methods
//! that return futures for non-blocking operation.
//!
//! It also enables [`Client`](struct.Client.html) to reuse TCP connections
//! across requests.
//!
//! ## `async-https` or `async-https-rustls`
//!
//! Like `https` or `https-rustls` but also uses
//! [`tokio-rustls`](https://crates.io/crates/tokio-rustls) (provided by the
//! `rustls` team) to provide HTTPS support for async connections. Uses
//! `webpki-roots` to load certificate authorities.
//!
//! ## `async-https-rustls-probe`
//!
//! The above except the equivalent of `https-rustls-probe` - this uses
//! [`rustls-native-certs`](https://crates.io/crates/rustls-native-certs)
//! to load certificate authorities.
//!
//! ## `async-https-native-tls`
//!
//! Like `https-native-tls` but also uses the
//! [`tokio-native-tls`](https://crates.io/crates/tokio-native-tls) crate
//! (provided by the `tokio` team) to provide HTTPS support for async
//! connections.
//!
//! ## `proxy`
//!
//! This feature enables HTTP proxy support.
//!
//! # Examples
//!
//! ## Get
//!
//! This is a simple example of sending a GET request and checking the
//! response's body, status code, and reason phrase. The `?` are
//! needed because the server could return invalid UTF-8 in the body,
//! or something could go wrong while sending the request or receiving
//! the response.
//!
//! ```
//! # #[cfg(feature = "std")]
//! # fn main() -> Result<(), Box<dyn std::error::Error + Send + Sync>> {
//! # use std::thread;
//! # use tiny_http::{Response, Server};
//! #
//! # let server = Server::http("127.0.0.1:0")?;
//! # let addr = server.server_addr().to_ip().expect("IP listen addr");
//! # let server_thread = thread::spawn(move || {
//! #     let request = server.recv().expect("server recv");
//! #     let response = Response::from_string("<html></html>");
//! #     let _ = request.respond(response);
//! # });
//! #
//! # let url = format!("http://{addr}/");
//! let response = bitreq::get(&url).with_timeout(10).send()?;
//! assert!(response.as_str()?.contains("</html>"));
//! assert_eq!(200, response.status_code);
//! assert_eq!("OK", response.reason_phrase);
//! # server_thread.join().expect("server thread join");
//! # Ok(()) }
//! # #[cfg(not(feature = "std"))]
//! # fn main() -> Result<(), Box<dyn std::error::Error + Send + Sync>> { Ok(()) }
//! ```
//!
//! Note: you could change the `get` function to `head` or `put` or
//! any other HTTP request method: the api is the same for all of
//! them, it just changes what is sent to the server.
//!
//! ## Body (sending)
//!
//! To include a body, add `with_body("<body contents>")` before
//! `send()`.
//!
//! ```
//! # #[cfg(feature = "std")]
//! # fn main() -> Result<(), Box<dyn std::error::Error>> {
//! let response = bitreq::post("http://example.com")
//!     .with_body("Foobar")
//!     .send()?;
//! # Ok(()) }
//! # #[cfg(not(feature = "std"))]
//! # fn main() -> Result<(), Box<dyn std::error::Error>> { Ok(()) }
//! ```
//!
//! ## Headers (sending)
//!
//! To add a header, add `with_header("Key", "Value")` before
//! `send()`.
//!
//! ```
//! # #[cfg(feature = "std")]
//! # fn main() -> Result<(), Box<dyn std::error::Error>> {
//! let response = bitreq::get("http://example.com")
//!     .with_header("Accept", "text/html")
//!     .send()?;
//! # Ok(()) }
//! # #[cfg(not(feature = "std"))]
//! # fn main() -> Result<(), Box<dyn std::error::Error>> { Ok(()) }
//! ```
//!
//! ## Headers (receiving)
//!
//! Reading the headers sent by the servers is done via the
//! [`headers`](struct.Response.html#structfield.headers) field of the
//! [`Response`](struct.Response.html). Note: the header field names
//! (that is, the *keys* of the `HashMap`) are all lowercase: this is
//! because the names are case-insensitive according to the spec, and
//! this unifies the casings for easier `get()`ing.
//!
//! ```
//! # #[cfg(feature = "std")]
//! # fn main() -> Result<(), Box<dyn std::error::Error>> {
//! let response = bitreq::get("http://example.com").send()?;
//! assert!(response.headers.get("content-type").unwrap().starts_with("text/html"));
//! # Ok(()) }
//! # #[cfg(not(feature = "std"))]
//! # fn main() -> Result<(), Box<dyn std::error::Error>> { Ok(()) }
//! ```
//!
//! ## Timeouts
//!
//! To avoid timing out, or limit the request's response time, use
//! `with_timeout(n)` before `send()`. The given value is in seconds.
//!
//! NOTE: There is no timeout by default.
//!
//! ```no_run
//! # #[cfg(feature = "std")]
//! # fn main() -> Result<(), Box<dyn std::error::Error>> {
//! let response = bitreq::post("http://example.com")
//!     .with_timeout(10)
//!     .send()?;
//! # Ok(()) }
//! # #[cfg(not(feature = "std"))]
//! # fn main() -> Result<(), Box<dyn std::error::Error>> { Ok(()) }
//! ```
//!
//! ## Proxy
//!
//! To use a proxy server, simply create a `Proxy` instance and use
//! `.with_proxy()` on your request.
//!
//! Supported proxy formats are `host:port` and
//! `user:password@proxy:host`. Only HTTP CONNECT proxies are
//! supported at this time.
//!
//! ```no_run
//! # #[cfg(feature = "std")]
//! # fn main() -> Result<(), Box<dyn std::error::Error>> {
//! #[cfg(feature = "proxy")]
//! {
//!     let proxy = bitreq::Proxy::new_http("localhost:8080")?;
//!     let response = bitreq::post("http://example.com")
//!         .with_proxy(proxy)
//!         .send()?;
//!     println!("{}", response.as_str()?);
//! }
//! # Ok(()) }
//! # #[cfg(not(feature = "std"))]
//! # fn main() -> Result<(), Box<dyn std::error::Error>> { Ok(()) }
//! ```
//!
//! # Timeouts
//!
//! By default, a request has no timeout. You can change this in two
//! ways:
//!
//! - Use [`with_timeout`](struct.Request.html#method.with_timeout) on
//!   your request to set the timeout per-request like so:
//!   ```text,ignore
//!   bitreq::get("/").with_timeout(8).send();
//!   ```
//! - Set the environment variable `BITREQ_TIMEOUT` to the desired
//!   amount of seconds until timeout. Ie. if you have a program called
//!   `foo` that uses bitreq, and you want all the requests made by that
//!   program to timeout in 8 seconds, you launch the program like so:
//!   ```text,ignore
//!   $ BITREQ_TIMEOUT=8 ./foo
//!   ```
//!   Or add the following somewhere before the requests in the code.
//!   ```
//!   std::env::set_var("BITREQ_TIMEOUT", "8");
//!   ```
//! If the timeout is set with `with_timeout`, the environment
//! variable will be ignored.

#![deny(missing_docs)]
// std::io::Error::other was added in 1.74, so occurrences of this lint can't be
// fixed before our MSRV gets that high.
#![allow(clippy::io_other_error)]

extern crate alloc;

#[cfg(feature = "std")]
mod client;
#[cfg(feature = "std")]
mod connection;
mod error;
mod http_url;
#[cfg(feature = "proxy")]
mod proxy;
mod request;
mod response;
#[cfg(feature = "forms")]
mod urlencode;

#[cfg(feature = "async")]
pub use client::{Client, RequestExt};
pub use error::*;
#[cfg(feature = "proxy")]
pub use proxy::*;
pub use request::*;
pub use response::Response;
#[cfg(feature = "std")]
pub use response::ResponseLazy;