xocomil 0.3.0

//! Fused single-pass header line scanner with SIMD acceleration.
//!
//! Finds both the colon (`:`) and the `\r\n` terminator in a header line
//! while validating header name bytes (TCHAR) and value bytes (no NUL, bare
//! CR, or bare LF) — all in a single pass.
//!
//! Uses SSE2 on x86-64, NEON on aarch64, wasm SIMD on wasm32 (with
//! `simd128`), and a scalar fallback for other architectures.
//!
//! # Obs-fold rejection
//!
//! RFC 7230 §3.2.4 defines obs-fold (`\r\n` followed by SP or HTAB) as a
//! deprecated form of line folding in header values. This scanner
//! intentionally **rejects** obs-fold — any `\r\n` within a header line
//! terminates it, and if it is not immediately followed by another header
//! name or the final `\r\n`, parsing fails with `MalformedHeader`.
//!
//! This is the correct security posture: obs-fold creates ambiguity
//! between parsers that support it and those that don't, enabling
//! request smuggling via header injection.

use crate::ascii::HttpChar;
use crate::error::ParseErrorKind;
use crate::tchar::TABLE as TCHAR;

/// Result of a fused header-line scan: positions of both the colon and the
/// `\r\n` terminator, found and validated in a single pass.
#[derive(Debug)]
pub struct HeaderLineSpan {
    pub colon: usize,
    pub line_end: usize,
}

/// Scalar header line scanner. Picks up from byte offset `start` with an
/// optional already-discovered colon position (set by the SIMD fast path).
#[inline]
fn scan_header_line_scalar(
    buf: &[u8],
    start: usize,
    mut colon_pos: Option<usize>,
) -> Result<HeaderLineSpan, ParseErrorKind> {
    let len = buf.len();
    let mut i = start;
    while i < len {
        let b = buf[i];
        if let Some(colon) = colon_pos {
            if b == HttpChar::CarriageReturn {
                if i + 1 < len && buf[i + 1] == HttpChar::LineFeed {
                    return Ok(HeaderLineSpan { colon, line_end: i });
                }
                return Err(ParseErrorKind::MalformedHeader);
            }
            if b == HttpChar::LineFeed || b == HttpChar::Null {
                return Err(ParseErrorKind::MalformedHeader);
            }
        } else if b == HttpChar::Colon {
            if i == 0 {
                return Err(ParseErrorKind::MalformedHeader);
            }
            colon_pos = Some(i);
        } else if !TCHAR[b as usize] {
            return Err(ParseErrorKind::MalformedHeader);
        }
        i += 1;
    }
    Err(ParseErrorKind::MalformedHeader)
}

// ---------------------------------------------------------------------------
// Shared bitmask-based scan_header_line (SSE2 + wasm SIMD)
// ---------------------------------------------------------------------------

/// Generates a bitmask-based `scan_header_line` using `simd_splat!`,
/// `simd_load!`, and `simd_mask!` helper macros defined by each call site.
/// `simd_mask!(chunk, vec)` must return a `u32` bitmask of matching lanes.
///
/// The TCHAR validation impl is parameterized so `x86_64` can instantiate
/// the scanner twice — once with `Ssse3` (under
/// `#[target_feature(enable = "ssse3")]` so `pshufb` inlines) and once
/// with `Sse2Only` — and dispatch between them once per call.
macro_rules! impl_bitmask_scan_header_line {
    ($tchar:ty) => {
        /// Safety: all SIMD loads stay within `buf[i..i+16]`
        /// where `i + 16 <= buf.len()`.
        #[inline]
        pub(super) unsafe fn scan_header_line(
            buf: &[u8],
        ) -> Result<HeaderLineSpan, ParseErrorKind> {
            let len = buf.len();
            unsafe {
                let v_cr = simd_splat!(HttpChar::CarriageReturn.as_u8());
                let v_lf = simd_splat!(HttpChar::LineFeed.as_u8());
                let v_nul = simd_splat!(HttpChar::Null.as_u8());
                let v_colon = simd_splat!(HttpChar::Colon.as_u8());
                let mut i = 0;
                let mut colon_pos: Option<usize> = None;

                while i + 16 <= len {
                    let chunk = simd_load!(buf.as_ptr().add(i));
                    let cr_mask = simd_mask!(chunk, v_cr);
                    let lf_mask = simd_mask!(chunk, v_lf);
                    let nul_mask = simd_mask!(chunk, v_nul);

                    match colon_pos {
                        None => {
                            let colon_mask = simd_mask!(chunk, v_colon);

                            if colon_mask != 0 {
                                let colon_bit = colon_mask.trailing_zeros() as usize;
                                let cpos = i + colon_bit;

                                if cpos == 0 {
                                    return Err(ParseErrorKind::MalformedHeader);
                                }

                                // SIMD TCHAR check on bytes before the colon.
                                let name_mask = (1u32 << colon_bit) - 1;
                                if <$tchar>::mask16(buf.as_ptr().add(i)) & name_mask != name_mask {
                                    return Err(ParseErrorKind::MalformedHeader);
                                }

                                colon_pos = Some(cpos);

                                if cr_mask != 0 {
                                    let cr_bit = cr_mask.trailing_zeros() as usize;
                                    if cr_bit > colon_bit {
                                        let pos = i + cr_bit;
                                        // Mask covering value bytes between colon and CR.
                                        // Invariant: cr_bit > colon_bit, so both shifts
                                        // are in [1, 15] — no overflow.
                                        let before_cr = (1u32 << cr_bit) - 1;
                                        let after_colon = !((1u32 << (colon_bit + 1)) - 1);
                                        let value_mask = before_cr & after_colon;
                                        if ((nul_mask | lf_mask) & value_mask) != 0 {
                                            return Err(ParseErrorKind::MalformedHeader);
                                        }
                                        if pos + 1 < len
                                            && *buf.get_unchecked(pos + 1) == HttpChar::LineFeed
                                        {
                                            return Ok(HeaderLineSpan {
                                                colon: cpos,
                                                line_end: pos,
                                            });
                                        }
                                        return Err(ParseErrorKind::MalformedHeader);
                                    }
                                    return Err(ParseErrorKind::MalformedHeader);
                                }

                                let after_colon = !((1u32 << (colon_bit + 1)) - 1);
                                if ((nul_mask | lf_mask) & after_colon) != 0 {
                                    return Err(ParseErrorKind::MalformedHeader);
                                }

                                i += 16;
                                continue;
                            }

                            if (cr_mask | lf_mask | nul_mask) != 0 {
                                return Err(ParseErrorKind::MalformedHeader);
                            }
                            // Full 16-byte SIMD TCHAR check — no scalar loop.
                            if <$tchar>::mask16(buf.as_ptr().add(i)) != 0xFFFF {
                                return Err(ParseErrorKind::MalformedHeader);
                            }
                        }
                        Some(colon) => {
                            if cr_mask != 0 {
                                let cr_bit = cr_mask.trailing_zeros();
                                let pos = i + cr_bit as usize;

                                let before_mask = (1u32 << cr_bit) - 1;
                                if ((nul_mask | lf_mask) & before_mask) != 0 {
                                    return Err(ParseErrorKind::MalformedHeader);
                                }

                                if pos + 1 < len
                                    && *buf.get_unchecked(pos + 1) == HttpChar::LineFeed
                                {
                                    return Ok(HeaderLineSpan {
                                        colon,
                                        line_end: pos,
                                    });
                                }
                                return Err(ParseErrorKind::MalformedHeader);
                            }

                            if (nul_mask | lf_mask) != 0 {
                                return Err(ParseErrorKind::MalformedHeader);
                            }
                        }
                    }

                    i += 16;
                }

                scan_header_line_scalar(buf, i, colon_pos)
            }
        }
    };
}

// ---------------------------------------------------------------------------
// Architecture-specific scan_header_line implementations
// ---------------------------------------------------------------------------

/// AVX2-specialized `x86_64` scanner using 32-byte SIMD chunks.
///
/// # Algorithm — "first interesting byte" dispatch
///
/// The scanner has two phases driven by an explicit [`Phase`] enum:
///
/// * [`Phase::Name`] — looking for the colon that ends the header
///   name. Anything other than TCHAR + `:` is a syntax error.
/// * [`Phase::Value`] — past the colon, looking for `CR`. A bare
///   `LF` or `NUL` in the value is a syntax error.
///
/// Each chunk computes four byte-equality masks (`CR`, `LF`, `NUL`,
/// `:`) unconditionally — the SIMD compares pipeline back-to-back
/// without data dependencies. The phase then OR-reduces those masks
/// into a single "stop here" bitmap and uses
/// [`u32::trailing_zeros`] to find the first interesting byte. A
/// small `match` on which mask hit decides whether to error,
/// transition phase, or return.
///
/// Compared to the previous nested-`if` form this:
///
/// * Eliminates two control-flow inversions per chunk (re-checking
///   "is `colon_pos` set" both at the top of the chunk and again at
///   the bottom).
/// * Computes `colon_mask` only in [`Phase::Name`]; in [`Phase::Value`]
///   it's never needed.
/// * Lets the compiler hoist all four `vpcmpeqb` instructions into a
///   single back-to-back schedule per chunk (the previous form
///   interleaved them with branches).
#[cfg(target_arch = "x86_64")]
#[allow(
    clippy::cast_possible_wrap,
    clippy::cast_sign_loss,
    clippy::cast_ptr_alignment
)]
mod avx2_mod {
    use std::arch::x86_64::{
        _mm256_cmpeq_epi8, _mm256_loadu_si256, _mm256_movemask_epi8, _mm256_set1_epi8,
    };

    use super::{HeaderLineSpan, ParseErrorKind, scan_header_line_scalar};
    use crate::ascii::HttpChar;
    use crate::tchar::Avx2;

    /// Phase of the header-line scanner state machine.
    #[derive(Clone, Copy)]
    enum Phase {
        /// Before the colon — looking for `:`.
        Name,
        /// After the colon — looking for `CR`. Carries the absolute
        /// byte offset of the colon for the final `HeaderLineSpan`.
        Value { colon: usize },
    }

    /// Construct the bitmask of bytes strictly before bit `b` in a
    /// 32-byte chunk. `b` may be 0..=32; at 32 the mask is `!0`.
    ///
    /// Compiler emits a single `bzhi` / shift-and-decrement here.
    /// `1u32 << 32` would overflow, so saturate via 64-bit math —
    /// the truncation back to `u32` is intentional and correct
    /// because the source value is at most `2^32 - 1`.
    #[inline]
    #[allow(clippy::cast_possible_truncation)]
    const fn before_bit(b: u32) -> u32 {
        ((1u64 << b) - 1) as u32
    }

    /// Safety: all SIMD loads stay within `buf[i..i+32]`
    /// where `i + 32 <= buf.len()`. Caller must verify AVX2 support.
    #[target_feature(enable = "avx2")]
    #[inline]
    pub(super) unsafe fn scan_header_line_avx2(
        buf: &[u8],
    ) -> Result<HeaderLineSpan, ParseErrorKind> {
        let len = buf.len();
        // Safety: AVX2 is enabled on this function via `target_feature`,
        // so all `_mm256_*` intrinsics below are sound to call. Each
        // SIMD load reads exactly 32 bytes and is gated on
        // `i + 32 <= len`. The pointer arithmetic
        // `buf.as_ptr().add(i)` stays in-bounds for the same reason.
        unsafe {
            let v_cr = _mm256_set1_epi8(HttpChar::CarriageReturn.as_i8());
            let v_lf = _mm256_set1_epi8(HttpChar::LineFeed.as_i8());
            let v_nul = _mm256_set1_epi8(HttpChar::Null.as_i8());
            let v_colon = _mm256_set1_epi8(HttpChar::Colon.as_i8());

            let mut i = 0;
            let mut phase = Phase::Name;

            while i + 32 <= len {
                let chunk = _mm256_loadu_si256(buf.as_ptr().add(i).cast());

                // Four parallel byte-equality compares — these emit
                // four independent `vpcmpeqb` + `vpmovmskb` pairs
                // that the CPU can issue in a single bundle.
                let cr_mask = _mm256_movemask_epi8(_mm256_cmpeq_epi8(chunk, v_cr)) as u32;
                let lf_mask = _mm256_movemask_epi8(_mm256_cmpeq_epi8(chunk, v_lf)) as u32;
                let nul_mask = _mm256_movemask_epi8(_mm256_cmpeq_epi8(chunk, v_nul)) as u32;
                // Bare `LF` or `NUL` is illegal in both phases —
                // collapse the two sentinel masks once per chunk.
                let bad_value = lf_mask | nul_mask;

                match phase {
                    Phase::Name => {
                        let colon_mask =
                            _mm256_movemask_epi8(_mm256_cmpeq_epi8(chunk, v_colon)) as u32;
                        // `stop_mask` covers every byte that ends or
                        // breaks the name region in this chunk.
                        let stop_mask = colon_mask | cr_mask | bad_value;

                        if stop_mask == 0 {
                            // Pure name region: every byte must be a TCHAR.
                            if Avx2::mask32(buf.as_ptr().add(i)) != 0xFFFF_FFFF {
                                return Err(ParseErrorKind::MalformedHeader);
                            }
                            i += 32;
                            continue;
                        }

                        let stop_bit = stop_mask.trailing_zeros();
                        let stop_pos = i + stop_bit as usize;
                        let stop_byte_mask = 1u32 << stop_bit;

                        // The first non-TCHAR-ish byte must be a `:`
                        // sitting at a non-zero absolute position.
                        // Anything else (`CR`, `LF`, `NUL`, or `:` at
                        // pos 0) is a syntax error.
                        if (colon_mask & stop_byte_mask) == 0 || stop_pos == 0 {
                            return Err(ParseErrorKind::MalformedHeader);
                        }

                        // Validate name bytes (all bits before stop_bit
                        // must be valid TCHARs).
                        let name_mask = before_bit(stop_bit);
                        if Avx2::mask32(buf.as_ptr().add(i)) & name_mask != name_mask {
                            return Err(ParseErrorKind::MalformedHeader);
                        }

                        // Transition to Value, then re-evaluate this
                        // same chunk: the value region may already
                        // contain `CR` (terminating the line) or
                        // `LF`/`NUL` (an error). Doing the work here
                        // saves a redundant SIMD load.
                        phase = Phase::Value { colon: stop_pos };

                        // Bytes strictly after the colon, within this chunk.
                        let after_colon = !before_bit(stop_bit + 1);
                        let value_stop = (cr_mask | bad_value) & after_colon;

                        if value_stop == 0 {
                            // No CR/LF/NUL after colon in this chunk — keep going.
                            i += 32;
                            continue;
                        }

                        // First interesting byte in the value region.
                        let v_bit = value_stop.trailing_zeros();
                        let v_byte = 1u32 << v_bit;

                        // Invariant: by `trailing_zeros`, no LF/NUL bit
                        // is set strictly before `v_bit` within the
                        // value region. If `v_byte` is itself in
                        // `bad_value`, the `(cr_mask & v_byte) == 0`
                        // check below catches it.
                        debug_assert_eq!(
                            (lf_mask | nul_mask) & after_colon & (v_byte - 1),
                            0,
                            "value_stop logic violated: LF/NUL before first stop byte"
                        );

                        // It must be a `CR` (and not preceded by any
                        // bare `LF` or `NUL`, which the mask logic
                        // already enforces by `trailing_zeros`).
                        if (cr_mask & v_byte) == 0 {
                            return Err(ParseErrorKind::MalformedHeader);
                        }
                        let pos = i + v_bit as usize;
                        return finish_line(buf, len, stop_pos, pos);
                    }

                    Phase::Value { colon } => {
                        let stop_mask = cr_mask | bad_value;

                        if stop_mask == 0 {
                            // Plain value bytes — keep scanning.
                            i += 32;
                            continue;
                        }

                        let stop_bit = stop_mask.trailing_zeros();
                        let stop_byte = 1u32 << stop_bit;

                        // The first interesting byte must be `CR`.
                        if (cr_mask & stop_byte) == 0 {
                            return Err(ParseErrorKind::MalformedHeader);
                        }
                        let pos = i + stop_bit as usize;
                        return finish_line(buf, len, colon, pos);
                    }
                }
            }

            // Tail (< 32 bytes left) — hand off to the shared scalar scanner.
            let colon_pos = match phase {
                Phase::Name => None,
                Phase::Value { colon } => Some(colon),
            };
            scan_header_line_scalar(buf, i, colon_pos)
        }
    }

    /// Verify the byte after `cr_pos` is `LF` and return the parsed span.
    ///
    /// Used by both `Phase::Name`-cross-chunk and `Phase::Value`
    /// success paths — keeping the LF check in a single helper makes
    /// the per-phase loop body easier to read.
    #[inline]
    fn finish_line(
        buf: &[u8],
        len: usize,
        colon: usize,
        cr_pos: usize,
    ) -> Result<HeaderLineSpan, ParseErrorKind> {
        // Safety: callers compute `cr_pos` from a SIMD match within
        // `buf[i..i+32]` where `i + 32 <= len`, so `cr_pos < len`.
        // Reading `cr_pos + 1` is gated on the explicit `< len` check.
        if cr_pos + 1 < len && unsafe { *buf.get_unchecked(cr_pos + 1) } == HttpChar::LineFeed {
            return Ok(HeaderLineSpan {
                colon,
                line_end: cr_pos,
            });
        }
        Err(ParseErrorKind::MalformedHeader)
    }
}

/// SSSE3-specialized `x86_64` scanner. The wrapper has
/// `#[target_feature(enable = "ssse3")]` so `Ssse3::mask16` (and the
/// `pshufb` inside it) inlines into the per-chunk SIMD loop. The
/// public `scan_header_line` dispatches to this when the host CPU
/// supports SSSE3.
#[cfg(target_arch = "x86_64")]
#[allow(
    clippy::cast_possible_wrap,
    clippy::cast_sign_loss,
    clippy::cast_ptr_alignment
)]
mod sse2_ssse3 {
    crate::simd::define_simd_primitives!();

    use super::{HeaderLineSpan, ParseErrorKind, scan_header_line_scalar};
    use crate::ascii::HttpChar;
    use crate::tchar::{Ssse3, TcharCheck};

    impl_bitmask_scan_header_line!(Ssse3);

    /// SSSE3 trampoline: re-exports `scan_header_line` under
    /// `#[target_feature(enable = "ssse3")]` so the SSSE3 instructions
    /// emitted inside `Ssse3::mask16` can be inlined here.
    ///
    /// # Safety
    ///
    /// Caller must ensure the host supports SSSE3 (verify with
    /// `crate::tchar::has_ssse3()`).
    #[target_feature(enable = "ssse3")]
    #[inline]
    pub(super) unsafe fn scan_header_line_ssse3(
        buf: &[u8],
    ) -> Result<HeaderLineSpan, ParseErrorKind> {
        // Safety: caller guarantees SSSE3.
        unsafe { scan_header_line(buf) }
    }
}

/// SSE2-only `x86_64` scanner using a scalar TCHAR table fallback.
/// Used on pre-2006 CPUs that lack SSSE3.
#[cfg(target_arch = "x86_64")]
#[allow(
    clippy::cast_possible_wrap,
    clippy::cast_sign_loss,
    clippy::cast_ptr_alignment
)]
mod sse2_scalar {
    crate::simd::define_simd_primitives!();

    use super::{HeaderLineSpan, ParseErrorKind, scan_header_line_scalar};
    use crate::ascii::HttpChar;
    use crate::tchar::{Sse2Only, TcharCheck};

    impl_bitmask_scan_header_line!(Sse2Only);
}

#[cfg(target_arch = "aarch64")]
mod neon {
    use std::arch::aarch64::{vceqq_u8, vdupq_n_u8, vld1q_u8, vmaxvq_u8};

    use super::{HeaderLineSpan, ParseErrorKind, scan_header_line_scalar};
    use crate::ascii::HttpChar;
    use crate::tchar::TcharCheck;

    /// NEON fused header line scanner. Uses `vmaxvq_u8` to detect whether
    /// interesting bytes (CR, LF, NUL, colon) exist in each 16-byte chunk,
    /// then scans the 16-byte window byte-by-byte to extract exact
    /// positions before continuing SIMD on the next chunk.
    ///
    /// Safety: NEON is guaranteed on all aarch64 processors.
    /// All loads stay within `buf[i..i+16]` where `i + 16 <= buf.len()`.
    #[inline]
    #[allow(clippy::cast_sign_loss)]
    pub(super) fn scan_header_line(buf: &[u8]) -> Result<HeaderLineSpan, ParseErrorKind> {
        let len = buf.len();
        unsafe {
            let v_cr = vdupq_n_u8(HttpChar::CarriageReturn.as_u8());
            let v_lf = vdupq_n_u8(HttpChar::LineFeed.as_u8());
            let v_nul = vdupq_n_u8(HttpChar::Null.as_u8());
            let v_colon = vdupq_n_u8(HttpChar::Colon.as_u8());
            let mut i = 0;
            let mut colon_pos: Option<usize> = None;

            while i + 16 <= len {
                let chunk = vld1q_u8(buf.as_ptr().add(i));
                let has_cr = vmaxvq_u8(vceqq_u8(chunk, v_cr)) != 0;
                let has_lf = vmaxvq_u8(vceqq_u8(chunk, v_lf)) != 0;
                let has_nul = vmaxvq_u8(vceqq_u8(chunk, v_nul)) != 0;

                if colon_pos.is_none() {
                    let has_colon = vmaxvq_u8(vceqq_u8(chunk, v_colon)) != 0;
                    if !has_cr && !has_lf && !has_nul && !has_colon {
                        // No interesting bytes — SIMD TCHAR check for all 16.
                        if !crate::tchar::Neon::all16(buf.as_ptr().add(i)) {
                            return Err(ParseErrorKind::MalformedHeader);
                        }
                        i += 16;
                        continue;
                    }

                    // Interesting bytes in this chunk — scan inline to find
                    // the colon (and possibly CR+LF) within the 16-byte
                    // window, then continue SIMD on subsequent chunks.
                    let chunk_end = i + 16;
                    let mut j = i;

                    // Phase 1: find the colon within this chunk.
                    // Use SIMD TCHAR to bulk-validate all 16 bytes, then
                    // only the scalar loop needs to find the colon position.
                    if has_colon {
                        // Validate name bytes before colon via SIMD.
                        // is_all_tchar checks all 16 bytes; we only care about
                        // bytes before the colon. Since we'll find the colon
                        // position below and non-TCHAR bytes after it (value
                        // bytes, the colon itself) are fine, we fall back to
                        // scalar for the colon-finding loop but skip the
                        // per-byte TCHAR check — we know all pre-colon bytes
                        // that are in [name] were validated by the SIMD pass.
                        while j < chunk_end {
                            let b = *buf.get_unchecked(j);
                            if b == HttpChar::Colon {
                                if j == 0 {
                                    return Err(ParseErrorKind::MalformedHeader);
                                }
                                // Validate that all bytes before the colon are TCHAR.
                                // Re-check via SIMD — the chunk is still hot in L1.
                                if !crate::tchar::Neon::all16(buf.as_ptr().add(i)) {
                                    // At least one non-TCHAR in this chunk. Check
                                    // if the bad byte is actually before the colon.
                                    let colon_off = j - i;
                                    for k in i..j {
                                        if !crate::tchar::TABLE[*buf.get_unchecked(k) as usize] {
                                            return Err(ParseErrorKind::MalformedHeader);
                                        }
                                    }
                                    // Bad byte was after colon — that's fine for
                                    // value bytes.
                                    let _ = colon_off;
                                }
                                colon_pos = Some(j);
                                j += 1;
                                break;
                            }
                            j += 1;
                        }
                    } else {
                        // No colon but has CR/LF/NUL — all are invalid
                        // before the colon.
                        return Err(ParseErrorKind::MalformedHeader);
                    }

                    // Phase 2: scan value bytes in the rest of this chunk.
                    // SIMD `has_colon` plus the phase-1 loop guarantees
                    // `colon_pos` is `Some` here; the scalar tail handles
                    // the SIMD/scalar disagreement case.
                    let Some(colon) = colon_pos else {
                        return scan_header_line_scalar(buf, i, colon_pos);
                    };
                    while j < chunk_end {
                        let b = *buf.get_unchecked(j);
                        if b == HttpChar::CarriageReturn {
                            if j + 1 < len && *buf.get_unchecked(j + 1) == HttpChar::LineFeed {
                                return Ok(HeaderLineSpan { colon, line_end: j });
                            }
                            return Err(ParseErrorKind::MalformedHeader);
                        }
                        if b == HttpChar::LineFeed || b == HttpChar::Null {
                            return Err(ParseErrorKind::MalformedHeader);
                        }
                        j += 1;
                    }

                    i = chunk_end;
                    continue;
                }

                // Already have colon — scanning value bytes.
                if has_cr || has_lf || has_nul {
                    let Some(colon) = colon_pos else {
                        return scan_header_line_scalar(buf, i, colon_pos);
                    };
                    // Scan the 16-byte window to find exact CR position.
                    for j in i..i + 16 {
                        let b = *buf.get_unchecked(j);
                        if b == HttpChar::CarriageReturn {
                            if j + 1 < len && *buf.get_unchecked(j + 1) == HttpChar::LineFeed {
                                return Ok(HeaderLineSpan { colon, line_end: j });
                            }
                            return Err(ParseErrorKind::MalformedHeader);
                        }
                        if b == HttpChar::LineFeed || b == HttpChar::Null {
                            return Err(ParseErrorKind::MalformedHeader);
                        }
                    }
                    // vmaxvq_u8 detected a match, so we must have found it
                    // and returned/errored above. If we reach here, there is
                    // a disagreement between NEON and scalar — a logic bug.
                    debug_assert!(
                        false,
                        "NEON vmaxvq_u8 detected CR/LF/NUL but scalar scan did not find it at offset {i}"
                    );
                    return scan_header_line_scalar(buf, i, colon_pos);
                }

                i += 16;
            }

            scan_header_line_scalar(buf, i, colon_pos)
        }
    }
}

#[cfg(all(target_arch = "wasm32", target_feature = "simd128"))]
#[allow(clippy::cast_sign_loss)]
mod wasm_simd {
    crate::simd::define_simd_primitives!();

    use super::{HeaderLineSpan, ParseErrorKind, scan_header_line_scalar};
    use crate::ascii::HttpChar;
    use crate::tchar::{TcharCheck, WasmSimd};

    impl_bitmask_scan_header_line!(WasmSimd);
}

/// Fused single-pass header line scanner. Finds both the colon (`:`) and
/// the `\r\n` terminator while validating:
///   - Header name bytes (before colon) are valid TCHAR
///   - Header value bytes (after colon) contain no NUL, bare CR, or bare LF
///   - The colon is not at position 0 (empty header name)
///
/// Dispatches to SSE2, NEON, wasm SIMD, or pure scalar depending on target.
#[inline]
pub fn scan_header_line(buf: &[u8]) -> Result<HeaderLineSpan, ParseErrorKind> {
    #[cfg(target_arch = "x86_64")]
    {
        // Runtime AVX2 → SSSE3 → SSE2 dispatch. std caches the
        // detection result internally after the first invocation, so
        // each subsequent call is one atomic load + a well-predicted
        // branch. AVX2 implies SSSE3, so the three-way ladder
        // collapses to two branches in practice.
        if crate::tchar::has_avx2() {
            // Safety: AVX2 confirmed available.
            unsafe { avx2_mod::scan_header_line_avx2(buf) }
        } else if crate::tchar::has_ssse3() {
            // Safety: SSSE3 confirmed available.
            unsafe { sse2_ssse3::scan_header_line_ssse3(buf) }
        } else {
            // Safety: SSE2 baseline is guaranteed on x86_64.
            unsafe { sse2_scalar::scan_header_line(buf) }
        }
    }
    #[cfg(target_arch = "aarch64")]
    {
        neon::scan_header_line(buf)
    }
    #[cfg(all(target_arch = "wasm32", target_feature = "simd128"))]
    {
        wasm_simd::scan_header_line(buf)
    }
    #[cfg(not(any(
        target_arch = "x86_64",
        target_arch = "aarch64",
        all(target_arch = "wasm32", target_feature = "simd128")
    )))]
    {
        scan_header_line_scalar(buf, 0, None)
    }
}

// ---------------------------------------------------------------------------
// Tests
// ---------------------------------------------------------------------------

#[cfg(test)]
mod tests {
    use super::*;

    // -- Basic scanning ------------------------------------------------------

    #[test]
    fn simple_header_line() {
        let span = scan_header_line(b"Host: localhost\r\n").unwrap();
        assert_eq!(span.colon, 4);
        assert_eq!(span.line_end, 15);
    }

    #[test]
    fn header_with_no_value() {
        let span = scan_header_line(b"X-Empty:\r\n").unwrap();
        assert_eq!(span.colon, 7);
        assert_eq!(span.line_end, 8);
    }

    #[test]
    fn header_with_spaces_in_value() {
        let span = scan_header_line(b"Content-Type: text/html; charset=utf-8\r\n").unwrap();
        assert_eq!(span.colon, 12);
        assert_eq!(span.line_end, 38);
    }

    #[test]
    fn header_with_colon_in_value() {
        let span = scan_header_line(b"X-Url: http://example.com:8080\r\n").unwrap();
        assert_eq!(span.colon, 5);
        assert_eq!(span.line_end, 30);
    }

    // -- SIMD boundary cases -------------------------------------------------

    #[test]
    fn colon_at_simd_boundary() {
        // Header name exactly 15 bytes, colon at position 15
        let span = scan_header_line(b"X-Long-Name-Hdr: val\r\n").unwrap();
        assert_eq!(span.colon, 15);
    }

    #[test]
    fn crlf_at_simd_boundary() {
        // Build a header where \r\n lands at positions 15-16
        let buf = b"X-H: 0123456789\r\n";
        let span = scan_header_line(buf).unwrap();
        assert_eq!(span.line_end, 15);
    }

    #[test]
    fn header_spanning_two_simd_chunks() {
        // >32 bytes to exercise two full SIMD chunks + scalar tail
        let buf = b"X-Very-Long-Header-Name-Here: some-value-that-is-long\r\n";
        let span = scan_header_line(buf).unwrap();
        assert_eq!(span.colon, 28);
        assert_eq!(span.line_end, 53);
    }

    #[test]
    fn short_header_in_scalar_path() {
        let span = scan_header_line(b"A: b\r\n").unwrap();
        assert_eq!(span.colon, 1);
        assert_eq!(span.line_end, 4);
    }

    // -- Error cases ---------------------------------------------------------

    #[test]
    fn rejects_empty_header_name() {
        let err = scan_header_line(b": value\r\n").unwrap_err();
        assert_eq!(err, ParseErrorKind::MalformedHeader);
    }

    #[test]
    fn rejects_no_colon() {
        let err = scan_header_line(b"NoColonHere\r\n").unwrap_err();
        assert_eq!(err, ParseErrorKind::MalformedHeader);
    }

    #[test]
    fn rejects_space_in_header_name() {
        let err = scan_header_line(b"Bad Name: val\r\n").unwrap_err();
        assert_eq!(err, ParseErrorKind::MalformedHeader);
    }

    #[test]
    fn rejects_nul_in_value() {
        let err = scan_header_line(b"X: val\x00ue\r\n").unwrap_err();
        assert_eq!(err, ParseErrorKind::MalformedHeader);
    }

    #[test]
    fn rejects_bare_lf_in_value() {
        let err = scan_header_line(b"X: val\nue\r\n").unwrap_err();
        assert_eq!(err, ParseErrorKind::MalformedHeader);
    }

    #[test]
    fn rejects_bare_cr_in_value() {
        let err = scan_header_line(b"X: val\rue\r\n").unwrap_err();
        assert_eq!(err, ParseErrorKind::MalformedHeader);
    }

    #[test]
    fn rejects_missing_lf_after_cr() {
        let err = scan_header_line(b"X: value\rX").unwrap_err();
        assert_eq!(err, ParseErrorKind::MalformedHeader);
    }

    #[test]
    fn rejects_no_terminator() {
        let err = scan_header_line(b"X: value").unwrap_err();
        assert_eq!(err, ParseErrorKind::MalformedHeader);
    }

    #[test]
    fn rejects_control_char_in_name() {
        let err = scan_header_line(b"X\x01Y: val\r\n").unwrap_err();
        assert_eq!(err, ParseErrorKind::MalformedHeader);
    }

    // -- obs-fold handling ----------------------------------------------------

    #[test]
    fn terminates_at_first_crlf() {
        // scan_header_line terminates at the first \r\n — obs-fold
        // rejection is handled by the caller (parse_headers).
        let span = scan_header_line(b"X: first\r\n second\r\n").unwrap();
        assert_eq!(span.colon, 1);
        assert_eq!(span.line_end, 8);
    }
}