io_imap/rfc3691/
unselect.rs

1//! IMAP UNSELECT coroutine: like CLOSE but without expunging \Deleted.
2//!
3//! # Example
4//!
5//! ```rust,no_run
6//! use std::{
7//!     io::{Read, Write},
8//!     net::TcpStream,
9//! };
10//!
11//! use io_imap::{
12//!     codec::fragmentizer::Fragmentizer,
13//!     coroutine::{ImapCoroutine, ImapCoroutineState, ImapYield},
14//!     rfc3691::unselect::ImapMailboxUnselect,
15//! };
16//!
17//! // Ready stream needed (TCP-connected, TLS-negociated, IMAP-authenticated)
18//! let mut stream = TcpStream::connect("localhost:143").unwrap();
19//!
20//! let mut fragmentizer = Fragmentizer::new(50 * 1024 * 1024);
21//! let mut buf = [0u8; 4096];
22//!
23//! let mut coroutine = ImapMailboxUnselect::new();
24//! let mut arg = None;
25//!
26//! loop {
27//!     match coroutine.resume(&mut fragmentizer, arg.take()) {
28//!         ImapCoroutineState::Yielded(ImapYield::WantsWrite(bytes)) => {
29//!             stream.write_all(&bytes).unwrap();
30//!         }
31//!         ImapCoroutineState::Yielded(ImapYield::WantsRead) => {
32//!             let n = stream.read(&mut buf).unwrap();
33//!             arg = Some(&buf[..n]);
34//!         }
35//!         ImapCoroutineState::Complete(Ok(())) => break,
36//!         ImapCoroutineState::Complete(Err(err)) => panic!("{err}"),
37//!     }
38//! }
39//! ```
40
41use core::fmt;
42
43use alloc::string::{String, ToString};
44
45use imap_codec::{
46    CommandCodec,
47    fragmentizer::Fragmentizer,
48    imap_types::{
49        command::{Command, CommandBody},
50        core::TagGenerator,
51        response::{StatusKind, Tagged},
52    },
53};
54use log::trace;
55use thiserror::Error;
56
57use crate::{coroutine::*, imap_try, send::*};
58
59/// Failure causes during the IMAP UNSELECT flow.
60#[derive(Clone, Debug, Error)]
61pub enum ImapMailboxUnselectError {
62    #[error("IMAP UNSELECT failed: NO {0}")]
63    No(String),
64    #[error("IMAP UNSELECT failed: BAD {0}")]
65    Bad(String),
66    #[error("IMAP UNSELECT failed: BYE {0}")]
67    Bye(String),
68
69    #[error("IMAP UNSELECT failed: server did not return a tagged response")]
70    MissingTagged,
71
72    #[error("IMAP UNSELECT failed: {0}")]
73    Send(#[from] SendImapCommandError),
74}
75
76/// I/O-free IMAP UNSELECT coroutine.
77pub struct ImapMailboxUnselect {
78    state: State,
79}
80
81impl ImapMailboxUnselect {
82    pub fn new() -> Self {
83        let command = Command {
84            tag: TagGenerator::new().generate(),
85            body: CommandBody::Unselect,
86        };
87
88        trace!("send IMAP command {command:?}");
89
90        let state = State::Send(SendImapCommand::new(CommandCodec::new(), command));
91
92        Self { state }
93    }
94}
95
96impl Default for ImapMailboxUnselect {
97    fn default() -> Self {
98        Self::new()
99    }
100}
101
102impl ImapCoroutine for ImapMailboxUnselect {
103    type Yield = ImapYield;
104    type Return = Result<(), ImapMailboxUnselectError>;
105
106    fn resume(
107        &mut self,
108        fragmentizer: &mut Fragmentizer,
109        arg: Option<&[u8]>,
110    ) -> ImapCoroutineState<Self::Yield, Self::Return> {
111        loop {
112            trace!("unselect: {}", self.state);
113
114            match &mut self.state {
115                State::Send(send) => {
116                    let out = imap_try!(send, fragmentizer, arg);
117
118                    if let Some(bye) = out.bye {
119                        let err = ImapMailboxUnselectError::Bye(bye.text.to_string());
120                        return ImapCoroutineState::Complete(Err(err));
121                    }
122
123                    let Some(Tagged { body, .. }) = out.tagged else {
124                        let err = ImapMailboxUnselectError::MissingTagged;
125                        return ImapCoroutineState::Complete(Err(err));
126                    };
127
128                    return match body.kind {
129                        StatusKind::Ok => ImapCoroutineState::Complete(Ok(())),
130                        StatusKind::No => {
131                            let err = ImapMailboxUnselectError::No(body.text.to_string());
132                            ImapCoroutineState::Complete(Err(err))
133                        }
134                        StatusKind::Bad => {
135                            let err = ImapMailboxUnselectError::Bad(body.text.to_string());
136                            ImapCoroutineState::Complete(Err(err))
137                        }
138                    };
139                }
140            }
141        }
142    }
143}
144
145enum State {
146    Send(SendImapCommand<CommandCodec>),
147}
148
149impl fmt::Display for State {
150    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
151        match self {
152            Self::Send(_) => f.write_str("send unselect"),
153        }
154    }
155}
156
157#[cfg(test)]
158mod tests {
159    use core::str;
160
161    use alloc::{borrow::ToOwned, vec::Vec};
162
163    use super::*;
164
165    #[test]
166    fn success_returns_ok() {
167        let mut unselect = ImapMailboxUnselect::new();
168        let mut frag = Fragmentizer::new(50 * 1024 * 1024);
169
170        let bytes = expect_wants_write(&mut unselect, &mut frag, None);
171        let line = str::from_utf8(&bytes).expect("utf8 command");
172        let tag = first_word(line).to_owned();
173        assert!(line.trim_end().ends_with("UNSELECT"));
174
175        expect_wants_read(&mut unselect, &mut frag);
176
177        let reply = format!("{tag} OK UNSELECT completed\r\n");
178        expect_complete_ok(&mut unselect, &mut frag, reply.as_bytes());
179    }
180
181    #[test]
182    fn tagged_no_returns_no_error() {
183        let mut unselect = ImapMailboxUnselect::new();
184        let mut frag = Fragmentizer::new(50 * 1024 * 1024);
185
186        let bytes = expect_wants_write(&mut unselect, &mut frag, None);
187        let tag = first_word(str::from_utf8(&bytes).expect("utf8 command")).to_owned();
188
189        expect_wants_read(&mut unselect, &mut frag);
190
191        let reply = format!("{tag} NO no mailbox selected\r\n");
192        let err = expect_complete_err(&mut unselect, &mut frag, reply.as_bytes());
193        let ImapMailboxUnselectError::No(text) = err else {
194            panic!("expected ImapMailboxUnselectError::No, got {err:?}");
195        };
196        assert_eq!(text, "no mailbox selected");
197    }
198
199    #[test]
200    fn tagged_bad_returns_bad_error() {
201        let mut unselect = ImapMailboxUnselect::new();
202        let mut frag = Fragmentizer::new(50 * 1024 * 1024);
203
204        let bytes = expect_wants_write(&mut unselect, &mut frag, None);
205        let tag = first_word(str::from_utf8(&bytes).expect("utf8 command")).to_owned();
206
207        expect_wants_read(&mut unselect, &mut frag);
208
209        let reply = format!("{tag} BAD UNSELECT not supported\r\n");
210        let err = expect_complete_err(&mut unselect, &mut frag, reply.as_bytes());
211        let ImapMailboxUnselectError::Bad(text) = err else {
212            panic!("expected ImapMailboxUnselectError::Bad, got {err:?}");
213        };
214        assert_eq!(text, "UNSELECT not supported");
215    }
216
217    #[test]
218    fn bye_returns_bye_error() {
219        let mut unselect = ImapMailboxUnselect::new();
220        let mut frag = Fragmentizer::new(50 * 1024 * 1024);
221
222        let _ = expect_wants_write(&mut unselect, &mut frag, None);
223        expect_wants_read(&mut unselect, &mut frag);
224
225        let err = expect_complete_err(&mut unselect, &mut frag, b"* BYE going down\r\n");
226        let ImapMailboxUnselectError::Bye(text) = err else {
227            panic!("expected ImapMailboxUnselectError::Bye, got {err:?}");
228        };
229        assert_eq!(text, "going down");
230    }
231
232    // --- utils
233
234    fn expect_wants_write(
235        cor: &mut ImapMailboxUnselect,
236        frag: &mut Fragmentizer,
237        arg: Option<&[u8]>,
238    ) -> Vec<u8> {
239        match cor.resume(frag, arg) {
240            ImapCoroutineState::Yielded(ImapYield::WantsWrite(bytes)) => bytes,
241            state => panic!("expected WantsWrite, got {state:?}"),
242        }
243    }
244
245    fn expect_wants_read(cor: &mut ImapMailboxUnselect, frag: &mut Fragmentizer) {
246        match cor.resume(frag, None) {
247            ImapCoroutineState::Yielded(ImapYield::WantsRead) => {}
248            state => panic!("expected WantsRead, got {state:?}"),
249        }
250    }
251
252    fn expect_complete_ok(cor: &mut ImapMailboxUnselect, frag: &mut Fragmentizer, reply: &[u8]) {
253        match cor.resume(frag, Some(reply)) {
254            ImapCoroutineState::Complete(Ok(())) => {}
255            state => panic!("expected Complete(Ok), got {state:?}"),
256        }
257    }
258
259    fn expect_complete_err(
260        cor: &mut ImapMailboxUnselect,
261        frag: &mut Fragmentizer,
262        reply: &[u8],
263    ) -> ImapMailboxUnselectError {
264        match cor.resume(frag, Some(reply)) {
265            ImapCoroutineState::Complete(Err(err)) => err,
266            state => panic!("expected Complete(Err), got {state:?}"),
267        }
268    }
269
270    fn first_word(line: &str) -> &str {
271        line.split_whitespace()
272            .next()
273            .expect("first whitespace-separated token")
274    }
275}
io_imap/rfc3691/unselect.rs

io_imap/rfc3691/
unselect.rs
