diff options
| -rw-r--r-- | .bleep | 2 | ||||
| -rw-r--r-- | pingora-core/src/lib.rs | 4 | ||||
| -rw-r--r-- | pingora-core/src/listeners/mod.rs | 5 | ||||
| -rw-r--r-- | pingora-core/src/modules/http/mod.rs | 6 | ||||
| -rw-r--r-- | pingora-core/src/protocols/http/client.rs | 2 | ||||
| -rw-r--r-- | pingora-core/src/protocols/http/v1/client.rs | 2 | ||||
| -rw-r--r-- | pingora-core/src/protocols/http/v2/client.rs | 2 | ||||
| -rw-r--r-- | pingora-core/src/protocols/mod.rs | 2 | ||||
| -rw-r--r-- | pingora-core/src/protocols/tls/noop_tls/mod.rs | 4 | ||||
| -rw-r--r-- | pingora-core/src/server/configuration/mod.rs | 13 | ||||
| -rw-r--r-- | pingora-rustls/Cargo.toml | 2 | ||||
| -rw-r--r-- | pingora/Cargo.toml | 56 | ||||
| -rw-r--r-- | pingora/src/lib.rs | 11 |
13 files changed, 82 insertions, 29 deletions
@@ -1 +1 @@ -9ec41e3e1817e36107195f6ca1a3168779857cc7
\ No newline at end of file +f03c6a3f42dddc28f95bc10022de285e10223866 diff --git a/pingora-core/src/lib.rs b/pingora-core/src/lib.rs index f4b5106..4f38580 100644 --- a/pingora-core/src/lib.rs +++ b/pingora-core/src/lib.rs @@ -37,6 +37,10 @@ //! # Optional features //! `boringssl`: Switch the internal TLS library from OpenSSL to BoringSSL. +// This enables the feature that labels modules that are only available with +// certain pingora features +#![cfg_attr(docsrs, feature(doc_cfg))] + pub mod apps; pub mod connectors; pub mod listeners; diff --git a/pingora-core/src/listeners/mod.rs b/pingora-core/src/listeners/mod.rs index 4a21632..02a7b83 100644 --- a/pingora-core/src/listeners/mod.rs +++ b/pingora-core/src/listeners/mod.rs @@ -41,8 +41,9 @@ pub use l4::{ServerAddress, TcpSocketOptions}; #[async_trait] pub trait TlsAccept { // TODO: return error? - /// This function is called in the middle of a TLS handshake. Structs who implement this function - /// should provide tls certificate and key to the [TlsRef] via [ext::ssl_use_certificate] and [ext::ssl_use_private_key]. + /// This function is called in the middle of a TLS handshake. Structs who + /// implement this function should provide tls certificate and key to the + /// [TlsRef] via `ssl_use_certificate` and `ssl_use_private_key`. async fn certificate_callback(&self, _ssl: &mut TlsRef) -> () { // does nothing by default } diff --git a/pingora-core/src/modules/http/mod.rs b/pingora-core/src/modules/http/mod.rs index f4b17ad..c04404b 100644 --- a/pingora-core/src/modules/http/mod.rs +++ b/pingora-core/src/modules/http/mod.rs @@ -14,9 +14,11 @@ //! Modules for HTTP traffic. //! -//! [HttpModule]s define request and response filters to use while running an [HttpServer] +//! [HttpModule]s define request and response filters to use while running an +//! [HttpServer](crate::apps::http_app::HttpServer) //! application. -//! See the [ResponseCompression] module for an example of how to implement a basic module. +//! See the [ResponseCompression](crate::modules::http::compression::ResponseCompression) +//! module for an example of how to implement a basic module. pub mod compression; pub mod grpc_web; diff --git a/pingora-core/src/protocols/http/client.rs b/pingora-core/src/protocols/http/client.rs index 4d3044d..6b1e00a 100644 --- a/pingora-core/src/protocols/http/client.rs +++ b/pingora-core/src/protocols/http/client.rs @@ -161,7 +161,7 @@ impl HttpSession { } } - /// Return a mutable [Digest] reference for the connection, see [`digest`] for more details. + /// Return a mutable [Digest] reference for the connection. /// /// Will return `None` if this is an H2 session and multiple streams are open. pub fn digest_mut(&mut self) -> Option<&mut Digest> { diff --git a/pingora-core/src/protocols/http/v1/client.rs b/pingora-core/src/protocols/http/v1/client.rs index 2b2640b..7125e49 100644 --- a/pingora-core/src/protocols/http/v1/client.rs +++ b/pingora-core/src/protocols/http/v1/client.rs @@ -639,7 +639,7 @@ impl HttpSession { &self.digest } - /// Return a mutable [Digest] reference for the connection, see [`digest`] for more details. + /// Return a mutable [Digest] reference for the connection. pub fn digest_mut(&mut self) -> &mut Digest { &mut self.digest } diff --git a/pingora-core/src/protocols/http/v2/client.rs b/pingora-core/src/protocols/http/v2/client.rs index 1d89004..4d5559a 100644 --- a/pingora-core/src/protocols/http/v2/client.rs +++ b/pingora-core/src/protocols/http/v2/client.rs @@ -310,7 +310,7 @@ impl Http2Session { Some(self.conn.digest()) } - /// Return a mutable [Digest] reference for the connection, see [`digest`] for more details. + /// Return a mutable [Digest] reference for the connection /// /// Will return `None` if multiple H2 streams are open. pub fn digest_mut(&mut self) -> Option<&mut Digest> { diff --git a/pingora-core/src/protocols/mod.rs b/pingora-core/src/protocols/mod.rs index c9218b9..007675b 100644 --- a/pingora-core/src/protocols/mod.rs +++ b/pingora-core/src/protocols/mod.rs @@ -59,7 +59,7 @@ pub trait Ssl { None } - /// Return the [`ssl::SslDigest`] for logging + /// Return the [`tls::SslDigest`] for logging fn get_ssl_digest(&self) -> Option<Arc<tls::SslDigest>> { None } diff --git a/pingora-core/src/protocols/tls/noop_tls/mod.rs b/pingora-core/src/protocols/tls/noop_tls/mod.rs index 5e8a701..ee34a0c 100644 --- a/pingora-core/src/protocols/tls/noop_tls/mod.rs +++ b/pingora-core/src/protocols/tls/noop_tls/mod.rs @@ -108,7 +108,7 @@ pub mod stream { use tokio::io::{AsyncRead, AsyncWrite, ReadBuf}; use crate::protocols::{ - GetProxyDigest, GetSocketDigest, GetTimingDigest, Shutdown, Ssl, UniqueID, + GetProxyDigest, GetSocketDigest, GetTimingDigest, Peek, Shutdown, Ssl, UniqueID, }; /// A TLS session over a stream. @@ -194,6 +194,8 @@ pub mod stream { None } } + + impl<S> Peek for SslStream<S> {} } pub mod utils { diff --git a/pingora-core/src/server/configuration/mod.rs b/pingora-core/src/server/configuration/mod.rs index 21428aa..db03455 100644 --- a/pingora-core/src/server/configuration/mod.rs +++ b/pingora-core/src/server/configuration/mod.rs @@ -67,21 +67,24 @@ pub struct ServerConf { /// Timeout in seconds of the final step for the graceful shutdown. pub graceful_shutdown_timeout_seconds: Option<u64>, // These options don't belong here as they are specific to certain services - /// IPv4 addresses for a client connector to bind to. See [`ConnectorOptions`]. + /// IPv4 addresses for a client connector to bind to. See + /// [`ConnectorOptions`](crate::connectors::ConnectorOptions). /// Note: this is an _unstable_ field that may be renamed or removed in the future. pub client_bind_to_ipv4: Vec<String>, - /// IPv6 addresses for a client connector to bind to. See [`ConnectorOptions`]. + /// IPv6 addresses for a client connector to bind to. See + /// [`ConnectorOptions`](crate::connectors::ConnectorOptions). /// Note: this is an _unstable_ field that may be renamed or removed in the future. pub client_bind_to_ipv6: Vec<String>, - /// Keepalive pool size for client connections to upstream. See [`ConnectorOptions`]. + /// Keepalive pool size for client connections to upstream. See + /// [`ConnectorOptions`](crate::connectors::ConnectorOptions). /// Note: this is an _unstable_ field that may be renamed or removed in the future. pub upstream_keepalive_pool_size: usize, /// Number of dedicated thread pools to use for upstream connection establishment. - /// See [`ConnectorOptions`]. + /// See [`ConnectorOptions`](crate::connectors::ConnectorOptions). /// Note: this is an _unstable_ field that may be renamed or removed in the future. pub upstream_connect_offload_threadpools: Option<usize>, /// Number of threads per dedicated upstream connection establishment pool. - /// See [`ConnectorOptions`]. + /// See [`ConnectorOptions`](crate::connectors::ConnectorOptions). /// Note: this is an _unstable_ field that may be renamed or removed in the future. pub upstream_connect_offload_thread_per_pool: Option<usize>, /// When enabled allows TLS keys to be written to a file specified by the SSLKEYLOG diff --git a/pingora-rustls/Cargo.toml b/pingora-rustls/Cargo.toml index 858ce30..677cf18 100644 --- a/pingora-rustls/Cargo.toml +++ b/pingora-rustls/Cargo.toml @@ -1,7 +1,6 @@ [package] name = "pingora-rustls" version = "0.3.0" -authors = ["Harald Gutmann <[email protected]>"] license = "Apache-2.0" edition = "2021" repository = "https://github.com/cloudflare/pingora" @@ -11,7 +10,6 @@ description = """ RusTLS async APIs for Pingora. """ -# See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html [lib] name = "pingora_rustls" path = "src/lib.rs" diff --git a/pingora/Cargo.toml b/pingora/Cargo.toml index 8dccca1..4213c65 100644 --- a/pingora/Cargo.toml +++ b/pingora/Cargo.toml @@ -18,7 +18,7 @@ name = "pingora" path = "src/lib.rs" [package.metadata.docs.rs] -all-features = true +features = ["document-features"] rustdoc-args = ["--cfg", "docsrs"] [dependencies] @@ -29,6 +29,10 @@ pingora-load-balancing = { version = "0.3.0", path = "../pingora-load-balancing" pingora-proxy = { version = "0.3.0", path = "../pingora-proxy", optional = true, default-features = false } pingora-cache = { version = "0.3.0", path = "../pingora-cache", optional = true, default-features = false } +# Only used for documenting features, but doesn't work in any other dependency +# group :( +document-features = { version = "0.2.10", optional = true } + [dev-dependencies] clap = { version = "3.2.25", features = ["derive"] } tokio = { workspace = true, features = ["rt-multi-thread", "signal"] } @@ -50,6 +54,15 @@ jemallocator = "0.5" [features] default = [] + +#! ### Tls +#! Tls is provided by adding one of these features. If no tls-providing feature +#! is added, only unencrypted http. Only one tls-providing feature can be +#! selected at a time + +## Use [OpenSSL](https://crates.io/crates/openssl) for tls +## +## Requires native openssl libraries and build tooling openssl = [ "pingora-core/openssl", "pingora-proxy?/openssl", @@ -57,6 +70,10 @@ openssl = [ "pingora-load-balancing?/openssl", "openssl_derived", ] + +## Use [BoringSSL](https://crates.io/crates/boring) for tls +## +## Requires native boring libraries and build tooling boringssl = [ "pingora-core/boringssl", "pingora-proxy?/boringssl", @@ -64,11 +81,11 @@ boringssl = [ "pingora-load-balancing?/boringssl", "openssl_derived", ] -proxy = ["pingora-proxy"] -lb = ["pingora-load-balancing", "proxy"] -cache = ["pingora-cache"] -time = [] -sentry = ["pingora-core/sentry"] + +# Coming soon +# ## Use [rustls](https://crates.io/crates/rustls) for tls +# ## +# ## ⚠️ _Highly Experimental_! ⚠️ Try it, but don't rely on it (yet) rustls = [ "pingora-core/rustls", "pingora-proxy?/rustls", @@ -76,5 +93,32 @@ rustls = [ "pingora-load-balancing?/rustls", "any_tls", ] + +#! ### Pingora extensions + +## Include the [proxy](crate::proxy) module +## +## This feature will include and export `pingora_proxy::prelude::*` +proxy = ["pingora-proxy"] + +## Include the [lb](crate::lb) (load-balancing) module +## +## This feature will include and export `pingora_load_balancing::prelude::*` +lb = ["pingora-load-balancing", "proxy"] + +## Include the [cache](crate::cache) module +## +## This feature will include and export `pingora_cache::prelude::*` +cache = ["pingora-cache"] + +## Enable time/scheduling functionality +time = [] + +## Enable sentry for error notifications +sentry = ["pingora-core/sentry"] + +# These features are intentionally not documented openssl_derived = ["any_tls"] any_tls = [] +patched_http1 = ["pingora-core/patched_http1"] +document-features = ["dep:document-features", "proxy", "lb", "cache", "time", "sentry"] diff --git a/pingora/src/lib.rs b/pingora/src/lib.rs index 9362818..ae2516e 100644 --- a/pingora/src/lib.rs +++ b/pingora/src/lib.rs @@ -36,12 +36,11 @@ //! //! If looking to build a (reverse) proxy, see [`pingora-proxy`](https://docs.rs/pingora-proxy) crate. //! -//! # features -//! * `openssl`: Using OpenSSL as the internal TLS backend. This feature is default on. -//! * `boringssl`: Switch the internal TLS library from OpenSSL to BoringSSL. This feature will disable `openssl`. -//! * `proxy`: This feature will include and export `pingora_proxy::prelude::*`. -//! * `lb`: This feature will include and export `pingora_load_balancing::prelude::*`. -//! * `cache`: This feature will include and export `pingora_cache::prelude::*`. +//! # Feature flags +#![cfg_attr( + feature = "document-features", + cfg_attr(doc, doc = ::document_features::document_features!()) +)] pub use pingora_core::*; |