-
Notifications
You must be signed in to change notification settings - Fork 83
/
metadata.rs
462 lines (437 loc) · 17.6 KB
/
metadata.rs
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
//! Adds support for the IMAP METADATA extension specificed in [RFC
//! 5464](https://tools.ietf.org/html/rfc5464).
//!
//! Mailboxes or the server as a whole may have zero or more annotations associated with them. An
//! annotation contains a uniquely named entry, which has a value. Annotations can be added to
//! mailboxes when a mailbox name is provided as the first argument to
//! [`set_metadata`](Session::set_metadata), or to the server as a whole when the first argument is
//! `None`.
//!
//! For example, a general comment being added to a mailbox may have an entry name of "/comment"
//! and a value of "Really useful mailbox".
use crate::client::*;
use crate::error::{Error, ParseError, Result};
use crate::parse::try_handle_unilateral;
use crate::types::*;
use imap_proto::types::{MailboxDatum, Metadata, Response, ResponseCode};
use std::io::{Read, Write};
use std::sync::mpsc;
// for intra-doc links
#[allow(unused_imports)]
use crate::error::No;
trait CmdListItemFormat {
fn format_as_cmd_list_item(&self, item_index: usize) -> Result<String>;
}
impl CmdListItemFormat for Metadata {
fn format_as_cmd_list_item(&self, item_index: usize) -> Result<String> {
let synopsis = "SETMETADATA";
Ok(format!(
"{} {}",
validate_str(
synopsis,
&format!("entry#{}", item_index + 1),
self.entry.as_str()
)?,
self.value
.as_ref()
.map(|v| validate_str(synopsis, &format!("value#{}", item_index + 1), v.as_str()))
.unwrap_or_else(|| Ok("NIL".to_string()))?
))
}
}
/// Represents variants of the `DEPTH` parameter for the `GETMETADATA` command.
///
/// When a non-zero depth is specified with the `GETMETADATA` command, it extends the list of entry
/// values returned by the server. For each entry name specified in the `GETMETADATA` command, the
/// server returns the value of the specified entry name (if it exists), plus all entries below the
/// entry name up to the specified `DEPTH`.
///
/// See also [RFC 5464, section 4.2.2](https://tools.ietf.org/html/rfc5464#section-4.2.2).
#[derive(Debug, Copy, Clone)]
pub enum MetadataDepth {
/// No entries below the specified entry are returned.
Zero,
/// Only entries immediately below the specified entry are returned.
///
/// Thus, a depth of one for an entry `/a` will match `/a` as well as its children entries
/// (e.g., `/a/b`), but will not match grandchildren entries (e.g., `/a/b/c`).
One,
/// All entries below the specified entry are returned
Infinity,
}
impl Default for MetadataDepth {
fn default() -> Self {
Self::Zero
}
}
impl MetadataDepth {
fn depth_str<'a>(self) -> &'a str {
match self {
MetadataDepth::Zero => "0",
MetadataDepth::One => "1",
MetadataDepth::Infinity => "infinity",
}
}
}
fn parse_metadata<'a>(
mut lines: &'a [u8],
unsolicited: &'a mut mpsc::Sender<UnsolicitedResponse>,
) -> Result<Vec<Metadata>> {
let mut res: Vec<Metadata> = Vec::new();
loop {
if lines.is_empty() {
break Ok(res);
}
match imap_proto::parser::parse_response(lines) {
Ok((rest, resp)) => {
lines = rest;
match resp {
Response::MailboxData(MailboxDatum::MetadataSolicited {
mailbox: _,
mut values,
}) => {
res.append(&mut values);
}
_ => {
if let Some(unhandled) = try_handle_unilateral(resp, unsolicited) {
break Err(unhandled.into());
}
}
}
}
Err(_) => {
return Err(Error::Parse(ParseError::Invalid(lines.to_vec())));
}
}
}
}
impl<T: Read + Write> Session<T> {
/// Retrieve server or mailbox annotations.
///
/// This uses the `GETMETADATA` command defined in the METADATA extension of the IMAP protocol.
/// See [RFC 5464, section 4.2](https://tools.ietf.org/html/rfc5464#section-4.2) for more
/// details. Server support for the extension is indicated by the `METADATA` capability.
///
/// When the mailbox name is empty, this command retrieves server annotations. Otherwise,
/// this command retrieves annotations on the specified mailbox. If the `METADATA-SERVER`
/// capability is present, server metadata is supported, but not mailbox metadata.
///
/// The `entries` list specifies which annotations should be fetched. The RFC defines a number
/// of standard names in [Section 3.2.1](https://tools.ietf.org/html/rfc5464#section-3.2.1):
///
/// - Server entries (when `mailbox` is `None`):
/// - `/shared/comment`: A comment or note that is associated with the server and that is
/// shared with authorized users of the server.
/// - `/shared/admin`: Indicates a method for contacting the server administrator. The value
/// MUST be a URI (e.g., a `mailto:` or `tel:` URL). This entry is always read-only --
/// clients cannot change it. It is visible to authorized users of the system.
/// - `/shared/vendor/<vendor-token>`: Defines the top level of shared entries associated
/// with the server, as created by a particular product of some vendor. This entry can be
/// used by vendors to provide server- or client-specific annotations. The vendor-token
/// MUST be registered with IANA, using the Application Configuration Access Protocol
/// (ACAP) [RFC2244] vendor subtree registry.
/// - `/private/vendor/<vendor-token>`: Defines the top level of private entries associated
/// with the server, as created by a particular product of some vendor. This entry can be
/// used by vendors to provide server- or client-specific annotations. The vendor-token
/// MUST be registered with IANA, using the ACAP [RFC2244] vendor subtree registry.
/// - Mailbox entries (when `mailbox` is `Some`):
/// - `/shared/comment`: Defines a shared comment or note associated with a mailbox.
/// - `/private/comment`: Defines a private (per-user) comment or note associated with a
/// mailbox.
/// - `/shared/vendor/<vendor-token>`: Defines the top level of shared entries associated
/// with a specific mailbox, as created by a particular product of some vendor. This entry
/// can be used by vendors to provide client-specific annotations. The vendor-token MUST
/// be registered with IANA, using the ACAP [RFC2244] vendor subtree registry.
/// - `/private/vendor/<vendor-token>`: Defines the top level of private entries associated
/// with a specific mailbox, as created by a particular product of some vendor. This entry
/// can be used by vendors to provide client- specific annotations. The vendor-token MUST
/// be registered with IANA, using the ACAP [RFC2244] vendor subtree registry.
///
/// [RFC2244]: https://tools.ietf.org/html/rfc2244
///
/// The `depth` argument dictates whether metadata on children of the requested entity are
/// returned. See [`MetadataDepth`] for details
///
/// When `maxsize` is specified, it restricts which entry values are returned by the server.
/// Only entries that are less than or equal in octet size to the specified `maxsize` are
/// returned. If there are any entries with values larger than `maxsize`, this method also
/// returns the size of the biggest entry requested by the client that exceeded `maxsize`.
pub fn get_metadata(
&mut self,
mailbox: Option<&str>,
entries: &[impl AsRef<str>],
depth: MetadataDepth,
maxsize: Option<usize>,
) -> Result<(Vec<Metadata>, Option<u64>)> {
let synopsis = "GETMETADATA";
let v: Vec<String> = entries
.iter()
.enumerate()
.map(|(i, e)| validate_str(synopsis, format!("entry#{}", i + 1), e.as_ref()))
.collect::<Result<_>>()?;
let s = v.as_slice().join(" ");
let mut command = format!("GETMETADATA (DEPTH {}", depth.depth_str());
if let Some(size) = maxsize {
command.push_str(format!(" MAXSIZE {}", size).as_str());
}
command.push_str(
format!(
") {} ({})",
mailbox
.map(|mbox| validate_str(synopsis, "mailbox", mbox))
.unwrap_or_else(|| Ok("\"\"".to_string()))?,
s
)
.as_str(),
);
let (lines, ok) = self.run(command)?;
let meta = parse_metadata(&lines[..ok], &mut self.unsolicited_responses_tx)?;
let missed = if maxsize.is_some() {
if let Ok((_, Response::Done { code, .. })) =
imap_proto::parser::parse_response(&lines[ok..])
{
match code {
None => None,
Some(ResponseCode::MetadataLongEntries(v)) => Some(v),
Some(_) => None,
}
} else {
unreachable!("already parsed as Done by Client::run");
}
} else {
None
};
Ok((meta, missed))
}
/// Set annotations.
///
/// This command sets the specified list of entries by adding or replacing the specified values
/// provided, on the specified existing mailboxes or on the server (if the mailbox argument is
/// `None`). Clients can use `None` for the value of entries it wants to remove.
///
/// If the server is unable to set an annotation because the size of its value is too large,
/// this command will fail with a [`Error::No`] and its [status code](No::code) will be
/// [`ResponseCode::MetadataMaxSize`] where the contained value is the maximum octet count that
/// the server is willing to accept.
///
/// If the server is unable to set a new annotation because the maximum number of allowed
/// annotations has already been reached, this command will fail with an [`Error::No`] and its
/// [status code](No::code) will be [`ResponseCode::MetadataTooMany`].
///
/// If the server is unable to set a new annotation because it does not support private
/// annotations on one of the specified mailboxes, you guess it, you'll get an [`Error::No`] with
/// a [status code](No::code) of [`ResponseCode::MetadataNoPrivate`].
///
/// When any one annotation fails to be set and [`Error::No`] is returned, the server will not
/// change the values for other annotations specified.
///
/// See [RFC 5464, section 4.3](https://tools.ietf.org/html/rfc5464#section-4.3)
pub fn set_metadata(&mut self, mbox: impl AsRef<str>, annotations: &[Metadata]) -> Result<()> {
let v: Vec<String> = annotations
.iter()
.enumerate()
.map(|(i, metadata)| metadata.format_as_cmd_list_item(i))
.collect::<Result<_>>()?;
let s = v.as_slice().join(" ");
let command = format!(
"SETMETADATA {} ({})",
validate_str("SETMETADATA", "mailbox", mbox.as_ref())?,
s
);
self.run_command_and_check_ok(command)
}
}
#[cfg(test)]
mod tests {
use crate::extensions::metadata::*;
use crate::mock_stream::MockStream;
use crate::*;
#[test]
fn test_getmetadata() {
let response = "a1 OK Logged in.\r\n* METADATA \"\" (/shared/vendor/vendor.coi/a {3}\r\nAAA /shared/vendor/vendor.coi/b {3}\r\nBBB /shared/vendor/vendor.coi/c {3}\r\nCCC)\r\na2 OK GETMETADATA Completed\r\n";
let mock_stream = MockStream::new(response.as_bytes().to_vec());
let client = Client::new(mock_stream);
let mut session = client.login("testuser", "pass").unwrap();
let r = session.get_metadata(
None,
&["/shared/vendor/vendor.coi", "/shared/comment"],
MetadataDepth::Infinity,
Option::None,
);
match r {
Ok((v, missed)) => {
assert_eq!(missed, None);
assert_eq!(v.len(), 3);
assert_eq!(v[0].entry, "/shared/vendor/vendor.coi/a");
assert_eq!(v[0].value.as_ref().expect("None is not expected"), "AAA");
assert_eq!(v[1].entry, "/shared/vendor/vendor.coi/b");
assert_eq!(v[1].value.as_ref().expect("None is not expected"), "BBB");
assert_eq!(v[2].entry, "/shared/vendor/vendor.coi/c");
assert_eq!(v[2].value.as_ref().expect("None is not expected"), "CCC");
}
Err(e) => panic!("Unexpected error: {:?}", e),
}
}
use crate::client::testutils::assert_validation_error_session;
#[test]
fn test_getmetadata_validation_entry1() {
assert_validation_error_session(
|mut session| {
session.get_metadata(
None,
&[
"/shared/vendor\n/vendor.coi",
"/shared/comment",
"/some/other/entry",
],
MetadataDepth::Infinity,
None,
)
},
"GETMETADATA",
"entry#1",
'\n',
)
}
#[test]
fn test_getmetadata_validation_entry2() {
assert_validation_error_session(
|mut session| {
session.get_metadata(
Some("INBOX"),
&["/shared/vendor/vendor.coi", "/\rshared/comment"],
MetadataDepth::Infinity,
None,
)
},
"GETMETADATA",
"entry#2",
'\r',
)
}
#[test]
fn test_getmetadata_validation_mailbox() {
assert_validation_error_session(
|mut session| {
session.get_metadata(
Some("INB\nOX"),
&["/shared/vendor/vendor.coi", "/shared/comment"],
MetadataDepth::Infinity,
None,
)
},
"GETMETADATA",
"mailbox",
'\n',
);
}
#[test]
fn test_setmetadata_validation_mailbox() {
assert_validation_error_session(
|mut session| {
session.set_metadata(
"INB\nOX",
&[
Metadata {
entry: "/shared/vendor/vendor.coi".to_string(),
value: None,
},
Metadata {
entry: "/shared/comment".to_string(),
value: Some("value".to_string()),
},
],
)
},
"SETMETADATA",
"mailbox",
'\n',
);
}
#[test]
fn test_setmetadata_validation_entry1() {
assert_validation_error_session(
|mut session| {
session.set_metadata(
"INBOX",
&[
Metadata {
entry: "/shared/\nvendor/vendor.coi".to_string(),
value: None,
},
Metadata {
entry: "/shared/comment".to_string(),
value: Some("value".to_string()),
},
],
)
},
"SETMETADATA",
"entry#1",
'\n',
);
}
#[test]
fn test_setmetadata_validation_entry2_key() {
assert_validation_error_session(
|mut session| {
session.set_metadata(
"INBOX",
&[
Metadata {
entry: "/shared/vendor/vendor.coi".to_string(),
value: None,
},
Metadata {
entry: "/shared\r/comment".to_string(),
value: Some("value".to_string()),
},
],
)
},
"SETMETADATA",
"entry#2",
'\r',
);
}
#[test]
fn test_setmetadata_validation_entry2_value() {
assert_validation_error_session(
|mut session| {
session.set_metadata(
"INBOX",
&[
Metadata {
entry: "/shared/vendor/vendor.coi".to_string(),
value: None,
},
Metadata {
entry: "/shared/comment".to_string(),
value: Some("va\nlue".to_string()),
},
],
)
},
"SETMETADATA",
"value#2",
'\n',
);
}
#[test]
fn test_setmetadata_validation_entry() {
assert_validation_error_session(
|mut session| {
session.set_metadata(
"INBOX",
&[Metadata {
entry: "/shared/\nvendor/vendor.coi".to_string(),
value: None,
}],
)
},
"SETMETADATA",
"entry#1",
'\n',
);
}
}