web_faith/
lib.rs

1//! A browser-shaped HTTP client.
2//!
3//! Faith behaves like a browser ("faithfully") wherever that translates to a server-side runtime:
4//! transparent HTTP/2 and HTTP/3 upgrades, Happy Eyeballs across IPv4 and IPv6, DNS caching, an
5//! optional cookie jar, and HTTP caching. We also publish the reusable components as separate
6//! crates.
7//!
8//! ```no_run
9//! use web_faith::Agent;
10//!
11//! # async fn example() -> Result<(), web_faith::FaithError> {
12//! let agent = Agent::new()?;
13//! let body = agent.fetch("https://example.com/").await?.text().await?;
14//! # Ok(())
15//! # }
16//! ```
17//!
18//! # HTTP/3 is opt-in
19//!
20//! Faith uses reqwest internally, and its HTTP/3 support is currently unstable. To enable HTTP/3
21//! support, you will need to set the `http3` feature on Faith, and use the `reqwest_unstable` rustc
22//! cfg flag:
23//!
24//! ```bash
25//! cargo add web-faith -F http3
26//! ```
27//!
28//! ```toml
29//! # .cargo/config.toml
30//! [build]
31//! rustflags = ["--cfg", "reqwest_unstable"]
32//! ```
33//!
34//! # Features
35//!
36//! | Feature | Default | What it adds |
37//! | --- | :-: | --- |
38//! | `cache` | ✓ | The HTTP cache. |
39//! | `connection-tracking` | ✓ | Kernel connection counters. |
40//! | `cookies` | ✓ | The cookie jar. |
41//! | `dns` | ✓ | Faith's own caching resolver. Without it, names resolve through the platform. |
42//! | `encoding` | ✓ | Content codings for request and response bodies. |
43//! | `tls-aws-lc-rs` | ✓ | aws-lc-rs as the rustls crypto provider. |
44//! | `tls-ring` |  | ring as the rustls crypto provider instead. |
45//! | `http3` |  | Transparent HTTP/3, upgraded into via Alt-Svc. Needs the cfg flag above. |
46//! | `raw-client` |  | Access to the reqwest client underneath. |
47//! | `unstable-internals` |  | Faith's internals. Permanently unstable and exempt from semver. |
48//!
49//! # Component crates
50//!
51//! - [`web-faith-cookies`](https://docs.rs/web-faith-cookies)
52//! - [`web-faith-dns`](https://docs.rs/web-faith-dns)
53//! - [`web-faith-conn-tracker`](https://docs.rs/web-faith-conn-tracker)
54//! - [`web-faith-alt-svc`](https://docs.rs/web-faith-alt-svc)
55//! - [`web-faith-encoding`](https://docs.rs/web-faith-encoding)
56//!
57//! # Elsewhere
58//!
59//! Faith is also a Node.js module which lets you use this Rust networking stack as a `fetch`
60//! drop-in replacement: [`@passcod/faith`](https://www.npmjs.com/package/@passcod/faith).
61
62#![deny(missing_docs)]
63// Lets docs.rs label each item with the feature or platform it needs.
64#![cfg_attr(docsrs, feature(doc_cfg))]
65
66// A build with no crypto provider cannot speak TLS, and an HTTPS client that cannot is not one.
67// Selecting a provider is therefore a choice between the two rather than an option to decline.
68#[cfg(not(any(feature = "tls-aws-lc-rs", feature = "tls-ring")))]
69compile_error!("web-faith needs a TLS backend: enable either tls-aws-lc-rs or tls-ring");
70
71pub mod agent;
72pub mod error;
73pub mod request;
74pub mod response;
75
76mod builder;
77mod client;
78mod integrity;
79mod retry;
80mod stats;
81mod timing;
82mod warm_up;
83
84// `unstable-internals` decides whether these module paths are public. The option types the
85// ordinary builder path needs are re-exported from `agent` either way; `doc(cfg(all()))` on the
86// private arm stops rustdoc labelling those re-exports as needing `not(unstable-internals)`.
87#[cfg(feature = "unstable-internals")]
88pub mod body;
89#[cfg(not(feature = "unstable-internals"))]
90#[cfg_attr(docsrs, doc(cfg(all())))]
91mod body;
92
93#[cfg(feature = "unstable-internals")]
94pub mod options;
95#[cfg(not(feature = "unstable-internals"))]
96#[cfg_attr(docsrs, doc(cfg(all())))]
97mod options;
98
99/// The `User-Agent` a request carries when nothing overrides it.
100///
101/// Prepend your own product token to it rather than replacing it, so a server still sees which
102/// client is calling:
103///
104/// ```
105/// # use web_faith::USER_AGENT;
106/// let ua = format!("YourApp/1.2.3 {USER_AGENT}");
107/// assert!(ua.ends_with(USER_AGENT));
108/// ```
109pub const USER_AGENT: &str = concat!(
110	"Faith/",
111	env!("CARGO_PKG_VERSION"),
112	" reqwest/",
113	env!("REQWEST_VERSION")
114);
115
116pub use agent::Agent;
117pub use error::FaithError;
118pub use request::Request;
119pub use response::Response;
120
121#[cfg(feature = "unstable-internals")]
122pub use error::error_codes;
web_faith/lib.rs

web_faith/
lib.rs
