Skip to main content

objectstore_server/
multipart.rs

1//! Types and utilities to support Multipart streaming responses.
2//!
3//! Compared to `axum_extra::response::MultipartForm`, this implementation supports attaching arbitrary headers to
4//! each part, as well as the possibility to convert a `Stream` of those parts to a streaming `Response`.
5
6use axum::body::Body;
7use axum::response::IntoResponse as _;
8use axum::response::Response;
9use bytes::{BufMut, Bytes, BytesMut};
10use futures::Stream;
11use futures::StreamExt;
12use futures::stream::BoxStream;
13use http::HeaderMap;
14use http::HeaderValue;
15use http::header::{CONTENT_DISPOSITION, CONTENT_TYPE};
16
17/// Error returned when a part name or filename cannot be serialized into a `Content-Disposition`.
18///
19/// Names and filenames are emitted verbatim inside double quotes, so they must be ASCII and must
20/// not contain `"`, `\`, CR, LF or other control characters.
21#[derive(Debug, thiserror::Error)]
22#[error("invalid multipart {field} {value:?}: must match `[ !#-\\[\\]-~]+`")]
23pub struct InvalidPartName {
24    field: &'static str,
25    value: String,
26}
27
28/// A part in a Multipart response.
29#[derive(Debug)]
30pub struct Part {
31    headers: HeaderMap,
32    body: Bytes,
33}
34
35impl Part {
36    /// Creates a part named `part` with the given body, extra headers and content type.
37    ///
38    /// It serializes as `Content-Disposition: form-data; name="part"`. See [`Part::named`] for
39    /// custom names.
40    pub fn new(body: Bytes, headers: HeaderMap, content_type: Option<HeaderValue>) -> Self {
41        // Insert after extending so callers cannot override the disposition or content type.
42        let mut part = Self { headers, body };
43        part.headers.insert(
44            CONTENT_DISPOSITION,
45            HeaderValue::from_static("form-data; name=\"part\""),
46        );
47        if let Some(content_type) = content_type {
48            part.headers.insert(CONTENT_TYPE, content_type);
49        }
50        part
51    }
52
53    /// Creates a part carrying only `Content-Disposition` and an optional `Content-Type`.
54    ///
55    /// The disposition serializes exactly as `form-data; name="<name>"`, or
56    /// `form-data; name="<name>"; filename="<filename>"` when a filename is given.
57    ///
58    /// # Errors
59    ///
60    /// Returns [`InvalidPartName`] if `name` or `filename` is empty or contains characters that
61    /// cannot be written verbatim into a quoted header value.
62    pub fn named(
63        name: &str,
64        body: Bytes,
65        filename: Option<&str>,
66        content_type: Option<HeaderValue>,
67    ) -> Result<Self, InvalidPartName> {
68        let mut headers = HeaderMap::new();
69        headers.insert(CONTENT_DISPOSITION, content_disposition(name, filename)?);
70        if let Some(content_type) = content_type {
71            headers.insert(CONTENT_TYPE, content_type);
72        }
73        Ok(Self { headers, body })
74    }
75}
76
77fn validate(field: &'static str, value: &str) -> Result<(), InvalidPartName> {
78    if !value.is_empty()
79        && value
80            .bytes()
81            .all(|b| (b.is_ascii_graphic() || b == b' ') && b != b'"' && b != b'\\')
82    {
83        Ok(())
84    } else {
85        Err(InvalidPartName {
86            field,
87            value: value.to_owned(),
88        })
89    }
90}
91
92/// Validates the inputs and builds `form-data; name="<name>"[; filename="<filename>"]`.
93fn content_disposition(name: &str, filename: Option<&str>) -> Result<HeaderValue, InvalidPartName> {
94    validate("name", name)?;
95    if let Some(filename) = filename {
96        validate("filename", filename)?;
97    }
98    let value = match filename {
99        Some(filename) => format!("form-data; name=\"{name}\"; filename=\"{filename}\""),
100        None => format!("form-data; name=\"{name}\""),
101    };
102    // Unreachable after validation, as printable ASCII is a valid header value.
103    HeaderValue::from_str(&value).map_err(|_| InvalidPartName {
104        field: "content-disposition",
105        value,
106    })
107}
108
109/// Converts a stream of [`Part`]s into a streaming `multipart/form-data` HTTP response.
110///
111/// Implemented for any `Stream<Item = T>` where `T: Into<Part>`. The boundary is
112/// formatted as `os-boundary-<hex>` using the provided `u128` value.
113pub trait IntoMultipartResponse {
114    /// Consumes `self` and returns a streaming `multipart/form-data` response.
115    ///
116    /// The `boundary` parameter is formatted as `os-boundary-<hex>` and embedded in the
117    /// `Content-Type` header. Each item yielded by the stream becomes one part, separated
118    /// by that boundary. A closing boundary is appended after the last item.
119    fn into_multipart_response(self, boundary: u128) -> Response;
120}
121
122impl<S, T> IntoMultipartResponse for S
123where
124    S: Stream<Item = T> + Send + 'static,
125    T: Into<Part> + Send,
126{
127    fn into_multipart_response(self, boundary: u128) -> Response {
128        let boundary_str = format!("os-boundary-{boundary:032x}");
129        let boundary = {
130            let mut bytes = BytesMut::with_capacity(boundary_str.len() + 4);
131            bytes.put(&b"--"[..]);
132            bytes.put(boundary_str.as_bytes());
133            bytes.put(&b"\r\n"[..]);
134            bytes.freeze()
135        };
136
137        let mut headers = HeaderMap::new();
138        headers.insert(
139            CONTENT_TYPE,
140            format!("multipart/form-data; boundary=\"{}\"", boundary_str)
141                .parse()
142                .expect("valid header value, as we just defined it as \"os-boundary-X\" where X are hex digits"),
143        );
144
145        let body: BoxStream<Result<Bytes, std::convert::Infallible>> = async_stream::try_stream! {
146            let items = self;
147            futures::pin_mut!(items);
148            while let Some(item) = items.next().await {
149                yield boundary.clone();
150                let part = item.into();
151                yield serialize_headers(part.headers);
152                yield serialize_body(part.body);
153            }
154
155            let mut closing = BytesMut::with_capacity(boundary.len());
156            closing.put(boundary.slice(..boundary.len() - 2)); // don't take trailing \r\n
157            closing.put(&b"--"[..]);
158            yield closing.freeze();
159        }
160        .boxed();
161
162        (headers, Body::from_stream(body)).into_response()
163    }
164}
165
166fn serialize_headers(headers: HeaderMap) -> Bytes {
167    // https://github.com/hyperium/hyper/blob/0f0b6ed3ac55ac1682afd2104cb8d0385149249a/src/proto/h1/role.rs#L399
168    let mut res = BytesMut::with_capacity(30 + 30 * headers.len());
169    for (name, value) in &headers {
170        res.put(name.as_str().as_bytes());
171        res.put(&b": "[..]);
172        res.put(value.as_bytes());
173        res.put(&b"\r\n"[..]);
174    }
175    res.put(&b"\r\n"[..]);
176    res.freeze()
177}
178
179fn serialize_body(body: Bytes) -> Bytes {
180    let mut res = BytesMut::with_capacity(body.len() + 2);
181    res.put(body);
182    res.put(&b"\r\n"[..]);
183    res.freeze()
184}
185
186#[cfg(test)]
187mod tests {
188    use super::*;
189    use axum::body::{Body, to_bytes};
190    use axum::extract::{FromRequest, Multipart};
191    use axum::http::Request;
192
193    #[test]
194    fn test_named_content_disposition() {
195        let json = || Some(HeaderValue::from_static("application/json"));
196        let cases = [
197            ("0", None, None, r#"form-data; name="0""#),
198            ("1", None, json(), r#"form-data; name="1""#),
199            (
200                "1.payload",
201                Some("a b.bin"),
202                None,
203                r#"form-data; name="1.payload"; filename="a b.bin""#,
204            ),
205        ];
206        for (name, filename, content_type, expected) in cases {
207            let has_type = content_type.is_some();
208            let part = Part::named(name, Bytes::new(), filename, content_type).unwrap();
209            assert_eq!(part.headers[CONTENT_DISPOSITION], expected);
210            assert_eq!(part.headers.len(), 1 + usize::from(has_type));
211        }
212    }
213
214    #[test]
215    fn test_legacy_part_name_is_quoted() {
216        let part = Part::new(Bytes::new(), HeaderMap::new(), None);
217        assert_eq!(
218            part.headers[CONTENT_DISPOSITION],
219            r#"form-data; name="part""#
220        );
221    }
222
223    #[test]
224    fn test_named_rejects_unsafe_values() {
225        for bad in ["", "a\"b", "a\\b", "a\r\nb", "a\nb", "รค", "a\0b", "a\tb"] {
226            assert!(
227                Part::named(bad, Bytes::new(), None, None).is_err(),
228                "{bad:?}"
229            );
230            assert!(
231                Part::named("ok", Bytes::new(), Some(bad), None).is_err(),
232                "{bad:?}"
233            );
234        }
235    }
236
237    /// Validates that our `Multipart` streaming response produces a valid `multipart/form-data` response
238    /// that's parsed as expected by `axum::extract::Multipart`.
239    #[tokio::test]
240    async fn test_multipart_response() {
241        let mut extra_headers = HeaderMap::new();
242        extra_headers.insert("X-Custom-Header", "custom-value".parse().unwrap());
243        extra_headers.insert("X-File-Id", "12345".parse().unwrap());
244        let parts = vec![
245            Part::new(
246                Bytes::from(r#"{"key":"value"}"#),
247                HeaderMap::new(),
248                Some(HeaderValue::from_static("application/json")),
249            ),
250            Part::new(
251                Bytes::from(vec![0x00, 0x01, 0x02, 0xff, 0xfe]),
252                extra_headers,
253                Some(HeaderValue::from_static("application/octet-stream")),
254            ),
255            Part::named("1.payload", Bytes::from("x"), Some("f.bin"), None).unwrap(),
256        ];
257        let boundary: u128 = 0xdeadbeef;
258        let response = futures::stream::iter(parts).into_multipart_response(boundary);
259
260        let boundary = format!("os-boundary-{boundary:032x}");
261        let content_type_str = format!("multipart/form-data; boundary=\"{boundary}\"");
262        assert_eq!(
263            response
264                .headers()
265                .get(CONTENT_TYPE)
266                .unwrap()
267                .to_str()
268                .unwrap(),
269            &content_type_str
270        );
271
272        let body = to_bytes(response.into_body(), usize::MAX).await.unwrap();
273        let request = Request::builder()
274            .header(CONTENT_TYPE, &content_type_str)
275            .body(Body::from(body))
276            .unwrap();
277        let mut multipart = Multipart::from_request(request, &()).await.unwrap();
278
279        let field = multipart.next_field().await.unwrap().unwrap();
280        assert_eq!(field.name(), Some("part"));
281        assert_eq!(field.file_name(), None);
282        assert_eq!(field.content_type(), Some("application/json"));
283        assert_eq!(field.headers().len(), 2);
284        assert_eq!(field.bytes().await.unwrap(), r#"{"key":"value"}"#);
285
286        let field = multipart.next_field().await.unwrap().unwrap();
287        assert_eq!(field.name(), Some("part"));
288        assert_eq!(field.file_name(), None);
289        assert_eq!(field.content_type(), Some("application/octet-stream"));
290        assert_eq!(field.headers().len(), 4);
291        assert_eq!(
292            field.headers().get("X-Custom-Header").unwrap(),
293            "custom-value"
294        );
295        assert_eq!(field.headers().get("X-File-Id").unwrap(), "12345");
296        assert!(field.headers().get("content-disposition").is_some());
297        assert!(field.headers().get("content-type").is_some());
298        assert_eq!(
299            field.bytes().await.unwrap(),
300            vec![0x00, 0x01, 0x02, 0xff, 0xfe]
301        );
302
303        let field = multipart.next_field().await.unwrap().unwrap();
304        assert_eq!(field.name(), Some("1.payload"));
305        assert_eq!(field.file_name(), Some("f.bin"));
306        assert_eq!(field.bytes().await.unwrap(), "x");
307
308        assert!(multipart.next_field().await.unwrap().is_none());
309    }
310}