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

//! Multipart framing shared by buffered forms and streamed byte ranges.

use axum_core::{body::Body, Error};
use bytes::Bytes;
use http_body::{Body as HttpBody, Frame, SizeHint};
use std::{
    pin::Pin,
    task::{ready, Context, Poll},
};

const CRLF: &[u8] = b"\r\n";

/// A prepared multipart section with buffered framing and a streamed body.
pub(super) struct Part {
    /// Opening boundary, headers, and blank line; excludes the body and its trailing CRLF.
    prefix: Bytes,
    /// Content emitted after the prefix, without buffering it in the encoder.
    body: Body,
}

impl Part {
    /// Build a section prefix from the boundary and headers, leaving `body` untouched.
    ///
    /// Callers must ensure the boundary and header names and values contain no line breaks.
    pub(super) fn new<'a>(
        boundary: &str,
        headers: impl IntoIterator<Item = (&'a str, &'a str)>,
        body: Body,
    ) -> Self {
        let headers = headers.into_iter();
        // Optimistic guess: fixed framing plus about 48 bytes per header; longer values may grow it.
        let mut prefix = Vec::with_capacity(boundary.len() + 6 + headers.size_hint().0 * 48);
        prefix.extend_from_slice(b"--");
        prefix.extend_from_slice(boundary.as_bytes());
        prefix.extend_from_slice(b"\r\n");
        for (name, value) in headers {
            prefix.extend_from_slice(name.as_bytes());
            prefix.extend_from_slice(b": ");
            prefix.extend_from_slice(value.as_bytes());
            prefix.extend_from_slice(b"\r\n");
        }
        prefix.extend_from_slice(b"\r\n");

        Self {
            prefix: prefix.into(),
            body,
        }
    }

    /// Exact remaining length, including framing, if the body has an exact size hint.
    fn content_length(&self) -> Option<u64> {
        (self.prefix.len() as u64)
            .checked_add(self.body.size_hint().exact()?)?
            .checked_add(CRLF.len() as u64)
    }
}

/// A streaming multipart body that derives its size hint from its remaining parts.
///
/// Storage can be a vector for forms or a fixed-size array for file ranges. Consumed parts
/// are cleared, and unknown or overflowing lengths never produce an exact size hint.
pub(super) struct Multipart<P> {
    parts: P,
    index: usize,
    closing: Bytes,
}

impl<P> Multipart<P> {
    /// Build the closing boundary without reading any part bodies.
    ///
    /// File ranges include a final CRLF; forms omit it to preserve their wire format.
    pub(super) fn new(boundary: &str, parts: P, trailing_crlf: bool) -> Self {
        let ending = if trailing_crlf { "\r\n" } else { "" };
        Self {
            parts,
            index: 0,
            closing: Bytes::from(format!("--{boundary}--{ending}")),
        }
    }
}

impl<P> HttpBody for Multipart<P>
where
    P: AsRef<[Option<Part>]> + AsMut<[Option<Part>]> + Unpin,
{
    type Data = Bytes;
    type Error = Error;

    fn poll_frame(
        self: Pin<&mut Self>,
        cx: &mut Context<'_>,
    ) -> Poll<Option<Result<Frame<Self::Data>, Self::Error>>> {
        let this = self.get_mut();
        loop {
            let Some(slot) = this.parts.as_mut().get_mut(this.index) else {
                return Poll::Ready(if this.closing.is_empty() {
                    None
                } else {
                    Some(Ok(Frame::data(std::mem::take(&mut this.closing))))
                });
            };
            let Some(part) = slot else {
                this.index += 1;
                continue;
            };
            if !part.prefix.is_empty() {
                return Poll::Ready(Some(Ok(Frame::data(std::mem::take(&mut part.prefix)))));
            }

            match ready!(Pin::new(&mut part.body).poll_frame(cx)) {
                Some(Ok(frame)) => {
                    // Part trailers are not multipart data, matching the previous data stream.
                    if let Ok(data) = frame.into_data() {
                        return Poll::Ready(Some(Ok(Frame::data(data))));
                    }
                }
                Some(Err(error)) => {
                    this.index = this.parts.as_ref().len();
                    this.closing = Bytes::new();
                    return Poll::Ready(Some(Err(error)));
                }
                None => {
                    *slot = None;
                    this.index += 1;
                    return Poll::Ready(Some(Ok(Frame::data(Bytes::from_static(CRLF)))));
                }
            }
        }
    }

    fn is_end_stream(&self) -> bool {
        self.index == self.parts.as_ref().len() && self.closing.is_empty()
    }

    fn size_hint(&self) -> SizeHint {
        let length = self.parts.as_ref()[self.index..]
            .iter()
            .flatten()
            .try_fold(self.closing.len() as u64, |length, part| {
                length.checked_add(part.content_length()?)
            });
        length.map_or_else(SizeHint::new, SizeHint::with_exact)
    }
}

#[cfg(test)]
mod tests {
    use super::{Multipart, Part};
    use axum_core::body::Body;
    use bytes::Bytes;
    use futures_util::{stream, StreamExt};
    use http_body::{Body as _, Frame, SizeHint};
    use http_body_util::{BodyExt, StreamBody};
    use std::{
        convert::Infallible,
        pin::Pin,
        task::{Context, Poll},
    };

    #[tokio::test]
    async fn exact_size_tracks_remaining_framing_and_data() {
        let cases: &[(&[&[u8]], &[u8])] = &[
            (&[], b"--test--"),
            (&[b""], b"--test\r\n\r\n\r\n--test--"),
            (
                &[b"a", b"bc"],
                b"--test\r\n\r\na\r\n--test\r\n\r\nbc\r\n--test--",
            ),
        ];
        for &(contents, expected) in cases {
            for trailing_crlf in [false, true] {
                let parts: Vec<_> = contents
                    .iter()
                    .map(|contents| {
                        let body = Body::from(Bytes::copy_from_slice(contents));
                        Some(Part::new("test", [], body))
                    })
                    .collect();
                let mut body = Multipart::new("test", parts, trailing_crlf);
                let mut expected = expected.to_vec();
                if trailing_crlf {
                    expected.extend_from_slice(b"\r\n");
                }
                let mut remaining = expected.len() as u64;
                let mut actual = Vec::new();
                assert_eq!(body.size_hint().exact(), Some(remaining));
                while let Some(frame) = body.frame().await {
                    let data = frame.unwrap().into_data().unwrap();
                    remaining -= data.len() as u64;
                    actual.extend_from_slice(&data);
                    assert_eq!(body.size_hint().exact(), Some(remaining));
                    assert_eq!(body.is_end_stream(), remaining == 0);
                }
                assert_eq!(actual, expected);
                assert!(body.is_end_stream());
            }
        }
    }

    #[tokio::test]
    async fn streams_body_chunks_in_order() {
        let chunks = stream::iter([
            Ok::<_, std::io::Error>(Frame::data(Bytes::from_static(b"ab"))),
            Ok(Frame::data(Bytes::from_static(b"cd"))),
            Ok(Frame::trailers(http::HeaderMap::new())),
        ])
        .then(|chunk| async move {
            tokio::task::yield_now().await;
            chunk
        });
        let part = Part::new(
            "test",
            [("Content-Type", "text/plain")],
            Body::new(StreamBody::new(chunks)),
        );
        let mut body = Multipart::new("test", [Some(part), None], false);
        assert_eq!(body.size_hint().exact(), None);

        let collected = (&mut body).collect().await.unwrap();
        assert!(collected.trailers().is_none());
        let bytes = collected.to_bytes();
        assert_eq!(
            bytes.as_ref(),
            b"--test\r\nContent-Type: text/plain\r\n\r\nabcd\r\n--test--"
        );
        assert_eq!(body.size_hint().exact(), Some(0));
        assert!(body.is_end_stream());
    }

    #[tokio::test]
    async fn body_error_stops_before_further_framing() {
        let chunks = stream::iter([
            Ok(Bytes::from_static(b"ab")),
            Err(std::io::Error::other("read failed")),
        ]);
        let parts = [
            Some(Part::new("test", [], Body::from_stream(chunks))),
            Some(Part::new("test", [], Body::from("not sent"))),
        ];
        let mut body = Multipart::new("test", parts, true);
        assert!(body.frame().await.unwrap().is_ok()); // Prefix.
        assert!(body.frame().await.unwrap().is_ok()); // Data.
        assert!(body.frame().await.unwrap().is_err());
        assert!(body.is_end_stream());
        assert_eq!(body.size_hint().exact(), Some(0));
        assert!(body.frame().await.is_none());
    }

    #[test]
    fn overflowing_lengths_have_no_exact_hint() {
        struct PendingBody(u64);

        impl http_body::Body for PendingBody {
            type Data = Bytes;
            type Error = Infallible;

            fn poll_frame(
                self: Pin<&mut Self>,
                _cx: &mut Context<'_>,
            ) -> Poll<Option<Result<Frame<Bytes>, Infallible>>> {
                Poll::Pending
            }

            fn size_hint(&self) -> SizeHint {
                SizeHint::with_exact(self.0)
            }
        }

        for length in [u64::MAX, u64::MAX / 2] {
            let parts = std::array::from_fn::<_, 2, _>(|_| {
                Some(Part::new("test", [], Body::new(PendingBody(length))))
            });
            let body = Multipart::new("test", parts, false);
            assert_eq!(body.size_hint().exact(), None);
        }
    }
}