NOJIRA Update documentation to reflect changes in features

13 files changed, 82 insertions, 29 deletions

diff --git a/.bleep b/.bleep
index d9ff5c9..e0dc84f 100644
--- a/.bleep
+++ b/.bleep
@@ -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::*;