tls doc updates

actix-rt/src/lib.rs

@@ -41,8 +41,8 @@
 //! In particular, when running a `System`, only `System::block_on` is supported.
 
 #![deny(rust_2018_idioms, nonstandard_style)]
-#![allow(clippy::type_complexity)]
 #![warn(missing_docs)]
+#![allow(clippy::type_complexity)]
 #![doc(html_logo_url = "https://actix.rs/img/logo.png")]
 #![doc(html_favicon_url = "https://actix.rs/favicon.ico")]
 

actix-tls/Cargo.toml

@@ -77,5 +77,5 @@ tokio-rustls = { version = "0.23", features = ["dangerous_configuration"] }
 trust-dns-resolver = "0.20.0"
 
 [[example]]
-name = "tcp-rustls"
+name = "accept-rustls"
 required-features = ["accept", "rustls"]

actix-tls/examples/accept-rustls.rs

@@ -1,4 +1,4 @@
-//! TLS Acceptor Server
+//! No-Op TLS Acceptor Server
 //!
 //! Using either HTTPie (`http`) or cURL:
 //!

actix-tls/src/accept/mod.rs

@@ -36,21 +36,38 @@ pub fn max_concurrent_tls_connect(num: usize) {
     MAX_CONN.store(num, Ordering::Relaxed);
 }
 
-/// TLS error combined with service error.
+/// TLS handshake error, TLS timeout, or inner service error.
+///
+/// All TLS acceptors from this crate will return the `SvcErr` type parameter as [`Infallible`],
+/// which can be cast to your own service type, inferred or otherwise,
+/// using [`into_service_error`](Self::into_service_error).
 #[derive(Debug)]
 pub enum TlsError<TlsErr, SvcErr> {
+    /// TLS handshake has timed-out.
     Timeout,
+
+    /// Wraps TLS service errors.
     Tls(TlsErr),
+
+    /// Wraps inner service errors.
     Service(SvcErr),
 }
 
 impl<TlsErr> TlsError<TlsErr, Infallible> {
     /// Casts the infallible service error type returned from acceptors into caller's type.
+    ///
+    /// # Examples
+    /// ```
+    /// # use std::convert::Infallible;
+    /// # use actix_tls::accept::TlsError;
+    /// let a: TlsError<u32, Infallible> = TlsError::Tls(42);
+    /// let _b: TlsError<u32, u64> = a.into_service_error();
+    /// ```
     pub fn into_service_error<SvcErr>(self) -> TlsError<TlsErr, SvcErr> {
         match self {
             Self::Timeout => TlsError::Timeout,
             Self::Tls(err) => TlsError::Tls(err),
-            Self::Service(_) => unreachable!(),
+            Self::Service(err) => match err {},
         }
     }
 }

actix-tls/src/connect/mod.rs

@@ -1,4 +1,4 @@
-//! TCP connector services for Actix ecosystem.
+//! TCP and TLS connector services.
 //!
 //! # Stages of the TCP connector service:
 //! - Resolve [`Address`] with given [`Resolver`] and collect list of socket addresses.
@@ -9,10 +9,6 @@
 //! - Wrap the stream and perform connect handshake with remote peer.
 //! - Return certain stream type that impls `AsyncRead` and `AsyncWrite`.
 //!
-//! # Package feature
-//! * `openssl` - enables TLS support via `openssl` crate
-//! * `rustls` - enables TLS support via `rustls` crate
-//!
 //! [`TcpStream`]: actix_rt::net::TcpStream
 
 #[allow(clippy::module_inception)]
@@ -22,55 +18,18 @@ mod error;
 mod resolve;
 mod service;
 pub mod tls;
+// TODO: remove `ssl` mod re-export in next break change
 #[doc(hidden)]
 pub use tls as ssl;
+mod tcp;
 #[cfg(feature = "uri")]
 mod uri;
 
-use actix_rt::net::TcpStream;
-use actix_service::{Service, ServiceFactory};
-
 pub use self::connect::{Address, Connect, Connection};
 pub use self::connector::{TcpConnector, TcpConnectorFactory};
 pub use self::error::ConnectError;
 pub use self::resolve::{Resolve, Resolver, ResolverFactory};
 pub use self::service::{ConnectService, ConnectServiceFactory};
-
-/// Create TCP connector service.
-pub fn new_connector<T: Address + 'static>(
-    resolver: Resolver,
-) -> impl Service<Connect<T>, Response = Connection<T, TcpStream>, Error = ConnectError> + Clone
-{
-    ConnectServiceFactory::new(resolver).service()
-}
-
-/// Create TCP connector service factory.
-pub fn new_connector_factory<T: Address + 'static>(
-    resolver: Resolver,
-) -> impl ServiceFactory<
-    Connect<T>,
-    Config = (),
-    Response = Connection<T, TcpStream>,
-    Error = ConnectError,
-    InitError = (),
-> + Clone {
-    ConnectServiceFactory::new(resolver)
-}
-
-/// Create connector service with default parameters.
-pub fn default_connector<T: Address + 'static>(
-) -> impl Service<Connect<T>, Response = Connection<T, TcpStream>, Error = ConnectError> + Clone
-{
-    new_connector(Resolver::Default)
-}
-
-/// Create connector service factory with default parameters.
-pub fn default_connector_factory<T: Address + 'static>() -> impl ServiceFactory<
-    Connect<T>,
-    Config = (),
-    Response = Connection<T, TcpStream>,
-    Error = ConnectError,
-    InitError = (),
-> + Clone {
-    new_connector_factory(Resolver::Default)
-}
+pub use self::tcp::{
+    default_connector, default_connector_factory, new_connector, new_connector_factory,
+};

actix-tls/src/connect/tcp.rs

@@ -0,0 +1,43 @@
+use actix_rt::net::TcpStream;
+use actix_service::{Service, ServiceFactory};
+
+use super::{Address, Connect, ConnectError, ConnectServiceFactory, Connection, Resolver};
+
+/// Create TCP connector service.
+pub fn new_connector<T: Address + 'static>(
+    resolver: Resolver,
+) -> impl Service<Connect<T>, Response = Connection<T, TcpStream>, Error = ConnectError> + Clone
+{
+    ConnectServiceFactory::new(resolver).service()
+}
+
+/// Create TCP connector service factory.
+pub fn new_connector_factory<T: Address + 'static>(
+    resolver: Resolver,
+) -> impl ServiceFactory<
+    Connect<T>,
+    Config = (),
+    Response = Connection<T, TcpStream>,
+    Error = ConnectError,
+    InitError = (),
+> + Clone {
+    ConnectServiceFactory::new(resolver)
+}
+
+/// Create TCP connector service with default parameters.
+pub fn default_connector<T: Address + 'static>(
+) -> impl Service<Connect<T>, Response = Connection<T, TcpStream>, Error = ConnectError> + Clone
+{
+    new_connector(Resolver::Default)
+}
+
+/// Create TCP connector service factory with default parameters.
+pub fn default_connector_factory<T: Address + 'static>() -> impl ServiceFactory<
+    Connect<T>,
+    Config = (),
+    Response = Connection<T, TcpStream>,
+    Error = ConnectError,
+    InitError = (),
+> + Clone {
+    new_connector_factory(Resolver::Default)
+}