io_imap/rfc3501/
create.rs

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

io_imap/rfc3501/
create.rs
