Skip to main content

Crate sieve

Crate sieve 

Source
Expand description

§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::{Arena, Compiler, Context, Handler, Reply, Runtime, SieveAction, Status};

struct Printer {
    messages: Vec<String>,
    raw_message: &'static str,
}

impl<'x> Handler<'x> for Printer {
    fn action(&mut self, _: &Context<'x>, action: SieveAction<'_>) -> Reply<()> {
        match action {
            SieveAction::Keep { flags, message_id } => {
                println!(
                    "Keep message '{}' with flags {:?}.",
                    self.message(message_id),
                    flags
                );
            }
            SieveAction::Discard => {
                println!("Discard message.");
            }
            SieveAction::Reject { reason, .. } => {
                println!("Reject message with reason {reason:?}.");
            }
            SieveAction::FileInto {
                folder,
                flags,
                message_id,
                ..
            } => {
                println!(
                    "File message '{}' in folder {:?} with flags {:?}.",
                    self.message(message_id),
                    folder,
                    flags
                );
            }
            SieveAction::SendMessage {
                recipient,
                message_id,
                ..
            } => {
                println!(
                    "Send message '{}' to {:?}.",
                    self.message(message_id),
                    recipient
                );
            }
            SieveAction::Notify {
                message, method, ..
            } => {
                println!("Notify URI {method:?} with message {message:?}");
            }
            SieveAction::SetEnvelope { envelope, value } => {
                println!("Set envelope {envelope:?} to {value:?}");
            }
            SieveAction::CreatedMessage { message, .. } => {
                self.messages
                    .push(String::from_utf8_lossy(&message).into_owned());
            }
        }
        Reply::Ready(())
    }
}

impl Printer {
    fn message(&self, message_id: usize) -> &str {
        if message_id > 0 {
            self.messages[message_id - 1].as_str()
        } else {
            self.raw_message
        }
    }
}

fn main() {
    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;
    }
    "#;
    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! 
"#;

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

    let runtime = Runtime::new();

    let mut arena = Arena::new();
    let mut instance = runtime.filter(raw_message.as_bytes(), &script, &mut arena);
    let mut handler = Printer {
        messages: Vec::new(),
        raw_message,
    };

    loop {
        match instance.run(&mut handler) {
            Ok(Status::Finished) => break,
            Ok(Status::Pending) => instance.resume(true),
            Err(error) => {
                println!("Runtime error {error}");
                break;
            }
        }
    }
}

Scripts compile to a compact bytecode. Store script.to_bytes() and load it again with Sieve::from_bytes(&bytes), which borrows the buffer instead of copying it, so a script can be loaded on every delivery at almost no cost. Operations that need an asynchronous answer (list lookups, duplicate tracking, mailbox checks, external functions, scripts loaded on demand) return Reply::Pending from the handler; the interpreter then returns Status::Pending and continues after resume(input). Scripts loaded while a run is in progress (include of a user script) must outlive the Context; push them into a ScriptArena declared before the context and hand the interpreter the reference it returns.

§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.

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, Stalwart Labs LLC

Re-exports§

pub use runtime::Action as SieveAction;
pub use runtime::Arena;
pub use runtime::Handler;
pub use runtime::Input;
pub use runtime::Mailbox;
pub use runtime::MessageSource;
pub use runtime::Recipient;
pub use runtime::Reply;
pub use runtime::Script;
pub use runtime::Status;
pub use sieve::LoadError;
pub use sieve::ScriptArena;
pub use sieve::Sieve;

Modules§

bytecode
compiler
runtime
sieve

Structs§

Compiler
Context
FunctionMap
Runtime

Enums§

Envelope
Importance
MatchAs
Metadata
SpamStatus
VirusStatus

Type Aliases§

ExternalId
Function