feat: add ID extension support

Author: link2xt

src/client.rs

@@ -1,4 +1,4 @@
-use std::collections::HashSet;
+use std::collections::{HashMap, HashSet};
 use std::fmt;
 use std::ops::{Deref, DerefMut};
 use std::pin::Pin;
@@ -11,6 +11,7 @@ use async_std::{
     io::{Read, Write, WriteExt},
     net::{TcpStream, ToSocketAddrs},
 };
+use extensions::id::{format_identification, parse_id};
 use extensions::quota::parse_get_quota_root;
 use futures::{io, Stream, StreamExt};
 use imap_proto::{RequestId, Response};
@@ -1307,6 +1308,39 @@ impl<T: Read + Write + Unpin + fmt::Debug + Send> Session<T> {
         Ok(c)
     }
 
+    /// The [`ID` command](https://datatracker.ietf.org/doc/html/rfc2971)
+    ///
+    /// `identification` is an iterable sequence of pairs such as `("name", Some("MyMailClient"))`.
+    pub async fn id(
+        &mut self,
+        identification: impl IntoIterator<Item = (&str, Option<&str>)>,
+    ) -> Result<Option<HashMap<String, String>>> {
+        let id = self
+            .run_command(format!("ID ({})", format_identification(identification)))
+            .await?;
+        let server_identification = parse_id(
+            &mut self.conn.stream,
+            self.unsolicited_responses_tx.clone(),
+            id,
+        )
+        .await?;
+        Ok(server_identification)
+    }
+
+    /// Similar to `id`, but don't identify ourselves.
+    ///
+    /// Sends `ID NIL` command and returns server response.
+    pub async fn id_nil(&mut self) -> Result<Option<HashMap<String, String>>> {
+        let id = self.run_command("ID NIL").await?;
+        let server_identification = parse_id(
+            &mut self.conn.stream,
+            self.unsolicited_responses_tx.clone(),
+            id,
+        )
+        .await?;
+        Ok(server_identification)
+    }
+
     // these are only here because they are public interface, the rest is in `Connection`
     /// Runs a command and checks if it returns OK.
     pub async fn run_command_and_check_ok<S: AsRef<str>>(&mut self, command: S) -> Result<()> {

src/extensions/id.rs

@@ -0,0 +1,93 @@
+//! IMAP ID extension specified in [RFC2971](https://datatracker.ietf.org/doc/html/rfc2971)
+
+use async_channel as channel;
+use futures::io;
+use futures::prelude::*;
+use imap_proto::{self, RequestId, Response};
+use std::collections::HashMap;
+
+use crate::types::ResponseData;
+use crate::types::*;
+use crate::{
+    error::Result,
+    parse::{filter, handle_unilateral},
+};
+
+fn escape(s: &str) -> String {
+    s.replace('\\', r"\\").replace('\"', "\\\"")
+}
+
+/// Formats list of key-value pairs for ID command.
+///
+/// Returned list is not wrapped in parenthesis, the caller should do it.
+pub(crate) fn format_identification<'a, 'b>(
+    id: impl IntoIterator<Item = (&'a str, Option<&'b str>)>,
+) -> String {
+    id.into_iter()
+        .map(|(k, v)| {
+            format!(
+                "\"{}\" {}",
+                escape(k),
+                v.map_or("NIL".to_string(), |v| format!("\"{}\"", escape(v)))
+            )
+        })
+        .collect::<Vec<String>>()
+        .join(" ")
+}
+
+pub(crate) async fn parse_id<T: Stream<Item = io::Result<ResponseData>> + Unpin>(
+    stream: &mut T,
+    unsolicited: channel::Sender<UnsolicitedResponse>,
+    command_tag: RequestId,
+) -> Result<Option<HashMap<String, String>>> {
+    let mut id = None;
+    while let Some(resp) = stream
+        .take_while(|res| filter(res, &command_tag))
+        .next()
+        .await
+    {
+        let resp = resp?;
+        match resp.parsed() {
+            Response::Id(res) => {
+                id = res.as_ref().map(|m| {
+                    m.iter()
+                        .map(|(k, v)| (k.to_string(), v.to_string()))
+                        .collect()
+                })
+            }
+            _ => {
+                handle_unilateral(resp, unsolicited.clone()).await;
+            }
+        }
+    }
+
+    Ok(id)
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn test_format_identification() {
+        assert_eq!(
+            format_identification([("name", Some("MyClient"))]),
+            r#""name" "MyClient""#
+        );
+
+        assert_eq!(
+            format_identification([("name", Some(r#""MyClient"\"#))]),
+            r#""name" "\"MyClient\"\\""#
+        );
+
+        assert_eq!(
+            format_identification([("name", Some("MyClient")), ("version", Some("2.0"))]),
+            r#""name" "MyClient" "version" "2.0""#
+        );
+
+        assert_eq!(
+            format_identification([("name", None), ("version", Some("2.0"))]),
+            r#""name" NIL "version" "2.0""#
+        );
+    }
+}

src/extensions/mod.rs

@@ -2,3 +2,5 @@
 pub mod idle;
 
 pub mod quota;
+
+pub mod id;