Add ClientBuilder helper to make setting up TLS connections easy. (#197)

Also replaces connect() and connect_starttls() with ClientBuilder.

Author: mordak

.cirrus.yml

@@ -11,12 +11,12 @@ task:
     - . $HOME/.cargo/env
   check_script:
     - . $HOME/.cargo/env
-    - cargo check --all-targets
+    - cargo check --all-targets --all-features
   build_script:
     - . $HOME/.cargo/env
-    - cargo build --all-targets --verbose
+    - cargo build --all-targets --verbose --all-features
   test_script:
     - . $HOME/.cargo/env
-    - cargo test --examples
-    - cargo test --doc
-    - cargo test --lib
+    - cargo test --examples --all-features
+    - cargo test --doc --all-features
+    - cargo test --lib --all-features

Cargo.toml

@@ -15,10 +15,12 @@ categories = ["email", "network-programming"]
 
 [features]
 tls = ["native-tls"]
+rustls-tls = ["rustls-connector"]
 default = ["tls"]
 
 [dependencies]
 native-tls = { version = "0.2.2", optional = true }
+rustls-connector = { version = "0.13.1", optional = true }
 regex = "1.0"
 bufstream = "0.1"
 imap-proto = "0.14.1"
@@ -45,6 +47,18 @@ required-features = ["default"]
 name = "idle"
 required-features = ["default"]
 
+[[example]]
+name = "rustls"
+required-features = ["rustls-tls"]
+
+[[example]]
+name = "starttls"
+required-features = ["default"]
+
+[[example]]
+name = "timeout"
+required-features = ["default"]
+
 [[test]]
 name = "imap_integration"
 required-features = ["default"]

README.md

@@ -22,7 +22,7 @@ results](https://dev.azure.com/jonhoo/jonhoo/_build/latest?definitionId=11&branc
 
 [@jonhoo]: https://thesquareplanet.com/
 
-To connect, use the [`connect`] function. This gives you an unauthenticated [`Client`]. You can
+To connect, use the [`ClientBuilder`]. This gives you an unauthenticated [`Client`]. You can
 then use [`Client::login`] or [`Client::authenticate`] to perform username/password or
 challenge/response authentication respectively. This in turn gives you an authenticated
 [`Session`], which lets you access the mailboxes at the server.
@@ -34,16 +34,9 @@ in the documentation for the various types and methods and read the raw text the
 Below is a basic client example. See the `examples/` directory for more.
 
 ```rust
-extern crate imap;
-extern crate native_tls;
-
 fn fetch_inbox_top() -> imap::error::Result<Option<String>> {
-    let domain = "imap.example.com";
-    let tls = native_tls::TlsConnector::builder().build().unwrap();
 
-    // we pass in the domain twice to check that the server's TLS
-    // certificate is valid for the domain we're connecting to.
-    let client = imap::connect((domain, 993), domain, &tls).unwrap();
+    let client = imap::ClientBuilder::new("imap.example.com", 993).native_tls()?;
 
     // the client we have here is unauthenticated.
     // to do anything useful with the e-mails, we need to log in
@@ -90,7 +83,8 @@ default-features = false
 ```
 
 Even without `native_tls`, you can still use TLS by leveraging the pure Rust `rustls`
-crate. See the example/rustls.rs file for a working example.
+crate, which is enabled with the `rustls-tls` feature. See the example/rustls.rs file
+for a working example.
 
 ## Running the test suite
 

azure-pipelines.yml

@@ -25,13 +25,13 @@ jobs:
      - template: install-rust.yml@templates
        parameters:
          rust: $(rust)
-     - script: cargo check --all-targets
+     - script: cargo check --all-targets --all-features
        displayName: cargo check
-     - script: cargo test --examples
+     - script: cargo test --examples --all-features
        displayName: cargo test --examples
-     - script: cargo test --doc
+     - script: cargo test --doc --all-features
        displayName: cargo test --doc
-     - script: cargo test --lib
+     - script: cargo test --lib --all-features
        displayName: cargo test --lib
      - script: |
          set -e
@@ -75,6 +75,18 @@ jobs:
        greenmail: greenmail
      env:
        TEST_HOST: greenmail
+ - job: features
+   displayName: "Check feature combinations"
+   pool:
+     vmImage: ubuntu-latest
+   steps:
+     - template: install-rust.yml@templates
+       parameters:
+         rust: stable
+     - script: cargo install cargo-hack
+       displayName: install cargo-hack
+     - script: cargo hack --feature-powerset check --all-targets
+       displayName: cargo hack
 
 resources:
   repositories:

codecov.yml

@@ -0,0 +1,17 @@
+coverage:
+  range: 70..100
+  round: down
+  precision: 2
+  status:
+    project:
+      default:
+        threshold: 2%
+
+# Tests aren't important for coverage
+ignore:
+  - "tests"
+
+# Make less noisy comments
+comment:
+  layout: "files"
+  require_changes: yes

examples/README.md

@@ -6,5 +6,7 @@ This directory contains examples of working with the IMAP client.
 Examples:
   * basic - This is a very basic example of using the client.
   * gmail_oauth2 - This is an example using oauth2 for logging into gmail as a secure appplication.
+  * idle - This is an example showing how to use IDLE to monitor a mailbox.
   * rustls - This demonstrates how to use Rustls instead of Openssl for secure connections (helpful for cross compilation).
-  * timeout - This demonstrates how to use timeouts while connecting to an IMAP server.
+  * starttls - This is an example showing how to use STARTTLS after connecting over plaintext.
+  * timeout - This demonstrates how to use timeouts while connecting to an IMAP server by using a custom TCP/TLS stream initialization and creating a `Client` directly instead of using the `ClientBuilder`.

examples/basic.rs

@@ -1,5 +1,4 @@
 extern crate imap;
-extern crate native_tls;
 
 fn main() {
     // To connect to the gmail IMAP server with this you will need to allow unsecure apps access.
@@ -9,12 +8,7 @@ fn main() {
 }
 
 fn fetch_inbox_top() -> imap::error::Result<Option<String>> {
-    let domain = "imap.example.com";
-    let tls = native_tls::TlsConnector::builder().build().unwrap();
-
-    // we pass in the domain twice to check that the server's TLS
-    // certificate is valid for the domain we're connecting to.
-    let client = imap::connect((domain, 993), domain, &tls).unwrap();
+    let client = imap::ClientBuilder::new("imap.example.com", 993).native_tls()?;
 
     // the client we have here is unauthenticated.
     // to do anything useful with the e-mails, we need to log in

examples/gmail_oauth2.rs

@@ -1,8 +1,5 @@
 extern crate base64;
 extern crate imap;
-extern crate native_tls;
-
-use native_tls::TlsConnector;
 
 struct GmailOAuth2 {
     user: String,
@@ -25,11 +22,10 @@ fn main() {
         user: String::from("[email protected]"),
         access_token: String::from("<access_token>"),
     };
-    let domain = "imap.gmail.com";
-    let port = 993;
-    let socket_addr = (domain, port);
-    let ssl_connector = TlsConnector::builder().build().unwrap();
-    let client = imap::connect(socket_addr, domain, &ssl_connector).unwrap();
+
+    let client = imap::ClientBuilder::new("imap.gmail.com", 993)
+        .native_tls()
+        .expect("Could not connect to imap.gmail.com");
 
     let mut imap_session = match client.authenticate("XOAUTH2", &gmail_auth) {
         Ok(c) => c,

examples/idle.rs

@@ -1,4 +1,3 @@
-use native_tls::TlsConnector;
 use structopt::StructOpt;
 
 #[derive(StructOpt, Debug)]
@@ -39,9 +38,10 @@ struct Opt {
 fn main() {
     let opt = Opt::from_args();
 
-    let ssl_conn = TlsConnector::builder().build().unwrap();
-    let client = imap::connect((opt.server.clone(), opt.port), opt.server, &ssl_conn)
+    let client = imap::ClientBuilder::new(opt.server.clone(), opt.port)
+        .native_tls()
         .expect("Could not connect to imap server");
+
     let mut imap = client
         .login(opt.username, opt.password)
         .expect("Could not authenticate");

examples/rustls.rs

@@ -1,9 +1,6 @@
 extern crate imap;
-extern crate rustls_connector;
 
-use std::{env, error::Error, net::TcpStream};
-
-use rustls_connector::RustlsConnector;
+use std::{env, error::Error};
 
 fn main() -> Result<(), Box<dyn Error>> {
     // Read config from environment or .env file
@@ -25,14 +22,7 @@ fn fetch_inbox_top(
     password: String,
     port: u16,
 ) -> Result<Option<String>, Box<dyn Error>> {
-    // Setup Rustls TcpStream
-    let stream = TcpStream::connect((host.as_ref(), port))?;
-    let tls = RustlsConnector::default();
-    let tlsstream = tls.connect(&host, stream)?;
-
-    // we pass in the domain twice to check that the server's TLS
-    // certificate is valid for the domain we're connecting to.
-    let client = imap::Client::new(tlsstream);
+    let client = imap::ClientBuilder::new(&host, port).rustls()?;
 
     // the client we have here is unauthenticated.
     // to do anything useful with the e-mails, we need to log in

examples/starttls.rs

@@ -1,8 +1,9 @@
 /**
  * Here's an example showing how to connect to the IMAP server with STARTTLS.
- * The only difference with the `basic.rs` example is when using `imap::connect_starttls()` method
- * instead of `imap::connect()` (l. 52), and so you can connect on port 143 instead of 993
- * as you have to when using TLS the entire way.
+ *
+ * The only difference is calling `starttls()` on the `ClientBuilder` before
+ * initiating the secure connection with `native_tls()` or `rustls()`, so you
+ * can connect on port 143 instead of 993.
  *
  * The following env vars are expected to be set:
  * - IMAP_HOST
@@ -11,9 +12,7 @@
  * - IMAP_PORT (supposed to be 143)
  */
 extern crate imap;
-extern crate native_tls;
 
-use native_tls::TlsConnector;
 use std::env;
 use std::error::Error;
 
@@ -42,13 +41,10 @@ fn fetch_inbox_top(
     password: String,
     port: u16,
 ) -> Result<Option<String>, Box<dyn Error>> {
-    let domain: &str = host.as_str();
-
-    let tls = TlsConnector::builder().build().unwrap();
-
-    // we pass in the domain twice to check that the server's TLS
-    // certificate is valid for the domain we're connecting to.
-    let client = imap::connect_starttls((domain, port), domain, &tls).unwrap();
+    let client = imap::ClientBuilder::new(&host, port)
+        .starttls()
+        .native_tls()
+        .expect("Could not connect to server");
 
     // the client we have here is unauthenticated.
     // to do anything useful with the e-mails, we need to log in

examples/timeout.rs

@@ -58,8 +58,7 @@ fn connect_timeout<S: AsRef<str>>(
     Ok(client)
 }
 
-// resolve address and try to connect to all in order; note that this function is required to fully
-// mimic `imap::connect` with the usage of `ToSocketAddrs`
+// resolve address and try to connect to all in order
 fn connect_all_timeout<A: ToSocketAddrs, S: AsRef<str>>(
     addr: A,
     domain: S,