4. Decouple RFC Codecs & Envelopes from MailboxGateway

Date: 2026-08-24

Status

Accepted

Context

MailSweep performs MIME header decoding (RFC 2047), Modified UTF-7 IMAP folder name encoding/decoding (RFC 3501), List-Unsubscribe extraction (RFC 2369 / RFC 8058), and zero-dependency .env configuration parsing.

Previously, these codec functions lived inside src/mailsweep/gateway.py alongside the active IMAP network connection logic and protocol commands (MailboxGateway). This introduced architectural friction:

1. Offline modules (BackupArchive, SafetyAuditor, UnsubscribeHub, cli.py) had to import from gateway.py merely to decode MIME strings or folder names, coupling offline file inspection to network gateway code.
2. gateway.py maintained circular import guards (TYPE_CHECKING and lazy inside-function imports of BackupArchive and CleanupPlan).
3. gateway.py became bloated (>1,000 lines) with mixed responsibilities.

Decision

We decoupled all pure RFC text transformations and configuration parsing into a dedicated domain module:

1. src/mailsweep/codecs.py (RFC Codecs & Envelopes):

   • decode_mime_header(s: str) -> str: Multi-pass RFC 2047 MIME decoder.
   • decode_imap_utf7(s: str) -> str: RFC 3501 Modified UTF-7 folder name decoder.
   • parse_unsubscribe_header(header_val: str) -> str: RFC 2369 / RFC 8058 unsubscription URL extractor.
   • load_env(env_path: Path | str) -> dict[str, str]: Zero-dependency .env parser.

2. Clean Seams Across Modules:

   • archive.py, audit.py, unsubscribe.py, and cli.py import directly from mailsweep.codecs without touching gateway.py.
   • gateway.py imports codecs from mailsweep.codecs and focuses strictly on IMAP connection lifecycles, protocol commands, and mailbox operations.
   • Re-exported codec functions via src/mailsweep/__init__.py.

3. Domain Vocabulary:

   • Formally registered RFC Codecs & Envelopes in CONTEXT.md.

Consequences

• Offline tools (archive inspection, safety audits, local brand aggregation) operate completely independently of IMAP network gateway code.
• Pure in-memory unit testing for all codecs with zero mocks or network abstractions.
• Clean module boundaries and elimination of circular import workarounds.