Idle builder

CHANGELOG.md

@@ -13,7 +13,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Changed
  - MSRV increased to 1.43 for nom6 and bitvec
  - `expunge` and `uid_expunge` return `Result<Deleted>` instead of `Result<Vec<u32>>`.
- - Idle `wait_keepalive_while` replaces `wait_keepalive` and takes a callback with an `UnsolicitedResponse` in parameter.
+ - IDLE capability now provides a builder interface. All `wait_*` functions are merged into `wait_while` which takes a callback with an `UnsolicitedResponse` in parameter.
  - All `Session.append_with_*` methods are obsoleted by `append` which returns now an `AppendCmd` builder.
  - Envelope `&'a [u8]` attributes are replaced by `Cow<'a, [u8]>`.
  - `Flag`, `Mailbox`, `UnsolicitedResponse` and `Error` are now declared as non exhaustive.

Cargo.toml

@@ -14,9 +14,8 @@ keywords = ["email", "imap"]
 categories = ["email", "network-programming"]
 
 [features]
-tls = ["native-tls"]
 rustls-tls = ["rustls-connector"]
-default = ["tls"]
+default = ["native-tls"]
 
 [dependencies]
 native-tls = { version = "0.2.2", optional = true }

examples/idle.rs

@@ -54,16 +54,14 @@ fn main() {
 
     imap.select(opt.mailbox).expect("Could not select mailbox");
 
-    let idle = imap.idle().expect("Could not IDLE");
-
     // Implement a trivial counter that causes the IDLE callback to end the IDLE
     // after a fixed number of responses.
     //
     // A threaded client could use channels or shared data to interact with the
     // rest of the program and update mailbox state, decide to exit the IDLE, etc.
     let mut num_responses = 0;
     let max_responses = opt.max_responses;
-    let idle_result = idle.wait_keepalive_while(|response| {
+    let idle_result = imap.idle().wait_while(|response| {
         num_responses += 1;
         println!("IDLE response #{}: {:?}", num_responses, response);
         if num_responses >= max_responses {
@@ -76,7 +74,7 @@ fn main() {
     });
 
     match idle_result {
-        Ok(()) => println!("IDLE finished normally"),
+        Ok(reason) => println!("IDLE finished normally {:?}", reason),
         Err(e) => println!("IDLE finished with error {:?}", e),
     }
 

src/client.rs

@@ -284,7 +284,7 @@ impl<T: Read + Write> Client<T> {
     /// # use imap::Client;
     /// # use std::io;
     /// # use std::net::TcpStream;
-    /// # {} #[cfg(feature = "tls")]
+    /// # {} #[cfg(feature = "native-tls")]
     /// # fn main() {
     /// # let server = "imap.example.com";
     /// # let username = "";
@@ -325,7 +325,7 @@ impl<T: Read + Write> Client<T> {
     /// transferred back to the caller.
     ///
     /// ```rust,no_run
-    /// # {} #[cfg(feature = "tls")]
+    /// # {} #[cfg(feature = "native-tls")]
     /// # fn main() {
     /// let client = imap::ClientBuilder::new("imap.example.org", 993)
     ///     .native_tls().unwrap();
@@ -376,7 +376,7 @@ impl<T: Read + Write> Client<T> {
     ///     }
     /// }
     ///
-    /// # {} #[cfg(feature = "tls")]
+    /// # {} #[cfg(feature = "native-tls")]
     /// fn main() {
     ///     let auth = OAuth2 {
     ///         user: String::from("me@example.com"),
@@ -1093,7 +1093,7 @@ impl<T: Read + Write> Session<T> {
     /// command, as specified in the base IMAP specification.
     ///
     /// See [`extensions::idle::Handle`] for details.
-    pub fn idle(&mut self) -> Result<extensions::idle::Handle<'_, T>> {
+    pub fn idle(&mut self) -> extensions::idle::Handle<'_, T> {
         extensions::idle::Handle::make(self)
     }
 

src/client_builder.rs

@@ -2,7 +2,7 @@ use crate::{Client, Result};
 use std::io::{Read, Write};
 use std::net::TcpStream;
 
-#[cfg(feature = "tls")]
+#[cfg(feature = "native-tls")]
 use native_tls::{TlsConnector, TlsStream};
 #[cfg(feature = "rustls-tls")]
 use rustls_connector::{RustlsConnector, TlsStream as RustlsStream};
@@ -12,7 +12,7 @@ use rustls_connector::{RustlsConnector, TlsStream as RustlsStream};
 /// Creating a [`Client`] using `native-tls` transport is straightforward:
 /// ```no_run
 /// # use imap::ClientBuilder;
-/// # {} #[cfg(feature = "tls")]
+/// # {} #[cfg(feature = "native-tls")]
 /// # fn main() -> Result<(), imap::Error> {
 /// let client = ClientBuilder::new("imap.example.com", 993).native_tls()?;
 /// # Ok(())
@@ -66,15 +66,15 @@ where
     }
 
     /// Use [`STARTTLS`](https://tools.ietf.org/html/rfc2595) for this connection.
-    #[cfg(any(feature = "tls", feature = "rustls-tls"))]
+    #[cfg(any(feature = "native-tls", feature = "rustls-tls"))]
     pub fn starttls(&mut self) -> &mut Self {
         self.starttls = true;
         self
     }
 
     /// Return a new [`Client`] using a `native-tls` transport.
-    #[cfg(feature = "tls")]
-    #[cfg_attr(docsrs, doc(cfg(feature = "tls")))]
+    #[cfg(feature = "native-tls")]
+    #[cfg_attr(docsrs, doc(cfg(feature = "native-tls")))]
     pub fn native_tls(&mut self) -> Result<Client<TlsStream<TcpStream>>> {
         self.connect(|domain, tcp| {
             let ssl_conn = TlsConnector::builder().build()?;

src/error.rs

@@ -10,9 +10,9 @@ use std::str::Utf8Error;
 use base64::DecodeError;
 use bufstream::IntoInnerError as BufError;
 use imap_proto::{types::ResponseCode, Response};
-#[cfg(feature = "tls")]
+#[cfg(feature = "native-tls")]
 use native_tls::Error as TlsError;
-#[cfg(feature = "tls")]
+#[cfg(feature = "native-tls")]
 use native_tls::HandshakeError as TlsHandshakeError;
 #[cfg(feature = "rustls-tls")]
 use rustls_connector::HandshakeError as RustlsHandshakeError;
@@ -62,10 +62,10 @@ pub enum Error {
     #[cfg(feature = "rustls-tls")]
     RustlsHandshake(RustlsHandshakeError<TcpStream>),
     /// An error from the `native_tls` library during the TLS handshake.
-    #[cfg(feature = "tls")]
+    #[cfg(feature = "native-tls")]
     TlsHandshake(TlsHandshakeError<TcpStream>),
     /// An error from the `native_tls` library while managing the socket.
-    #[cfg(feature = "tls")]
+    #[cfg(feature = "native-tls")]
     Tls(TlsError),
     /// A BAD response from the IMAP server.
     Bad(Bad),
@@ -114,14 +114,14 @@ impl From<RustlsHandshakeError<TcpStream>> for Error {
     }
 }
 
-#[cfg(feature = "tls")]
+#[cfg(feature = "native-tls")]
 impl From<TlsHandshakeError<TcpStream>> for Error {
     fn from(err: TlsHandshakeError<TcpStream>) -> Error {
         Error::TlsHandshake(err)
     }
 }
 
-#[cfg(feature = "tls")]
+#[cfg(feature = "native-tls")]
 impl From<TlsError> for Error {
     fn from(err: TlsError) -> Error {
         Error::Tls(err)
@@ -140,9 +140,9 @@ impl fmt::Display for Error {
             Error::Io(ref e) => fmt::Display::fmt(e, f),
             #[cfg(feature = "rustls-tls")]
             Error::RustlsHandshake(ref e) => fmt::Display::fmt(e, f),
-            #[cfg(feature = "tls")]
+            #[cfg(feature = "native-tls")]
             Error::Tls(ref e) => fmt::Display::fmt(e, f),
-            #[cfg(feature = "tls")]
+            #[cfg(feature = "native-tls")]
             Error::TlsHandshake(ref e) => fmt::Display::fmt(e, f),
             Error::Validate(ref e) => fmt::Display::fmt(e, f),
             Error::Parse(ref e) => fmt::Display::fmt(e, f),
@@ -163,9 +163,9 @@ impl StdError for Error {
             Error::Io(ref e) => e.description(),
             #[cfg(feature = "rustls-tls")]
             Error::RustlsHandshake(ref e) => e.description(),
-            #[cfg(feature = "tls")]
+            #[cfg(feature = "native-tls")]
             Error::Tls(ref e) => e.description(),
-            #[cfg(feature = "tls")]
+            #[cfg(feature = "native-tls")]
             Error::TlsHandshake(ref e) => e.description(),
             Error::Parse(ref e) => e.description(),
             Error::Validate(ref e) => e.description(),
@@ -183,9 +183,9 @@ impl StdError for Error {
             Error::Io(ref e) => Some(e),
             #[cfg(feature = "rustls-tls")]
             Error::RustlsHandshake(ref e) => Some(e),
-            #[cfg(feature = "tls")]
+            #[cfg(feature = "native-tls")]
             Error::Tls(ref e) => Some(e),
-            #[cfg(feature = "tls")]
+            #[cfg(feature = "native-tls")]
             Error::TlsHandshake(ref e) => Some(e),
             Error::Parse(ParseError::DataNotUtf8(_, ref e)) => Some(e),
             _ => None,