ycdemo / axum / axum-extra/ src/ response/ multiple.rs

//! Generate forms to use in responses.

use super::{
    content_disposition::{contains_newlines, EscapedQuotedString},
    multipart,
};
use axum_core::{
    body,
    response::{IntoResponse, Response},
};
use fastrand;
use http::{header, HeaderMap, StatusCode};
use mime::Mime;

/// Create multipart forms to be used in API responses.
///
/// This struct implements [`IntoResponse`], and so it can be returned from a handler.
#[must_use]
#[derive(Debug)]
pub struct MultipartForm {
    parts: Vec<Part>,
}

impl MultipartForm {
    /// Initialize a new multipart form with the provided vector of parts.
    ///
    /// # Examples
    ///
    /// ```rust
    /// use axum_extra::response::multiple::{MultipartForm, Part};
    ///
    /// let parts: Vec<Part> = vec![Part::text("foo".to_string(), "abc"), Part::text("bar".to_string(), "def")];
    /// let form = MultipartForm::with_parts(parts);
    /// ```
    pub fn with_parts(parts: Vec<Part>) -> Self {
        Self { parts }
    }
}

impl IntoResponse for MultipartForm {
    fn into_response(self) -> Response {
        // see RFC 7578 for details
        let Some(boundary) = generate_boundary_for_parts(&self.parts) else {
            return (
                StatusCode::INTERNAL_SERVER_ERROR,
                "Unable to generate multipart boundary",
            )
                .into_response();
        };
        let mut headers = HeaderMap::new();
        let mime_type: Mime = match format!("multipart/form-data; boundary={boundary}").parse() {
            Ok(m) => m,
            // Realistically this should never happen unless the boundary generation code
            // is modified, and that will be caught by unit tests
            Err(_) => {
                return (
                    StatusCode::INTERNAL_SERVER_ERROR,
                    "Invalid multipart boundary generated",
                )
                    .into_response()
            }
        };
        // The use of unwrap is safe here because mime types are inherently string representable
        headers.insert(header::CONTENT_TYPE, mime_type.to_string().parse().unwrap());
        let mut parts = Vec::with_capacity(self.parts.len());
        for part in self.parts {
            let Ok(encoded) = part.into_multipart_part(&boundary) else {
                return (
                    StatusCode::INTERNAL_SERVER_ERROR,
                    "Invalid multipart field name or filename",
                )
                    .into_response();
            };
            parts.push(Some(encoded));
        }
        let body = body::Body::new(multipart::Multipart::new(&boundary, parts, false));
        (headers, body).into_response()
    }
}

// Valid settings for that header are: "base64", "quoted-printable", "8bit", "7bit", and "binary".
/// A single part of a multipart form as defined by
/// <https://www.w3.org/TR/html401/interact/forms.html#h-17.13.4>
/// and RFC 7578.
#[derive(Debug)]
pub struct Part {
    // Every part is expected to contain:
    // - a [Content-Disposition](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Disposition
    // header, where `Content-Disposition` is set to `form-data`, with a parameter of `name` that is set to
    // the name of the field in the form. In the below example, the name of the field is `user`:
    // ```
    // Content-Disposition: form-data; name="user"
    // ```
    // If the field contains a file, then the `filename` parameter may be set to the name of the file.
    // Handling for non-ascii field names is not done here, support for non-ascii characters may be encoded using
    // methodology described in RFC 2047.
    // - (optionally) a `Content-Type` header, which if not set, defaults to `text/plain`.
    // If the field contains a file, then the file should be identified with that file's MIME type (e.g., `image/gif`).
    // If the `MIME` type is not known or specified, then the MIME type should be set to `application/octet-stream`.
    /// The name of the part in question
    name: String,
    /// If the part should be treated as a file, the filename that should be attached that part
    filename: Option<String>,
    /// The `Content-Type` header. While not strictly required, it is always set here
    mime_type: Mime,
    /// The content/body of the part
    contents: Vec<u8>,
}

impl Part {
    /// Create a new part with `Content-Type` of `text/plain` with the supplied name and contents.
    ///
    /// This form will not have a defined file name.
    ///
    /// # Examples
    ///
    /// ```rust
    /// use axum_extra::response::multiple::{MultipartForm, Part};
    ///
    /// // create a form with a single part that has a field with a name of "foo",
    /// // and a value of "abc"
    /// let parts: Vec<Part> = vec![Part::text("foo".to_string(), "abc")];
    /// let form = MultipartForm::from_iter(parts);
    /// ```
    #[must_use]
    pub fn text(name: String, contents: &str) -> Self {
        Self {
            name,
            filename: None,
            mime_type: mime::TEXT_PLAIN_UTF_8,
            contents: contents.as_bytes().to_vec(),
        }
    }

    /// Create a new part containing a generic file, with a `Content-Type` of `application/octet-stream`
    /// using the provided file name, field name, and contents.
    ///
    /// If the MIME type of the file is known, consider using `Part::raw_part`.
    ///
    /// # Examples
    ///
    /// ```rust
    /// use axum_extra::response::multiple::{MultipartForm, Part};
    ///
    /// // create a form with a single part that has a field with a name of "foo",
    /// // with a file name of "foo.txt", and with the specified contents
    /// let parts: Vec<Part> = vec![Part::file("foo", "foo.txt", vec![0x68, 0x68, 0x20, 0x6d, 0x6f, 0x6d])];
    /// let form = MultipartForm::from_iter(parts);
    /// ```
    #[must_use]
    pub fn file(field_name: &str, file_name: &str, contents: Vec<u8>) -> Self {
        Self {
            name: field_name.to_owned(),
            filename: Some(file_name.to_owned()),
            // If the `MIME` type is not known or specified, then the MIME type should be set to `application/octet-stream`.
            // See RFC2388 section 3 for specifics.
            mime_type: mime::APPLICATION_OCTET_STREAM,
            contents,
        }
    }

    /// Create a new part with more fine-grained control over the semantics of that part.
    ///
    /// The caller is assumed to have set a valid MIME type.
    ///
    /// This function will return an error if the provided MIME type is not valid.
    ///
    /// # Examples
    ///
    /// ```rust
    /// use axum_extra::response::multiple::{MultipartForm, Part};
    ///
    /// // create a form with a single part that has a field with a name of "part_name",
    /// // with a MIME type of "application/json", and the supplied contents.
    /// let parts: Vec<Part> = vec![Part::raw_part("part_name", "application/json", vec![0x68, 0x68, 0x20, 0x6d, 0x6f, 0x6d], None).expect("MIME type must be valid")];
    /// let form = MultipartForm::from_iter(parts);
    /// ```
    pub fn raw_part(
        name: &str,
        mime_type: &str,
        contents: Vec<u8>,
        filename: Option<&str>,
    ) -> Result<Self, &'static str> {
        let mime_type = mime_type.parse().map_err(|_| "Invalid MIME type")?;
        Ok(Self {
            name: name.to_owned(),
            filename: filename.map(|f| f.to_owned()),
            mime_type,
            contents,
        })
    }

    /// Prepare this part for multipart serialization.
    fn into_multipart_part(self, boundary: &str) -> Result<multipart::Part, &'static str> {
        // A part is serialized in this general format:
        // // the filename is optional
        // Content-Disposition: form-data; name="FIELD_NAME"; filename="FILENAME"\r\n
        // // the mime type (not strictly required by the spec, but always sent here)
        // Content-Type: mime/type\r\n
        // // a blank line, then the contents of the file start
        // \r\n
        // CONTENTS\r\n

        if contains_newlines(&self.name) {
            return Err("Invalid multipart field name");
        }

        let mut disposition = format!("form-data; name=\"{}\"", EscapedQuotedString(&self.name));
        // specify a filename if one was set
        if let Some(filename) = &self.filename {
            if contains_newlines(filename) {
                return Err("Invalid multipart filename");
            }
            disposition += &format!("; filename=\"{}\"", EscapedQuotedString(filename));
        }
        let content_type = self.mime_type.to_string();
        let part = multipart::Part::new(
            boundary,
            [
                ("Content-Disposition", disposition.as_str()),
                ("Content-Type", content_type.as_str()),
            ],
            body::Body::from(self.contents),
        );

        Ok(part)
    }

    fn contains_boundary(&self, boundary: &str) -> bool {
        let boundary_bytes = boundary.as_bytes();

        self.name.contains(boundary)
            || self
                .filename
                .as_ref()
                .is_some_and(|filename| filename.contains(boundary))
            || self.mime_type.to_string().contains(boundary)
            || self
                .contents
                .windows(boundary_bytes.len())
                .any(|window| window == boundary_bytes)
    }
}

impl FromIterator<Part> for MultipartForm {
    fn from_iter<T: IntoIterator<Item = Part>>(iter: T) -> Self {
        Self {
            parts: iter.into_iter().collect(),
        }
    }
}

// Boundary collisions are extremely unlikely, but response generation should not loop forever
// if the generated candidates keep colliding with part data.
const BOUNDARY_GENERATION_ATTEMPTS: usize = 16;

fn generate_boundary_for_parts(parts: &[Part]) -> Option<String> {
    for _ in 0..BOUNDARY_GENERATION_ATTEMPTS {
        let boundary = generate_boundary();
        if !parts.iter().any(|part| part.contains_boundary(&boundary)) {
            return Some(boundary);
        }
    }

    None
}

/// A boundary is defined as a user-defined (arbitrary) value that does not occur in any of the data.
///
/// Because the specification does not clearly define a methodology for generating boundaries, this implementation
/// follows Reqwest's, and generates a boundary in the format of `XXXXXXXX-XXXXXXXX-XXXXXXXX-XXXXXXXX` where `XXXXXXXX`
/// is a hexadecimal representation of a pseudo randomly generated u64.
fn generate_boundary() -> String {
    let a = fastrand::u64(0..u64::MAX);
    let b = fastrand::u64(0..u64::MAX);
    let c = fastrand::u64(0..u64::MAX);
    let d = fastrand::u64(0..u64::MAX);
    format!("{a:016x}-{b:016x}-{c:016x}-{d:016x}")
}

#[cfg(test)]
mod tests {
    use super::{generate_boundary, MultipartForm, Part};
    use axum::{body::Body, http};
    use axum::{routing::get, Router};
    use axum_core::response::IntoResponse;
    use http::{Request, Response, StatusCode};
    use http_body::Body as _;
    use http_body_util::BodyExt;
    use mime::Mime;
    use tower::ServiceExt;

    #[tokio::test]
    async fn process_form() -> Result<(), Box<dyn std::error::Error>> {
        // create a boilerplate handle that returns a form
        async fn handle() -> MultipartForm {
            let parts: Vec<Part> = vec![
                Part::text("part1".to_owned(), "basictext"),
                Part::file(
                    "part2",
                    "file.txt",
                    vec![0x68, 0x69, 0x20, 0x6d, 0x6f, 0x6d],
                ),
                Part::raw_part("part3", "text/plain", b"rawpart".to_vec(), None).unwrap(),
            ];
            MultipartForm::from_iter(parts)
        }

        // make a request to that handle
        let app = Router::new().route("/", get(handle));
        let response: Response<_> = app
            .oneshot(Request::builder().uri("/").body(Body::empty())?)
            .await?;
        // content_type header
        let ct_header = response.headers().get("content-type").unwrap().to_str()?;
        let boundary = ct_header.split("boundary=").nth(1).unwrap().to_owned();
        let content_length: usize = response
            .headers()
            .get("content-length")
            .unwrap()
            .to_str()?
            .parse()?;
        let body: &[u8] = &response.into_body().collect().await?.to_bytes();
        assert_eq!(content_length, body.len());
        assert_eq!(
            std::str::from_utf8(body)?,
            format!(
                "--{boundary}\r\n\
                Content-Disposition: form-data; name=\"part1\"\r\n\
                Content-Type: text/plain; charset=utf-8\r\n\
                \r\n\
                basictext\r\n\
                --{boundary}\r\n\
                Content-Disposition: form-data; name=\"part2\"; filename=\"file.txt\"\r\n\
                Content-Type: application/octet-stream\r\n\
                \r\n\
                hi mom\r\n\
                --{boundary}\r\n\
                Content-Disposition: form-data; name=\"part3\"\r\n\
                Content-Type: text/plain\r\n\
                \r\n\
                rawpart\r\n\
                --{boundary}--",
            )
        );

        Ok(())
    }

    #[tokio::test]
    async fn multipart_part_escapes_content_disposition_params() {
        let part = Part::file(
            "field\"; injected=\"1",
            "evil\\name\"; filename*=UTF-8''pwned.txt; x=\"",
            b"hi".to_vec(),
        );

        let response = MultipartForm::with_parts(vec![part]).into_response();
        let content_length = response.body().size_hint().exact().unwrap();
        let body = response.into_body().collect().await.unwrap().to_bytes();
        assert_eq!(content_length, body.len() as u64);
        let body = std::str::from_utf8(&body).unwrap();

        assert!(body.contains(
            "Content-Disposition: form-data; name=\"field\\\"; injected=\\\"1\"; filename=\"evil\\\\name\\\"; filename*=UTF-8''pwned.txt; x=\\\"\"\r\n"
        ));
    }

    #[tokio::test]
    async fn multipart_form_rejects_newlines_in_field_metadata(
    ) -> Result<(), Box<dyn std::error::Error>> {
        async fn handle() -> MultipartForm {
            MultipartForm::from_iter(vec![Part::file(
                "bad\r\nx-extra: injected",
                "file.txt",
                b"hi".to_vec(),
            )])
        }

        let app = Router::new().route("/", get(handle));
        let response = app
            .oneshot(Request::builder().uri("/").body(Body::empty())?)
            .await?;

        assert_eq!(response.status(), StatusCode::INTERNAL_SERVER_ERROR);

        let body = response.into_body().collect().await?.to_bytes();
        assert_eq!(&body[..], b"Invalid multipart field name or filename");

        Ok(())
    }

    #[test]
    fn valid_boundary_generation() {
        for _ in 0..256 {
            let boundary = generate_boundary();
            let mime_type: Result<Mime, _> =
                format!("multipart/form-data; boundary={boundary}").parse();
            assert!(
                mime_type.is_ok(),
                "The generated boundary was unable to be parsed into a valid mime type."
            );
        }
    }

    #[tokio::test]
    async fn generated_boundary_does_not_appear_in_part_contents() {
        fastrand::seed(0);
        let colliding_boundary = generate_boundary();
        let colliding_boundary_marker = format!("--{colliding_boundary}");
        let contents = format!("before\r\n{colliding_boundary_marker}\r\nafter");
        let parts = vec![Part::text("part".to_owned(), &contents)];

        fastrand::seed(0);
        let response = MultipartForm::from_iter(parts).into_response();
        let content_type = response
            .headers()
            .get("content-type")
            .unwrap()
            .to_str()
            .unwrap();
        let boundary = content_type.split("boundary=").nth(1).unwrap().to_owned();
        assert_ne!(boundary, colliding_boundary);

        let body = response.into_body().collect().await.unwrap().to_bytes();
        let body = std::str::from_utf8(&body).unwrap();
        let boundary_marker = format!("--{boundary}");

        assert_eq!(body.matches(&boundary_marker).count(), 2);
        assert_eq!(body.matches(&colliding_boundary_marker).count(), 1);
    }
}