docs: add docs for sasl

Author: Guusvanmeerveld

src/response/parser/mod.rs

@@ -25,7 +25,7 @@ pub(crate) fn parse<'a>(input: &'a [u8], request: &Command) -> IResult<&'a [u8],
 
     #[cfg(feature = "sasl")]
     match request {
-        Command::Base64(_) => match rfc1734::auth(input) {
+        Command::Base64(_) | Command::Auth => match rfc1734::auth(input) {
             Ok((input, base64_challenge)) => {
                 if let Ok(challenge) = crate::base64::decode(base64_challenge) {
                     return Ok((input, Response::Challenge(challenge.into())));

src/sasl.rs

@@ -1,3 +1,46 @@
+/*!
+# Sasl
+
+This module provides support for SASL (Simple Authentication and Security Layer), as specified in [RFC4422](https://datatracker.ietf.org/doc/html/rfc4422)
+
+It allows one to use these mechanisms to authenticate with a Pop3 compatible server and implement more mechanisms if they are needed.
+
+The mechanisms for PLAIN and XOAUTH2 are already present as they are commonly used.
+
+Implementing a mechanism is simple:
+
+```rust,ignore
+pub struct MyAuthenticator {
+    username: String,
+    secret_token: String,
+}
+
+impl Authenticator for MyAuthenticator {
+    fn mechanism(&self) -> &str {
+        "SUPER_COOL_MECHANISM"
+    }
+
+    fn auth(&self) -> Option<String> {
+        // Specify your cool format
+        Some(format!("\x00{}\x00{}", self.username, self.secret_token))
+    }
+
+    async fn handle<'a, S: Read + Write + Unpin + Send>(
+        &self,
+        communicator: Communicator<'a, S>,
+    ) -> Result<()> {
+        let challenge = communicator.next_challenge().await?;
+
+        let response = mechanism_lib::handle_challenge(challenge)?;
+
+        communicator.send(response).await?;
+
+        Ok(())
+    }
+}
+```
+*/
+
 use std::collections::VecDeque;
 
 use async_trait::async_trait;
@@ -79,7 +122,9 @@ pub trait Authenticator {
         None
     }
 
-    /// Get
+    /// Handle a handshake conversation between the server and the client.
+    ///
+    /// The [Communicator] allows you to send and receive data needed for authentication
     async fn handle<'a, S: Read + Write + Unpin + Send>(
         &self,
         _communicator: Communicator<'a, S>,

src/test.rs

@@ -10,7 +10,6 @@ use tokio::net::TcpStream;
 
 use crate::{
     response::{capability::Capability, list::ListResponse, types::DataType, uidl::UidlResponse},
-    sasl::PlainAuthenticator,
     ClientState,
 };
 
@@ -98,6 +97,7 @@ async fn e2e_login() {
 
 #[cfg_attr(feature = "runtime-tokio", tokio::test)]
 #[cfg_attr(feature = "runtime-async-std", async_std::test)]
+#[cfg(feature = "sasl")]
 async fn e2e_auth() {
     let client_info = create_client_info();
 
@@ -106,7 +106,8 @@ async fn e2e_auth() {
 
     let mut client = super::connect_plain((server, port)).await.unwrap();
 
-    let plain_auth = PlainAuthenticator::new(client_info.username, client_info.password);
+    let plain_auth =
+        crate::sasl::PlainAuthenticator::new(client_info.username, client_info.password);
 
     client.auth(plain_auth).await.unwrap();