RuleProcessor

cull_gmail

Trait RuleProcessor 

Source 
pub trait RuleProcessor {
    // Required methods
    fn find_rule_and_messages_for_label(
        &mut self,
        label: &str,
    ) -> impl Future<Output = Result<()>> + Send;
    fn set_execute(&mut self, value: bool);
    fn initialise_lists(&mut self);
    fn set_rule(&mut self, rule: EolRule);
    fn action(&self) -> Option<EolAction>;
    fn prepare(&mut self, pages: u32) -> impl Future<Output = Result<()>> + Send;
    fn batch_delete(&mut self) -> impl Future<Output = Result<()>> + Send;
    fn batch_trash(&mut self) -> impl Future<Output = Result<()>> + Send;
    fn process_in_chunks(
        &self,
        message_ids: Vec<String>,
        action: EolAction,
    ) -> impl Future<Output = Result<()>> + Send;
    fn call_batch_delete(
        &self,
        ids: &[String],
    ) -> impl Future<Output = Result<()>> + Send;
    fn call_batch_trash(
        &self,
        ids: &[String],
    ) -> impl Future<Output = Result<()>> + Send;
}
Expand description

Trait for processing Gmail messages according to configured end-of-life rules.

This trait defines the interface for finding, filtering, and acting upon Gmail messages based on retention rules. Implementations should handle the complete workflow from rule application to message processing.

Required Methods§

Source

fn find_rule_and_messages_for_label( &mut self, label: &str, ) -> impl Future<Output = Result<()>> + Send

Processes all messages for a specific Gmail label according to the configured rule.

This is the main entry point for rule processing. It coordinates the entire workflow:

  1. Validates that the label exists in the mailbox
  2. Applies the rule’s query to find matching messages
  3. Prepares the message list for processing
  4. Executes the rule’s action (if execute flag is true) or runs in dry-run mode
§Arguments
  • label - The Gmail label name to process (e.g., “INBOX”, “old-emails”)
§Returns
  • Ok(()) - Processing completed successfully
  • Err(Error::LabelNotFoundInMailbox) - The specified label doesn’t exist
  • Err(Error::RuleNotFound) - No rule has been set via set_rule
  • Err(Error::NoQueryStringCalculated) - The rule doesn’t provide a valid query
§Side Effects

When execute flag is true, messages may be moved to trash or permanently deleted. When execute flag is false, runs in dry-run mode with no destructive actions.

Source

fn set_execute(&mut self, value: bool)

Sets the execution mode for destructive operations.

§Arguments
  • value - true to enable destructive operations, false for dry-run mode
§Safety

When set to true, subsequent calls to processing methods will perform actual destructive operations on Gmail messages. Always verify your rules and queries in dry-run mode (false) before enabling execution.

Source

fn initialise_lists(&mut self)

Initialises the message and label lists to prepare for application of rule.

§Arguments
  • none
§Example
use cull_gmail::{GmailClient, RuleProcessor, ClientConfig};

async fn example() -> Result<(), Box<dyn std::error::Error>> {
    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?;
     
    // Rules would typically be loaded from configuration
    // let rule = load_rule_from_config();
    // client.initialise_message_list();
    // client.set_rule(rule);
    Ok(())
}
Source

fn set_rule(&mut self, rule: EolRule)

Configures the end-of-life rule to apply during processing.

§Arguments
  • rule - The EolRule containing query criteria and action to perform
§Example
use cull_gmail::{GmailClient, RuleProcessor, ClientConfig};

async fn example() -> Result<(), Box<dyn std::error::Error>> {
    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?;
     
    // Rules would typically be loaded from configuration
    // let rule = load_rule_from_config();
    // client.set_rule(rule);
    Ok(())
}
Source

fn action(&self) -> Option<EolAction>

Returns the action that will be performed by the currently configured rule.

§Returns
  • Some(EolAction) - The action (e.g., EolAction::Trash) if a rule is set
  • None - If no rule has been configured via set_rule
Source

fn prepare(&mut self, pages: u32) -> impl Future<Output = Result<()>> + Send

Prepares the list of messages for processing by fetching them from Gmail.

This method queries the Gmail API to retrieve messages matching the current query and label filters, up to the specified number of pages.

§Arguments
  • pages - Maximum number of result pages to fetch (0 = all pages)
§Returns
  • Ok(()) - Messages successfully retrieved and prepared
  • Err(_) - Gmail API error or network failure
§Side Effects

Makes API calls to Gmail to retrieve message metadata. No messages are modified by this operation.

Source

fn batch_delete(&mut self) -> impl Future<Output = Result<()>> + Send

Permanently deletes all prepared messages from Gmail.

§Returns
  • Ok(()) - All messages successfully deleted
  • Err(_) - Gmail API error, network failure, or insufficient permissions
§Safety

⚠️ DESTRUCTIVE OPERATION - This permanently removes messages from Gmail. Deleted messages cannot be recovered. Use batch_trash for recoverable deletion.

§Gmail API Requirements

Requires the https://mail.google.com/ scope.

Source

fn batch_trash(&mut self) -> impl Future<Output = Result<()>> + Send

Calls the Gmail API to move a slice of the prepared messages to the Gmail trash folder.

Messages moved to trash can be recovered within 30 days through the Gmail web interface or API calls.

§Returns
  • Ok(()) - All messages successfully moved to trash
  • Err(_) - Gmail API error, network failure, or insufficient permissions
§Recovery

Messages can be recovered from trash within 30 days. After 30 days, Gmail automatically purges trashed messages.

§Gmail API Requirements

Requires the https://www.googleapis.com/auth/gmail.modify scope.

Source

fn process_in_chunks( &self, message_ids: Vec<String>, action: EolAction, ) -> impl Future<Output = Result<()>> + Send

Chunk the message lists to respect API limits and call required action.

§Returns
  • Ok(()) - All messages successfully deleted
  • Err(_) - Gmail API error, network failure, or insufficient permissions
Source

fn call_batch_delete( &self, ids: &[String], ) -> impl Future<Output = Result<()>> + Send

Calls the Gmail API to permanently deletes a slice from the list of messages.

§Returns
  • Ok(()) - All messages successfully deleted
  • Err(_) - Gmail API error, network failure, or insufficient permissions
§Safety

⚠️ DESTRUCTIVE OPERATION - This permanently removes messages from Gmail. Deleted messages cannot be recovered. Use batch_trash for recoverable deletion.

§Gmail API Requirements

Requires the https://mail.google.com/ scope.

Source

fn call_batch_trash( &self, ids: &[String], ) -> impl Future<Output = Result<()>> + Send

Moves all prepared messages to the Gmail trash folder.

Messages moved to trash can be recovered within 30 days through the Gmail web interface or API calls.

§Returns
  • Ok(()) - All messages successfully moved to trash
  • Err(_) - Gmail API error, network failure, or insufficient permissions
§Recovery

Messages can be recovered from trash within 30 days. After 30 days, Gmail automatically purges trashed messages.

§Gmail API Requirements

Requires the https://www.googleapis.com/auth/gmail.modify scope.

Dyn Compatibility§

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety", so this trait is not object safe.

Implementors§