8. Port MailSweep to Synchronous Rust

Date: 2026-08-30

Status

Accepted

Context

MailSweep's Python implementation provides a zero-dependency toolkit for scanning, classifying, backing up, and cleaning IMAP mailboxes across 13 European languages.

As the volume of messages and mailbox complexity grow, rewriting the engine in Rust provides substantial benefits in memory safety, single-binary distribution, zero-startup latency, and high-performance multi-pattern regex matching.

A design interview established the key constraints, dependency scope, and architecture for the rewrite.

Decision

We will implement the complete MailSweep toolkit in Rust under a single unified crate architecture following these decisions:

1. Synchronous Execution Model:

   • Use synchronous standard library I/O (std::net::TcpStream) with threads/scoped parallelism where needed.
   • Avoid async runtime complexity (tokio), maintaining simple linear error traces and predictable memory utilization.

2. Crate & Protocol Ecosystem:

   • IMAP: Synchronous imap crate with rustls for secure, pure-Rust TLS communication.
   • MIME & Charset Codecs: email-encoding, encoding_rs for multi-pass RFC 2047 and legacy European charsets.
   • Archiving & Checksums: zip and sha2 for streaming timestamped backup creation and SHA-256 validation.
   • CLI & Diagnostics: clap (derive) and indicatif for argument parsing and progress bars.
   • Serialization: serde and serde_json for scan cache storage with full schema parity against the Python cache.
   • Configuration: dotenvy for parsing .env files into strongly typed config structs.
   • Error Handling: thiserror for structured domain error enums enforcing strict safety aborts (UIDVALIDITY changes, backup verification failures).

3. Rules & Classifier Engine:

   • Pre-compile 13-language category regexes and keyword sets using std::sync::LazyLock and regex.
   • Guarantee exact precedence ordering across Safety Tiers (Tier 0 through Tier 5) and Clutter Tiers.

4. Migration & Parity Verification:

   • Coexist alongside existing Python modules during development.
   • Use existing fixtures, unit tests, and the Python implementation as a reference test oracle to verify 100% heuristic and classification parity before completing cutover.

Consequences

• Delivers a single, fast, self-contained binary (mailsweep) with instant startup.
• Enables sub-second multi-language regex scans across tens of thousands of headers.
• Retains full JSON scan cache interoperability between Python and Rust.
• Preserves all inviolable domain safety guarantees, atomic backup checkpoints, and non-destructive trash semantics.