document the public interface

Author: jbr

src/lib.rs

@@ -1,11 +1,42 @@
+//! tide tls listener built on async-tls and rustls
+//!
+//!
+//! # Example
+//! ```rust
+//! # use tide_rustls::TlsListener;
+//! fn main() -> tide::Result<()> { async_std::task::block_on(async {
+//!     let mut app = tide::new();
+//!     app.at("/").get(|_| async { Ok("Hello tls") });
+//! # if false {
+//!     app.listen(
+//!         TlsListener::build()
+//!             .addrs("localhost:4433")
+//!             .cert(std::env::var("TIDE_CERT_PATH").unwrap())
+//!             .key(std::env::var("TIDE_KEY_PATH").unwrap()),
+//!     )
+//!    .await?;
+//! # }
+//! Ok(()) }) }
+//! ```
+#![forbid(unsafe_code, future_incompatible)]
+#![deny(
+    missing_debug_implementations,
+    nonstandard_style,
+    missing_docs,
+    unreachable_pub,
+    missing_copy_implementations,
+    unused_qualifications
+)]
+
 mod tcp_connection;
 mod tls_listener;
 mod tls_listener_builder;
 mod tls_listener_config;
 mod tls_stream_wrapper;
 
-pub use tcp_connection::TcpConnection;
+pub(crate) use tcp_connection::TcpConnection;
+pub(crate) use tls_listener_config::TlsListenerConfig;
+pub(crate) use tls_stream_wrapper::TlsStreamWrapper;
+
 pub use tls_listener::TlsListener;
 pub use tls_listener_builder::TlsListenerBuilder;
-pub use tls_listener_config::TlsListenerConfig;
-pub use tls_stream_wrapper::TlsStreamWrapper;

src/tcp_connection.rs

@@ -2,7 +2,7 @@ use async_std::net::{SocketAddr, TcpListener};
 use std::fmt::{self, Debug, Display, Formatter};
 
 #[derive(Debug)]
-pub enum TcpConnection {
+pub(crate) enum TcpConnection {
     Addrs(Vec<SocketAddr>),
     Connected(TcpListener),
 }

src/tls_listener.rs

@@ -18,6 +18,7 @@ use std::path::Path;
 use std::sync::Arc;
 use std::time::Duration;
 
+/// The primary type for this crate
 #[derive(Debug)]
 pub struct TlsListener {
     connection: TcpConnection,
@@ -28,6 +29,20 @@ impl TlsListener {
     pub(crate) fn new(connection: TcpConnection, config: TlsListenerConfig) -> Self {
         Self { connection, config }
     }
+    /// The primary entrypoint to create a TlsListener. See
+    /// [TlsListenerBuilder](crate::TlsListenerBuilder) for more
+    /// configuration options.
+    ///
+    /// # Example
+    ///
+    /// ```rust
+    /// # use tide_rustls::TlsListener;
+    /// let listener = TlsListener::build()
+    ///     .addrs("localhost:4433")
+    ///     .cert("./tls/localhost-4433.cert")
+    ///     .key("./tls/localhost-4433.key")
+    ///     .finish();
+    /// ```
     pub fn build() -> TlsListenerBuilder {
         TlsListenerBuilder::new()
     }
@@ -120,7 +135,7 @@ impl<State: Clone + Send + Sync + 'static> ToListener<State> for TlsListener {
 impl<State: Clone + Send + Sync + 'static> ToListener<State> for TlsListenerBuilder {
     type Listener = TlsListener;
     fn to_listener(self) -> io::Result<Self::Listener> {
-        self.build()
+        self.finish()
     }
 }
 

src/tls_listener_builder.rs

@@ -8,6 +8,31 @@ use super::{TcpConnection, TlsListener, TlsListenerConfig};
 use std::net::{SocketAddr, ToSocketAddrs};
 use std::path::{Path, PathBuf};
 
+/// # A builder for TlsListeners
+///
+/// This is created with a call to
+/// [`TlsListener::build`](crate::TlsListener::build). This also can
+/// be passed directly to [`tide::Server::listen`], skipping the
+/// [`TlsListenerBuilder::finish`] call.
+///
+/// # Examples
+///
+/// ```rust
+/// # use tide_rustls::TlsListener;
+/// let listener = TlsListener::build()
+///     .addrs("localhost:4433")
+///     .cert("./tls/localhost-4433.cert")
+///     .key("./tls/localhost-4433.key")
+///     .finish();
+/// ```
+///
+/// ```rust
+/// # use tide_rustls::TlsListener;
+/// let listener = TlsListener::build()
+///     .tcp(std::net::TcpListener::bind("localhost:4433").unwrap())
+///     .config(rustls::ServerConfig::new(rustls::NoClientAuth::new()))
+///     .finish();
+/// ```
 #[derive(Default)]
 pub struct TlsListenerBuilder {
     key: Option<PathBuf>,
@@ -17,34 +42,88 @@ pub struct TlsListenerBuilder {
     addrs: Option<Vec<SocketAddr>>,
 }
 
+impl std::fmt::Debug for TlsListenerBuilder {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        f.debug_struct("TlsListenerBuilder")
+            .field("key", &self.key)
+            .field("cert", &self.cert)
+            .field(
+                "config",
+                &if self.config.is_some() {
+                    "Some(ServerConfig { .. })"
+                } else {
+                    "None"
+                },
+            )
+            .field("tcp", &self.tcp)
+            .field("addrs", &self.addrs)
+            .finish()
+    }
+}
+
 impl TlsListenerBuilder {
     pub(crate) fn new() -> Self {
         TlsListenerBuilder::default()
     }
+
+    /// Provide a path to a key file, in either pkcs8 or rsa
+    /// formats. This is mutually exclusive with providing a server
+    /// config with [`TlsListenerBuilder::config`], but must be used
+    /// in conjunction with [`TlsListenerBuilder::cert`]
     pub fn key(mut self, path: impl AsRef<Path>) -> Self {
         self.key = Some(path.as_ref().into());
         self
     }
+
+    /// Provide a path to a cert file. This is mutually exclusive with
+    /// providing a server config with [`TlsListenerBuilder::config`],
+    /// but must be used in conjunction with
+    /// [`TlsListenerBuilder::key`]
     pub fn cert(mut self, path: impl AsRef<Path>) -> Self {
         self.cert = Some(path.as_ref().into());
         self
     }
+
+    /// Provide a prebuilt
+    /// [`rustls::ServerConfig`](::rustls::ServerConfig) with any
+    /// options. This is mutually exclusive with both
+    /// [`TlsListenerBuilder::key`] and [`TlsListenerBuilder::cert`],
+    /// but provides the opportunity for more configuration choices.
     pub fn config(mut self, config: ServerConfig) -> Self {
         self.config = Some(config);
         self
     }
+
+    /// Provides a bound tcp listener (either async-std or std) to
+    /// build this tls listener on. This is mutually exclusive with
+    /// [`TlsListenerBuilder::addrs`], but one of them is mandatory.
     pub fn tcp(mut self, tcp: impl Into<TcpListener>) -> Self {
         self.tcp = Some(tcp.into());
         self
     }
+
+    /// Provides a [`std::net::ToSocketAddrs`] specification for this
+    /// tls listener. This is mutually exclusive with
+    /// [`TlsListenerBuilder::tcp`] but one of them is mandatory.
     pub fn addrs(mut self, addrs: impl ToSocketAddrs) -> Self {
         if let Ok(socket_addrs) = addrs.to_socket_addrs() {
             self.addrs = Some(socket_addrs.collect());
         }
         self
     }
 
-    pub(crate) fn build(self) -> io::Result<TlsListener> {
+    /// finishes building a TlsListener from this TlsListenerBuilder.
+    ///
+    /// # Errors
+    ///
+    /// this will return an error unless all of the following conditions are met:
+    /// * either of these is provided, but not both
+    ///   * [`TlsListenerBuilder::tcp`]
+    ///   * [`TlsListenerBuilder::addrs`]
+    /// * either of these is provided, but not both
+    ///   * both [`TlsListenerBuilder::cert`] AND [`TlsListenerBuilder::key`]
+    ///   * [`TlsListenerBuilder::config`]
+    pub fn finish(self) -> io::Result<TlsListener> {
         let Self {
             key,
             cert,

src/tls_listener_config.rs

@@ -10,7 +10,7 @@ impl Default for TlsListenerConfig {
         Self::Unconfigured
     }
 }
-pub enum TlsListenerConfig {
+pub(crate) enum TlsListenerConfig {
     Unconfigured,
     Acceptor(TlsAcceptor),
     ServerConfig(ServerConfig),

src/tls_stream_wrapper.rs

@@ -6,10 +6,10 @@ use std::pin::Pin;
 use std::task::{Context, Poll};
 
 #[derive(Clone)]
-pub struct TlsStreamWrapper(Arc<Mutex<TlsStream<TcpStream>>>);
+pub(crate) struct TlsStreamWrapper(Arc<Mutex<TlsStream<TcpStream>>>);
 
 impl TlsStreamWrapper {
-    pub fn new(stream: TlsStream<TcpStream>) -> Self {
+    pub(crate) fn new(stream: TlsStream<TcpStream>) -> Self {
         Self(Arc::new(Mutex::new(stream)))
     }
 }