web-faith 1.1.0

A browser-shaped HTTP client
Documentation 
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

//! A browser-shaped HTTP client.
//!
//! Faith behaves like a browser ("faithfully") wherever that translates to a server-side runtime:
//! transparent HTTP/2 and HTTP/3 upgrades, Happy Eyeballs across IPv4 and IPv6, DNS caching, an
//! optional cookie jar, and HTTP caching. We also publish the reusable components as separate
//! crates.
//!
//! ```no_run
//! use web_faith::Agent;
//!
//! # async fn example() -> Result<(), web_faith::FaithError> {
//! let agent = Agent::new()?;
//! let body = agent.fetch("https://example.com/").await?.text().await?;
//! # Ok(())
//! # }
//! ```
//!
//! # HTTP/3 is opt-in
//!
//! Faith uses reqwest internally, and its HTTP/3 support is currently unstable. To enable HTTP/3
//! support, you will need to set the `http3` feature on Faith, and use the `reqwest_unstable` rustc
//! cfg flag:
//!
//! ```bash
//! cargo add web-faith -F http3
//! ```
//!
//! ```toml
//! # .cargo/config.toml
//! [build]
//! rustflags = ["--cfg", "reqwest_unstable"]
//! ```
//!
//! # Features
//!
//! | Feature | Default | What it adds |
//! | --- | :-: | --- |
//! | `cache` | ✓ | The HTTP cache. |
//! | `connection-tracking` | ✓ | Kernel connection counters. |
//! | `cookies` | ✓ | The cookie jar. |
//! | `dns` | ✓ | Faith's own caching resolver. Without it, names resolve through the platform. |
//! | `encoding` | ✓ | Content codings for request and response bodies. |
//! | `tls-aws-lc-rs` | ✓ | aws-lc-rs as the rustls crypto provider. |
//! | `tls-ring` |  | ring as the rustls crypto provider instead. |
//! | `http3` |  | Transparent HTTP/3, upgraded into via Alt-Svc. Needs the cfg flag above. |
//! | `raw-client` |  | Access to the reqwest client underneath. |
//! | `unstable-internals` |  | Faith's internals. Permanently unstable and exempt from semver. |
//!
//! # Component crates
//!
//! - [`web-faith-cookies`](https://docs.rs/web-faith-cookies)
//! - [`web-faith-dns`](https://docs.rs/web-faith-dns)
//! - [`web-faith-conn-tracker`](https://docs.rs/web-faith-conn-tracker)
//! - [`web-faith-alt-svc`](https://docs.rs/web-faith-alt-svc)
//! - [`web-faith-encoding`](https://docs.rs/web-faith-encoding)
//!
//! # Elsewhere
//!
//! Faith is also a Node.js module which lets you use this Rust networking stack as a `fetch`
//! drop-in replacement: [`@passcod/faith`](https://www.npmjs.com/package/@passcod/faith).

#![deny(missing_docs)]
// Lets docs.rs label each item with the feature or platform it needs.
#![cfg_attr(docsrs, feature(doc_cfg))]

// A build with no crypto provider cannot speak TLS, and an HTTPS client that cannot is not one.
// Selecting a provider is therefore a choice between the two rather than an option to decline.
#[cfg(not(any(feature = "tls-aws-lc-rs", feature = "tls-ring")))]
compile_error!("web-faith needs a TLS backend: enable either tls-aws-lc-rs or tls-ring");

pub mod agent;
pub mod error;
pub mod request;
pub mod response;

mod builder;
mod client;
mod integrity;
mod retry;
mod stats;
mod timing;
mod warm_up;

// `unstable-internals` decides whether these module paths are public. The option types the
// ordinary builder path needs are re-exported from `agent` either way; `doc(cfg(all()))` on the
// private arm stops rustdoc labelling those re-exports as needing `not(unstable-internals)`.
#[cfg(feature = "unstable-internals")]
pub mod body;
#[cfg(not(feature = "unstable-internals"))]
#[cfg_attr(docsrs, doc(cfg(all())))]
mod body;

#[cfg(feature = "unstable-internals")]
pub mod options;
#[cfg(not(feature = "unstable-internals"))]
#[cfg_attr(docsrs, doc(cfg(all())))]
mod options;

/// The `User-Agent` a request carries when nothing overrides it.
///
/// Prepend your own product token to it rather than replacing it, so a server still sees which
/// client is calling:
///
/// ```
/// # use web_faith::USER_AGENT;
/// let ua = format!("YourApp/1.2.3 {USER_AGENT}");
/// assert!(ua.ends_with(USER_AGENT));
/// ```
pub const USER_AGENT: &str = concat!(
	"Faith/",
	env!("CARGO_PKG_VERSION"),
	" reqwest/",
	env!("REQWEST_VERSION")
);

pub use agent::Agent;
pub use error::FaithError;
pub use request::Request;
pub use response::Response;

#[cfg(feature = "unstable-internals")]
pub use error::error_codes;