Revert removal of the Authenticate trait.

Author: dequbed

Cargo.toml

@@ -27,6 +27,7 @@ bufstream = "0.1.3"
 imap-proto = "0.16.1"
 nom = { version = "7.1.0", default-features = false }
 rsasl = { version = "2.0.0-rc.2", default-features = false, features = ["provider_base64"] }
+base64 = "0.13.0"
 chrono = { version = "0.4", default-features = false, features = ["std"]}
 lazy_static = "1.4"
 ouroboros = "0.15.0"

examples/rustls_sasl.rs

@@ -32,7 +32,7 @@ fn fetch_inbox_top(
 
     // 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.authenticate(saslconfig, mechanism).map_err(|e| e.0)?;
+    let mut imap_session = client.sasl_auth(saslconfig, mechanism).map_err(|e| e.0)?;
 
     // we want to fetch the first email in the INBOX mailbox
     imap_session.select("INBOX")?;

src/authenticator.rs

@@ -0,0 +1,10 @@
+/// This trait allows for pluggable authentication schemes. It is used by `Client::authenticate` to
+/// [authenticate using SASL](https://tools.ietf.org/html/rfc3501#section-6.2.2).
+pub trait Authenticator {
+    /// The type of the response to the challenge. This will usually be a `Vec<u8>` or `String`.
+    type Response: AsRef<[u8]>;
+
+    /// Each base64-decoded server challenge is passed to `process`.
+    /// The returned byte-string is base64-encoded and then sent back to the server.
+    fn process(&self, challenge: &[u8]) -> Self::Response;
+}

src/client.rs

@@ -9,6 +9,7 @@ use std::sync::mpsc;
 use std::sync::Arc;
 use rsasl::prelude::{Mechname, SASLClient, SASLConfig, Session as SASLSession, State as SASLState};
 
+use super::authenticator::Authenticator;
 use super::error::{Bad, Bye, Error, No, ParseError, Result, ValidateError};
 use super::extensions;
 use super::parse::*;

src/error.rs

@@ -7,6 +7,7 @@ use std::net::TcpStream;
 use std::result;
 use std::str::Utf8Error;
 
+use base64::DecodeError;
 use bufstream::IntoInnerError as BufError;
 use imap_proto::{types::ResponseCode, Response};
 #[cfg(feature = "native-tls")]
@@ -239,7 +240,7 @@ pub enum ParseError {
     /// Indicates an error parsing the status response. Such as OK, NO, and BAD.
     Invalid(Vec<u8>),
     /// The client could not find or decode the server's authentication challenge.
-    Authentication(String),
+    Authentication(String, Option<DecodeError>),
     /// The client received data that was not UTF-8 encoded.
     DataNotUtf8(Vec<u8>, Utf8Error),
 }
@@ -248,7 +249,7 @@ impl fmt::Display for ParseError {
     fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
         match *self {
             ParseError::Invalid(_) => f.write_str("Unable to parse status response"),
-            ParseError::Authentication(_) => {
+            ParseError::Authentication(_, _) => {
                 f.write_str("Unable to parse authentication response")
             }
             ParseError::DataNotUtf8(_, _) => f.write_str("Unable to parse data as UTF-8 text"),
@@ -260,10 +261,17 @@ impl StdError for ParseError {
     fn description(&self) -> &str {
         match *self {
             ParseError::Invalid(_) => "Unable to parse status response",
-            ParseError::Authentication(_) => "Unable to parse authentication response",
+            ParseError::Authentication(_, _) => "Unable to parse authentication response",
             ParseError::DataNotUtf8(_, _) => "Unable to parse data as UTF-8 text",
         }
     }
+
+    fn cause(&self) -> Option<&dyn StdError> {
+        match *self {
+            ParseError::Authentication(_, Some(ref e)) => Some(e),
+            _ => None,
+        }
+    }
 }
 
 /// An [invalid character](https://tools.ietf.org/html/rfc3501#section-4.3) was found in a command

src/lib.rs

@@ -81,6 +81,9 @@ mod parse;
 
 pub mod types;
 
+mod authenticator;
+pub use crate::authenticator::Authenticator;
+
 mod client;
 pub use crate::client::*;
 mod client_builder;

src/parse.rs

@@ -18,7 +18,10 @@ pub fn parse_authenticate_response(line: &str) -> Result<&str> {
         let data = cap.get(1).map(|x| x.as_str()).unwrap_or("");
         return Ok(data);
     }
-    Err(Error::Parse(ParseError::Authentication(line.to_string())))
+    Err(Error::Parse(ParseError::Authentication(
+        line.to_string(),
+        None,
+    )))
 }
 
 pub(crate) enum MapOrNot<'a, T> {