Decode base64 bodies with SIMD, keeping data-encoding as the arbiter (#228)

[kurok]

Closes #228.

Branched from master (73f56da), independent of #242 and #243.

What changed

After #213/#214/#218 fixed the two byte-at-a-time loops, what remained of a full parse was the base64 decode proper: 53% of it in data_encoding's scalar loop — four table lookups per three bytes, at scalar peak on both CPUs tried. The 0.9.0 changelog said it in one line: "what remains is the base64 decode proper."

The only lever left on that is wider lanes. decode_base64 now decodes the whitespace-free buffer with base64_simd::STANDARD (AVX2/SSE4.1 with runtime detection on x86-64, NEON on aarch64), and falls back to data_encoding::BASE64_MIME_PERMISSIVE on any rejection.

The fallback is what makes this a speed change and not a change to what this library accepts. STANDARD accepts a strict subset on a whitespace-free buffer — same alphabet, padding required by both, and STANDARD is additionally strict about = appearing mid-stream and about non-zero trailing bits, which are exactly the two lenient cases this library has always accepted. So "SIMD accepts, data_encoding rejects" is empty, anything both accept decodes to the same bytes, and every rejection still carries data_encoding's own DecodeError { position, kind } into MailParseError::Base64DecodeError and reaches Python with identical text.

How that claim is held up

Three independent things, because "the fast path is a subset" is an argument, not evidence:

1. simd_and_data_encoding_agree (vendored, src/body.rs) sweeps a built corpus against the old decoder as oracle: every length to 200 padded and unpadded, every byte at every position of a one- and two-block body, mid-stream = on and off block boundaries, both trailing-bit shapes, every ASCII whitespace byte interleaved, and \x0b/\x00 — which are not whitespace, so they survive the strip and must be rejected. Asserts equal bytes on accept and an equal DecodeError on reject.
2. base64_agreement, a new fuzz target, asserts the same three-way agreement — acceptance, bytes, and error text — on arbitrary input through the public entry point. 3,578,785 executions clean in 60 s locally. I also confirmed its canary still fires (FMP_FUZZ_CANARY=1 → deliberate panic), since an unarmed canary is a silent hole.
3. Three Python tests pin the lenient cases that now reach the fallback (test_midstream_padding_still_decodes, test_nonzero_trailing_bits_still_decode, test_missing_padding_still_raises). Without them a fast path that quietly swallowed those would still look green.

The shape of the call is not cosmetic

The issue asks for both capacity strategies to be measured. They were, and the result is the most interesting thing in this PR.

form	what it does	full parse
decode_inplace over the stripped buffer, then truncate	reuses the strip's allocation, no second one	9% slower
decode_to_vec into an exactly-sized buffer (shipped)	one extra allocation, no zero-fill	51% faster

Same machine, same corpus, same decoder — and standalone the two are within 10% of each other (77 µs vs 70 µs on a 781 KB payload). The in-place form is the one that reads better, which is precisely why the function and PATCH.md both carry a note saying not to "tidy" it back.

Getting there ruled things out in order rather than guessing: the fixture takes the fast path (all three parts are strict-clean — length % 4 = 0, no mid-stream =, zero trailing bits), so it wasn't silently falling back; shrink_to_fit wasn't the cost (identical 0.274 ms with and without); and linking base64-simd without calling it costs 1.5–3.4%, at or below that run's noise floor, so it isn't mere linkage either. What's left is the code-layout sensitivity of #204, which this crate builds squarely into: lto = true, codegen-units = 1.

Numbers

Apple M4 (10 vCPU), rustc 1.98.0, CPython 3.12. Two independent interleaved A/Bs pooled to 8 rounds per side (ab_median.py). Pure-Python controls within 1.1%.

Benchmark	master	this branch
parse_message	0.254 ms	0.168 ms	−34%
parse_tree	0.246 ms	0.159 ms	−35%
full_read	0.261 ms	0.172 ms	−34%
parse_many (8 × 767 KiB)	1.989 ms	1.318 ms	−34%

mode="metadata" (+0.2%) and parse_lazy_untouched (+1.5%) never call this function and are flat, which is the control that says the gain is the decode and not the weather.

Full pooled A/B report (8 rounds/side)

Measured on Apple M4, 10 vCPU.

Median of 8 interleaved rounds per side; each value is a benchmark's minimum. Positive delta = master is slower.

Benchmark	simd-to-vec	master	Delta
test__fast_mail_parser___full_read	0.172 ms	0.261 ms	+51.9%
test__fast_mail_parser___parse_lazy_all_attachments	0.176 ms	0.265 ms	+50.8%
test__fast_mail_parser___parse_lazy_untouched	0.043 ms	0.043 ms	+1.5%
test__fast_mail_parser___parse_many	1.318 ms	1.989 ms	+50.9%
test__fast_mail_parser___parse_many_metadata	0.240 ms	0.238 ms	-0.7%
test__fast_mail_parser___parse_message	0.168 ms	0.254 ms	+50.7%
test__fast_mail_parser___parse_message_strict	0.166 ms	0.253 ms	+52.0%
test__fast_mail_parser___parse_metadata	0.030 ms	0.030 ms	+0.2%
test__fast_mail_parser___parse_tree	0.159 ms	0.246 ms	+55.0%
test__fast_mail_parser___parse_tree_lazy_untouched	0.042 ms	0.042 ms	-0.3%
test__fast_mail_parser___parse_tree_metadata	0.031 ms	0.031 ms	+0.4%
test__mail_parser___parse_message	5.490 ms	5.548 ms	+1.1%	control
test__mailparser_lib___full_read	5.874 ms	5.873 ms	-0.0%	control
test__stdlib_email___full_read	7.471 ms	7.483 ms	+0.2%	control
test__threaded___parse_many	0.734 ms	1.015 ms	+38.2%	informational
test__threaded___parse_many_metadata_small	2.538 ms	2.550 ms	+0.5%	informational
test__threaded___parse_many_small	2.762 ms	2.746 ms	-0.5%	informational
test__threaded___threadpool_parse_email	0.630 ms	0.892 ms	+41.6%	informational
test__threaded___threadpool_parse_email_small	14.079 ms	14.182 ms	+0.7%	informational

Noise floor from the pure-Python controls: 1.1% (they cannot be affected by the build, so this is measurement error).

Worst treatment delta: +55.0% (test__fast_mail_parser___parse_tree).

Supply chain

base64-simd 0.8.0 is MIT and pulls vsimd 0.8.0 and outref 0.5.2, both MIT, all from crates.io — covered by deny.toml's allowlist and source policy. I verified the licenses by hand locally; cargo deny and cargo audit are not installed on this machine, so the CI jobs are the actual gate for them.

Stated plainly rather than buried: base64-simd's last release is 2022-12 and it is unsafe-heavy SIMD. PATCH.md says so, and notes that the fallback bounds the blast radius of a rejection bug to a slow path but bounds nothing about a wrong-bytes bug — which is what the differential test and the fuzz target exist for.

Checks run locally

pytest tests --ignore=tests/benchmark (806 passed, 2 skipped), the vendored suite (cargo test --manifest-path vendor/mailparse/Cargo.toml --target-dir elsewhere — 53 + 25 passed, including test_base64_content_encoding_multiple_strings unchanged), cargo fmt --all --check and cargo fmt --manifest-path vendor/mailparse/Cargo.toml --check (the root one does not format the vendored crate), cargo clippy --all-targets -- -D warnings -W clippy::cast_possible_truncation, mypy --strict, ruff check . — all green. No target/ under vendor/mailparse/.

The M4 is not a proxy for x86, and the issue expects a larger win on the gate's EPYC (AVX2 from a lower scalar base). The Benchmark quality gate job is the authoritative number; I'll add its result to the CHANGELOG entry once it reports.

Housekeeping

The PR fuzz budget stays at a minute — three targets at 20 s rather than two at 30 s — and deep-fuzz.yml gains the target in its matrix. .gitignore gains what cargo fuzz leaves behind, since running the new target locally is now something a contributor will do.

[kurok]

Rebased onto c1da4f8 now that #242 has landed. CHANGELOG.md was the only conflict; both entries kept.

Worth recording why this PR showed only CodeQL results before the rebase. It was opened after #242 merged, so it conflicted with master from the moment it was created. GitHub evaluates pull_request-triggered workflows against the PR's merge commit — and a conflicting PR has none, so test.yml never ran at all. The four CodeQL checks passed and nothing else existed, which is a state that reads as "green" at a glance while Lint, the test matrix, the benchmark gate, the fuzz pass and cargo deny/cargo audit had not run. The rebase makes the PR mergeable and the full suite is running now.

Re-measured against the new base:

Benchmark	master c1da4f8	this branch
parse_message	0.239 ms	0.157 ms	−52%
parse_tree	0.248 ms	0.157 ms	−57%
full_read	0.257 ms	0.172 ms	−50%
parse_many (8 × 767 KiB)	1.989 ms	1.326 ms	−50%

Controls within 0.3%. One honest note: parse_many_metadata read +2.8% slower in this run, above that run's noise floor. Metadata mode never calls decode_base64, so it is either layout or the measurement; it is well inside the 7% gate, and I will re-check it against the gate's own numbers rather than assert it away.

[kurok]

Rebased onto abb31b8 (post-#243). Green: 15/15, CLEAN.

One thing the rebase turned up that is worth recording, because it is the #204 failure mode again and it nearly read as a blocker.

Re-measuring on the M4 against the new base — i.e. with #227 in master — the decode paths were still ~−40%, but the paths that never call decode_base64 came back 13–19% slower:

Benchmark	M4 vs abb31b8	x86 gate (this run)
parse_metadata	−19.1% (slower)	−1.5% (faster)
parse_metadata_str	−18.8% (slower)	+2.1%
parse_many_metadata	−18.7% (slower)	−0.8%
parse_lazy_untouched	−12.6% (slower)	−4.2% (faster)
parse_tree_metadata	−18.3% (slower)	−0.1%

That is above the 7% threshold, so I did not assume it away. What I established before pushing:

• It is not anything the code does at runtime. With base64-simd linked but never executed (if black_box(false) { … }, work otherwise identical to master) the metadata paths are still 14–19% slower.
• It is deterministic, not noise: per-round minima have zero spread — 0.030 0.030 0.030 on master against 0.037 0.037 0.037 on the branch, controls at 0.7%.
• #[inline(never)] on decode_base64 — the remedy this repo's issues prescribe for exactly this — did not move it. It is not on the branch; the diff stays minimal.
• It did not exist when this branch was based on c1da4f8. It emerges only in combination with Full-mode attachments are deep-copied on every mail.attachments read and again on every .content read; give PyAttachment/PyMimePart the lazy types' Py<_> + OnceLock<Py<PyBytes>> shape #227, which is what makes it a placement effect rather than a property of either change.

The gate above is the verdict, and it is flat: worst delta +2.1%, inside the threshold, controls at 0.5%. So this is an M4-only artifact — the mirror image of #204, where Zen showed swings the M4 never did.

Recording it because it is a live example of the thing PATCH.md warns about, and because the next person to rebase this branch onto a different master may well see it again and should not spend the afternoon I did rediscovering that it is placement.