Docs and refactorings

Author: monoid

benches/tls_certs.rs

@@ -8,14 +8,13 @@ use wiremock::tls_certs::MockTlsCertificates;
 // On the good old M1 processor it takes ~77 µs
 pub fn tls_mock_tls_certificates_new(c: &mut Criterion) {
     c.bench_function("MockTlsCertificates::new", |b| {
-        b.iter(|| MockTlsCertificates::new())
+        b.iter(|| MockTlsCertificates::random())
     });
 }
 
 #[cfg(feature = "tls")]
-// TODO measure with a charger connected
 pub fn tls_mock_tls_certificates_client(c: &mut Criterion) {
-    let mock_tls_certificates = MockTlsCertificates::new();
+    let mock_tls_certificates = MockTlsCertificates::random();
     c.bench_function("MockTlsCertificates::gen_client", |b| {
         b.iter(|| mock_tls_certificates.gen_client("[email protected]"))
     });

src/lib.rs

@@ -107,6 +107,16 @@
 //! The pool is designed to be invisible: it makes your life easier and your tests faster. If you
 //! end up having to worry about it, it's a bug: open an issue!
 //!
+//! ## HTTPS
+//!
+//! You may start a HTTPS server with `MockServer::start_https(MockServerTlsConfig)` method.
+//! The `MockServerTlsConfig` can be created from pregenerated TLS certificates, or you can
+//! generate self-signed server and client certificates with a `MockTlsCertificates` instance.
+//!
+//! HTTPS servers are not pooled yet.
+//!
+//! HTTPS functionality is gated by the `tls` feature.
+//!
 //! ## Prior art
 //!
 //! [`mockito`] and [`httpmock`] provide HTTP mocking for Rust.

src/mock_server/builder.rs

@@ -146,7 +146,7 @@ impl MockServerBuilder {
 
         let rustls_config = RustlsConfig::from_der(
             vec![certs.server_cert_der, certs.root_cert_der],
-            certs.server_key_der,
+            certs.server_keypair_der,
         )
         .await
         .expect("Failed to build RustlsConfig");

src/mock_server/tls_certs.rs

@@ -1,4 +1,4 @@
-//! Certificate generation.
+//! TLS Certificate generation helpers.
 //!
 // Based on https://github.com/rustls/rustls/blob/main/rustls/examples/internal/test_ca.rs
 use std::{
@@ -39,116 +39,131 @@ const EE_KEY_USAGES: &[KeyUsagePurpose; 2] = &[
 
 static SERIAL_NUMBER: AtomicU64 = AtomicU64::new(1);
 
+/// Configuration for a mock server TLS setup.
 pub struct MockServerTlsConfig {
+    /// Root CA certificate in DER format.
     pub root_cert_der: Vec<u8>,
+    /// Server certificate in DER format.
     pub server_cert_der: Vec<u8>,
-    pub server_key_der: Vec<u8>,
+    /// Server keypair in DER format.
+    pub server_keypair_der: Vec<u8>,
 }
 
 impl MockServerTlsConfig {
     #[inline]
     pub fn from_der(
         root_cert_der: Vec<u8>,
         server_cert_der: Vec<u8>,
-        server_key_der: Vec<u8>,
+        server_keypair_der: Vec<u8>,
     ) -> Self {
         Self {
             root_cert_der,
             server_cert_der,
-            server_key_der,
+            server_keypair_der,
         }
     }
 
     /// Create a new `MockServerTlsConfig` from PEM-encoded certificates and key.
     ///
     /// Panics if the data cannot be parsed as valid PEM.
-    #[inline]
     pub fn from_pem(
         root_cert_pem: Vec<u8>,
         server_cert_pem: Vec<u8>,
-        server_key_pem: Vec<u8>,
+        server_keypair_pem: Vec<u8>,
     ) -> Self {
         let root_cert_der = CertificateDer::from_pem_slice(&root_cert_pem)
             .expect("Failed to parse root certificate from PEM")
             .to_vec();
         let server_cert_der = CertificateDer::from_pem_slice(&server_cert_pem)
             .expect("Failed to parse server certificate from PEM")
             .to_vec();
-        let server_key_der = PrivateKeyDer::from_pem_slice(&server_key_pem)
+        let server_keypair_der = PrivateKeyDer::from_pem_slice(&server_keypair_pem)
             .expect("Failed to parse server key from PEM")
             .secret_der()
             .to_vec();
 
         Self {
             root_cert_der,
             server_cert_der,
-            server_key_der,
+            server_keypair_der,
         }
     }
 }
 
+/// Mock self-signed TLS certificates for testing purposes.
+///
+/// This struct generates a root CA certificate and a server certificate signed by it, along with a key pair for the
+/// server.
 pub struct MockTlsCertificates {
     pub root_cert: Certificate,
     pub server_cert: Certificate,
-    pub server_key: KeyPair,
+    pub server_keypair: KeyPair,
 }
 
 impl MockTlsCertificates {
-    /// Generate server certificates and key with "localhost" and "127.0.0.1" as hostnames.
+    /// Generate server certificates and keypair with "localhost" and "127.0.0.1" as hostnames.
+    ///
+    /// Ed25519 is used as the default signature algorithm.
     // On the good old M1 processor it takes ~77 µs
     #[inline]
-    #[allow(clippy::new_without_default)]
-    pub fn new() -> Self {
-        Self::with_hostnames(default_hostnames())
+    pub fn random() -> Self {
+        Self::random_with_hostnames(default_hostnames())
     }
 
     /// Generate server certificates and key with custom hostnames and IPs.
-    pub fn with_hostnames(hostnames: impl Into<Vec<SanType>>) -> Self {
+    pub fn random_with_hostnames(hostnames: impl Into<Vec<SanType>>) -> Self {
         let (root_cert, root_key) = gen_root_cert(DEFAULT_ALGORITHM);
         // We do not bother to have an intermediate certificate because CAs use them for flexibility only.
-        let (server_cert, server_key) =
+        let (server_cert, server_keypair) =
             gen_server_cert(&root_cert, &root_key, DEFAULT_ALGORITHM, hostnames.into());
 
         Self {
             root_cert,
             server_cert,
-            server_key,
+            server_keypair,
         }
     }
 
+    /// Get the root CA certificate.
     #[inline]
-    pub fn get_root_cert(&self) -> &Certificate {
+    pub fn get_root_ca_cert(&self) -> &Certificate {
         &self.root_cert
     }
 
+    /// Get the server certificate signed by CA certificate, in DER format.
     #[inline]
     pub fn server_cert_der(&self) -> &CertificateDer {
         self.server_cert.der()
     }
 
-    pub fn server_private_key_der(&self) -> PrivateKeyDer {
-        self.server_key
+    /// Get the server keypair in DER format.
+    pub fn server_private_keypair_der(&self) -> PrivateKeyDer {
+        self.server_keypair
             .serialize_der()
             .try_into()
             .expect("Failed to deserialize a serialized key")
     }
 
+    /// Generate a client certificate signed by the CA certificate.
+    ///
+    /// Each invocation generates a new keypair and a certificate.
     #[inline]
-    pub fn gen_client_cert(&self, email: &str) -> (Certificate, KeyPair) {
+    pub fn generate_client_cert(&self, email: &str) -> (Certificate, KeyPair) {
         gen_client_cert(
             &self.server_cert,
-            &self.server_key,
+            &self.server_keypair,
             DEFAULT_ALGORITHM,
             email,
         )
     }
 
+    /// Get the server configuration for use with a mock server.
     #[inline]
     pub fn get_server_config(&self) -> MockServerTlsConfig {
         MockServerTlsConfig {
             root_cert_der: self.root_cert.der().to_vec(),
             server_cert_der: self.server_cert.der().to_vec(),
-            server_key_der: self.server_key.serialize_der(),
+            server_keypair_der: self.server_keypair.serialize_der(),
         }
     }
 }
@@ -180,7 +195,7 @@ fn gen_root_cert(alg: &'static SignatureAlgorithm) -> (Certificate, KeyPair) {
 
 fn gen_server_cert(
     signer_cert: &Certificate,
-    signer_key: &KeyPair,
+    signer_keypair: &KeyPair,
     alg: &'static SignatureAlgorithm,
     hostnames: Vec<SanType>,
 ) -> (Certificate, KeyPair) {
@@ -195,13 +210,13 @@ fn gen_server_cert(
     params.key_usages = EE_KEY_USAGES.to_vec();
     params.subject_alt_names = hostnames;
 
-    let cert = params.signed_by(&keypair, signer_cert, signer_key).unwrap();
+    let cert = params.signed_by(&keypair, signer_cert, signer_keypair).unwrap();
     (cert, keypair)
 }
 
 fn gen_client_cert(
     signer_cert: &Certificate,
-    signer_key: &KeyPair,
+    signer_keypair: &KeyPair,
     alg: &'static SignatureAlgorithm,
     email: &str,
 ) -> (Certificate, KeyPair) {
@@ -222,7 +237,7 @@ fn gen_client_cert(
             .unwrap_or_else(|_| panic!("Invalid email: {}", email)),
     )];
 
-    let cert = params.signed_by(&keypair, signer_cert, signer_key).unwrap();
+    let cert = params.signed_by(&keypair, signer_cert, signer_keypair).unwrap();
     (cert, keypair)
 }
 

tests/tls.rs

@@ -4,7 +4,7 @@ mod tlstests {
 
     #[async_std::test]
     async fn test_tls_basic() {
-        let certs = MockTlsCertificates::new();
+        let certs = MockTlsCertificates::random();
 
         let mock_server = wiremock::MockServer::builder()
             .start_https(certs.get_server_config())
@@ -17,7 +17,7 @@ mod tlstests {
 
     #[async_std::test]
     async fn test_tls_invalid() {
-        let certs = MockTlsCertificates::new();
+        let certs = MockTlsCertificates::random();
 
         let mock_server = wiremock::MockServer::builder()
             .start_https(certs.get_server_config())
@@ -38,15 +38,16 @@ mod tlstests {
 
     #[async_std::test]
     async fn test_tls_anonymous() {
-        let certs = MockTlsCertificates::new();
+        let certs = MockTlsCertificates::random();
 
         let mock_server = wiremock::MockServer::builder()
             .start_https(certs.get_server_config())
             .await;
         let uri = mock_server.uri();
 
-        let reqwest_root_certificate = reqwest::Certificate::from_der(certs.get_root_cert().der())
-            .expect("Failed to create certificate from DER");
+        let reqwest_root_certificate =
+            reqwest::Certificate::from_der(certs.get_root_ca_cert().der())
+                .expect("Failed to create certificate from DER");
         let client = reqwest::Client::builder()
             .add_root_certificate(reqwest_root_certificate)
             .use_rustls_tls() // It fails on MacOS with native-tls no mattter what, so use rustls.
@@ -62,16 +63,17 @@ mod tlstests {
 
     #[async_std::test]
     async fn test_tls_with_client_cert() {
-        let certs = MockTlsCertificates::new();
+        let certs = MockTlsCertificates::random();
 
         let mock_server = wiremock::MockServer::builder()
             .start_https(certs.get_server_config())
             .await;
         let uri = mock_server.uri();
 
-        let reqwest_root_certificate = reqwest::Certificate::from_der(certs.get_root_cert().der())
-            .expect("Failed to create certificate from DER");
-        let (client_cert, client_key) = certs.gen_client_cert("[email protected]");
+        let reqwest_root_certificate =
+            reqwest::Certificate::from_der(certs.get_root_ca_cert().der())
+                .expect("Failed to create certificate from DER");
+        let (client_cert, client_key) = certs.generate_client_cert("[email protected]");
         let client_cert_pem = client_cert.pem();
         let client_key_pem = client_key.serialize_pem();
         let client_cert =