+ 
+
+# Fetch Tls
+
+[](https://crates.io/crates/fetch_tls)
+[](https://docs.rs/fetch_tls)
+[](https://crates.io/crates/fetch_tls)
+[](https://github.com/microsoft/oxidizer/actions/workflows/main.yml)
+[](https://codecov.io/gh/microsoft/oxidizer)
+[](../../LICENSE)
+
+
+
+
+Backend-agnostic TLS configuration for HTTP clients.
+
+`fetch_tls` separates *what* TLS behavior an application wants from
+*which* TLS implementation actually provides it. Applications describe
+their TLS requirements once, and the HTTP client (or other consuming
+library) decides which backend to materialize at runtime.
+
+## Two perspectives
+
+Applications work with [`TlsOptions`][__link0] (and its builder,
+[`TlsOptionsBuilder`][__link1]) to describe what they want: leave the backend
+choice entirely to the consuming library via
+[`TlsOptions::builder`][__link2], pick a specific backend, wrap an already-built
+backend, or use [`TlsOptions::default`][__link3] for backend-agnostic defaults.
+
+Libraries that adopt `fetch_tls` use [`TlsBackendBuilder`][__link4] to turn a
+[`TlsOptions`][__link5] into a ready-to-use [`TlsBackend`][__link6]. The library
+contributes the environment-specific pieces (such as the rustls crypto
+provider and default certificate verifier) and decides which backend to
+use when the application did not pin one.
+
+## Cargo features
+
+* `rustls` — enables the rustls backend. `fetch_tls` does not bundle a
+ crypto provider; the consuming library supplies one along with a
+ default server certificate verifier.
+* `native-tls` — enables the platform native TLS backend (`SChannel` on
+ Windows, Security Framework on `macOS`, `OpenSSL` on Linux).
+
+With neither feature enabled, the API surface is limited to wrapping a
+pre-built backend; attempting to build any other configuration returns
+a [`BackendError`][__link7].
+
+
+
+
+# Fetch Tls
+
+[](https://crates.io/crates/fetch_tls)
+[](https://docs.rs/fetch_tls)
+[](https://crates.io/crates/fetch_tls)
+[](https://github.com/microsoft/oxidizer/actions/workflows/main.yml)
+[](https://codecov.io/gh/microsoft/oxidizer)
+[](../../LICENSE)
+
+
++ +This crate was developed as part of The Oxidizer Project. Browse this crate's source code. + + + [__cargo_doc2readme_dependencies_info]: ggGkYW0CYXSEGy4k8ldDFPOhG2VNeXtD5nnKG6EPY6OfW5wBG8g18NOFNdxpYXKEG0APetLRG81kG2jqZKP1V1oAGzCNx4vdBBsCG91rLMGz6fsVYWSBgmlmZXRjaF90bHNlMC4yLjA + [__link0]: https://docs.rs/fetch_tls/0.2.0/fetch_tls/?search=TlsOptions + [__link1]: https://docs.rs/fetch_tls/0.2.0/fetch_tls/?search=TlsOptionsBuilder + [__link2]: https://docs.rs/fetch_tls/0.2.0/fetch_tls/?search=TlsOptions::builder + [__link3]: https://docs.rs/fetch_tls/0.2.0/fetch_tls/?search=TlsOptions::default + [__link4]: https://docs.rs/fetch_tls/0.2.0/fetch_tls/?search=TlsBackendBuilder + [__link5]: https://docs.rs/fetch_tls/0.2.0/fetch_tls/?search=TlsOptions + [__link6]: https://docs.rs/fetch_tls/0.2.0/fetch_tls/?search=TlsBackend + [__link7]: https://docs.rs/fetch_tls/0.2.0/fetch_tls/?search=BackendError diff --git a/crates/fetch_tls/favicon.ico b/crates/fetch_tls/favicon.ico new file mode 100644 index 000000000..b394ce24d --- /dev/null +++ b/crates/fetch_tls/favicon.ico @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:118aa67d3e567980eae98e411c94eb6703b152121ff16fd286ad10c7406c98a8 +size 201783 diff --git a/crates/fetch_tls/logo.png b/crates/fetch_tls/logo.png new file mode 100644 index 000000000..2196837fc --- /dev/null +++ b/crates/fetch_tls/logo.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:fd2869fb1f894691ce53146253fc98b5b00ff1bef9b1af443d4c4943cac7a6ff +size 88709 diff --git a/crates/fetch_tls/src/alpn.rs b/crates/fetch_tls/src/alpn.rs new file mode 100644 index 000000000..737020289 --- /dev/null +++ b/crates/fetch_tls/src/alpn.rs @@ -0,0 +1,52 @@ +// Copyright (c) Microsoft Corporation. +// Licensed under the MIT License. + +//! `ALPN` protocol mapping from supported HTTP versions. + +use http::Version; + +const HTTP_11_ALPN: &str = "http/1.1"; +const HTTP_2_ALPN: &str = "h2"; + +/// Maps configured HTTP versions to the advertised `ALPN` identifiers. +pub(crate) fn map_to_alpn(versions: &[Version]) -> &[&str] { + let http1 = supports_http1(versions); + let http2 = supports_http2(versions); + if http2 && http1 { + &[HTTP_2_ALPN, HTTP_11_ALPN] + } else if http2 { + &[HTTP_2_ALPN] + } else if http1 { + &[HTTP_11_ALPN] + } else { + &[] + } +} + +fn supports_http1(versions: &[Version]) -> bool { + versions.contains(&Version::HTTP_11) || versions.contains(&Version::HTTP_10) +} + +fn supports_http2(versions: &[Version]) -> bool { + versions.contains(&Version::HTTP_2) +} + +#[cfg(test)] +#[cfg_attr(coverage_nightly, coverage(off))] +mod tests { + use rstest::rstest; + + use super::*; + + #[rstest] + #[case(&[Version::HTTP_11, Version::HTTP_2], &["h2", "http/1.1"])] + #[case(&[Version::HTTP_2], &["h2"])] + #[case(&[Version::HTTP_11], &["http/1.1"])] + #[case(&[Version::HTTP_10], &["http/1.1"])] + #[case(&[], &[])] + #[case(&[Version::HTTP_3], &[])] + #[case(&[Version::HTTP_10, Version::HTTP_2], &["h2", "http/1.1"])] + fn map_to_alpn(#[case] versions: &[Version], #[case] expected_str: &[&str]) { + assert_eq!(super::map_to_alpn(versions), expected_str); + } +} diff --git a/crates/fetch_tls/src/backend.rs b/crates/fetch_tls/src/backend.rs new file mode 100644 index 000000000..a67224aa9 --- /dev/null +++ b/crates/fetch_tls/src/backend.rs @@ -0,0 +1,55 @@ +// Copyright (c) Microsoft Corporation. +// Licensed under the MIT License. + +//! Fully constructed TLS backends ready for use by an HTTP client. + +/// Error returned when materializing a [`TlsBackend`] from +/// [`TlsOptions`](super::TlsOptions) fails. +#[ohno::error] +pub struct BackendError; + +/// A fully constructed TLS backend ready for use by an HTTP client. +/// +/// Where [`TlsOptions`](super::TlsOptions) describes *how* to build a TLS +/// configuration, `TlsBackend` holds the result. Which variants are +/// available depends on the enabled Cargo features. +/// +/// Typically produced by [`TlsBackendBuilder`](super::TlsBackendBuilder); +/// construct directly only when wrapping a backend you have already built. +#[derive(Debug, Clone)] +#[allow( + clippy::allow_attributes, + clippy::large_enum_variant, + reason = "configuration object; boxing would clutter the public API without performance benefit" +)] +pub enum TlsBackend { + /// rustls backend, carrying a shared `rustls::ClientConfig`. + #[cfg(any(feature = "rustls", test))] + Rustls(std::sync::Arc<::rustls::ClientConfig>), + + /// Platform native TLS backend (`SChannel` on Windows, Security Framework + /// on `macOS`, `OpenSSL` on Linux). + #[cfg(any(feature = "native-tls", test))] + NativeTls(::native_tls::TlsConnector), +} + +#[cfg(any(feature = "rustls", test))] +impl From<::rustls::ClientConfig> for TlsBackend { + fn from(config: ::rustls::ClientConfig) -> Self { + Self::Rustls(std::sync::Arc::new(config)) + } +} + +#[cfg(any(feature = "rustls", test))] +impl From