form_net/multipart/

parser.rs

//! The sans-IO multipart parser: a state machine over the delimiter matcher
//! and the header reader.

use core::fmt;

use crate::error::{EncodingError, FormError, Limit, Location, PolicyRefusal, SyntaxError};
use crate::limits::{CHARSET_CAPTURE, EmptyFilePolicy, Limits, Policy, TokenPlacement};
use crate::multipart::boundary::{Boundary, Hit};
use crate::multipart::filename::FileName;
use crate::multipart::header::{Areas, BlockScan, HeadFacts, Text, read_block};

/// Whether a part is a text field or a file.
///
/// # Examples
///
/// ```
/// # let body = b"--X\r\nContent-Disposition: form-data; name=a\r\n\r\n1\r\n--X--";
/// let mp = form_net::parse_multipart(b"multipart/form-data; boundary=X", body)?;
/// assert_eq!(mp.parts()[0].kind(), form_net::PartKind::Field);
/// # Ok::<(), form_net::FormError>(())
/// ```
#[non_exhaustive]
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub enum PartKind {
    /// A text field: no `filename` parameter.
    Field,
    /// A file: a `filename` parameter (even an empty one) or an accepted
    /// `filename*`.
    File,
}

/// The `charset` a part declared.
///
/// `Unspecified` means no `charset` parameter: UTF-8 is assumed unless a
/// `_charset_` field before the part said otherwise. `Other` is any label
/// that is not UTF-8 or US-ASCII; its text is refused by every text accessor.
///
/// # Examples
///
/// ```
/// use form_net::Charset;
///
/// # let body = b"--X\r\nContent-Disposition: form-data; name=a\r\nContent-Type: text/plain; charset=UTF-8\r\n\r\n1\r\n--X--";
/// # let mp = form_net::parse_multipart(b"multipart/form-data; boundary=X", body)?;
/// assert_eq!(mp.parts()[0].content_type().unwrap().charset(), Charset::Utf8);
/// # Ok::<(), form_net::FormError>(())
/// ```
#[non_exhaustive]
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub enum Charset {
    /// `utf-8`.
    Utf8,
    /// `us-ascii`.
    Ascii,
    /// No `charset` parameter.
    Unspecified,
    /// Any other label.
    Other,
}

/// How a text value is read, from its charset label.
#[cfg(feature = "alloc")]
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub(crate) enum TextRule {
    /// UTF-8 (no label, or `utf-8`).
    Utf8,
    /// `us-ascii`: every byte below 0x80. WHATWG readers decode the label as
    /// windows-1252, so a higher byte would read differently there (D-150).
    Ascii,
    /// Any other label.
    Refuse,
}

#[cfg(feature = "alloc")]
impl TextRule {
    /// Checks `bytes` against the rule, then as UTF-8.
    pub(crate) fn check(self, bytes: &[u8]) -> Result<(), EncodingError> {
        match self {
            TextRule::Refuse => Err(EncodingError::UnsupportedCharset),
            TextRule::Ascii if !bytes.is_ascii() => Err(EncodingError::UnsupportedCharset),
            _ if core::str::from_utf8(bytes).is_err() => Err(EncodingError::InvalidUtf8),
            _ => Ok(()),
        }
    }
}

/// The rule a declared `_charset_` value sets for the text after it.
#[cfg(feature = "alloc")]
pub(crate) fn declared_rule(declared: Option<&[u8]>) -> TextRule {
    match declared {
        None => TextRule::Utf8,
        Some(label) => match Charset::from_label(label) {
            Charset::Utf8 => TextRule::Utf8,
            Charset::Ascii => TextRule::Ascii,
            _ => TextRule::Refuse,
        },
    }
}

impl Charset {
    /// How a text part with this charset is read: by its own label, else by
    /// the `_charset_` declared before it, else as UTF-8.
    #[cfg(feature = "alloc")]
    pub(crate) const fn rule(self, declared: TextRule) -> TextRule {
        match self {
            Charset::Utf8 => TextRule::Utf8,
            Charset::Ascii => TextRule::Ascii,
            Charset::Other => TextRule::Refuse,
            Charset::Unspecified => declared,
        }
    }

    pub(crate) fn from_label(label: &[u8]) -> Charset {
        if label.eq_ignore_ascii_case(b"utf-8") {
            Charset::Utf8
        } else if label.eq_ignore_ascii_case(b"us-ascii") {
            Charset::Ascii
        } else {
            Charset::Other
        }
    }
}

/// One step of the parser: how many input bytes it consumed, and what
/// happened.
///
/// # Examples
///
/// ```
/// # use form_net::{Boundary, Charset, Limits, MultipartEvent, MultipartParser, PartKind, Policy};
/// # let mut parser = MultipartParser::new(Boundary::new(b"X")?, &Limits::DEFAULT, &Policy::DEFAULT)?;
/// let body = b"--X\r\nContent-Disposition: form-data; name=a\r\n\r\n1\r\n--X--";
/// let step = parser.parse(body, true)?;
/// assert!(matches!(step.event, MultipartEvent::PartStart(_)));
/// // The rest of the body goes to the next call.
/// assert!(step.consumed > 0 && step.consumed < body.len());
/// # Ok::<(), form_net::FormError>(())
/// ```
#[non_exhaustive]
#[derive(Debug)]
pub struct MultipartStep<'p> {
    /// Bytes of the input consumed; pass the rest (and later new bytes) to
    /// the next call.
    pub consumed: usize,
    /// What happened.
    pub event: MultipartEvent<'p>,
}

/// What the parser found.
///
/// Per part the order is always `PartStart`, any number of `Data` (none for
/// an empty part), `PartEnd`. A `Data` slice is never empty. After the last
/// part comes `End`. `NeedInput` can appear anywhere between.
///
/// `Debug` prints the length of `Data`, never the bytes.
///
/// # Examples
///
/// ```
/// # use form_net::{Boundary, Charset, Limits, MultipartEvent, MultipartParser, PartKind, Policy};
/// # let mut parser = MultipartParser::new(Boundary::new(b"X")?, &Limits::DEFAULT, &Policy::DEFAULT)?;
/// let mut rest = &b"--X\r\nContent-Disposition: form-data; name=a\r\n\r\n12\r\n--X--"[..];
/// let mut seen = String::new();
/// loop {
///     let step = parser.parse(rest, true)?;
///     rest = &rest[step.consumed..];
///     match step.event {
///         MultipartEvent::PartStart(head) => seen.push_str(head.name()),
///         MultipartEvent::Data(bytes) => seen.push_str(&format!(" {}", bytes.len())),
///         MultipartEvent::PartEnd(_) => seen.push_str(" end"),
///         MultipartEvent::End | MultipartEvent::NeedInput => break,
///         _ => {}
///     }
/// }
/// assert_eq!(seen, "a 2 end");
/// # Ok::<(), form_net::FormError>(())
/// ```
#[non_exhaustive]
pub enum MultipartEvent<'p> {
    /// A part's headers were read and checked.
    PartStart(PartHead<'p>),
    /// Bytes of the current part's data.
    Data(&'p [u8]),
    /// The current part ended.
    PartEnd(PartSummary),
    /// The close delimiter was read: the form is complete.
    End,
    /// Every byte given was consumed; give more.
    NeedInput,
}

impl fmt::Debug for MultipartEvent<'_> {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        match self {
            Self::PartStart(head) => f.debug_tuple("PartStart").field(head).finish(),
            Self::Data(bytes) => write!(f, "Data({} bytes)", bytes.len()),
            Self::PartEnd(summary) => f.debug_tuple("PartEnd").field(summary).finish(),
            Self::End => f.write_str("End"),
            Self::NeedInput => f.write_str("NeedInput"),
        }
    }
}

/// What one part was.
///
/// # Examples
///
/// ```
/// # use form_net::{Boundary, Charset, Limits, MultipartEvent, MultipartParser, PartKind, Policy};
/// # let mut parser = MultipartParser::new(Boundary::new(b"X")?, &Limits::DEFAULT, &Policy::DEFAULT)?;
/// let mut rest = &b"--X\r\nContent-Disposition: form-data; name=a\r\n\r\nhello\r\n--X--"[..];
/// let summary = loop {
///     let step = parser.parse(rest, true)?;
///     rest = &rest[step.consumed..];
///     if let MultipartEvent::PartEnd(summary) = step.event {
///         break summary;
///     }
/// };
/// assert_eq!((summary.index, summary.bytes, summary.skipped), (0, 5, false));
/// assert_eq!(summary.kind, PartKind::Field);
/// # Ok::<(), form_net::FormError>(())
/// ```
#[non_exhaustive]
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub struct PartSummary {
    /// The part index, from 0.
    pub index: u32,
    /// Field or file.
    pub kind: PartKind,
    /// The length of the part's data.
    pub bytes: u64,
    /// Whether the part was skipped (by `skip_part` or an inspector).
    pub skipped: bool,
}

/// The validated header block of one part, borrowed.
///
/// A head is only produced after every header budget and rule passed.
///
/// # Examples
///
/// ```
/// # use form_net::{Boundary, Charset, Limits, MultipartEvent, MultipartParser, PartKind, Policy};
/// # let mut parser = MultipartParser::new(Boundary::new(b"X")?, &Limits::DEFAULT, &Policy::DEFAULT)?;
/// let body = b"--X\r\nContent-Disposition: form-data; name=doc; filename=a.pdf\r\nContent-Type: application/pdf\r\n\r\n%PDF\r\n--X--";
/// let MultipartEvent::PartStart(head) = parser.parse(body, true)?.event else { unreachable!() };
/// assert_eq!(head.name(), "doc");
/// assert!(head.is_file());
/// assert!(head.content_type().unwrap().is("application", "pdf"));
/// # Ok::<(), form_net::FormError>(())
/// ```
#[derive(Clone, Copy)]
pub struct PartHead<'p> {
    index: u32,
    block: &'p [u8],
    name: &'p str,
    name_raw: &'p [u8],
    kind: PartKind,
    filename: Option<FileName<'p>>,
    content_type: Option<&'p [u8]>,
    charset: Charset,
}

impl fmt::Debug for PartHead<'_> {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        f.debug_struct("PartHead")
            .field("index", &self.index)
            .field("name", &self.name)
            .field("kind", &self.kind)
            .field("filename", &self.filename)
            .finish_non_exhaustive()
    }
}

impl<'p> PartHead<'p> {
    /// A head over bytes kept elsewhere (an owned copy).
    #[cfg(feature = "alloc")]
    #[allow(clippy::too_many_arguments)]
    pub(crate) const fn from_parts(
        index: u32,
        block: &'p [u8],
        name: &'p str,
        name_raw: &'p [u8],
        kind: PartKind,
        filename: Option<FileName<'p>>,
        content_type: Option<&'p [u8]>,
        charset: Charset,
    ) -> Self {
        Self {
            index,
            block,
            name,
            name_raw,
            kind,
            filename,
            content_type,
            charset,
        }
    }

    /// The header block, the final CRLF CRLF included.
    #[cfg(feature = "alloc")]
    pub(crate) const fn block(&self) -> &'p [u8] {
        self.block
    }

    /// The part index, from 0, in body order.
    ///
    /// # Examples
    ///
    /// ```
    /// # use form_net::{Boundary, Charset, Limits, MultipartEvent, MultipartParser, PartKind, Policy};
    /// # let mut parser = MultipartParser::new(Boundary::new(b"X")?, &Limits::DEFAULT, &Policy::DEFAULT)?;
    /// # let body = b"--X\r\nContent-Disposition: form-data; name=a\r\n\r\n1\r\n--X--";
    /// let MultipartEvent::PartStart(head) = parser.parse(body, true)?.event else { unreachable!() };
    /// assert_eq!(head.index(), 0);
    /// # Ok::<(), form_net::FormError>(())
    /// ```
    #[must_use]
    pub const fn index(&self) -> u32 {
        self.index
    }

    /// The field name, with `%0A`, `%0D`, `%22` decoded to LF, CR, `"` (no
    /// other escape is decoded). Always valid UTF-8 and never empty.
    ///
    /// # Examples
    ///
    /// ```
    /// # use form_net::{Boundary, Charset, Limits, MultipartEvent, MultipartParser, PartKind, Policy};
    /// # let mut parser = MultipartParser::new(Boundary::new(b"X")?, &Limits::DEFAULT, &Policy::DEFAULT)?;
    /// # let body = b"--X\r\nContent-Disposition: form-data; name=\"a%22b\"\r\n\r\n1\r\n--X--";
    /// let MultipartEvent::PartStart(head) = parser.parse(body, true)?.event else { unreachable!() };
    /// assert_eq!(head.name(), "a\"b");
    /// # Ok::<(), form_net::FormError>(())
    /// ```
    #[must_use]
    pub const fn name(&self) -> &'p str {
        self.name
    }

    /// The field name as sent.
    ///
    /// # Examples
    ///
    /// ```
    /// # use form_net::{Boundary, Charset, Limits, MultipartEvent, MultipartParser, PartKind, Policy};
    /// # let mut parser = MultipartParser::new(Boundary::new(b"X")?, &Limits::DEFAULT, &Policy::DEFAULT)?;
    /// # let body = b"--X\r\nContent-Disposition: form-data; name=\"a%22b\"\r\n\r\n1\r\n--X--";
    /// let MultipartEvent::PartStart(head) = parser.parse(body, true)?.event else { unreachable!() };
    /// assert_eq!(head.name_raw(), b"a%22b");
    /// # Ok::<(), form_net::FormError>(())
    /// ```
    #[must_use]
    pub const fn name_raw(&self) -> &'p [u8] {
        self.name_raw
    }

    /// Field or file.
    ///
    /// # Examples
    ///
    /// ```
    /// # use form_net::{Boundary, Charset, Limits, MultipartEvent, MultipartParser, PartKind, Policy};
    /// # let mut parser = MultipartParser::new(Boundary::new(b"X")?, &Limits::DEFAULT, &Policy::DEFAULT)?;
    /// # let body = b"--X\r\nContent-Disposition: form-data; name=f; filename=a.txt\r\n\r\nhi\r\n--X--";
    /// let MultipartEvent::PartStart(head) = parser.parse(body, true)?.event else { unreachable!() };
    /// assert_eq!(head.kind(), PartKind::File);
    /// # Ok::<(), form_net::FormError>(())
    /// ```
    #[must_use]
    pub const fn kind(&self) -> PartKind {
        self.kind
    }

    /// Whether this is a file part.
    ///
    /// # Examples
    ///
    /// ```
    /// # use form_net::{Boundary, Charset, Limits, MultipartEvent, MultipartParser, PartKind, Policy};
    /// # let mut parser = MultipartParser::new(Boundary::new(b"X")?, &Limits::DEFAULT, &Policy::DEFAULT)?;
    /// # let body = b"--X\r\nContent-Disposition: form-data; name=a\r\n\r\n1\r\n--X--";
    /// let MultipartEvent::PartStart(head) = parser.parse(body, true)?.event else { unreachable!() };
    /// assert!(!head.is_file());
    /// # Ok::<(), form_net::FormError>(())
    /// ```
    #[must_use]
    pub const fn is_file(&self) -> bool {
        matches!(self.kind, PartKind::File)
    }

    /// The client's file name, for file parts.
    ///
    /// # Examples
    ///
    /// ```
    /// # use form_net::{Boundary, Charset, Limits, MultipartEvent, MultipartParser, PartKind, Policy};
    /// # let mut parser = MultipartParser::new(Boundary::new(b"X")?, &Limits::DEFAULT, &Policy::DEFAULT)?;
    /// # let body = b"--X\r\nContent-Disposition: form-data; name=f; filename=a.txt\r\n\r\nhi\r\n--X--";
    /// let MultipartEvent::PartStart(head) = parser.parse(body, true)?.event else { unreachable!() };
    /// assert_eq!(head.filename().unwrap().raw(), b"a.txt");
    /// # Ok::<(), form_net::FormError>(())
    /// ```
    #[must_use]
    pub const fn filename(&self) -> Option<FileName<'p>> {
        self.filename
    }

    /// The declared `Content-Type`: a hint, never trusted.
    ///
    /// # Examples
    ///
    /// ```
    /// # use form_net::{Boundary, Charset, Limits, MultipartEvent, MultipartParser, PartKind, Policy};
    /// # let mut parser = MultipartParser::new(Boundary::new(b"X")?, &Limits::DEFAULT, &Policy::DEFAULT)?;
    /// # let body = b"--X\r\nContent-Disposition: form-data; name=a\r\nContent-Type: text/plain\r\n\r\n1\r\n--X--";
    /// let MultipartEvent::PartStart(head) = parser.parse(body, true)?.event else { unreachable!() };
    /// assert!(head.content_type().unwrap().is("text", "plain"));
    /// # Ok::<(), form_net::FormError>(())
    /// ```
    #[must_use]
    pub fn content_type(&self) -> Option<ContentType<'p>> {
        self.content_type.and_then(ContentType::parse)
    }

    /// The part's own `charset` parameter (`Unspecified` when absent).
    ///
    /// # Examples
    ///
    /// ```
    /// # use form_net::{Boundary, Charset, Limits, MultipartEvent, MultipartParser, PartKind, Policy};
    /// # let mut parser = MultipartParser::new(Boundary::new(b"X")?, &Limits::DEFAULT, &Policy::DEFAULT)?;
    /// # let body = b"--X\r\nContent-Disposition: form-data; name=a\r\nContent-Type: text/plain; charset=us-ascii\r\n\r\n1\r\n--X--";
    /// let MultipartEvent::PartStart(head) = parser.parse(body, true)?.event else { unreachable!() };
    /// assert_eq!(head.charset(), Charset::Ascii);
    /// # Ok::<(), form_net::FormError>(())
    /// ```
    #[must_use]
    pub const fn charset(&self) -> Charset {
        self.charset
    }

    /// Every header line, in order, as raw `(name, value)` bytes.
    ///
    /// # Examples
    ///
    /// ```
    /// # use form_net::{Boundary, Charset, Limits, MultipartEvent, MultipartParser, PartKind, Policy};
    /// # let mut parser = MultipartParser::new(Boundary::new(b"X")?, &Limits::DEFAULT, &Policy::DEFAULT)?;
    /// # let body = b"--X\r\nContent-Disposition: form-data; name=a\r\nContent-Type: text/plain\r\n\r\n1\r\n--X--";
    /// let MultipartEvent::PartStart(head) = parser.parse(body, true)?.event else { unreachable!() };
    /// let (name, value) = head.headers().nth(1).unwrap();
    /// assert_eq!((name, value), (&b"Content-Type"[..], &b"text/plain"[..]));
    /// # Ok::<(), form_net::FormError>(())
    /// ```
    #[must_use]
    pub fn headers(&self) -> Headers<'p> {
        Headers { rest: self.block }
    }

    /// The size of the header block, the final CRLF CRLF included.
    ///
    /// # Examples
    ///
    /// ```
    /// # use form_net::{Boundary, Charset, Limits, MultipartEvent, MultipartParser, PartKind, Policy};
    /// # let mut parser = MultipartParser::new(Boundary::new(b"X")?, &Limits::DEFAULT, &Policy::DEFAULT)?;
    /// # let body = b"--X\r\nContent-Disposition: form-data; name=a\r\n\r\n1\r\n--X--";
    /// let MultipartEvent::PartStart(head) = parser.parse(body, true)?.event else { unreachable!() };
    /// // The block ends with the blank line.
    /// let block = "Content-Disposition: form-data; name=a\r\n\r\n";
    /// assert_eq!(head.header_bytes() as usize, block.len());
    /// # Ok::<(), form_net::FormError>(())
    /// ```
    #[must_use]
    pub const fn header_bytes(&self) -> u32 {
        self.block.len() as u32
    }
}

/// A part's declared `Content-Type`, already checked. **A hint**: the client
/// chose it.
///
/// # Examples
///
/// ```
/// # let body = b"--X\r\nContent-Disposition: form-data; name=f; filename=a.png\r\nContent-Type: Image/PNG; q=\"x y\"\r\n\r\n\r\n--X--";
/// # let mp = form_net::parse_multipart(b"multipart/form-data; boundary=X", body)?;
/// let ct = mp.file("f").unwrap().content_type().unwrap();
/// assert!(ct.is("image", "png"));
/// assert_eq!((ct.type_(), ct.subtype()), ("Image", "PNG"));
/// assert_eq!(ct.parameter("Q"), Some(&b"x y"[..]));
/// # Ok::<(), form_net::FormError>(())
/// ```
#[derive(Clone, Copy)]
pub struct ContentType<'p> {
    raw: &'p [u8],
    media: parse_net::MediaType<'p>,
}

impl fmt::Debug for ContentType<'_> {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        f.debug_struct("ContentType")
            .field("type", &self.type_())
            .field("subtype", &self.subtype())
            .finish_non_exhaustive()
    }
}

impl<'p> ContentType<'p> {
    pub(crate) fn parse(raw: &'p [u8]) -> Option<ContentType<'p>> {
        parse_net::media::parse(raw, &crate::kind::HEADER_LIMITS)
            .ok()
            .map(|media| ContentType { raw, media })
    }

    /// The value as sent.
    ///
    /// # Examples
    ///
    /// ```
    /// # let body = b"--X\r\nContent-Disposition: form-data; name=a\r\nContent-Type: text/plain; charset=utf-8\r\n\r\n1\r\n--X--";
    /// # let mp = form_net::parse_multipart(b"multipart/form-data; boundary=X", body)?;
    /// let ct = mp.parts()[0].content_type().unwrap();
    /// assert_eq!(ct.raw(), b"text/plain; charset=utf-8");
    /// # Ok::<(), form_net::FormError>(())
    /// ```
    #[must_use]
    pub const fn raw(&self) -> &'p [u8] {
        self.raw
    }

    /// The type, as sent.
    ///
    /// # Examples
    ///
    /// ```
    /// # let body = b"--X\r\nContent-Disposition: form-data; name=a\r\nContent-Type: text/plain; charset=utf-8\r\n\r\n1\r\n--X--";
    /// # let mp = form_net::parse_multipart(b"multipart/form-data; boundary=X", body)?;
    /// let ct = mp.parts()[0].content_type().unwrap();
    /// assert_eq!(ct.type_(), "text");
    /// # Ok::<(), form_net::FormError>(())
    /// ```
    #[must_use]
    pub fn type_(&self) -> &'p str {
        core::str::from_utf8(self.media.type_()).unwrap_or("")
    }

    /// The subtype, as sent.
    ///
    /// # Examples
    ///
    /// ```
    /// # let body = b"--X\r\nContent-Disposition: form-data; name=a\r\nContent-Type: text/plain; charset=utf-8\r\n\r\n1\r\n--X--";
    /// # let mp = form_net::parse_multipart(b"multipart/form-data; boundary=X", body)?;
    /// let ct = mp.parts()[0].content_type().unwrap();
    /// assert_eq!(ct.subtype(), "plain");
    /// # Ok::<(), form_net::FormError>(())
    /// ```
    #[must_use]
    pub fn subtype(&self) -> &'p str {
        core::str::from_utf8(self.media.subtype()).unwrap_or("")
    }

    /// Whether the type and subtype are these, ASCII case-insensitively.
    ///
    /// # Examples
    ///
    /// ```
    /// # let body = b"--X\r\nContent-Disposition: form-data; name=a\r\nContent-Type: text/plain; charset=utf-8\r\n\r\n1\r\n--X--";
    /// # let mp = form_net::parse_multipart(b"multipart/form-data; boundary=X", body)?;
    /// let ct = mp.parts()[0].content_type().unwrap();
    /// assert!(ct.is("TEXT", "Plain"));
    /// assert!(!ct.is("text", "html"));
    /// # Ok::<(), form_net::FormError>(())
    /// ```
    #[must_use]
    pub fn is(&self, type_: &str, subtype: &str) -> bool {
        self.media.is(type_, subtype)
    }

    /// A parameter's value by name (ASCII case-insensitive), without
    /// surrounding quotes; backslashes are literal, as browsers send them.
    ///
    /// # Examples
    ///
    /// ```
    /// # let body = b"--X\r\nContent-Disposition: form-data; name=a\r\nContent-Type: text/plain; charset=utf-8\r\n\r\n1\r\n--X--";
    /// # let mp = form_net::parse_multipart(b"multipart/form-data; boundary=X", body)?;
    /// let ct = mp.parts()[0].content_type().unwrap();
    /// assert_eq!(ct.parameter("Charset"), Some(&b"utf-8"[..]));
    /// assert_eq!(ct.parameter("boundary"), None);
    /// # Ok::<(), form_net::FormError>(())
    /// ```
    #[must_use]
    pub fn parameter(&self, name: &str) -> Option<&'p [u8]> {
        self.media
            .params()
            .get(name)
            .map(|w| crate::kind::word_raw(&w))
    }

    /// The `charset` parameter.
    ///
    /// # Examples
    ///
    /// ```
    /// use form_net::Charset;
    ///
    /// # let body = b"--X\r\nContent-Disposition: form-data; name=a\r\nContent-Type: text/plain; charset=utf-8\r\n\r\n1\r\n--X--";
    /// # let mp = form_net::parse_multipart(b"multipart/form-data; boundary=X", body)?;
    /// let ct = mp.parts()[0].content_type().unwrap();
    /// assert_eq!(ct.charset(), Charset::Utf8);
    /// # Ok::<(), form_net::FormError>(())
    /// ```
    #[must_use]
    pub fn charset(&self) -> Charset {
        self.parameter("charset")
            .map_or(Charset::Unspecified, Charset::from_label)
    }
}

/// Every header line of a part, in order, as raw `(name, value)` bytes with
/// the value trimmed.
///
/// `Debug` prints the header names only: values carry file names.
///
/// # Examples
///
/// ```
/// # use form_net::{Boundary, Charset, Limits, MultipartEvent, MultipartParser, PartKind, Policy};
/// # let mut parser = MultipartParser::new(Boundary::new(b"X")?, &Limits::DEFAULT, &Policy::DEFAULT)?;
/// # let body = b"--X\r\nContent-Disposition: form-data; name=a\r\nContent-Type: text/plain\r\n\r\n1\r\n--X--";
/// let MultipartEvent::PartStart(head) = parser.parse(body, true)?.event else { unreachable!() };
/// let names: Vec<&[u8]> = head.headers().map(|(name, _)| name).collect();
/// assert_eq!(names, [&b"Content-Disposition"[..], &b"Content-Type"[..]]);
/// # Ok::<(), form_net::FormError>(())
/// ```
#[derive(Clone)]
pub struct Headers<'p> {
    rest: &'p [u8],
}

impl fmt::Debug for Headers<'_> {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        let mut list = f.debug_list();
        for (name, _) in self.clone() {
            list.entry(&core::str::from_utf8(name).unwrap_or("?"));
        }
        list.finish()
    }
}

impl<'p> Iterator for Headers<'p> {
    type Item = (&'p [u8], &'p [u8]);

    fn next(&mut self) -> Option<Self::Item> {
        let lf = self.rest.iter().position(|&b| b == b'\n')?;
        let line = self.rest.get(..lf.saturating_sub(1)).unwrap_or(&[]);
        self.rest = self.rest.get(lf.wrapping_add(1)..).unwrap_or(&[]);
        if line.is_empty() {
            self.rest = &[];
            return None;
        }
        let colon = line.iter().position(|&b| b == b':').unwrap_or(line.len());
        let name = line.get(..colon).unwrap_or(&[]);
        let value = line.get(colon.wrapping_add(1)..).unwrap_or(&[]);
        Some((name, parse_net::text::trim_ows(value)))
    }
}

#[derive(Clone, Copy, Debug, PartialEq, Eq)]
enum State {
    Preamble,
    /// After a delimiter: expecting `--`, padding, or CRLF.
    AfterDelimiter(After),
    Headers,
    Body,
    /// The delimiter that ends the current part was found; `PartEnd` is due.
    EndOfPart,
    Epilogue,
    Poisoned,
}

#[derive(Clone, Copy, Debug, PartialEq, Eq)]
enum After {
    Start,
    Dash,
    Padding(u8),
    Cr,
}

/// The token field's progress.
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
enum Token {
    NotSeen,
    Capturing,
    Captured,
}

const SKIPPING: u8 = 1;
const IS_TOKEN: u8 = 2;
const IS_CHARSET: u8 = 4;
const DEFERRED: u8 = 8;

/// Where a head's block is.
#[derive(Clone, Copy, Debug)]
pub(crate) enum Source {
    /// In the input, from this index.
    Input(usize),
    /// In the parser buffer, from 0.
    Buffer,
}

/// What a call to `advance` produced, as positions only.
#[derive(Clone, Copy, Debug)]
pub(crate) enum Outcome {
    PartStart(HeadFacts, Source),
    /// `input[start..end]`.
    DataInput(usize, usize),
    /// The first bytes of the delimiter.
    DataDelimiter(usize),
    PartEnd(PartSummary),
    End,
    NeedInput,
}

/// The sans-IO `multipart/form-data` parser.
///
/// Feed it bytes as they arrive, in chunks of any size split at any byte;
/// it returns one [`MultipartEvent`] per call and how many bytes it consumed. The
/// events are identical for every split of a body that parses; for a body
/// that fails, the error is identical, though a split body may emit data
/// before it that a whole one does not. It never allocates after
/// construction. The delimiter search skips 32 bytes at a time to a line
/// break followed by `-` and compares the delimiter there a word at a time;
/// bytes that may start a delimiter at a chunk's end are carried and
/// scanned again with the next chunk (at most 73 per boundary), so the
/// search stays linear. The streaming automaton (a Knuth-Morris-Pratt
/// table) only carries that state between chunks.
///
/// The buffer holds the header block, the decoded field name, the decoded
/// `filename*` (under `AcceptAlone`), the token, and the `_charset_` value:
/// [`Limits::multipart_buffer_len`] bytes. It is wiped on `reset` and on
/// drop.
///
/// # Examples
///
/// ```
/// use form_net::{MultipartEvent, FormKind, Limits, MultipartParser, Policy};
///
/// let content_type = b"multipart/form-data; boundary=X";
/// let body = b"--X\r\nContent-Disposition: form-data; name=\"title\"\r\n\r\nHoliday\r\n--X--\r\n";
/// let FormKind::Multipart(boundary) = FormKind::detect(content_type)? else { unreachable!() };
/// let mut parser = MultipartParser::new(boundary, &Limits::DEFAULT, &Policy::DEFAULT)?;
///
/// let mut events = Vec::new();
/// let mut chunks = body.chunks(7).peekable();     // any split gives the same events
/// while let Some(chunk) = chunks.next() {
///     let last = chunks.peek().is_none();
///     let mut rest = chunk;
///     loop {
///         let step = parser.parse(rest, last)?;
///         rest = &rest[step.consumed..];
///         match step.event {
///             MultipartEvent::PartStart(head) => events.push(format!("start {}", head.name())),
///             MultipartEvent::Data(bytes) => events.push(format!("data {}", bytes.len())),
///             MultipartEvent::PartEnd(summary) => events.push(format!("end {}", summary.bytes)),
///             MultipartEvent::End => break,
///             MultipartEvent::NeedInput => break,
///             _ => {}
///         }
///     }
/// }
/// assert!(parser.is_done());
/// assert_eq!(events.first().map(String::as_str), Some("start title"));
/// assert_eq!(events.last().map(String::as_str), Some("end 7"));
/// # Ok::<(), form_net::FormError>(())
/// ```
pub struct MultipartParser<B: AsMut<[u8]> + AsRef<[u8]>> {
    boundary: Boundary,
    limits: Limits,
    policy: Policy,
    buffer: B,
    state: State,
    /// Delimiter bytes matched and not yet known to be data.
    k: u8,
    /// Bytes of a lone CR or LF and `--boundary` matched (D-113); while
    /// `k > 0` it follows from `k`.
    bare: u8,
    flags: u8,
    token: Token,
    token_len: u16,
    charset_len: u8,
    charset_done: bool,
    scan: BlockScan,
    /// Header bytes copied into the buffer.
    copied: u32,
    /// The longest header block read so far: every byte the parser writes
    /// into the header, name, and file-name areas lies within this many
    /// bytes of each area's start (decoding never lengthens), so the wipe
    /// covers exactly what was written (D-103).
    dirty: u32,
    parts: u32,
    files: u32,
    fields: u32,
    kind: PartKind,
    part_bytes: u64,
    text_total: u64,
    data_start: u64,
    preamble: u64,
    epilogue: u64,
    /// Where the current header block starts in the body.
    head_start: u64,
    /// Where the epilogue starts in the body.
    epilogue_start: u64,
    bytes_seen: u64,
}

impl<B: AsMut<[u8]> + AsRef<[u8]>> fmt::Debug for MultipartParser<B> {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        f.debug_struct("MultipartParser")
            .field("boundary", &self.boundary)
            .field("state", &self.state)
            .field("bytes_seen", &self.bytes_seen)
            .field("parts_seen", &self.parts)
            .finish_non_exhaustive()
    }
}

#[cfg(feature = "alloc")]
impl MultipartParser<alloc::vec::Vec<u8>> {
    /// A parser with its own buffer of
    /// [`Limits::multipart_buffer_len`] bytes, allocated once.
    ///
    /// # Errors
    ///
    /// `InvalidLimits` from validating the limits with the policy.
    ///
    /// # Examples
    ///
    /// ```
    /// use form_net::{Boundary, Limits, MultipartParser, Policy};
    ///
    /// let parser = MultipartParser::new(Boundary::new(b"X")?, &Limits::DEFAULT, &Policy::DEFAULT)?;
    /// assert_eq!(parser.bytes_seen(), 0);
    /// # Ok::<(), form_net::FormError>(())
    /// ```
    pub fn new(boundary: Boundary, limits: &Limits, policy: &Policy) -> Result<Self, FormError> {
        limits.validate_with(policy)?;
        let buffer = alloc::vec![0u8; limits.multipart_buffer_len(policy)];
        Self::with_buffer(boundary, limits, policy, buffer)
    }
}

impl<B: AsMut<[u8]> + AsRef<[u8]>> MultipartParser<B> {
    /// A parser over a buffer the caller provides; it never allocates.
    ///
    /// # Errors
    ///
    /// `InvalidLimits`; `BufferTooSmall` when `buffer` is shorter than
    /// [`Limits::multipart_buffer_len`].
    ///
    /// # Examples
    ///
    /// ```
    /// use form_net::{Boundary, Limits, MultipartParser, Policy};
    ///
    /// const LIMITS: Limits = Limits::DEFAULT.with_max_part_header_bytes(1024);
    /// const LEN: usize = LIMITS.multipart_buffer_len(&Policy::DEFAULT);
    /// let mut buffer = [0u8; LEN];
    /// let parser = MultipartParser::with_buffer(Boundary::new(b"X")?, &LIMITS, &Policy::DEFAULT, &mut buffer[..])?;
    /// # Ok::<(), form_net::FormError>(())
    /// ```
    pub fn with_buffer(
        boundary: Boundary,
        limits: &Limits,
        policy: &Policy,
        buffer: B,
    ) -> Result<Self, FormError> {
        limits.validate_with(policy)?;
        let needed = limits.multipart_buffer_len(policy);
        if buffer.as_ref().len() < needed {
            return Err(FormError::BufferTooSmall { needed });
        }
        Ok(Self {
            boundary,
            limits: *limits,
            policy: *policy,
            buffer,
            state: State::Preamble,
            // The body may start with `--boundary`: start as if CRLF had
            // been seen.
            k: 2,
            bare: 1,
            flags: 0,
            token: Token::NotSeen,
            token_len: 0,
            charset_len: 0,
            charset_done: false,
            scan: BlockScan::default(),
            copied: 0,
            dirty: 0,
            parts: 0,
            files: 0,
            fields: 0,
            kind: PartKind::Field,
            part_bytes: 0,
            text_total: 0,
            data_start: 0,
            preamble: 0,
            epilogue: 0,
            head_start: 0,
            epilogue_start: 0,
            bytes_seen: 0,
        })
    }

    /// Consumes a prefix of `input` and returns one event. `eof = true` says
    /// `input` ends the body.
    ///
    /// # Errors
    ///
    /// Every multipart error (see the crate's `docs/API.md`); `Poisoned`
    /// after any error until [`reset`](Self::reset).
    ///
    /// # Examples
    ///
    /// ```
    /// # use form_net::{Boundary, Charset, Limits, MultipartEvent, MultipartParser, PartKind, Policy};
    /// # let mut parser = MultipartParser::new(Boundary::new(b"X")?, &Limits::DEFAULT, &Policy::DEFAULT)?;
    /// let body = b"--X\r\nContent-Disposition: form-data; name=a\r\n\r\n1\r\n--X--";
    /// // The first 10 bytes are not a whole header block: give more.
    /// let step = parser.parse(&body[..10], false)?;
    /// assert!(matches!(step.event, MultipartEvent::NeedInput));
    /// let rest = &body[step.consumed..];
    /// let step = parser.parse(rest, true)?;
    /// assert!(matches!(step.event, MultipartEvent::PartStart(head) if head.name() == "a"));
    /// # Ok::<(), form_net::FormError>(())
    /// ```
    pub fn parse<'p>(
        &'p mut self,
        input: &'p [u8],
        eof: bool,
    ) -> Result<MultipartStep<'p>, FormError> {
        let (consumed, outcome) = self.advance(input, eof)?;
        Ok(MultipartStep {
            consumed,
            event: self.view(outcome, input),
        })
    }

    /// Discards the rest of the current part: its bytes are consumed and
    /// counted against the budgets but produce no `Data` events, and its
    /// summary has `skipped = true`. Outside a part it does nothing.
    ///
    /// # Examples
    ///
    /// ```
    /// # use form_net::{Boundary, Charset, Limits, MultipartEvent, MultipartParser, PartKind, Policy};
    /// # let mut parser = MultipartParser::new(Boundary::new(b"X")?, &Limits::DEFAULT, &Policy::DEFAULT)?;
    /// # let body = b"--X\r\nContent-Disposition: form-data; name=big\r\n\r\nunwanted\r\n--X--";
    /// let step = parser.parse(body, true)?;
    /// # assert!(matches!(step.event, MultipartEvent::PartStart(_)));
    /// let mut rest = &body[step.consumed..];
    /// parser.skip_part();
    /// let summary = loop {
    ///     let step = parser.parse(rest, true)?;
    ///     rest = &rest[step.consumed..];
    ///     assert!(!matches!(step.event, MultipartEvent::Data(_)));
    ///     if let MultipartEvent::PartEnd(summary) = step.event {
    ///         break summary;
    ///     }
    /// };
    /// assert!(summary.skipped);
    /// # Ok::<(), form_net::FormError>(())
    /// ```
    pub fn skip_part(&mut self) {
        if matches!(self.state, State::Body) {
            self.flags |= SKIPPING;
        }
    }

    /// Returns the parser to its initial state for a new body, wipes its
    /// buffer, and clears the poisoned state. It never allocates.
    ///
    /// # Examples
    ///
    /// ```
    /// # use form_net::{Boundary, Charset, Limits, MultipartEvent, MultipartParser, PartKind, Policy};
    /// # let mut parser = MultipartParser::new(Boundary::new(b"X")?, &Limits::DEFAULT, &Policy::DEFAULT)?;
    /// assert!(parser.parse(b"no delimiter here", true).is_err());
    /// // Poisoned until reset; reset also takes the next body's boundary.
    /// assert!(parser.parse(b"", true).is_err());
    /// parser.reset(Boundary::new(b"Y")?);
    /// let body = b"--Y\r\nContent-Disposition: form-data; name=a\r\n\r\n1\r\n--Y--";
    /// assert!(matches!(parser.parse(body, true)?.event, MultipartEvent::PartStart(_)));
    /// # Ok::<(), form_net::FormError>(())
    /// ```
    pub fn reset(&mut self, boundary: Boundary) {
        self.wipe_used();
        let limits = self.limits;
        let policy = self.policy;
        self.boundary = boundary;
        self.state = State::Preamble;
        self.k = 2;
        self.bare = 1;
        self.flags = 0;
        self.token = Token::NotSeen;
        self.token_len = 0;
        self.charset_len = 0;
        self.charset_done = false;
        self.scan = BlockScan::default();
        self.copied = 0;
        self.parts = 0;
        self.files = 0;
        self.fields = 0;
        self.kind = PartKind::Field;
        self.part_bytes = 0;
        self.text_total = 0;
        self.data_start = 0;
        self.preamble = 0;
        self.epilogue = 0;
        self.head_start = 0;
        self.epilogue_start = 0;
        self.bytes_seen = 0;
        self.limits = limits;
        self.policy = policy;
    }

    /// Body bytes consumed so far.
    ///
    /// # Examples
    ///
    /// ```
    /// # use form_net::{Boundary, Charset, Limits, MultipartEvent, MultipartParser, PartKind, Policy};
    /// # let mut parser = MultipartParser::new(Boundary::new(b"X")?, &Limits::DEFAULT, &Policy::DEFAULT)?;
    /// # let body = b"--X\r\nContent-Disposition: form-data; name=a\r\n\r\n1\r\n--X--";
    /// let consumed = parser.parse(body, true)?.consumed;
    /// assert_eq!(parser.bytes_seen(), consumed as u64);
    /// # Ok::<(), form_net::FormError>(())
    /// ```
    #[must_use]
    pub const fn bytes_seen(&self) -> u64 {
        self.bytes_seen
    }

    /// Parts started so far.
    ///
    /// # Examples
    ///
    /// ```
    /// # use form_net::{Boundary, Charset, Limits, MultipartEvent, MultipartParser, PartKind, Policy};
    /// # let mut parser = MultipartParser::new(Boundary::new(b"X")?, &Limits::DEFAULT, &Policy::DEFAULT)?;
    /// # let body = b"--X\r\nContent-Disposition: form-data; name=a\r\n\r\n1\r\n--X--";
    /// parser.parse(body, true)?;
    /// assert_eq!(parser.parts_seen(), 1);
    /// # Ok::<(), form_net::FormError>(())
    /// ```
    #[must_use]
    pub const fn parts_seen(&self) -> u32 {
        self.parts
    }

    /// File parts counted so far.
    ///
    /// # Examples
    ///
    /// ```
    /// # use form_net::{Boundary, Charset, Limits, MultipartEvent, MultipartParser, PartKind, Policy};
    /// # let mut parser = MultipartParser::new(Boundary::new(b"X")?, &Limits::DEFAULT, &Policy::DEFAULT)?;
    /// # let body = b"--X\r\nContent-Disposition: form-data; name=f; filename=a.txt\r\n\r\nhi\r\n--X--";
    /// parser.parse(body, true)?;
    /// assert_eq!(parser.files_seen(), 1);
    /// # Ok::<(), form_net::FormError>(())
    /// ```
    #[must_use]
    pub const fn files_seen(&self) -> u32 {
        self.files
    }

    /// Whether the close delimiter was read.
    ///
    /// # Examples
    ///
    /// ```
    /// # use form_net::{Boundary, Charset, Limits, MultipartEvent, MultipartParser, PartKind, Policy};
    /// # let mut parser = MultipartParser::new(Boundary::new(b"X")?, &Limits::DEFAULT, &Policy::DEFAULT)?;
    /// let mut rest = &b"--X\r\nContent-Disposition: form-data; name=a\r\n\r\n1\r\n--X--"[..];
    /// assert!(!parser.is_done());
    /// while !parser.is_done() {
    ///     let step = parser.parse(rest, true)?;
    ///     rest = &rest[step.consumed..];
    /// }
    /// // The close delimiter was read.
    /// assert!(rest.is_empty());
    /// # Ok::<(), form_net::FormError>(())
    /// ```
    #[must_use]
    pub fn is_done(&self) -> bool {
        self.state == State::Epilogue
    }

    /// The limits the parser was built with.
    ///
    /// # Examples
    ///
    /// ```
    /// use form_net::{Boundary, Limits, MultipartParser, Policy};
    ///
    /// let limits = Limits::DEFAULT.with_max_part_header_bytes(1024);
    /// let parser = MultipartParser::new(Boundary::new(b"X")?, &limits, &Policy::DEFAULT)?;
    /// assert_eq!(parser.limits(), &limits);
    /// # Ok::<(), form_net::FormError>(())
    /// ```
    #[must_use]
    pub const fn limits(&self) -> &Limits {
        &self.limits
    }

    /// The policy the parser was built with.
    ///
    /// # Examples
    ///
    /// ```
    /// use form_net::{Boundary, Limits, MultipartParser, Policy, TokenField};
    ///
    /// let policy = Policy::DEFAULT.with_token_field(TokenField::new("csrf"));
    /// let parser = MultipartParser::new(Boundary::new(b"X")?, &Limits::DEFAULT, &policy)?;
    /// assert_eq!(parser.policy(), &policy);
    /// # Ok::<(), form_net::FormError>(())
    /// ```
    #[must_use]
    pub const fn policy(&self) -> &Policy {
        &self.policy
    }

    /// The token field's value, once its part has ended.
    ///
    /// # Examples
    ///
    /// ```
    /// use form_net::{Boundary, Limits, MultipartParser, Policy, TokenField};
    ///
    /// let policy = Policy::DEFAULT.with_token_field(TokenField::new("csrf"));
    /// let mut parser = MultipartParser::new(Boundary::new(b"X")?, &Limits::DEFAULT, &policy)?;
    /// let mut rest = &b"--X\r\nContent-Disposition: form-data; name=csrf\r\n\r\nabc123\r\n--X--"[..];
    /// while !parser.is_done() {
    ///     let step = parser.parse(rest, true)?;
    ///     rest = &rest[step.consumed..];
    /// }
    /// assert_eq!(parser.captured_token(), Some("abc123"));
    /// # Ok::<(), form_net::FormError>(())
    /// ```
    #[must_use]
    pub fn captured_token(&self) -> Option<&str> {
        if self.token != Token::Captured {
            return None;
        }
        let start = self.token_area();
        let bytes = self
            .buffer
            .as_ref()
            .get(start..start.saturating_add(usize::from(self.token_len)))?;
        core::str::from_utf8(bytes).ok()
    }

    /// The value of the last complete `_charset_` field.
    ///
    /// # Examples
    ///
    /// ```
    /// # use form_net::{Boundary, Charset, Limits, MultipartEvent, MultipartParser, PartKind, Policy};
    /// # let mut parser = MultipartParser::new(Boundary::new(b"X")?, &Limits::DEFAULT, &Policy::DEFAULT)?;
    /// let mut rest = &b"--X\r\nContent-Disposition: form-data; name=_charset_\r\n\r\nutf-8\r\n--X--"[..];
    /// while !parser.is_done() {
    ///     let step = parser.parse(rest, true)?;
    ///     rest = &rest[step.consumed..];
    /// }
    /// assert_eq!(parser.declared_charset(), Some(&b"utf-8"[..]));
    /// # Ok::<(), form_net::FormError>(())
    /// ```
    #[must_use]
    pub fn declared_charset(&self) -> Option<&[u8]> {
        if !self.charset_done {
            return None;
        }
        let start = self.charset_area();
        self.buffer
            .as_ref()
            .get(start..start.saturating_add(usize::from(self.charset_len)))
    }

    /// The decoded name of the last head, `len` bytes in the name area.
    #[cfg(feature = "alloc")]
    pub(crate) fn area_name(&self, len: u32) -> &str {
        let start = self.name_area();
        let bytes = self
            .buffer
            .as_ref()
            .get(start..start.saturating_add(len as usize))
            .unwrap_or(&[]);
        core::str::from_utf8(bytes).unwrap_or("")
    }

    /// The decoded `filename*` of the last head, `len` bytes.
    #[cfg(feature = "alloc")]
    pub(crate) fn area_filename(&self, len: u32) -> &[u8] {
        let start = self.filename_area();
        self.buffer
            .as_ref()
            .get(start..start.saturating_add(len as usize))
            .unwrap_or(&[])
    }

    /// Where the current part's data starts in the body.
    #[cfg(feature = "alloc")]
    pub(crate) const fn data_start(&self) -> u64 {
        self.data_start
    }

    // Buffer layout: header block, name, filename (AcceptAlone), token, charset.

    fn name_area(&self) -> usize {
        self.limits.max_part_header_bytes as usize
    }

    fn filename_area(&self) -> usize {
        self.name_area().saturating_add(self.limits.name() as usize)
    }

    fn token_area(&self) -> usize {
        let filename = if matches!(
            self.policy.extended_filename,
            crate::ExtendedFilenamePolicy::AcceptAlone
        ) {
            self.limits.filename() as usize
        } else {
            0
        };
        self.filename_area().saturating_add(filename)
    }

    fn charset_area(&self) -> usize {
        let token = if self.policy.token_field.is_some() {
            usize::from(self.limits.token())
        } else {
            0
        };
        self.token_area().saturating_add(token)
    }

    /// The location of the current part's header block.
    fn head_at(&self) -> Location {
        Location::in_part(self.parts.checked_sub(1), self.head_start)
    }

    /// The location of the first data byte past a budget of `limit` of
    /// which `used` is spent, in the current part.
    fn excess(&self, used: u64, limit: u64) -> Location {
        let into_part = self.part_bytes.saturating_add(limit.saturating_sub(used));
        Location::in_part(
            self.parts.checked_sub(1),
            self.data_start.saturating_add(into_part),
        )
    }

    fn at(&self, pos: usize) -> Location {
        self.at_offset(self.bytes_seen.saturating_add(pos as u64))
    }

    /// As [`at`](Self::at), for an offset in the whole body.
    fn at_offset(&self, offset: u64) -> Location {
        let part = if matches!(self.state, State::Preamble | State::Epilogue) {
            None
        } else {
            self.parts.checked_sub(1)
        };
        Location::in_part(part, offset)
    }

    /// Runs the state machine and returns positions only, so callers that
    /// own the input for longer (the buffered parser) can slice it
    /// themselves.
    pub(crate) fn advance(
        &mut self,
        input: &[u8],
        eof: bool,
    ) -> Result<(usize, Outcome), FormError> {
        if self.state == State::Poisoned {
            return Err(FormError::Poisoned);
        }
        match self.run(input, eof) {
            Ok((consumed, outcome)) => {
                self.bytes_seen = self.bytes_seen.saturating_add(consumed as u64);
                Ok((consumed, outcome))
            }
            Err(e) => {
                self.state = State::Poisoned;
                Err(e)
            }
        }
    }

    /// An input that crosses `max_body_bytes`: off the hot path. It parses
    /// what fits, as a split at the limit would, and refuses only when a byte
    /// past the limit is needed, so an error inside the limit is reported
    /// the same however the body was split (D-080, D-145).
    #[cold]
    #[inline(never)]
    fn run_over_limit(&mut self, input: &[u8]) -> Result<(usize, Outcome), FormError> {
        let over = FormError::limit(Limit::Body, Location::at(self.limits.body()));
        let room = self.limits.body().saturating_sub(self.bytes_seen);
        if room == 0 {
            return Err(over);
        }
        let within = input.get(..room as usize).unwrap_or(&[]);
        let (consumed, outcome) = self.run(within, false)?;
        // More input is needed, or the body ended with bytes left past the
        // limit (epilogue): either way a byte past it is read.
        if matches!(outcome, Outcome::NeedInput | Outcome::End) {
            return Err(over);
        }
        Ok((consumed, outcome))
    }

    fn run(&mut self, input: &[u8], eof: bool) -> Result<(usize, Outcome), FormError> {
        // The comparison saturates, so `u64::MAX` is no limit at all.
        if self.bytes_seen.saturating_add(input.len() as u64) > self.limits.body() {
            return self.run_over_limit(input);
        }
        let mut pos = 0usize;
        loop {
            let hay = input.get(pos..).unwrap_or(&[]);
            match self.state {
                State::Poisoned => return Err(FormError::Poisoned),
                State::Preamble => {
                    if let Some(after) = self.preamble_step(hay)? {
                        pos = pos.wrapping_add(after);
                        self.state = State::AfterDelimiter(After::Start);
                        continue;
                    }
                    if eof {
                        return Err(FormError::syntax(
                            SyntaxError::NoInitialDelimiter,
                            self.at(input.len()),
                        ));
                    }
                    return Ok((input.len(), Outcome::NeedInput));
                }
                State::AfterDelimiter(sub) => {
                    let Some(&c) = hay.first() else {
                        return self.need_input(input.len(), eof);
                    };
                    pos = pos.wrapping_add(1);
                    let at = self.at(pos);
                    self.state = match (sub, c) {
                        (After::Start, b'-') => State::AfterDelimiter(After::Dash),
                        (After::Dash, b'-') => {
                            self.state = State::Epilogue;
                            self.epilogue_start = self.bytes_seen.saturating_add(pos as u64);
                            return Ok((pos, Outcome::End));
                        }
                        (After::Start, b' ' | b'\t') => {
                            if self.limits.max_padding_bytes == 0 {
                                return Err(FormError::limit(Limit::Padding, at));
                            }
                            State::AfterDelimiter(After::Padding(1))
                        }
                        (After::Padding(n), b' ' | b'\t') => {
                            if n >= self.limits.max_padding_bytes {
                                return Err(FormError::limit(Limit::Padding, at));
                            }
                            State::AfterDelimiter(After::Padding(n.saturating_add(1)))
                        }
                        (After::Start | After::Padding(_), b'\r') => {
                            State::AfterDelimiter(After::Cr)
                        }
                        (After::Cr, b'\n') => {
                            self.parts = self.parts.saturating_add(1);
                            if self.parts > self.limits.max_parts {
                                return Err(FormError::limit(Limit::Parts, self.at(pos)));
                            }
                            self.scan = BlockScan::default();
                            self.copied = 0;
                            self.head_start = self.bytes_seen.saturating_add(pos as u64);
                            State::Headers
                        }
                        (After::Start | After::Padding(_), b'\n') => {
                            return Err(FormError::syntax(SyntaxError::BareLineFeed, at));
                        }
                        _ => return Err(FormError::syntax(SyntaxError::BoundaryInContent, at)),
                    };
                }
                State::Headers => {
                    let at = self.head_at();
                    match self.scan.feed(hay, &self.limits, at)? {
                        Some(end) => {
                            let source = if self.copied == 0 {
                                Source::Input(pos)
                            } else {
                                self.copy_header(hay.get(..end).unwrap_or(&[]), at)?;
                                Source::Buffer
                            };
                            let block_start_in_input = pos;
                            pos = pos.wrapping_add(end);
                            let facts =
                                self.read_head(input, source, block_start_in_input, end, at)?;
                            let (is_token, is_charset) = {
                                let block = self.block(&facts, source, input);
                                let name = self.name_bytes(&facts, block);
                                let token = self
                                    .policy
                                    .token_field
                                    .is_some_and(|t| name == t.name().as_bytes());
                                (token, name == b"_charset_")
                            };
                            self.start_part(&facts, is_token, is_charset, at)?;
                            self.data_start = self.bytes_seen.saturating_add(pos as u64);
                            return Ok((pos, Outcome::PartStart(facts, source)));
                        }
                        None => {
                            self.copy_header(hay, at)?;
                            return self.need_input(input.len(), eof);
                        }
                    }
                }
                State::Body => {
                    if hay.is_empty() {
                        return self.need_input(input.len(), eof);
                    }
                    match self.body_step(hay, pos, input.len(), eof)? {
                        BodyStep::Emit(consumed, outcome) => return Ok((consumed, outcome)),
                        BodyStep::Continue(next) => pos = next,
                    }
                }
                State::EndOfPart => {
                    let summary = self.end_part(self.at(pos))?;
                    self.state = State::AfterDelimiter(After::Start);
                    return Ok((pos, Outcome::PartEnd(summary)));
                }
                State::Epilogue => {
                    self.epilogue = self.epilogue.saturating_add(hay.len() as u64);
                    if self.epilogue > self.limits.epilogue() {
                        let at = self.epilogue_start.saturating_add(self.limits.epilogue());
                        return Err(FormError::limit(Limit::Epilogue, Location::at(at)));
                    }
                    return Ok((input.len(), Outcome::End));
                }
            }
        }
    }

    fn need_input(&self, len: usize, eof: bool) -> Result<(usize, Outcome), FormError> {
        if eof {
            Err(FormError::syntax(SyntaxError::Truncated, self.at(len)))
        } else {
            Ok((len, Outcome::NeedInput))
        }
    }

    /// The refusal for `--boundary` after a lone CR or LF, ending at `after`
    /// in a `hay` that starts at `pos` in the input (D-113).
    /// The location is the line break's, in whichever chunk it came.
    fn bare_break(&self, after: usize, pos: usize) -> FormError {
        let end = self
            .bytes_seen
            .saturating_add(pos.wrapping_add(after) as u64);
        let bare = self.boundary.len().saturating_sub(1) as u64;
        FormError::syntax(
            SyntaxError::BoundaryInContent,
            self.at_offset(end.saturating_sub(bare)),
        )
    }

    /// Scans the preamble. Returns the index in `hay` just after the first
    /// delimiter, or `None` when all of `hay` was consumed.
    fn preamble_step(&mut self, hay: &[u8]) -> Result<Option<usize>, FormError> {
        let len = self.boundary.len() as u64;
        // A delimiter must end within max_preamble_bytes + its own length.
        let budget = self.limits.preamble().saturating_add(len);
        let room = usize::try_from(budget.saturating_sub(self.preamble)).unwrap_or(usize::MAX);
        let window = hay.get(..room.min(hay.len())).unwrap_or(hay);
        let (k, m, found) = self
            .boundary
            .run(usize::from(self.k), usize::from(self.bare), window);
        self.k = k as u8;
        self.bare = m as u8;
        match found {
            Hit::BareBreak(after) => Err(self.bare_break(after, 0)),
            Hit::Delimiter(after) => {
                // Real bytes up to the end of the delimiter; a delimiter that
                // includes the two virtual bytes (CRLF) starts the body.
                let end = self.preamble.saturating_add(after as u64);
                let preamble = end.saturating_sub(len);
                if preamble > self.limits.preamble() {
                    return Err(FormError::limit(
                        Limit::Preamble,
                        Location::at(self.limits.preamble()),
                    ));
                }
                self.k = 0;
                self.bare = 0;
                Ok(Some(after))
            }
            Hit::None => {
                self.preamble = self.preamble.saturating_add(window.len() as u64);
                if window.len() < hay.len() || self.preamble >= budget {
                    return Err(FormError::limit(
                        Limit::Preamble,
                        Location::at(self.limits.preamble()),
                    ));
                }
                Ok(None)
            }
        }
    }

    fn copy_header(&mut self, bytes: &[u8], at: Location) -> Result<(), FormError> {
        let start = self.copied as usize;
        let end = start.saturating_add(bytes.len());
        if end > self.limits.max_part_header_bytes as usize {
            return Err(FormError::limit(Limit::PartHeaderBytes, at));
        }
        match self.buffer.as_mut().get_mut(start..end) {
            Some(dst) => dst.copy_from_slice(bytes),
            None => return Err(FormError::limit(Limit::PartHeaderBytes, at)),
        }
        self.copied = end as u32;
        self.dirty = self.dirty.max(self.copied);
        Ok(())
    }

    fn read_head(
        &mut self,
        input: &[u8],
        source: Source,
        start: usize,
        end: usize,
        at: Location,
    ) -> Result<HeadFacts, FormError> {
        let name_area = self.name_area();
        let filename_area = self.filename_area();
        let filename_end = self.token_area();
        let limits = self.limits;
        let policy = self.policy;
        let copied = self.copied as usize;
        let block_len = match source {
            Source::Input(_) => end,
            Source::Buffer => copied,
        };
        self.dirty = self.dirty.max(u32::try_from(block_len).unwrap_or(u32::MAX));
        let buf = self.buffer.as_mut();
        let (head, rest) = buf.split_at_mut(name_area.min(buf.len()));
        let (name, rest) =
            rest.split_at_mut(filename_area.saturating_sub(name_area).min(rest.len()));
        let filename = rest
            .get_mut(..filename_end.saturating_sub(filename_area))
            .unwrap_or(&mut []);
        let block = match source {
            Source::Input(_) => input.get(start..start.saturating_add(end)).unwrap_or(&[]),
            Source::Buffer => head.get(..copied).unwrap_or(&[]),
        };
        read_block(block, &limits, &policy, Areas { name, filename }, at)
    }

    /// The budgets and rules that apply when a part starts.
    fn start_part(
        &mut self,
        facts: &HeadFacts,
        is_token: bool,
        is_charset: bool,
        at: Location,
    ) -> Result<(), FormError> {
        self.state = State::Body;
        self.k = 0;
        // The data starts after the blank line's LF: `--boundary` right
        // there reads as an empty part to an RFC 2046 reader (D-113).
        self.bare = 1;
        self.flags = 0;
        self.kind = facts.kind;
        self.part_bytes = 0;
        match facts.kind {
            PartKind::Field => {
                self.fields = self.fields.saturating_add(1);
                if self.fields > self.limits.max_fields {
                    return Err(FormError::limit(Limit::Fields, at));
                }
                if is_token {
                    if self.token != Token::NotSeen {
                        return Err(FormError::policy(PolicyRefusal::DuplicateToken, at));
                    }
                    self.token = Token::Capturing;
                    self.token_len = 0;
                    self.flags |= IS_TOKEN;
                }
                if is_charset {
                    self.flags |= IS_CHARSET;
                    self.charset_len = 0;
                    self.charset_done = false;
                }
            }
            PartKind::File => {
                let empty = matches!(facts.filename, Some((Text::Block(span), _)) if span.len == 0)
                    || matches!(facts.filename, Some((Text::Area(0), _)));
                if empty && self.policy.empty_files == EmptyFilePolicy::Skip {
                    self.flags |= DEFERRED;
                } else {
                    self.count_file(at)?;
                }
            }
        }
        Ok(())
    }

    /// The block of a head, wherever it is.
    fn block<'a>(&'a self, facts: &HeadFacts, source: Source, input: &'a [u8]) -> &'a [u8] {
        let len = facts.block_len as usize;
        match source {
            Source::Input(start) => input.get(start..start.saturating_add(len)).unwrap_or(&[]),
            Source::Buffer => self.buffer.as_ref().get(..len).unwrap_or(&[]),
        }
    }

    /// The decoded name of a head.
    fn name_bytes<'a>(&'a self, facts: &HeadFacts, block: &'a [u8]) -> &'a [u8] {
        match facts.name {
            Text::Block(span) => span.get(block),
            Text::Area(len) => {
                let start = self.name_area();
                self.buffer
                    .as_ref()
                    .get(start..start.saturating_add(len as usize))
                    .unwrap_or(&[])
            }
        }
    }

    /// The borrowed view of a head.
    fn head_view<'p>(&'p self, facts: &HeadFacts, source: Source, input: &'p [u8]) -> PartHead<'p> {
        let block = self.block(facts, source, input);
        let name = core::str::from_utf8(self.name_bytes(facts, block)).unwrap_or("");
        let filename = facts.filename.map(|(text, origin)| {
            let raw = match text {
                Text::Block(span) => span.get(block),
                Text::Area(len) => {
                    let start = self.filename_area();
                    self.buffer
                        .as_ref()
                        .get(start..start.saturating_add(len as usize))
                        .unwrap_or(&[])
                }
            };
            FileName::new(raw, origin)
        });
        PartHead {
            index: self.parts.saturating_sub(1),
            block,
            name,
            name_raw: facts.name_raw.get(block),
            kind: facts.kind,
            filename,
            content_type: facts.content_type.map(|span| span.get(block)),
            charset: facts.charset,
        }
    }

    /// Turns positions into borrowed events.
    fn view<'p>(&'p self, outcome: Outcome, input: &'p [u8]) -> MultipartEvent<'p> {
        match outcome {
            Outcome::PartStart(facts, source) => {
                MultipartEvent::PartStart(self.head_view(&facts, source, input))
            }
            Outcome::DataInput(start, end) => {
                MultipartEvent::Data(input.get(start..end).unwrap_or(&[]))
            }
            Outcome::DataDelimiter(n) => {
                MultipartEvent::Data(self.boundary.delimiter().get(..n).unwrap_or(&[]))
            }
            Outcome::PartEnd(summary) => MultipartEvent::PartEnd(summary),
            Outcome::End => MultipartEvent::End,
            Outcome::NeedInput => MultipartEvent::NeedInput,
        }
    }

    fn count_file(&mut self, at: Location) -> Result<(), FormError> {
        self.files = self.files.saturating_add(1);
        if self.files > self.limits.max_files {
            return Err(FormError::limit(Limit::Files, at));
        }
        if let Some(t) = self.policy.token_field {
            if t.placement() == TokenPlacement::BeforeFirstFile && self.token != Token::Captured {
                return Err(FormError::policy(PolicyRefusal::TokenFieldLate, at));
            }
        }
        Ok(())
    }

    /// Checks budgets for `n` more data bytes of the current part, and
    /// captures the token or `_charset_` value.
    fn take_data(&mut self, bytes: &[u8]) -> Result<(), FormError> {
        let n = bytes.len() as u64;
        if n == 0 {
            return Ok(());
        }
        if self.flags & DEFERRED != 0 {
            self.flags &= !DEFERRED;
            let at = Location::in_part(self.parts.checked_sub(1), self.data_start);
            self.count_file(at)?;
        }
        let total = self.part_bytes.saturating_add(n);
        match self.kind {
            PartKind::File => {
                let limit = self.limits.file();
                if total > limit {
                    let at = self.excess(self.part_bytes, limit);
                    return Err(FormError::limit(Limit::FileSize, at));
                }
            }
            PartKind::Field => {
                let limit = u64::from(self.limits.value());
                if total > limit {
                    let at = self.excess(self.part_bytes, limit);
                    return Err(FormError::limit(Limit::ValueLength, at));
                }
                let text = self.text_total.saturating_add(n);
                let limit = self.limits.text();
                if text > limit {
                    let at = self.excess(self.text_total, limit);
                    return Err(FormError::limit(Limit::TextTotal, at));
                }
                self.text_total = text;
            }
        }
        if self.flags & IS_TOKEN != 0 {
            let start = self
                .token_area()
                .saturating_add(usize::from(self.token_len));
            let end = start.saturating_add(bytes.len());
            let limit = u64::from(self.limits.token());
            let at = self.excess(u64::from(self.token_len), limit);
            if end
                > self
                    .token_area()
                    .saturating_add(usize::from(self.limits.token()))
            {
                return Err(FormError::limit(Limit::TokenLength, at));
            }
            match self.buffer.as_mut().get_mut(start..end) {
                Some(dst) => dst.copy_from_slice(bytes),
                None => return Err(FormError::limit(Limit::TokenLength, at)),
            }
            self.token_len = self.token_len.saturating_add(bytes.len() as u16);
        }
        if self.flags & IS_CHARSET != 0 {
            let start = self
                .charset_area()
                .saturating_add(usize::from(self.charset_len));
            let end = start.saturating_add(bytes.len());
            let at = self.excess(u64::from(self.charset_len), CHARSET_CAPTURE as u64);
            if end > self.charset_area().saturating_add(CHARSET_CAPTURE) {
                return Err(FormError::encoding(EncodingError::UnsupportedCharset, at));
            }
            match self.buffer.as_mut().get_mut(start..end) {
                Some(dst) => dst.copy_from_slice(bytes),
                None => return Err(FormError::encoding(EncodingError::UnsupportedCharset, at)),
            }
            self.charset_len = self.charset_len.saturating_add(bytes.len() as u8);
        }
        self.part_bytes = total;
        Ok(())
    }

    fn end_part(&mut self, at: Location) -> Result<PartSummary, FormError> {
        if self.flags & IS_TOKEN != 0 {
            let start = self.token_area();
            let bytes = self
                .buffer
                .as_ref()
                .get(start..start.saturating_add(usize::from(self.token_len)))
                .unwrap_or(&[]);
            if core::str::from_utf8(bytes).is_err() {
                return Err(FormError::encoding(EncodingError::InvalidUtf8, at));
            }
            self.token = Token::Captured;
        }
        if self.flags & IS_CHARSET != 0 {
            self.charset_done = true;
        }
        let summary = PartSummary {
            index: self.parts.saturating_sub(1),
            kind: self.kind,
            bytes: self.part_bytes,
            skipped: self.flags & SKIPPING != 0,
        };
        self.flags = 0;
        self.k = 0;
        Ok(summary)
    }

    /// One step in a part's data. `pos` is where `hay` starts in the input.
    fn body_step(
        &mut self,
        hay: &[u8],
        pos: usize,
        input_len: usize,
        eof: bool,
    ) -> Result<BodyStep, FormError> {
        let len = self.boundary.len();
        let k0 = usize::from(self.k);
        if k0 > 0 {
            // Bytes from earlier chunks that matched the start of the
            // delimiter: resolve them before anything else. The delimiter
            // has one CR, so the match either goes on or all of it is over.
            let need = self.boundary.delimiter().get(k0..).unwrap_or(&[]);
            let (need_len, n) = (need.len(), super::boundary::shared(need, hay));
            if n == need_len {
                // The delimiter started inside the held bytes.
                self.k = 0;
                self.bare = 0;
                self.state = State::EndOfPart;
                return self.emit_delimiter_bytes(0, pos.wrapping_add(n));
            }
            if n < hay.len() {
                // Every held byte is data; scan the input again from 0,
                // with the bare-break state the held bytes leave: they
                // are a CR, a CR LF, or a CR LF and dashes (D-113).
                self.k = 0;
                self.bare = k0.max(2).wrapping_sub(1) as u8;
                return self.emit_delimiter_bytes(k0, pos);
            }
            // All of `hay` extended the partial match.
            if eof {
                // Every byte is data now: charge it first, as a split body
                // charges it before it learns the body ended (D-145).
                let boundary = self.boundary;
                self.take_data(boundary.delimiter().get(..k0).unwrap_or(&[]))?;
                self.take_data(hay)?;
                return Err(FormError::syntax(
                    SyntaxError::Truncated,
                    self.at(input_len),
                ));
            }
            self.k = k0.saturating_add(n) as u8;
            return self.emit_delimiter_bytes(0, input_len);
        }
        let (k, m, found) = self.boundary.run(0, usize::from(self.bare), hay);
        match found {
            Hit::BareBreak(after) => {
                // The data before the break is charged first, as a split
                // before the break would charge it (D-145).
                let start = after.saturating_sub(len.saturating_sub(1));
                self.take_data(hay.get(..start).unwrap_or(&[]))?;
                Err(self.bare_break(after, pos))
            }
            Hit::Delimiter(after) => {
                let data = after.saturating_sub(len);
                self.k = 0;
                self.bare = 0;
                self.state = State::EndOfPart;
                let bytes = hay.get(..data).unwrap_or(&[]);
                self.emit_input_bytes(bytes, pos, pos.wrapping_add(data), pos.wrapping_add(after))
            }
            Hit::None => {
                if eof {
                    // As above: the rest is data, charged before `Truncated`.
                    self.take_data(hay)?;
                    return Err(FormError::syntax(
                        SyntaxError::Truncated,
                        self.at(input_len),
                    ));
                }
                self.k = k as u8;
                self.bare = m as u8;
                let data_end = hay.len().saturating_sub(k);
                let bytes = hay.get(..data_end).unwrap_or(&[]);
                self.emit_input_bytes(bytes, pos, pos.wrapping_add(data_end), input_len)
            }
        }
    }

    /// Emits `delimiter[..n]` as data (or skips it), consuming up to
    /// `consumed`.
    fn emit_delimiter_bytes(&mut self, n: usize, consumed: usize) -> Result<BodyStep, FormError> {
        let boundary = self.boundary;
        let bytes = boundary.delimiter().get(..n).unwrap_or(&[]);
        self.take_data(bytes)?;
        if n == 0 || self.flags & SKIPPING != 0 {
            return Ok(BodyStep::Continue(consumed));
        }
        Ok(BodyStep::Emit(consumed, Outcome::DataDelimiter(n)))
    }

    /// Emits `input[start..end]` as data (or skips it), consuming up to
    /// `consumed`.
    fn emit_input_bytes(
        &mut self,
        bytes: &[u8],
        start: usize,
        end: usize,
        consumed: usize,
    ) -> Result<BodyStep, FormError> {
        self.take_data(bytes)?;
        if start == end || self.flags & SKIPPING != 0 {
            return Ok(BodyStep::Continue(consumed));
        }
        Ok(BodyStep::Emit(consumed, Outcome::DataInput(start, end)))
    }
}

/// What a body step did.
enum BodyStep {
    Emit(usize, Outcome),
    Continue(usize),
}

impl<B: AsMut<[u8]> + AsRef<[u8]>> MultipartParser<B> {
    /// Wipes every byte the parser wrote into its buffer, and nothing more:
    /// a buffer of the default size is 9.6 KiB, and a login form writes a
    /// few hundred bytes of it (D-103).
    fn wipe_used(&mut self) {
        let used = self.dirty as usize;
        let regions = [
            (0, used.min(self.name_area())),
            (
                self.name_area(),
                used.min(self.filename_area().saturating_sub(self.name_area())),
            ),
            (
                self.filename_area(),
                used.min(self.token_area().saturating_sub(self.filename_area())),
            ),
            (self.token_area(), usize::from(self.token_len)),
            // The whole capture area: a second, shorter `_charset_` value
            // resets the length over the tail of the first (found by review).
            (self.charset_area(), CHARSET_CAPTURE),
        ];
        let buf = self.buffer.as_mut();
        for (start, len) in regions {
            if let Some(region) = buf.get_mut(start..start.saturating_add(len)) {
                crate::wipe::wipe(region);
            }
        }
        self.dirty = 0;
    }
}

impl<B: AsMut<[u8]> + AsRef<[u8]>> Drop for MultipartParser<B> {
    fn drop(&mut self) {
        self.wipe_used();
    }
}

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

    /// D-103: the wipe covers every byte the parser wrote. With a caller
    /// buffer the result is visible: after a body that writes every area
    /// (header blocks, an escaped name, a decoded `filename*`, the token,
    /// `_charset_`), dropping or resetting leaves the buffer all zeros.
    #[test]
    fn test_wipe_covers_every_area_written() {
        let policy = Policy::DEFAULT
            .with_extended_filename(crate::ExtendedFilenamePolicy::AcceptAlone)
            .with_token_field(crate::TokenField::new("csrf"));
        let limits = Limits::DEFAULT.with_max_part_header_bytes(512);
        let long = "x".repeat(300);
        let body = alloc::format!(
            "--X\r\nContent-Disposition: form-data; name=csrf\r\n\r\nsecret-token-value\r\n\
             --X\r\nContent-Disposition: form-data; name=_charset_\r\n\r\nUTF-8\r\n\
             --X\r\nContent-Disposition: form-data; name=\"pass%22word\"\r\nX-Pad: {long}\r\n\r\nhunter2\r\n\
             --X\r\nContent-Disposition: form-data; name=f; filename*=UTF-8''caf%C3%A9.txt\r\n\r\nfile\r\n--X--"
        );
        // Two `_charset_` values, the second shorter: the first one's tail
        // must not survive (found by review).
        let body = body.replace(
            "name=_charset_\r\n\r\nUTF-8\r\n",
            "name=_charset_\r\n\r\nunicode-1-1-utf-8\r\n--X\r\nContent-Disposition: form-data; name=_charset_\r\n\r\nutf8\r\n",
        );
        assert!(body.contains("unicode-1-1-utf-8"));
        for split in [usize::MAX, 7, 1] {
            let mut buf = alloc::vec![0u8; limits.multipart_buffer_len(&policy)];
            {
                let mut p = MultipartParser::with_buffer(
                    Boundary::new(b"X").unwrap(),
                    &limits,
                    &policy,
                    &mut buf[..],
                )
                .unwrap();
                let bytes = body.as_bytes();
                let chunks: alloc::vec::Vec<&[u8]> = bytes.chunks(split.min(bytes.len())).collect();
                let mut ended = false;
                for (i, c) in chunks.iter().enumerate() {
                    let last = i + 1 == chunks.len();
                    let mut rest = *c;
                    loop {
                        let step = p.parse(rest, last).unwrap();
                        rest = &rest[step.consumed..];
                        match step.event {
                            MultipartEvent::NeedInput => break,
                            MultipartEvent::End => {
                                ended = true;
                                break;
                            }
                            _ => {}
                        }
                    }
                }
                assert!(ended);
                assert_eq!(p.captured_token(), Some("secret-token-value"));
            }
            assert!(
                buf.iter().all(|&b| b == 0),
                "split {split}: bytes left at {:?}",
                buf.iter().position(|&b| b != 0)
            );
        }
    }

    /// Feeds `body` whole and returns the first error, or `None` at `End`.
    #[cfg(feature = "alloc")]
    fn run(p: &mut MultipartParser<alloc::vec::Vec<u8>>, body: &[u8]) -> Option<FormError> {
        let mut rest = body;
        loop {
            match p.parse(rest, true) {
                Err(e) => return Some(e),
                Ok(step) => {
                    rest = &rest[step.consumed..];
                    if matches!(step.event, MultipartEvent::End) {
                        return None;
                    }
                }
            }
        }
    }

    /// T-28, through the counter seam: counters set near `u64::MAX` never
    /// wrap. Under finite limits they still refuse; under `u64::MAX` limits
    /// they saturate and positions stay at the maximum.
    #[cfg(feature = "alloc")]
    #[test]
    fn test_attack_t28_counters_near_u64_max_never_wrap() {
        let body = b"--X\r\nContent-Disposition: form-data; name=a\r\n\r\nvalue\r\n--X--";
        let new = |limits: &Limits| {
            MultipartParser::new(Boundary::new(b"X").unwrap(), limits, &Policy::DEFAULT).unwrap()
        };
        let mut p = new(&Limits::DEFAULT);
        p.bytes_seen = u64::MAX - 4;
        assert!(matches!(
            run(&mut p, body),
            Some(FormError::Limit {
                limit: crate::error::Limit::Body,
                ..
            })
        ));

        let mut p = new(&Limits::DEFAULT);
        p.text_total = u64::MAX - 2;
        assert!(matches!(
            run(&mut p, body),
            Some(FormError::Limit {
                limit: crate::error::Limit::TextTotal,
                ..
            })
        ));

        let open = Limits::DEFAULT
            .with_max_body_bytes(u64::MAX)
            .with_max_text_bytes(u64::MAX);
        let mut p = new(&open);
        p.bytes_seen = u64::MAX - 4;
        assert!(run(&mut p, body).is_none());
        assert_eq!(p.bytes_seen, u64::MAX);
    }

    #[test]
    fn test_parser_size_is_bounded() {
        // NFR-18 as measured: the boundary and its matcher table are 149 of
        // these bytes; the buffer is separate.
        assert!(core::mem::size_of::<MultipartParser<&mut [u8]>>() <= 384);
        assert!(core::mem::size_of::<Boundary>() <= 150);
    }

    #[cfg(feature = "alloc")]
    #[test]
    fn test_debug_never_shows_data_or_file_names() {
        let body = b"--X\r\nContent-Disposition: form-data; name=f; filename=\"secret.pdf\"\r\n\r\nhunter2\r\n--X--";
        let mut p = MultipartParser::new(
            Boundary::new(b"X").unwrap(),
            &Limits::DEFAULT,
            &Policy::DEFAULT,
        )
        .unwrap();
        let mut rest: &[u8] = body;
        let mut seen = alloc::string::String::new();
        loop {
            let step = p.parse(rest, true).unwrap();
            rest = &rest[step.consumed..];
            if let MultipartEvent::PartStart(head) = &step.event {
                seen.push_str(&alloc::format!("{:?}", head.headers()));
            }
            seen.push_str(&alloc::format!("{step:?}"));
            if matches!(step.event, MultipartEvent::End) {
                break;
            }
        }
        assert!(seen.contains("Data(7 bytes)"), "{seen}");
        assert!(
            !seen.contains("hunter2") && !seen.contains("secret"),
            "{seen}"
        );
    }

    #[test]
    fn test_charset_labels() {
        assert_eq!(Charset::from_label(b"UTF-8"), Charset::Utf8);
        assert_eq!(Charset::from_label(b"us-ascii"), Charset::Ascii);
        assert_eq!(Charset::from_label(b"utf8"), Charset::Other);
    }
}