Files
cull-gmail/src/message_list.rs

706 lines
22 KiB
Rust

//! # Message List Module
//!
//! This module provides the `MessageList` trait for interacting with Gmail message lists.
//! The trait defines methods for retrieving, filtering, and managing collections of Gmail messages.
//!
//! ## Overview
//!
//! The `MessageList` trait provides:
//!
//! - Message list retrieval with pagination support
//! - Label and query-based filtering
//! - Message metadata fetching and logging
//! - Configuration of result limits and query parameters
//!
//! ## Error Handling
//!
//! All asynchronous methods return `Result<T>` where errors may include:
//! - Gmail API communication errors
//! - Authentication failures
//! - Network connectivity issues
//! - Invalid query parameters
//!
//! ## Threading
//!
//! All async methods in this trait are `Send` compatible, allowing them to be used
//! across thread boundaries in concurrent contexts.
//!
//! ## Example
//!
//! ```rust,no_run
//! use cull_gmail::{GmailClient, MessageList, ClientConfig};
//!
//! async fn example() -> Result<(), Box<dyn std::error::Error>> {
//! // Create a client with proper configuration (credentials required)
//! let config = ClientConfig::builder()
//! .with_client_id("your-client-id")
//! .with_client_secret("your-client-secret")
//! .build();
//! let mut client = GmailClient::new_with_config(config).await?;
//!
//! // Configure search parameters
//! client.set_query("is:unread");
//! client.set_max_results(50);
//!
//! // Retrieve messages from Gmail
//! client.get_messages(1).await?;
//!
//! // Access retrieved message summaries
//! let messages = client.messages();
//! println!("Found {} messages", messages.len());
//!
//! Ok(())
//! }
//! ```
#![warn(missing_docs)]
#![allow(clippy::missing_errors_doc, clippy::missing_panics_doc)]
use crate::{GmailClient, MessageSummary, Result};
use google_gmail1::{
Gmail,
api::{ListMessagesResponse, Message as GmailMessage},
hyper_rustls::HttpsConnector,
hyper_util::client::legacy::connect::HttpConnector,
};
/// A trait for interacting with Gmail message lists, providing methods for
/// retrieving, filtering, and managing collections of Gmail messages.
///
/// This trait abstracts the core operations needed to work with Gmail message lists,
/// including pagination, filtering by labels and queries, and configuring result limits.
///
/// # Examples
///
/// ```rust,no_run
/// use cull_gmail::{MessageList, GmailClient, ClientConfig};
///
/// # async fn example() -> Result<(), Box<dyn std::error::Error>> {
/// let config = ClientConfig::builder().build();
/// let mut client = GmailClient::new_with_config(config).await?;
///
/// // Set search parameters
/// client.set_query("is:unread");
/// client.set_max_results(100);
///
/// // Retrieve first page of messages
/// client.get_messages(1).await?;
/// # Ok(())
/// # }
/// ```
pub trait MessageList {
/// Fetches detailed metadata for stored messages and logs their subjects and dates.
///
/// This method retrieves the subject line and date for each message currently
/// stored in the message list and outputs them to the log.
///
/// # Returns
///
/// Returns `Result<()>` on success, or an error if the Gmail API request fails.
///
/// # Errors
///
/// This method can fail if:
/// - The Gmail API is unreachable
/// - Authentication credentials are invalid or expired
/// - Network connectivity issues occur
/// - Individual message retrieval fails
fn log_messages(&mut self) -> impl std::future::Future<Output = Result<()>> + Send;
/// Retrieves a list of messages from Gmail based on current filter settings.
///
/// This method calls the Gmail API to get a page of messages matching the
/// configured query and label filters. Retrieved message IDs are stored
/// internally for further operations.
///
/// # Arguments
///
/// * `next_page_token` - Optional token for pagination. Use `None` for the first page,
/// or the token from a previous response to get subsequent pages.
///
/// # Returns
///
/// Returns the raw `ListMessagesResponse` from the Gmail API, which contains
/// message metadata and pagination tokens.
///
/// # Errors
///
/// This method can fail if:
/// - The Gmail API request fails
/// - Authentication is invalid
/// - The query syntax is malformed
/// - Network issues prevent the API call
///
/// # Examples
///
/// ```rust,no_run
/// # use cull_gmail::{MessageList, GmailClient, ClientConfig};
/// # async fn example(mut client: impl MessageList) -> cull_gmail::Result<()> {
/// // Get the first page of results
/// let response = client.list_messages(None).await?;
///
/// // Get the next page if available
/// if let Some(token) = response.next_page_token {
/// let next_page = client.list_messages(Some(token)).await?;
/// }
/// # Ok(())
/// # }
/// ```
fn list_messages(
&mut self,
next_page_token: Option<String>,
) -> impl std::future::Future<Output = Result<ListMessagesResponse>> + Send;
/// Retrieves multiple pages of messages based on the specified page limit.
///
/// This method handles pagination automatically, fetching the specified number
/// of pages or all available pages if `pages` is 0.
///
/// # Arguments
///
/// * `pages` - Number of pages to retrieve:
/// - `0`: Fetch all available pages
/// - `1`: Fetch only the first page
/// - `n > 1`: Fetch exactly `n` pages or until no more pages are available
///
/// # Returns
///
/// Returns `Result<()>` on success. All retrieved messages are stored internally
/// and can be accessed via `messages()`.
///
/// # Errors
///
/// This method can fail if any individual page request fails. See `list_messages`
/// for specific error conditions.
///
/// # Examples
///
/// ```rust,no_run
/// # use cull_gmail::{MessageList, GmailClient, ClientConfig};
/// # async fn example(mut client: impl MessageList) -> cull_gmail::Result<()> {
/// // Get all available pages
/// client.get_messages(0).await?;
///
/// // Get exactly 3 pages
/// client.get_messages(3).await?;
/// # Ok(())
/// # }
/// ```
fn get_messages(&mut self, pages: u32) -> impl std::future::Future<Output = Result<()>> + Send;
/// Returns a reference to the Gmail API hub for direct API access.
///
/// This method provides access to the underlying Gmail API client for
/// advanced operations not covered by this trait.
///
/// # Returns
///
/// A cloned `Gmail` hub instance configured with the appropriate connectors.
fn hub(&self) -> Gmail<HttpsConnector<HttpConnector>>;
/// Returns the list of label IDs currently configured for message filtering.
///
/// # Returns
///
/// A vector of Gmail label ID strings. These IDs are used to filter
/// messages during API calls.
///
/// # Examples
///
/// ```rust,no_run
/// # use cull_gmail::MessageList;
/// # fn example(client: impl MessageList) {
/// let labels = client.label_ids();
/// println!("Filtering by {} labels", labels.len());
/// # }
/// ```
fn label_ids(&self) -> Vec<String>;
/// Returns a list of message IDs for all currently stored messages.
///
/// # Returns
///
/// A vector of Gmail message ID strings. These IDs can be used for
/// further Gmail API operations on specific messages.
///
/// # Examples
///
/// ```rust,no_run
/// # use cull_gmail::MessageList;
/// # fn example(client: impl MessageList) {
/// let message_ids = client.message_ids();
/// println!("Found {} messages", message_ids.len());
/// # }
/// ```
fn message_ids(&self) -> Vec<String>;
/// Returns a reference to the collection of message summaries.
///
/// This method provides access to all message summaries currently stored,
/// including any metadata that has been fetched.
///
/// # Returns
///
/// A reference to a vector of `MessageSummary` objects containing
/// message IDs and any retrieved metadata.
fn messages(&self) -> &Vec<MessageSummary>;
/// Sets the search query string for filtering messages.
///
/// This method configures the Gmail search query that will be used in
/// subsequent API calls. The query uses Gmail's search syntax.
///
/// # Arguments
///
/// * `query` - A Gmail search query string (e.g., "is:unread", "from:example@gmail.com")
///
/// # Examples
///
/// ```rust,no_run
/// # use cull_gmail::MessageList;
/// # fn example(mut client: impl MessageList) {
/// client.set_query("is:unread older_than:30d");
/// client.set_query("from:noreply@example.com");
/// # }
/// ```
fn set_query(&mut self, query: &str);
/// Adds Gmail label IDs to the current filter list.
///
/// This method appends the provided label IDs to the existing list of
/// labels used for filtering messages. Messages must match ALL specified labels.
///
/// # Arguments
///
/// * `label_ids` - A slice of Gmail label ID strings to add to the filter
///
/// # Examples
///
/// ```rust,no_run
/// # use cull_gmail::MessageList;
/// # fn example(mut client: impl MessageList) {
/// let label_ids = vec!["Label_1".to_string(), "Label_2".to_string()];
/// client.add_labels_ids(&label_ids);
/// # }
/// ```
fn add_labels_ids(&mut self, label_ids: &[String]);
/// Adds Gmail labels by name to the current filter list.
///
/// This method resolves label names to their corresponding IDs and adds them
/// to the filter list. This is more convenient than using `add_labels_ids`
/// when you know the label names but not their IDs.
///
/// # Arguments
///
/// * `labels` - A slice of Gmail label name strings (e.g., "INBOX", "SPAM")
///
/// # Returns
///
/// Returns `Result<()>` on success, or an error if label name resolution fails.
///
/// # Errors
///
/// This method can fail if label name to ID resolution is not available
/// or if the underlying label ID mapping is not accessible.
///
/// # Examples
///
/// ```rust,no_run
/// # use cull_gmail::MessageList;
/// # async fn example(mut client: impl MessageList) -> cull_gmail::Result<()> {
/// let labels = vec!["INBOX".to_string(), "IMPORTANT".to_string()];
/// client.add_labels(&labels)?;
/// # Ok(())
/// # }
/// ```
fn add_labels(&mut self, labels: &[String]) -> Result<()>;
/// Returns the current maximum results limit per API request.
///
/// # Returns
///
/// The maximum number of messages to retrieve in a single API call.
/// Default is typically 200.
fn max_results(&self) -> u32;
/// Sets the maximum number of results to return per API request.
///
/// This controls how many messages are retrieved in each page when calling
/// the Gmail API. Larger values reduce the number of API calls needed but
/// increase memory usage and response time.
///
/// # Arguments
///
/// * `value` - Maximum results per page (typically 1-500, Gmail API limits apply)
///
/// # Examples
///
/// ```rust,no_run
/// # use cull_gmail::MessageList;
/// # fn example(mut client: impl MessageList) {
/// client.set_max_results(100); // Retrieve 100 messages per page
/// client.set_max_results(500); // Retrieve 500 messages per page (maximum)
/// # }
/// ```
fn set_max_results(&mut self, value: u32);
}
/// Abstraction for Gmail API calls used by MessageList.
pub(crate) trait GmailService {
/// Fetch a page of messages using current filters.
async fn list_messages_page(
&self,
label_ids: &[String],
query: &str,
max_results: u32,
page_token: Option<String>,
) -> Result<ListMessagesResponse>;
/// Fetch minimal metadata for a message (subject, date, etc.).
async fn get_message_metadata(&self, message_id: &str) -> Result<GmailMessage>;
}
impl GmailClient {
/// Append any message IDs from a ListMessagesResponse into the provided messages vector.
fn append_list_to_messages(out: &mut Vec<MessageSummary>, list: &ListMessagesResponse) {
if let Some(msgs) = &list.messages {
let mut list_ids: Vec<MessageSummary> = msgs
.iter()
.flat_map(|item| item.id.as_deref().map(MessageSummary::new))
.collect();
out.append(&mut list_ids);
}
}
}
impl GmailService for GmailClient {
async fn list_messages_page(
&self,
label_ids: &[String],
query: &str,
max_results: u32,
page_token: Option<String>,
) -> Result<ListMessagesResponse> {
let hub = self.hub();
let mut call = hub.users().messages_list("me").max_results(max_results);
if !label_ids.is_empty() {
for id in label_ids {
call = call.add_label_ids(id);
}
}
if !query.is_empty() {
call = call.q(query);
}
if let Some(token) = page_token {
call = call.page_token(&token);
}
let (_response, list) = call.doit().await.map_err(Box::new)?;
Ok(list)
}
async fn get_message_metadata(&self, message_id: &str) -> Result<GmailMessage> {
let hub = self.hub();
let (_res, m) = hub
.users()
.messages_get("me", message_id)
.add_scope("https://mail.google.com/")
.format("metadata")
.add_metadata_headers("subject")
.add_metadata_headers("date")
.doit()
.await
.map_err(Box::new)?;
Ok(m)
}
}
impl MessageList for GmailClient {
/// Set the maximum results
fn set_max_results(&mut self, value: u32) {
self.max_results = value;
}
/// Report the maximum results value
fn max_results(&self) -> u32 {
self.max_results
}
/// Add label to the labels collection
fn add_labels(&mut self, labels: &[String]) -> Result<()> {
log::debug!("labels from command line: {labels:?}");
let mut label_ids = Vec::new();
for label in labels {
if let Some(id) = self.get_label_id(label) {
label_ids.push(id)
}
}
self.add_labels_ids(label_ids.as_slice());
Ok(())
}
/// Add label to the labels collection
fn add_labels_ids(&mut self, label_ids: &[String]) {
if !label_ids.is_empty() {
self.label_ids.extend(label_ids.iter().cloned());
}
}
/// Set the query string
fn set_query(&mut self, query: &str) {
self.query = query.to_string()
}
/// Get the summary of the messages
fn messages(&self) -> &Vec<MessageSummary> {
&self.messages
}
/// Get a reference to the message_ids
fn message_ids(&self) -> Vec<String> {
self.messages.iter().map(|m| m.id().to_string()).collect()
}
/// Get a reference to the message_ids
fn label_ids(&self) -> Vec<String> {
self.label_ids.clone()
}
/// Get the hub
fn hub(&self) -> Gmail<HttpsConnector<HttpConnector>> {
self.hub().clone()
}
/// Run the Gmail api as configured
async fn get_messages(&mut self, pages: u32) -> Result<()> {
let list = self.list_messages(None).await?;
match pages {
1 => {}
0 => {
let mut list = list;
let mut page = 1;
loop {
page += 1;
log::debug!("Processing page #{page}");
if list.next_page_token.is_none() {
break;
}
list = self.list_messages(list.next_page_token).await?;
// self.log_message_subjects(&list).await?;
}
}
_ => {
let mut list = list;
for page in 2..=pages {
log::debug!("Processing page #{page}");
if list.next_page_token.is_none() {
break;
}
list = self.list_messages(list.next_page_token).await?;
// self.log_message_subjects(&list).await?;
}
}
}
Ok(())
}
async fn list_messages(
&mut self,
next_page_token: Option<String>,
) -> Result<ListMessagesResponse> {
if !self.label_ids.is_empty() {
log::debug!("Setting labels for list: {:#?}", self.label_ids);
}
if !self.query.is_empty() {
log::debug!("Setting query string `{}`", self.query);
}
if next_page_token.is_some() {
log::debug!("Setting token for next page.");
}
let list = self
.list_messages_page(
&self.label_ids,
&self.query,
self.max_results,
next_page_token,
)
.await?;
log::trace!(
"Estimated {} messages.",
list.result_size_estimate.unwrap_or(0)
);
if list.result_size_estimate.unwrap_or(0) == 0 {
log::warn!("Search returned no messages.");
return Ok(list);
}
Self::append_list_to_messages(&mut self.messages, &list);
Ok(list)
}
async fn log_messages(&mut self) -> Result<()> {
for i in 0..self.messages.len() {
let id = self.messages[i].id().to_string();
log::trace!("{id}");
let m = self.get_message_metadata(&id).await?;
let message = &mut self.messages[i];
let Some(payload) = m.payload else { continue };
let Some(headers) = payload.headers else {
continue;
};
for header in headers {
if let Some(name) = header.name {
match name.to_lowercase().as_str() {
"subject" => message.set_subject(header.value),
"date" => message.set_date(header.value),
_ => {}
}
} else {
continue;
}
}
log::info!("{}", message.list_date_and_subject());
}
Ok(())
}
}
#[cfg(test)]
mod tests {
use super::*;
struct MockList {
label_ids: Vec<String>,
query: String,
max_results: u32,
messages: Vec<MessageSummary>,
}
impl MockList {
fn new() -> Self {
Self {
label_ids: vec![],
query: String::new(),
max_results: 200,
messages: vec![],
}
}
fn push_msg(&mut self, id: &str) {
self.messages.push(MessageSummary::new(id));
}
}
impl MessageList for MockList {
async fn log_messages(&mut self) -> Result<()> {
Ok(())
}
async fn list_messages(
&mut self,
_next_page_token: Option<String>,
) -> Result<ListMessagesResponse> {
Ok(ListMessagesResponse::default())
}
async fn get_messages(&mut self, _pages: u32) -> Result<()> {
Ok(())
}
fn hub(&self) -> Gmail<HttpsConnector<HttpConnector>> {
panic!("not used in tests")
}
fn label_ids(&self) -> Vec<String> {
self.label_ids.clone()
}
fn message_ids(&self) -> Vec<String> {
self.messages.iter().map(|m| m.id().to_string()).collect()
}
fn messages(&self) -> &Vec<MessageSummary> {
&self.messages
}
fn set_query(&mut self, query: &str) {
self.query = query.to_string();
}
fn add_labels_ids(&mut self, label_ids: &[String]) {
self.label_ids.extend_from_slice(label_ids);
}
fn add_labels(&mut self, _labels: &[String]) -> Result<()> {
Ok(())
}
fn max_results(&self) -> u32 {
self.max_results
}
fn set_max_results(&mut self, value: u32) {
self.max_results = value;
}
}
#[test]
fn set_query_updates_state() {
let mut ml = MockList::new();
ml.set_query("from:noreply@example.com");
// not directly accessible; rely on behavior by calling again
ml.set_query("is:unread");
assert_eq!(ml.query, "is:unread");
}
#[test]
fn add_label_ids_accumulates() {
let mut ml = MockList::new();
ml.add_labels_ids(&["Label_1".into()]);
ml.add_labels_ids(&["Label_2".into(), "Label_3".into()]);
assert_eq!(ml.label_ids, vec!["Label_1", "Label_2", "Label_3"]);
}
#[test]
fn max_results_get_set() {
let mut ml = MockList::new();
assert_eq!(ml.max_results(), 200);
ml.set_max_results(123);
assert_eq!(ml.max_results(), 123);
}
#[test]
fn message_ids_maps_from_messages() {
let mut ml = MockList::new();
ml.push_msg("abc");
ml.push_msg("def");
assert_eq!(ml.message_ids(), vec!["abc", "def"]);
assert_eq!(ml.messages().len(), 2);
}
#[test]
fn append_list_to_messages_extracts_ids() {
use google_gmail1::api::Message;
let mut out = Vec::<MessageSummary>::new();
let list = ListMessagesResponse {
messages: Some(vec![
Message {
id: Some("m1".into()),
..Default::default()
},
Message {
id: None,
..Default::default()
},
Message {
id: Some("m2".into()),
..Default::default()
},
]),
..Default::default()
};
GmailClient::append_list_to_messages(&mut out, &list);
let ids: Vec<_> = out.iter().map(|m| m.id().to_string()).collect();
assert_eq!(ids, vec!["m1", "m2"]);
}
}