From beb41d2f52a1f5e56451f376d4b40a266ad9a84b Mon Sep 17 00:00:00 2001
From: Bryce Fisher-Fleig <brycefisher@users.noreply.github.com>
Date: Tue, 17 Sep 2019 12:51:38 -0700
Subject: [PATCH] (feat) Provide example integration with Rustls crate

By checking this code in as an example, we can prevent bitrot as we continuously test this
in CI. It also demonstrates how to setup TLS without relying on platform specific dependencies
via native_tls crate.
---
 Cargo.toml         |  2 ++
 examples/README.md |  1 +
 examples/rustls.rs | 67 ++++++++++++++++++++++++++++++++++++++++++++++
 src/client.rs      |  3 +++
 4 files changed, 73 insertions(+)
 create mode 100644 examples/rustls.rs

diff --git a/Cargo.toml b/Cargo.toml
index 5deabea..855d12e 100644
--- a/Cargo.toml
+++ b/Cargo.toml
@@ -32,5 +32,7 @@ chrono = "0.4"
 lazy_static = "1.4"
 
 [dev-dependencies]
+dotenv = "0.14.1"
 lettre = "0.9"
 lettre_email = "0.9"
+rustls-connector = "0.8.0"
diff --git a/examples/README.md b/examples/README.md
index 7de0c82..b1bde9d 100644
--- a/examples/README.md
+++ b/examples/README.md
@@ -6,3 +6,4 @@ 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.
+  * rustls - This demonstrates how to use Rustls instead of Openssl for secure connections (helpful for cross compilation).
diff --git a/examples/rustls.rs b/examples/rustls.rs
new file mode 100644
index 0000000..0d8b803
--- /dev/null
+++ b/examples/rustls.rs
@@ -0,0 +1,67 @@
+extern crate imap;
+extern crate rustls_connector;
+
+use std::{
+    env,
+    error::Error,
+    net::TcpStream,
+};
+
+use dotenv::dotenv;
+use rustls_connector::RustlsConnector;
+
+
+fn main() -> Result<(), Box<dyn Error>> {
+    // Read config from environment or .env file
+    dotenv().ok();
+    let host = env::var("HOST").expect("missing envvar host");
+    let user = env::var("MAILUSER").expect("missing envvar USER");
+    let password = env::var("PASSWORD").expect("missing envvar password");
+    let port = 993;
+
+    if let Some(email) = fetch_inbox_top(host, user, password, port)? {
+        println!("{}", &email);
+    }
+
+    Ok(())
+}
+
+fn fetch_inbox_top(host: String, user: String, 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);
+
+    // the client we have here is unauthenticated.
+    // to do anything useful with the e-mails, we need to log in
+    let mut imap_session = client
+        .login(&user, &password)
+        .map_err(|e| e.0)?;
+
+    // we want to fetch the first email in the INBOX mailbox
+    imap_session.select("INBOX")?;
+
+    // fetch message number 1 in this mailbox, along with its RFC822 field.
+    // RFC 822 dictates the format of the body of e-mails
+    let messages = imap_session.fetch("1", "RFC822")?;
+    let message = if let Some(m) = messages.iter().next() {
+        m
+    } else {
+        return Ok(None);
+    };
+
+    // extract the message's body
+    let body = message.body().expect("message did not have a body!");
+    let body = std::str::from_utf8(body)
+        .expect("message was not valid utf-8")
+        .to_string();
+
+    // be nice to the server and log out
+    imap_session.logout()?;
+
+    Ok(Some(body))
+}
diff --git a/src/client.rs b/src/client.rs
index 8ec0db9..f517a6c 100644
--- a/src/client.rs
+++ b/src/client.rs
@@ -222,6 +222,9 @@ macro_rules! ok_or_unauth_client_err {
 impl<T: Read + Write> Client<T> {
     /// Creates a new client over the given stream.
     ///
+    /// For an example of how to use this method to provide a pure-Rust TLS integration, see the
+    /// rustls.rs in the examples/ directory.
+    ///
     /// This method primarily exists for writing tests that mock the underlying transport, but can
     /// also be used to support IMAP over custom tunnels.
     pub fn new(stream: T) -> Client<T> {