MailSweep Architecture, Internals & Performance

This document describes performance optimizations, memory streaming, cryptographic validation, and security design in MailSweep.

1. Performance Optimizations

Non-Destructive Fetching: MailSweep fetches email metadata with the BODY.PEEK command:
```
BODY.PEEK[HEADER.FIELDS (SUBJECT FROM TO DATE MESSAGE-ID IN-REPLY-TO REFERENCES LIST-UNSUBSCRIBE CONTENT-TYPE)]
```
The BODY.PEEK command does not modify server \Seen message flags. Unread messages remain unread.
Chunked Paging: MailSweep queries UIDs in batches of 100 messages. This avoids protocol timeouts and buffer errors on high-volume IMAP servers. The scanner indexes more than 7,500 headers in under four seconds over standard SSL connections.

Scoped Worker Threads: The Unsubscribe Hub uses worker threads to validate unsubscription URLs in parallel.
DNS and Socket Pre-Checks: Each URL candidate undergoes a socket resolution pre-check. Strict 3-second connect and read timeouts prevent threads from hanging on unresponsive domains.

Direct-to-ZIP Streaming: MailSweep writes raw RFC 822 message streams directly into an open zip::ZipWriter stream while simultaneously updating SHA-256 digest computation.
Low Memory Footprint: The archiver processes email bodies message by message. It does not load large mailboxes into system memory.

One-Time Initialization: MailSweep pre-compiles keyword patterns and regexes for all 13 European languages with std::sync::LazyLock and regex::Regex.
Zero-Allocation Matching: Header classification matches pre-compiled patterns directly. It does not recompile regular expressions during scan loops.

Protocol Extension Negotiation: MailSweep detects server X-GM-EXT-1 capability during connection. It requests X-GM-MSGID and X-GM-LABELS in header fetch commands.
Message Deduplication: MailSweep identifies duplicate messages across virtual folders and categories using dedup_key. It deduplicates messages by X-GM-MSGID or RFC 5322 Message-ID.
Label Enrichment: When a message appears in multiple folders, MailSweep merges its labels into an immutable EmailHeader instance.
BODYSTRUCTURE Inspection: MailSweep inspects BODYSTRUCTURE tokens to detect PDF attachments and calendar invites without downloading email bodies.

Local Execution: MailSweep processes all email headers, message contents, metadata, and credentials on the local host. No data leaves the local machine.
Self-Contained Native Binary: MailSweep compiles to a single, static native executable with zero external runtime interpreters or Python dependencies.
SHA-256 Checksums: Every backup archive includes a companion .sha256 checksum file. MailSweep verifies the archive hash before restore operations.
Standard Storage Formats: Backup archives use standard ZIP containers with raw RFC 822 .eml files. Users can open and recover messages with standard email clients.

Protocol Standard	Domain Role	Implementation in MailSweep
RFC 6154	IMAP SPECIAL-USE Attributes	Auto-discovers server `\Trash`, `\Sent`, and `\Drafts` folder flags without guessing.
RFC 8058	One-Click List-Unsubscribe	Parses `List-Unsubscribe-Post: List-Unsubscribe=One-Click` headers.
RFC 2369	List Header Meta-Syntax	Extracts HTTPS URLs and `mailto:` endpoints from `List-Unsubscribe` headers.
RFC 3501	Modified UTF-7 Folders	Decodes international folder names like `Roskakori`, `Skickat`, and `Lähetetyt`.
RFC 2047	MIME Message Header Extensions	Decodes multi-pass RFC 2047 encoded words in Subject and From headers.
RFC 3834	Automatic Responses	Detects automated `Auto-Submitted` robot headers.
RFC 5322	Internet Message Format	Inspects `In-Reply-To` and `References` for conversation thread immunity.
RFC 5545	iCalendar Transport	Detects `.ics` calendar invites and appointment updates.
X-GM-EXT-1	Google IMAP Extensions	Extracts `X-GM-MSGID` and `X-GM-LABELS` for deduplication and category classification.