Change the client builder so that it abstracts away connecting to TLS…

… or non-TLS connections and what TLS provider is used.

- this allows a more transparent and versatile usage of the library as one can simply compile it as-is and then use the builder to configure where we connect and how we connect without having to be concerned about what type is used for the imap::Client / imap::Session

.github/workflows/test.yml

@@ -118,8 +118,10 @@ jobs:
       - name: cargo generate-lockfile
         if: hashFiles('Cargo.lock') == ''
         run: cargo generate-lockfile
+      - name: cargo install cargo-hack
+        uses: taiki-e/install-action@cargo-hack
       - name: cargo check
-        run: cargo check --locked --all-features --all-targets
+        run: cargo hack --feature-powerset check --locked --all-targets
   coverage:
     runs-on: ubuntu-latest
     name: ubuntu / stable / coverage

Cargo.toml

@@ -23,7 +23,7 @@ test-full-imap = []
 
 [dependencies]
 native-tls = { version = "0.2.2", optional = true }
-rustls-connector = { version = "0.18.0", optional = true }
+rustls-connector = { version = "0.18.0", optional = true, features = ["dangerous-configuration"] }
 regex = "1.0"
 bufstream = "0.1.3"
 imap-proto = "0.16.1"
@@ -73,5 +73,9 @@ required-features = ["default"]
 name = "imap_integration"
 required-features = ["default"]
 
+[[test]]
+name = "builder_integration"
+required-features = []
+
 [package.metadata.docs.rs]
 all-features = true

README.md

@@ -34,7 +34,7 @@ Below is a basic client example. See the `examples/` directory for more.
 ```rust
 fn fetch_inbox_top() -> imap::error::Result<Option<String>> {
 
-    let client = imap::ClientBuilder::new("imap.example.com", 993).native_tls()?;
+    let client = imap::ClientBuilder::new("imap.example.com", 993).connect()?;
 
     // the client we have here is unauthenticated.
     // to do anything useful with the e-mails, we need to log in

examples/basic.rs

@@ -8,7 +8,7 @@ fn main() {
 }
 
 fn fetch_inbox_top() -> imap::error::Result<Option<String>> {
-    let client = imap::ClientBuilder::new("imap.example.com", 993).native_tls()?;
+    let client = imap::ClientBuilder::new("imap.example.com", 993).connect()?;
 
     // the client we have here is unauthenticated.
     // to do anything useful with the e-mails, we need to log in

examples/gmail_oauth2.rs

@@ -24,7 +24,7 @@ fn main() {
     };
 
     let client = imap::ClientBuilder::new("imap.gmail.com", 993)
-        .native_tls()
+        .connect()
         .expect("Could not connect to imap.gmail.com");
 
     let mut imap_session = match client.authenticate("XOAUTH2", &gmail_auth) {

examples/idle.rs

@@ -39,7 +39,7 @@ fn main() {
     let opt = Opt::from_args();
 
     let client = imap::ClientBuilder::new(opt.server.clone(), opt.port)
-        .native_tls()
+        .connect()
         .expect("Could not connect to imap server");
 
     let mut imap = client

examples/rustls.rs

@@ -22,7 +22,7 @@ fn fetch_inbox_top(
     password: String,
     port: u16,
 ) -> Result<Option<String>, Box<dyn Error>> {
-    let client = imap::ClientBuilder::new(&host, port).rustls()?;
+    let client = imap::ClientBuilder::new(&host, port).connect()?;
 
     // the client we have here is unauthenticated.
     // to do anything useful with the e-mails, we need to log in

examples/starttls.rs

@@ -2,7 +2,7 @@
  * Here's an example showing how to connect to the IMAP server with STARTTLS.
  *
  * The only difference is calling `starttls()` on the `ClientBuilder` before
- * initiating the secure connection with `native_tls()` or `rustls()`, so you
+ * initiating the secure connection with `connect()`, so you
  * can connect on port 143 instead of 993.
  *
  * The following env vars are expected to be set:
@@ -42,8 +42,7 @@ fn fetch_inbox_top(
     port: u16,
 ) -> Result<Option<String>, Box<dyn Error>> {
     let client = imap::ClientBuilder::new(&host, port)
-        .starttls()
-        .native_tls()
+        .connect()
         .expect("Could not connect to server");
 
     // the client we have here is unauthenticated.

src/client.rs

@@ -340,11 +340,23 @@ impl<T: Read + Write> Client<T> {
     ///
     /// This consumes `self` since the Client is not much use without
     /// an underlying transport.
-    pub(crate) fn into_inner(self) -> Result<T> {
+    pub fn into_inner(self) -> Result<T> {
         let res = self.conn.stream.into_inner()?;
         Ok(res)
     }
 
+    /// The [`CAPABILITY` command](https://tools.ietf.org/html/rfc3501#section-6.1.1) requests a
+    /// listing of capabilities that the server supports.  The server will include "IMAP4rev1" as
+    /// one of the listed capabilities. See [`Capabilities`] for further details.
+    ///
+    /// This allows reading capabilities before authentication.
+    pub fn capabilities(&mut self) -> Result<Capabilities> {
+        // Create a temporary channel as we do not care about out of band responses before login
+        let (mut tx, _rx) = mpsc::channel();
+        self.run_command_and_read_response("CAPABILITY")
+            .and_then(|lines| Capabilities::parse(lines, &mut tx))
+    }
+
     /// Log in to the IMAP server. Upon success a [`Session`](struct.Session.html) instance is
     /// returned; on error the original `Client` instance is returned in addition to the error.
     /// This is because `login` takes ownership of `self`, so in order to try again (e.g. after
@@ -355,7 +367,7 @@ impl<T: Read + Write> Client<T> {
     /// # {} #[cfg(feature = "native-tls")]
     /// # fn main() {
     /// let client = imap::ClientBuilder::new("imap.example.org", 993)
-    ///     .native_tls().unwrap();
+    ///     .connect().unwrap();
     ///
     /// match client.login("user", "pass") {
     ///     Ok(s) => {
@@ -412,7 +424,7 @@ impl<T: Read + Write> Client<T> {
     ///         user: String::from("[email protected]"),
     ///         access_token: String::from("<access_token>"),
     ///     };
-    ///     let client = imap::ClientBuilder::new("imap.example.com", 993).native_tls()
+    ///     let client = imap::ClientBuilder::new("imap.example.com", 993).connect()
     ///         .expect("Could not connect to server");
     ///
     ///     match client.authenticate("XOAUTH2", &auth) {
@@ -1821,6 +1833,31 @@ mod tests {
         );
     }
 
+    #[test]
+    fn pre_login_capability() {
+        let response = b"* CAPABILITY IMAP4rev1 STARTTLS AUTH=GSSAPI LOGINDISABLED\r\n\
+            a1 OK CAPABILITY completed\r\n"
+            .to_vec();
+        let expected_capabilities = vec![
+            Capability::Imap4rev1,
+            Capability::Atom(Cow::Borrowed("STARTTLS")),
+            Capability::Auth(Cow::Borrowed("GSSAPI")),
+            Capability::Atom(Cow::Borrowed("LOGINDISABLED")),
+        ];
+        let mock_stream = MockStream::new(response);
+        let mut client = Client::new(mock_stream);
+        let capabilities = client.capabilities().unwrap();
+        assert_eq!(
+            client.stream.get_ref().written_buf,
+            b"a1 CAPABILITY\r\n".to_vec(),
+            "Invalid capability command"
+        );
+        assert_eq!(capabilities.len(), 4);
+        for e in expected_capabilities {
+            assert!(capabilities.has(&e));
+        }
+    }
+
     #[test]
     fn login() {
         let response = b"a1 OK Logged in\r\n".to_vec();