|
| 1 | +# opendal-http-transport-reqwest |
| 2 | + |
| 3 | +Reqwest-based HTTP transport for [Apache OpenDAL](https://opendal.apache.org). |
| 4 | + |
| 5 | +This crate provides `ReqwestTransport`, an implementation of OpenDAL's |
| 6 | +`HttpTransport` trait backed by [reqwest](https://crates.io/crates/reqwest). |
| 7 | + |
| 8 | +## TLS configuration |
| 9 | + |
| 10 | +OpenDAL does not add another TLS backend selector on top of reqwest. Pick the |
| 11 | +Cargo feature set you need, build a `reqwest::Client` with reqwest's |
| 12 | +`ClientBuilder`, and pass that client to `ReqwestTransport::new`. |
| 13 | + |
| 14 | +The default feature is `rustls`. When `ReqwestTransport::default()` is used on |
| 15 | +native targets, this crate explicitly asks reqwest for the Rustls backend if the |
| 16 | +`rustls` feature is compiled in. |
| 17 | + |
| 18 | +If this crate is built with only `rustls-no-provider`, install a Rustls default |
| 19 | +crypto provider before using `ReqwestTransport::default()`, or build a |
| 20 | +preconfigured `reqwest::Client` yourself and pass it to `ReqwestTransport::new`. |
| 21 | + |
| 22 | +### Reqwest TLS resolution |
| 23 | + |
| 24 | +Reqwest has its own TLS resolution rules. For OpenDAL users, the practical |
| 25 | +resolution order is: |
| 26 | + |
| 27 | +- Explicit reqwest client configuration wins. Call |
| 28 | + `ClientBuilder::tls_backend_rustls()`, |
| 29 | + `ClientBuilder::tls_backend_native()`, or |
| 30 | + `ClientBuilder::tls_backend_preconfigured()`, but reqwest documents that API |
| 31 | + as semver-unstable because the concrete TLS config type must match reqwest's |
| 32 | + dependency versions. |
| 33 | +- Otherwise, reqwest's automatic TLS backend selection applies. The reqwest |
| 34 | + `default-tls` feature takes precedence if any crate in the dependency tree |
| 35 | + enables it. Disable reqwest defaults with `default-features = false` when you |
| 36 | + need deterministic TLS features. |
| 37 | +- Cargo features are additive. If multiple TLS backends are compiled by feature |
| 38 | + unification, use explicit client configuration instead of relying on automatic |
| 39 | + selection. |
| 40 | + |
| 41 | +See reqwest's TLS documentation: |
| 42 | + |
| 43 | +- [reqwest TLS module](https://docs.rs/reqwest/latest/reqwest/tls/index.html) |
| 44 | +- [ClientBuilder::tls_backend_rustls](https://docs.rs/reqwest/latest/reqwest/struct.ClientBuilder.html#method.tls_backend_rustls) |
| 45 | +- [ClientBuilder::tls_backend_native](https://docs.rs/reqwest/latest/reqwest/struct.ClientBuilder.html#method.tls_backend_native) |
| 46 | +- [ClientBuilder::tls_backend_preconfigured](https://docs.rs/reqwest/latest/reqwest/struct.ClientBuilder.html#method.tls_backend_preconfigured) |
| 47 | + |
| 48 | +### Feature matrix |
| 49 | + |
| 50 | +| Feature | Crypto provider | Certificate roots | Use when | |
| 51 | +|---------|-----------------|-------------------|----------| |
| 52 | +| `rustls` (default) | reqwest default | Platform verifier | Pure-Rust TLS with the system trust store | |
| 53 | +| `rustls-no-provider` | You provide | You provide | BYO crypto provider, roots, or FIPS module | |
| 54 | +| `native-tls` | OS library | OS trust store | You want platform TLS | |
| 55 | + |
| 56 | +## Cargo features |
| 57 | + |
| 58 | +Most users depend on the `opendal` facade crate: |
| 59 | + |
| 60 | +```toml |
| 61 | +[dependencies] |
| 62 | +# Default: reqwest transport with rustls. |
| 63 | +opendal = { version = "0.57" } |
| 64 | +``` |
| 65 | + |
| 66 | +To select one transport TLS feature explicitly, disable default features: |
| 67 | + |
| 68 | +```toml |
| 69 | +[dependencies] |
| 70 | +opendal = { version = "0.57", default-features = false, features = [ |
| 71 | + "http-transport-reqwest-rustls", |
| 72 | +] } |
| 73 | +``` |
| 74 | + |
| 75 | +## Build different TLS backends |
| 76 | + |
| 77 | +### Rustls |
| 78 | + |
| 79 | +Use reqwest's Rustls backend explicitly when you build the client: |
| 80 | + |
| 81 | +```toml |
| 82 | +[dependencies] |
| 83 | +opendal = { version = "0.57", default-features = false, features = [ |
| 84 | + "http-transport-reqwest-rustls", |
| 85 | +] } |
| 86 | +reqwest = { version = "0.13.4", default-features = false, features = [ |
| 87 | + "rustls", |
| 88 | + "stream", |
| 89 | +] } |
| 90 | +``` |
| 91 | + |
| 92 | +```rust |
| 93 | +use std::time::Duration; |
| 94 | + |
| 95 | +use opendal::HttpTransporter; |
| 96 | +use opendal::ReqwestTransport; |
| 97 | + |
| 98 | +fn build_transport() -> Result<HttpTransporter, Box<dyn std::error::Error>> { |
| 99 | + let client = reqwest::Client::builder() |
| 100 | + .tls_backend_rustls() |
| 101 | + .connect_timeout(Duration::from_secs(10)) |
| 102 | + .build()?; |
| 103 | + |
| 104 | + Ok(HttpTransporter::new(ReqwestTransport::new(client))) |
| 105 | +} |
| 106 | +``` |
| 107 | + |
| 108 | +### Native TLS |
| 109 | + |
| 110 | +Use `native-tls` when you want reqwest to delegate TLS to the platform stack: |
| 111 | + |
| 112 | +```toml |
| 113 | +[dependencies] |
| 114 | +opendal = { version = "0.57", default-features = false, features = [ |
| 115 | + "http-transport-reqwest-native-tls", |
| 116 | +] } |
| 117 | +reqwest = { version = "0.13.4", default-features = false, features = [ |
| 118 | + "native-tls", |
| 119 | + "stream", |
| 120 | +] } |
| 121 | +``` |
| 122 | + |
| 123 | +```rust |
| 124 | +use opendal::HttpTransporter; |
| 125 | +use opendal::ReqwestTransport; |
| 126 | + |
| 127 | +fn build_transport() -> Result<HttpTransporter, Box<dyn std::error::Error>> { |
| 128 | + let client = reqwest::Client::builder() |
| 129 | + .tls_backend_native() |
| 130 | + .build()?; |
| 131 | + |
| 132 | + Ok(HttpTransporter::new(ReqwestTransport::new(client))) |
| 133 | +} |
| 134 | +``` |
| 135 | + |
| 136 | +### rustls-no-provider |
| 137 | + |
| 138 | +When using `wekpki-roots`, you could use `rustls-no-provider`. |
| 139 | + |
| 140 | +Use `rustls-no-provider` when the application owns the Rustls provider and |
| 141 | +certificate roots. This example only configures Mozilla roots from |
| 142 | +`webpki-roots`; install or configure the Rustls crypto provider in application |
| 143 | +startup. |
| 144 | + |
| 145 | +```toml |
| 146 | +[dependencies] |
| 147 | +opendal = { version = "0.57", default-features = false, features = [ |
| 148 | + "http-transport-reqwest-rustls-no-provider", |
| 149 | +] } |
| 150 | +reqwest = { version = "0.13.4", default-features = false, features = [ |
| 151 | + "rustls-no-provider", |
| 152 | + "stream", |
| 153 | +] } |
| 154 | +rustls = { version = "0.23", default-features = false, features = ["std"] } |
| 155 | +webpki-roots = "1" |
| 156 | +``` |
| 157 | + |
| 158 | +```rust |
| 159 | +use opendal::HttpTransporter; |
| 160 | +use opendal::ReqwestTransport; |
| 161 | + |
| 162 | +fn build_transport() -> Result<HttpTransporter, Box<dyn std::error::Error>> { |
| 163 | + let root_store = |
| 164 | + rustls::RootCertStore::from_iter(webpki_roots::TLS_SERVER_ROOTS.iter().cloned()); |
| 165 | + |
| 166 | + let tls_config = rustls::ClientConfig::builder() |
| 167 | + .with_root_certificates(root_store) |
| 168 | + .with_no_client_auth(); |
| 169 | + |
| 170 | + let client = reqwest::Client::builder() |
| 171 | + .tls_backend_preconfigured(tls_config) |
| 172 | + .build()?; |
| 173 | + |
| 174 | + Ok(HttpTransporter::new(ReqwestTransport::new(client))) |
| 175 | +} |
| 176 | +``` |
| 177 | + |
| 178 | +To use `ring` crate, please refer `rustls` documentation. |
| 179 | + |
| 180 | +## WASM targets |
| 181 | + |
| 182 | +On `wasm32-unknown-unknown` and `wasm32-none`, reqwest switches to its WASM |
| 183 | +client implementation. It uses the browser or host Fetch API instead of hyper. |
| 184 | +TLS is provided by the browser or host environment, so the effective choice is |
| 185 | +the system TLS stack exposed to that environment. |
| 186 | + |
| 187 | +This means `native-tls`, `rustls`, `rustls-no-provider`, custom root stores, |
| 188 | +and custom Rustls crypto providers do not select the TLS implementation for |
| 189 | +wasm requests. See [reqwest's WASM documentation](https://docs.rs/reqwest/latest/reqwest/#wasm) |
| 190 | +for the target-specific limitations. |
| 191 | + |
| 192 | +## License and Trademarks |
| 193 | + |
| 194 | +Licensed under the Apache License, Version 2.0: http://www.apache.org/licenses/LICENSE-2.0 |
| 195 | + |
| 196 | +Apache OpenDAL, OpenDAL, and Apache are either registered trademarks or trademarks of the Apache Software Foundation. |
0 commit comments