shared_framework/utils/

request_parser.rs

//! Query, JSON, and multipart request parsing.
//!
//! [`RequestParser`] parses query parameters, JSON bodies, and
//! `multipart/form-data` payloads (RFC 7578) into [`MultipartBody`] with text
//! fields and [`UploadedFile`] entries. Multipart DTOs are conventionally
//! decoded from the `body` form field; see [`CorrelationContext::body`](crate::logging::CorrelationContext::body).
//!
//! ```ignore
//! let boundary = RequestParser::multipart_boundary(content_type).unwrap();
//! let multipart = RequestParser::parse_multipart(&bytes, &boundary);
//! let name: Option<&str> = multipart.field("name");
//! ```
use serde::de::DeserializeOwned;
use std::collections::HashMap;

/// Parsers for query strings, JSON bodies, and multipart payloads.
pub struct RequestParser;

impl RequestParser {
    /// Parses `query` as form-urlencoded and converts the `key` value via `FromStr`.
    /// Returns `None` when the key is absent or cannot be parsed.
    pub fn query_param<T: std::str::FromStr>(query: &str, key: &str) -> Option<T> {
        let params: HashMap<String, String> = serde_urlencoded::from_str(query).unwrap_or_default();
        params.get(key).and_then(|v| v.parse().ok())
    }

    /// Deserializes a JSON body. Returns an error on invalid JSON or shape mismatch.
    pub fn parse_body<T: DeserializeOwned>(body: &[u8]) -> Result<T, serde_json::Error> {
        serde_json::from_slice(body)
    }

    /// Extracts the `boundary` from a `multipart/form-data; boundary=...` content type.
    /// Returns `None` when absent, empty, or longer than 128 characters.
    pub fn multipart_boundary(content_type: &str) -> Option<String> {
        content_type.split(';').find_map(|part| {
            let part = part.trim();
            let (k, v) = part.split_once('=')?;
            if k.trim().eq_ignore_ascii_case("boundary") {
                let b = v.trim().trim_matches('"').trim().to_string();
                if b.is_empty() || b.len() > 128 { None } else { Some(b) }
            } else {
                None
            }
        })
    }

    /// Parse a `multipart/form-data` payload (RFC 7578) into text fields and files.
    /// Byte-oriented so file contents are never mangled by UTF-8 decoding.
    pub fn parse_multipart(body: &[u8], boundary: &str) -> MultipartBody {
        MultipartBody::parse(body, boundary)
    }
}

/// A file received in a `multipart/form-data` part.
#[derive(Debug, Clone)]
pub struct UploadedFile {
    /// The form field name (`name="..."`).
    pub field_name: String,
    /// The client-supplied file name, if any.
    pub file_name: Option<String>,
    /// The part's content type, if any.
    pub content_type: Option<String>,
    /// Raw file bytes.
    pub bytes: Vec<u8>,
}

impl UploadedFile {
    /// Returns the file size in bytes.
    pub fn len(&self) -> usize {
        self.bytes.len()
    }

    /// Returns true when the file holds no bytes.
    pub fn is_empty(&self) -> bool {
        self.bytes.is_empty()
    }
}

/// Decoded `multipart/form-data` payload: text fields plus uploaded files.
#[derive(Debug, Clone, Default)]
pub struct MultipartBody {
    /// Text fields; repeated names keep every value in order.
    pub fields: HashMap<String, Vec<String>>,
    /// Uploaded files in part order.
    pub files: Vec<UploadedFile>,
}

/// Safety cap on part count per request (consistent with the framework
/// collecting the whole body before dispatch; prevents delimiter abuse).
const MAX_PARTS: usize = 512;

impl MultipartBody {
    /// Parses a raw multipart payload with the given boundary.
    /// Returns an empty body for an empty boundary or payload; at most 512 parts are kept.
    pub fn parse(body: &[u8], boundary: &str) -> Self {
        let mut out = Self::default();
        if boundary.is_empty() || body.is_empty() {
            return out;
        }
        let delimiter = format!("--{}", boundary);
        let delim = delimiter.as_bytes();
        // Locate delimiter lines: the delimiter must open a line (start of body
        // or right after `\n`, tolerating a preamble) and be followed by a line
        // break or the close marker — so boundary-like bytes inside file
        // contents never split apart.
        let mut offsets = Vec::new();
        let mut i = 0;
        while i + delim.len() <= body.len() {
            if &body[i..i + delim.len()] == delim
                && (i == 0 || body[i - 1] == b'\n')
                && follows_delimiter(&body[i + delim.len()..])
            {
                offsets.push(i);
                i += delim.len();
            } else {
                i += 1;
            }
        }
        for (idx, &start) in offsets.iter().enumerate() {
            if idx >= MAX_PARTS {
                break;
            }
            let mut seg_start = start + delim.len();
            // Close delimiter (`--boundary--`) ends the payload.
            if body.get(seg_start..seg_start + 2) == Some(b"--".as_slice()) {
                break;
            }
            // Strip the CRLF following the delimiter line.
            if body.get(seg_start..seg_start + 2) == Some(b"\r\n".as_slice()) {
                seg_start += 2;
            } else if body.get(seg_start..seg_start + 1) == Some(b"\n".as_slice()) {
                seg_start += 1;
            }
            let seg_end = offsets.get(idx + 1).copied().unwrap_or(body.len());
            if seg_end <= seg_start {
                continue;
            }
            let mut segment = &body[seg_start..seg_end];
            // Strip the CRLF preceding the next delimiter.
            if segment.ends_with(b"\r\n") {
                segment = &segment[..segment.len() - 2];
            } else if segment.ends_with(b"\n") {
                segment = &segment[..segment.len() - 1];
            }
            out.add_part(segment);
        }
        out
    }

    fn add_part(&mut self, segment: &[u8]) {
        let split = find_subslice(segment, b"\r\n\r\n")
            .or_else(|| find_subslice(segment, b"\n\n"));
        let Some(at) = split else { return };
        let sep_len = if segment[at..].starts_with(b"\r\n\r\n") { 4 } else { 2 };
        let raw_headers = &segment[..at];
        let content = &segment[at + sep_len..];
        let headers = String::from_utf8_lossy(raw_headers);

        let mut name: Option<String> = None;
        let mut file_name: Option<String> = None;
        let mut part_content_type: Option<String> = None;
        for line in headers.split("\r\n") {
            let line = line.trim();
            if line.is_empty() {
                continue;
            }
            if let Some((k, v)) = line.split_once(':') {
                let key = k.trim();
                let val = v.trim().to_string();
                if key.eq_ignore_ascii_case("content-disposition") {
                    let (disp_name, disp_file) = parse_disposition(&val);
                    if disp_name.is_some() {
                        name = disp_name;
                    }
                    if disp_file.is_some() {
                        file_name = disp_file;
                    }
                } else if key.eq_ignore_ascii_case("content-type") {
                    part_content_type = Some(val.split(';').next().unwrap_or("").trim().to_string());
                }
            }
        }
        let Some(name) = name.filter(|n| !n.is_empty()) else { return };
        // A part is a file upload when it carries a filename or an explicit
        // non-text content type. Plain `text/plain` parts stay text fields even
        // when a client sends the content type explicitly (e.g., curl `-F`).
        let is_file = match (&file_name, &part_content_type) {
            (Some(f), _) if !f.is_empty() => true,
            (_, Some(ct)) if !ct.is_empty() && ct != "text/plain" => true,
            _ => false,
        };
        if is_file {
            self.files.push(UploadedFile {
                field_name: name,
                file_name: file_name.filter(|f| !f.is_empty()),
                content_type: part_content_type.filter(|c| !c.is_empty()),
                bytes: content.to_vec(),
            });
        } else {
            self.fields
                .entry(name)
                .or_default()
                .push(String::from_utf8_lossy(content).into_owned());
        }
    }

    /// Returns the first value of a text field, if present.
    pub fn field(&self, name: &str) -> Option<&str> {
        self.fields.get(name).and_then(|v| v.first().map(|s| s.as_str()))
    }
}

/// Parse `form-data; name="..."`; `filename="..."` from a Content-Disposition value.
fn parse_disposition(value: &str) -> (Option<String>, Option<String>) {
    let mut name = None;
    let mut filename = None;
    for part in value.split(';').skip(1) {
        let part = part.trim();
        if let Some((k, v)) = part.split_once('=') {
            let v = v.trim().trim_matches('"').to_string();
            if k.trim().eq_ignore_ascii_case("name") {
                name = Some(v);
            } else if k.trim().eq_ignore_ascii_case("filename") {
                filename = Some(v);
            }
        }
    }
    (name, filename)
}

fn find_subslice(haystack: &[u8], needle: &[u8]) -> Option<usize> {
    if needle.is_empty() || haystack.len() < needle.len() {
        return None;
    }
    (0..=haystack.len() - needle.len()).find(|&i| &haystack[i..i + needle.len()] == needle)
}

/// Remainder after a delimiter must start a new line, close the payload, or be empty.
fn follows_delimiter(rest: &[u8]) -> bool {
    rest.is_empty()
        || rest.starts_with(b"--")
        || rest.starts_with(b"\r\n")
        || rest.starts_with(b"\n")
}