sander/rust-imap
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Much better metadata docs

Browse source
This commit is contained in:
Jon Gjengset 2021-03-06 10:54:22 -08:00
parent 6fbbcb88f3
commit abf820bfb9
3 changed files with 160 additions and 33 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

48
src/client.rs
View file

@ -10,7 +10,7 @@ use std::str;
use std::sync::mpsc;
use super::authenticator::Authenticator;
use super::error::{Error, ParseError, Result, ValidateError};
use super::error::{Error, No, ParseError, Result, ValidateError};
use super::extensions;
use super::parse::*;
use super::types::*;
@ -1309,12 +1309,27 @@ impl<T: Read + Write> Session<T> {
/// a selected mailbox whose status has changed. See the note on [unilateral server responses
/// in RFC 3501](https://tools.ietf.org/html/rfc3501#section-7). This means that you *may* see
/// additional untagged `RECENT`, `EXISTS`, `FETCH`, and `EXPUNGE` responses!
///
/// The response includes the final [`Response::Done`], which starts at the returned index.
pub fn run<S: AsRef<str>>(&mut self, untagged_command: S) -> Result<(Vec<u8>, usize)> {
self.conn.run(untagged_command.as_ref())
}
/// Run a raw IMAP command and read back its response.
///
/// Note that the server *is* allowed to unilaterally send things to the client for messages in
/// a selected mailbox whose status has changed. See the note on [unilateral server responses
/// in RFC 3501](https://tools.ietf.org/html/rfc3501#section-7). This means that you *may* see
/// additional untagged `RECENT`, `EXISTS`, `FETCH`, and `EXPUNGE` responses!
///
/// The response does not include the final [`Response::Done`].
pub fn run_command_and_read_response<S: AsRef<str>>(
&mut self,
untagged_command: S,
) -> Result<Vec<u8>> {
self.conn
.run_command_and_read_response(untagged_command.as_ref())
let (mut data, ok) = self.run(untagged_command)?;
data.truncate(ok);
Ok(data)
}
}
@ -1342,17 +1357,26 @@ impl<T: Read + Write> Connection<T> {
}
fn run_command_and_read_response(&mut self, untagged_command: &str) -> Result<Vec<u8>> {
let (mut data, ok) = self.run(untagged_command)?;
data.truncate(ok);
Ok(data)
}
fn run(&mut self, untagged_command: &str) -> Result<(Vec<u8>, usize)> {
self.run_command(untagged_command)?;
self.read_response()
}
pub(crate) fn read_response(&mut self) -> Result<Vec<u8>> {
pub(crate) fn read_response(&mut self) -> Result<(Vec<u8>, usize)> {
let mut v = Vec::new();
self.read_response_onto(&mut v)?;
Ok(v)
let ok = self.read_response_onto(&mut v)?;
Ok((v, ok))
}
pub(crate) fn read_response_onto(&mut self, data: &mut Vec<u8>) -> Result<()> {
/// Read responses until a Response::Done is encountered.
///
/// The `Done` is included in `data`, and the index of the `Done` is returned.
pub(crate) fn read_response_onto(&mut self, data: &mut Vec<u8>) -> Result<usize> {
let mut continue_from = None;
let mut try_first = !data.is_empty();
let match_tag = format!("{}{}", TAG_PREFIX, self.tag);
@ -1400,8 +1424,7 @@ impl<T: Read + Write> Connection<T> {
match break_with {
Some(Ok(_)) => {
data.truncate(line_start);
break Ok(());
break Ok(line_start);
}
Some(Err((status, expl))) => {
use imap_proto::Status;
@ -1412,9 +1435,10 @@ impl<T: Read + Write> Connection<T> {
));
}
Status::No => {
break Err(Error::No(
expl.unwrap_or_else(|| "no explanation given".to_string()),
));
break Err(Error::No(No {
information: expl
.unwrap_or_else(|| "no explanation given".to_string()),
}));
}
_ => break Err(Error::Parse(ParseError::Invalid(data.split_off(0)))),
}

9
src/error.rs
View file

@ -19,6 +19,13 @@ use native_tls::HandshakeError as TlsHandshakeError;
/// A convenience wrapper around `Result` for `imap::Error`.
pub type Result<T> = result::Result<T, Error>;
/// A `NO` response from the server, which may contain additional metadata about the error.
#[derive(Debug)]
#[non_exhaustive]
pub struct No {
pub information: String,
}
/// A set of errors that can occur in the IMAP client
#[derive(Debug)]
#[non_exhaustive]
@ -34,7 +41,7 @@ pub enum Error {
/// A BAD response from the IMAP server.
Bad(String),
/// A NO response from the IMAP server.
No(String),
No(No),
/// The connection was terminated unexpectedly.
ConnectionLost,
/// Error parsing a server response.

136
src/extensions/metadata.rs
View file

@ -1,5 +1,13 @@
//! 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`], 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};
@ -98,21 +106,63 @@ fn parse_metadata<'a>(
}
impl<T: Read + Write> Session<T> {
/// Sends GETMETADATA command of the METADATA extension to IMAP protocol
/// to the server and returns the list of entries and their values.
/// Server support for the extension is indicated by METADATA capability.
/// @param mbox mailbox name. When the mailbox name is the empty string, this command retrieves server annotations. When the mailbox name is not empty, this command retrieves annotations on the specified mailbox.
/// @param entries list of metadata entries to be retrieved.
/// @param depth GETMETADATA DEPTH option, specifies if children entries are to be retrieved as well.
/// @param maxside GETMETADATA MAXSIZE option. When the MAXSIZE option is specified with the GETMETADATA command, it restricts which entry values are returned by the server. Only entry values that are less than or equal in octet size to the specified MAXSIZE limit are returned.
/// See [RFC 5464, section 4.2](https://tools.ietf.org/html/rfc5464#section-4.2) for more details.
/// 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,
mbox: impl AsRef<str>,
mailbox: Option<&str>,
entries: &[impl AsRef<str>],
depth: MetadataDepth,
maxsize: Option<usize>,
) -> Result<Vec<Metadata>> {
) -> Result<(Vec<Metadata>, Option<usize>)> {
let v: Vec<String> = entries
.iter()
.map(|e| validate_str(e.as_ref()).unwrap())
@ -127,19 +177,65 @@ impl<T: Read + Write> Session<T> {
_ => {}
}
command.push_str(format!(") {} ({})", validate_str(mbox.as_ref()).unwrap(), s).as_str());
self.run_command_and_read_response(command)
.and_then(|lines| parse_metadata(&lines[..], &mut self.unsolicited_responses_tx))
command.push_str(
format!(
") {} ({})",
mailbox
.map(|mbox| validate_str(mbox.as_ref()).unwrap())
.unwrap_or_else(|| "\"\"".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,
// TODO: https://github.com/djc/tokio-imap/issues/113
Some(_) => {}
}
} else {
unreachable!("already parsed as Done by Client::run");
}
} else {
None
};
Ok((meta, missed))
}
/// Sends SETMETADATA command of the METADATA extension to IMAP protocol
/// to the server and checks if it was executed successfully.
/// Server support for the extension is indicated by METADATA capability.
/// @param mbox mailbox name. When the mailbox name is the empty string, this command sets server annotations. When the mailbox name is not empty, this command sets annotations on the specified mailbox.
/// @param keyvl list of entry value pairs to be set.
/// 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`].
// TODO: https://github.com/djc/tokio-imap/issues/113
// with a "[METADATA MAXSIZE NNN]" response code when NNN is the maximum octet count that it 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 also fail with an
/// [`Error::No`].
// TODO: https://github.com/djc/tokio-imap/issues/113
// with a "[METADATA TOOMANY]" response code.
///
/// 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`].
// TODO: https://github.com/djc/tokio-imap/issues/113
// with a "[METADATA NOPRIVATE]" response code.
///
/// 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>, keyval: &[Metadata]) -> Result<()> {
let v: Vec<String> = keyval
pub fn set_metadata(&mut self, mbox: impl AsRef<str>, annotations: &[Metadata]) -> Result<()> {
let v: Vec<String> = annotations
.iter()
.map(|metadata| metadata.format_as_cmd_list_item())
.collect();