6 releases (breaking)

new 0.5.0 Mar 28, 2024
0.4.0 Dec 28, 2023
0.3.1 Jun 2, 2023
0.2.1 Jan 29, 2023
0.1.0 Oct 21, 2022

#37 in Email

Download history 39/week @ 2023-12-25 48/week @ 2024-01-01 43/week @ 2024-01-08 33/week @ 2024-01-15 5/week @ 2024-01-22 72/week @ 2024-02-12 31/week @ 2024-02-19 31/week @ 2024-02-26 80/week @ 2024-03-11 17/week @ 2024-03-18

131 downloads per month

AGPL-3.0-only

760KB
17K SLoC

sieve

crates.io build docs.rs License: AGPL v3

sieve is a fast and secure Sieve filter interpreter for Rust that supports all registered Sieve extensions.

Usage Example

use sieve::{runtime::RuntimeError, Action, Compiler, Event, Input, Runtime};

// Sieve script to execute
let text_script = br#"
require ["fileinto", "body", "imap4flags"];

if body :contains "tps" {
    setflag "$tps_reports";
}

if header :matches "List-ID" "*<*@*" {
    fileinto "INBOX.lists.${2}"; stop;
}
"#;

// Message to filter
let raw_message = r#"From: Sales Mailing List <list-sales@example.org>
To: John Doe <jdoe@example.org>
List-ID: <sales@example.org>
Subject: TPS Reports

We're putting new coversheets on all the TPS reports before they go out now.
So if you could go ahead and try to remember to do that from now on, that'd be great. All right! 
"#;

// Compile
let compiler = Compiler::new();
let script = compiler.compile(text_script).unwrap();

// Build runtime
let runtime = Runtime::new();

// Create filter instance
let mut instance = runtime.filter(raw_message.as_bytes());
let mut input = Input::script("my-script", script);
let mut messages: Vec<String> = Vec::new();

// Start event loop
while let Some(result) = instance.run(input) {
    match result {
        Ok(event) => match event {
            Event::IncludeScript { name, optional } => {
                // NOTE: Just for demonstration purposes, script name needs to be validated first.
                if let Ok(bytes) = std::fs::read(name.as_str()) {
                    let script = compiler.compile(&bytes).unwrap();
                    input = Input::script(name, script);
                } else if optional {
                    input = Input::False;
                } else {
                    panic!("Script {} not found.", name);
                }
            }
            Event::MailboxExists { .. } => {
                // Set to true if the mailbox exists
                input = false.into();
            }
            Event::ListContains { .. } => {
                // Set to true if the list(s) contains an entry
                input = false.into();
            }
            Event::DuplicateId { .. } => {
                // Set to true if the ID is duplicate
                input = false.into();
            }
            Event::Execute { command, arguments } => {
                println!(
                    "Script executed command {:?} with parameters {:?}",
                    command, arguments
                );
                // Set to true if the script succeeded
                input = false.into();
            }

            Event::Keep { flags, message_id } => {
                println!(
                    "Keep message '{}' with flags {:?}.",
                    if message_id > 0 {
                        messages[message_id - 1].as_str()
                    } else {
                        raw_message
                    },
                    flags
                );
                input = true.into();
            }
            Event::Discard => {
                println!("Discard message.");
                input = true.into();
            }
            Event::Reject { reason, .. } => {
                println!("Reject message with reason {:?}.", reason);
                input = true.into();
            }
            Event::FileInto {
                folder,
                flags,
                message_id,
                ..
            } => {
                println!(
                    "File message '{}' in folder {:?} with flags {:?}.",
                    if message_id > 0 {
                        messages[message_id - 1].as_str()
                    } else {
                        raw_message
                    },
                    folder,
                    flags
                );
                input = true.into();
            }
            Event::SendMessage {
                recipient,
                message_id,
                ..
            } => {
                println!(
                    "Send message '{}' to {:?}.",
                    if message_id > 0 {
                        messages[message_id - 1].as_str()
                    } else {
                        raw_message
                    },
                    recipient
                );
                input = true.into();
            }
            Event::Notify {
                message, method, ..
            } => {
                println!("Notify URI {:?} with message {:?}", method, message);
                input = true.into();
            }
            Event::CreatedMessage { message, .. } => {
                messages.push(String::from_utf8(message).unwrap());
                input = true.into();
            }

            #[cfg(test)]
            _ => unreachable!(),
        },
        Err(error) => {
            match error {
                RuntimeError::TooManyIncludes => {
                    eprintln!("Too many included scripts.");
                }
                RuntimeError::InvalidInstruction(instruction) => {
                    eprintln!(
                        "Invalid instruction {:?} found at {}:{}.",
                        instruction.name(),
                        instruction.line_num(),
                        instruction.line_pos()
                    );
                }
                RuntimeError::ScriptErrorMessage(message) => {
                    eprintln!("Script called the 'error' function with {:?}", message);
                }
                RuntimeError::CapabilityNotAllowed(capability) => {
                    eprintln!(
                        "Capability {:?} has been disabled by the administrator.",
                        capability
                    );
                }
                RuntimeError::CapabilityNotSupported(capability) => {
                    eprintln!("Capability {:?} not supported.", capability);
                }
                RuntimeError::CPULimitReached => {
                    eprintln!("Script exceeded the configured CPU limit.");
                }
            }
            input = true.into();
        }
    }
}

Testing & Fuzzing

To run the testsuite:

 $ cargo test --all-features

To fuzz the library with cargo-fuzz:

 $ cargo +nightly fuzz run sieve

Conformed RFCs

License

Licensed under the terms of the GNU Affero General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version. See LICENSE for more details.

You can be released from the requirements of the AGPLv3 license by purchasing a commercial license. Please contact licensing@stalw.art for more details.

Copyright (C) 2020-2023, Stalwart Labs Ltd.

Dependencies

~5–13MB
~122K SLoC