base_endpoint/
tls.rs

1// Released under the MIT License.
2// Copyright, 2026, by Samuel Williams.
3
4//! Provider-neutral TLS handshakes, stream I/O and endpoint composition. The optional `rustls` feature supplies a concrete provider in `tls::rustls`. Applications select trust stores and credentials through provider configuration.
5//!
6//! Client connectors authenticate the peer's certificate and requested server identity. Server acceptors apply their configured certificate and client-authentication policy. Providers own TLS configuration, trust roots, credentials, protocol versions, ALPN offers and selection, TLS I/O, shutdown and failed-handshake cleanup; application code can retain concrete configuration types without erasing them into a shared options map.
7//!
8//! [`TlsClientEndpoint::new(endpoint, connector, server_name)`](TlsClientEndpoint::new) implements the same connection contract as other endpoints and returns the provider's TLS connection. [`TlsServerEndpoint::new(endpoint, acceptor)`](TlsServerEndpoint::new) implements binding and returns [`TlsListener`] values; their `accept` method accepts and handshakes one native scheduler connection. A failed handshake leaves the listener available for another accept. Custom listener types can access the underlying listener and provider directly. Wrap composite binding inside the TLS server endpoint.
9//!
10//! The server name used for authentication is independent of the address used for routing. Client providers must verify certificate trust and server identity. [`TlsSession::negotiated_protocol`] exposes the selected ALPN bytes. [`TlsStream<S>`](TlsStream) supplies sequential reads, buffered writes, flushing, TLS shutdown and transport closure without naming a provider. There is no plaintext fallback. HTTP protocol names and engine selection remain owned by HTTP, outside endpoint/TLS.
11//!
12//! For example, application code can configure a provider elsewhere and compose it without naming a TLS backend:
13//!
14//! ```rust
15//! use base_endpoint::{ConnectEndpoint, tls::{TlsClientEndpoint, TlsConnector}};
16//! use base_scheduler::{Cancellation, OperationResult};
17//!
18//! async fn secure_connection<S, E, T>(
19//!     scheduler: &S,
20//!     endpoint: E,
21//!     connector: T,
22//!     server_name: &str,
23//!     cancellation: &Cancellation,
24//! ) -> OperationResult<T::Connection>
25//! where
26//!     S: Sync,
27//!     E: ConnectEndpoint<S>,
28//!     T: TlsConnector<S, E::Connection>,
29//! {
30//!     TlsClientEndpoint::new(endpoint, connector, server_name)
31//!         .connect(scheduler, cancellation).await
32//! }
33//! ```
34//!
35//! # Rustls
36//!
37//! Enable the optional `rustls` Cargo feature to use `tls::rustls::{RustlsConnector, RustlsAcceptor, RustlsConnection}`. The providers accept shared rustls configurations, so applications select certificate trust roots, credentials, client authentication, protocol versions and ALPN. The feature enables rustls's ring crypto provider and TLS 1.2/1.3 support; configurations may also use another explicitly selected rustls crypto provider. No trust roots are loaded implicitly.
38//!
39//! ```rust
40//! # #[cfg(feature = "rustls")]
41//! # fn example(client_config: rustls::ClientConfig, server_config: rustls::ServerConfig) {
42//! use base_endpoint::{AddressEndpoint, HostEndpoint, tls::{TlsClientEndpoint, TlsServerEndpoint,
43//!     rustls::{RustlsAcceptor, RustlsConnector}}};
44//! use std::sync::Arc;
45//!
46//! let client = TlsClientEndpoint::new(
47//!     HostEndpoint::new("example.com", 443),
48//!     RustlsConnector::new(Arc::new(client_config)),
49//!     "example.com",
50//! );
51//! let server = TlsServerEndpoint::new(
52//!     AddressEndpoint::new("127.0.0.1:8443".parse().unwrap()),
53//!     RustlsAcceptor::new(Arc::new(server_config)),
54//! );
55//! // Use the same connect/bind traits as plain endpoints.
56//! # }
57//! ```
58
59mod tls_acceptor;
60mod tls_client_endpoint;
61mod tls_connector;
62mod tls_listener;
63mod tls_server_endpoint;
64mod tls_session;
65mod tls_stream;
66
67pub use tls_acceptor::TlsAcceptor;
68pub use tls_client_endpoint::TlsClientEndpoint;
69pub use tls_connector::TlsConnector;
70pub use tls_listener::TlsListener;
71pub use tls_server_endpoint::TlsServerEndpoint;
72pub use tls_session::TlsSession;
73pub use tls_stream::TlsStream;
74
75#[cfg(feature = "rustls")]
76pub mod rustls;
base_endpoint/tls.rs

base_endpoint/
tls.rs
