use std::{
collections::{VecDeque, hash_map::RandomState},
fmt,
hash::BuildHasher,
io::{Error as IoError, ErrorKind as IoErrorKind},
path::Path,
pin::Pin,
sync::atomic::{AtomicU64, Ordering},
task::{Context, Poll},
time::{SystemTime, UNIX_EPOCH},
};
use http::{
HeaderMap, HeaderName, HeaderValue,
header::{CONTENT_DISPOSITION, CONTENT_TYPE},
};
use mime::Mime;
#[cfg(feature = "json")]
use serde::Serialize;
use tokio::{
fs::File,
io::{AsyncRead, ReadBuf},
};
use crate::{Body, BodyChunk, BodyFrame, BodySource, Error, ErrorKind, Result};
const FILE_CHUNK_SIZE: usize = 64 * 1024;
#[derive(Default)]
pub struct Multipart {
parts: Vec<Part>,
}
pub struct Part {
name: String,
file_name: Option<String>,
headers: HeaderMap,
body: PartBody,
}
enum PartBody {
Body(Body),
File { file: File, length: u64 },
}
impl fmt::Debug for Multipart {
fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
formatter
.debug_struct("Multipart")
.field("part_count", &self.parts.len())
.finish()
}
}
impl fmt::Debug for Part {
fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
formatter
.debug_struct("Part")
.field("has_name", &!self.name.is_empty())
.field("has_file_name", &self.file_name.is_some())
.field("header_count", &self.headers.len())
.field("body", &self.body)
.finish()
}
}
impl fmt::Debug for PartBody {
fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
match self {
Self::Body(body) => formatter
.debug_struct("PartBody")
.field("kind", &"body")
.field("len", &body.len())
.finish(),
Self::File { length, .. } => formatter
.debug_struct("PartBody")
.field("kind", &"file")
.field("length", length)
.finish(),
}
}
}
impl Multipart {
#[must_use]
pub fn new() -> Self {
Self::default()
}
#[must_use]
pub fn part(mut self, part: Part) -> Self {
self.parts.push(part);
self
}
#[must_use]
pub fn text(self, name: impl Into<String>, value: impl Into<String>) -> Self {
self.part(Part::text(name, value))
}
#[must_use]
pub fn bytes(self, name: impl Into<String>, bytes: impl Into<Vec<u8>>) -> Self {
self.part(Part::bytes(name, bytes))
}
#[cfg(feature = "json")]
pub fn json<T>(self, name: impl Into<String>, value: &T) -> Result<Self>
where
T: Serialize + ?Sized,
{
Ok(self.part(Part::json(name, value)?))
}
pub async fn file(self, name: impl Into<String>, path: impl AsRef<Path>) -> Result<Self> {
Ok(self.part(Part::file(name, path).await?))
}
#[must_use]
pub fn len(&self) -> usize {
self.parts.len()
}
#[must_use]
pub fn is_empty(&self) -> bool {
self.parts.is_empty()
}
pub(crate) fn encode(self) -> Result<(HeaderValue, Body)> {
let boundary = select_boundary_with(&self.parts, fresh_boundary);
let mut segments = VecDeque::new();
for part in self.parts {
validate_part(&part)?;
let prefix = encode_part_prefix(&boundary, &part);
segments.push_back(Segment::Bytes(prefix));
match part.body {
PartBody::Body(body) => segments.push_back(Segment::Body(body)),
PartBody::File { file, length } => {
segments.push_back(Segment::File(FileSegment {
file,
remaining: length,
}));
}
}
segments.push_back(Segment::Bytes(b"\r\n".to_vec()));
}
segments.push_back(Segment::Bytes(format!("--{boundary}--\r\n").into_bytes()));
let content_type =
HeaderValue::from_str(&format!("multipart/form-data; boundary={boundary}"))?;
Ok((content_type, Body::stream(MultipartSource { segments })))
}
}
impl Part {
#[must_use]
pub fn new(name: impl Into<String>, body: impl Into<Body>) -> Self {
Self {
name: name.into(),
file_name: None,
headers: HeaderMap::new(),
body: PartBody::Body(body.into()),
}
}
#[must_use]
pub fn text(name: impl Into<String>, value: impl Into<String>) -> Self {
Self::new(name, Body::text(value))
}
#[must_use]
pub fn bytes(name: impl Into<String>, bytes: impl Into<Vec<u8>>) -> Self {
Self::new(name, Body::bytes(bytes))
}
pub async fn file(name: impl Into<String>, path: impl AsRef<Path>) -> Result<Self> {
tokio::runtime::Handle::try_current().map_err(|_| {
Error::new(
ErrorKind::Runtime,
"multipart file access requires an active asynchronous runtime",
)
})?;
let path = path.as_ref();
let file = File::open(path).await?;
let metadata = file.metadata().await?;
if !metadata.is_file() {
return Err(Error::invalid_request(
"multipart file path must refer to a regular file",
));
}
let part = Self {
name: name.into(),
file_name: None,
headers: HeaderMap::new(),
body: PartBody::File {
file,
length: metadata.len(),
},
};
let part = match path.file_name() {
Some(file_name) => part.file_name(file_name.to_string_lossy()),
None => part,
};
let content_type = mime_guess::from_path(path).first_or_octet_stream();
part.content_type(content_type.as_ref())
}
#[cfg(feature = "json")]
pub fn json<T>(name: impl Into<String>, value: &T) -> Result<Self>
where
T: Serialize + ?Sized,
{
Self::new(name, Body::json(value)?).content_type("application/json")
}
#[must_use]
pub fn file_name(mut self, file_name: impl Into<String>) -> Self {
self.file_name = Some(file_name.into());
self
}
pub fn header<K, V>(mut self, name: K, value: V) -> Result<Self>
where
K: TryInto<HeaderName>,
K::Error: Into<Error>,
V: TryInto<HeaderValue>,
V::Error: Into<Error>,
{
let name = name.try_into().map_err(Into::into)?;
let value = value.try_into().map_err(Into::into)?;
if name == CONTENT_DISPOSITION {
return Err(Error::invalid_request(
"multipart Content-Disposition is generated from the part name",
));
}
if is_unsupported_content_header(&name) {
return Err(Error::invalid_request(
"multipart parts do not support other Content-* headers",
));
}
if name == CONTENT_TYPE {
validate_media_type_header(&value)?;
}
self.headers.append(name, value);
Ok(self)
}
#[must_use]
pub fn headers(mut self, headers: HeaderMap) -> Self {
self.headers.extend(headers);
self
}
pub fn content_type(mut self, content_type: impl Into<String>) -> Result<Self> {
let content_type = content_type.into();
let content_type = content_type.parse::<Mime>().map_err(|_| {
Error::invalid_request("multipart part content type must be a valid media type")
})?;
let content_type = HeaderValue::from_str(content_type.as_ref())?;
self.headers.insert(CONTENT_TYPE, content_type);
Ok(self)
}
}
fn fresh_boundary() -> String {
static COUNTER: AtomicU64 = AtomicU64::new(0);
let count = COUNTER.fetch_add(1, Ordering::Relaxed);
let nanos = SystemTime::now()
.duration_since(UNIX_EPOCH)
.map_or(0, |duration| duration.as_nanos());
let process = std::process::id();
let first = RandomState::new().hash_one((nanos, count, process, 0_u8));
let second = RandomState::new().hash_one((nanos, count, process, 1_u8));
let third = RandomState::new().hash_one((nanos, count, process, 2_u8));
let fourth = RandomState::new().hash_one((nanos, count, process, 3_u8));
format!("tez-{first:016x}{second:016x}{third:016x}{fourth:016x}")
}
fn select_boundary_with(parts: &[Part], mut next_candidate: impl FnMut() -> String) -> String {
loop {
let candidate = next_candidate();
let candidate_bytes = candidate.as_bytes();
let conflicts = parts.iter().any(|part| match &part.body {
PartBody::Body(body) => body.as_bytes().is_some_and(|bytes| {
bytes
.windows(candidate_bytes.len())
.any(|window| window == candidate_bytes)
}),
PartBody::File { .. } => false,
});
if !conflicts {
return candidate;
}
}
}
fn validate_part(part: &Part) -> Result<()> {
if part.name.is_empty() {
return Err(Error::invalid_request("multipart field name is required"));
}
if part.headers.contains_key(CONTENT_DISPOSITION) {
return Err(Error::invalid_request(
"multipart Content-Disposition is generated from the part name",
));
}
if part.headers.keys().any(is_unsupported_content_header) {
return Err(Error::invalid_request(
"multipart parts do not support other Content-* headers",
));
}
let mut content_types = part.headers.get_all(CONTENT_TYPE).iter();
if let Some(content_type) = content_types.next() {
validate_media_type_header(content_type)?;
}
if content_types.next().is_some() {
return Err(Error::invalid_request(
"multipart parts may contain only one Content-Type",
));
}
Ok(())
}
fn is_unsupported_content_header(name: &HeaderName) -> bool {
*name != CONTENT_TYPE && *name != CONTENT_DISPOSITION && name.as_str().starts_with("content-")
}
fn validate_media_type_header(value: &HeaderValue) -> Result<()> {
let value = value.to_str().map_err(|_| {
Error::invalid_request("multipart part content type must be a valid media type")
})?;
value.parse::<Mime>().map_err(|_| {
Error::invalid_request("multipart part content type must be a valid media type")
})?;
Ok(())
}
fn encode_part_prefix(boundary: &str, part: &Part) -> Vec<u8> {
let mut bytes = Vec::new();
bytes.extend_from_slice(b"--");
bytes.extend_from_slice(boundary.as_bytes());
bytes.extend_from_slice(b"\r\nContent-Disposition: form-data; name=\"");
write_quoted_parameter(&mut bytes, &part.name);
bytes.extend_from_slice(b"\"");
if let Some(file_name) = &part.file_name {
bytes.extend_from_slice(b"; filename=\"");
write_quoted_parameter(&mut bytes, file_name);
bytes.extend_from_slice(b"\"");
}
bytes.extend_from_slice(b"\r\n");
write_part_headers(&mut bytes, &part.headers);
bytes.extend_from_slice(b"\r\n");
bytes
}
fn write_part_headers(bytes: &mut Vec<u8>, headers: &HeaderMap) {
for value in headers.get_all(CONTENT_TYPE) {
write_header_line(bytes, "Content-Type", value);
}
for (name, value) in headers {
if *name != CONTENT_TYPE && *name != CONTENT_DISPOSITION {
write_header_line(bytes, name.as_str(), value);
}
}
}
fn write_header_line(bytes: &mut Vec<u8>, name: &str, value: &HeaderValue) {
bytes.extend_from_slice(name.as_bytes());
bytes.extend_from_slice(b": ");
bytes.extend_from_slice(value.as_bytes());
bytes.extend_from_slice(b"\r\n");
}
fn write_quoted_parameter(bytes: &mut Vec<u8>, value: &str) {
for byte in value.bytes() {
match byte {
b'"' | b'\\' => {
bytes.push(b'\\');
bytes.push(byte);
}
b'%' | 0..=31 | 127..=u8::MAX => write_percent_encoded(bytes, byte),
_ => bytes.push(byte),
}
}
}
fn write_percent_encoded(bytes: &mut Vec<u8>, byte: u8) {
const HEX: &[u8; 16] = b"0123456789ABCDEF";
bytes.push(b'%');
bytes.push(HEX[usize::from(byte >> 4)]);
bytes.push(HEX[usize::from(byte & 0x0f)]);
}
#[derive(Debug)]
struct MultipartSource {
segments: VecDeque<Segment>,
}
#[derive(Debug)]
enum Segment {
Bytes(Vec<u8>),
Body(Body),
File(FileSegment),
}
impl Segment {
fn len(&self) -> Option<u64> {
match self {
Self::Bytes(bytes) => u64::try_from(bytes.len()).ok(),
Self::Body(body) => body.len().or_else(|| body.is_absent().then_some(0)),
Self::File(file) => Some(file.remaining),
}
}
fn try_clone(&self) -> Option<Self> {
match self {
Self::Bytes(bytes) => Some(Self::Bytes(bytes.clone())),
Self::Body(body) => body.try_clone().map(Self::Body),
Self::File(_) => None,
}
}
}
#[derive(Debug)]
struct FileSegment {
file: File,
remaining: u64,
}
impl BodySource for MultipartSource {
fn poll_frame(
mut self: Pin<&mut Self>,
cx: &mut Context<'_>,
) -> Poll<Result<Option<BodyFrame>>> {
loop {
let (chunk, finished) = match self.segments.front_mut() {
None => return Poll::Ready(Ok(None)),
Some(Segment::Bytes(bytes)) => {
let bytes = std::mem::take(bytes);
let chunk = if bytes.is_empty() {
None
} else {
Some(BodyChunk::new(bytes))
};
(chunk, true)
}
Some(Segment::Body(body)) => match Pin::new(body).poll_frame(cx) {
Poll::Pending => return Poll::Pending,
Poll::Ready(Err(error)) => return Poll::Ready(Err(error)),
Poll::Ready(Ok(Some(BodyFrame::Data(chunk)))) => (Some(chunk), false),
Poll::Ready(Ok(Some(BodyFrame::Trailers(_)))) => {
return Poll::Ready(Err(Error::invalid_request(
"multipart part bodies cannot contain HTTP trailers",
)));
}
Poll::Ready(Ok(None)) => (None, true),
},
Some(Segment::File(file)) => match poll_file_chunk(file, cx) {
Poll::Pending => return Poll::Pending,
Poll::Ready(result) => match result {
Ok(result) => result,
Err(error) => return Poll::Ready(Err(error)),
},
},
};
if finished {
self.segments.pop_front();
}
if let Some(chunk) = chunk {
return Poll::Ready(Ok(Some(BodyFrame::Data(chunk))));
}
}
}
fn len(&self) -> Option<u64> {
self.segments
.iter()
.try_fold(0_u64, |total, segment| total.checked_add(segment.len()?))
}
fn try_clone(&self) -> Option<Box<dyn BodySource>> {
let segments = self
.segments
.iter()
.map(Segment::try_clone)
.collect::<Option<VecDeque<_>>>()?;
Some(Box::new(Self { segments }))
}
}
fn poll_file_chunk(
file: &mut FileSegment,
cx: &mut Context<'_>,
) -> Poll<Result<(Option<BodyChunk>, bool)>> {
if file.remaining == 0 {
return Poll::Ready(Ok((None, true)));
}
let capacity = usize::try_from(file.remaining)
.unwrap_or(usize::MAX)
.min(FILE_CHUNK_SIZE);
let mut bytes = vec![0; capacity];
let read = {
let mut read_buffer = ReadBuf::new(&mut bytes);
match Pin::new(&mut file.file).poll_read(cx, &mut read_buffer) {
Poll::Pending => return Poll::Pending,
Poll::Ready(Err(error)) => return Poll::Ready(Err(error.into())),
Poll::Ready(Ok(())) => {}
}
read_buffer.filled().len()
};
if read == 0 {
return Poll::Ready(Err(IoError::new(
IoErrorKind::UnexpectedEof,
"multipart file ended before its captured length",
)
.into()));
}
bytes.truncate(read);
file.remaining -= u64::try_from(read).expect("read byte count fits u64");
Poll::Ready(Ok((Some(BodyChunk::new(bytes)), file.remaining == 0)))
}
#[cfg(test)]
mod describe_multipart {
use super::*;
#[test]
fn it_multipart_debug_redacts_names_headers_and_values() {
let multipart = Multipart::new().part(
Part::text("secret-name", "secret-value")
.file_name("secret-file.txt")
.header("x-secret", "secret-header")
.unwrap(),
);
let debug = format!("{multipart:?}");
for secret in [
"secret-name",
"secret-value",
"secret-file.txt",
"secret-header",
] {
assert!(!debug.contains(secret), "debug leaked {secret}: {debug}");
}
}
async fn encode(multipart: Multipart) -> (String, Vec<Vec<u8>>, Option<u64>) {
let (content_type, mut body) = multipart.encode().unwrap();
let length = body.len();
let mut chunks = Vec::new();
while let Some(chunk) = body.next_chunk().await.unwrap() {
chunks.push(chunk.into_bytes());
}
(content_type.to_str().unwrap().to_owned(), chunks, length)
}
async fn body_text(multipart: Multipart) -> String {
let (_, chunks, _) = encode(multipart).await;
String::from_utf8(chunks.concat()).unwrap()
}
mod describe_multipart_builder {
use super::*;
#[test]
fn it_starts_empty() {
let multipart = Multipart::new();
assert!(multipart.is_empty());
assert_eq!(multipart.len(), 0);
}
#[test]
fn it_appends_text_and_byte_parts() {
let multipart = Multipart::new()
.text("name", "nous")
.bytes("blob", b"abc".to_vec());
assert!(!multipart.is_empty());
assert_eq!(multipart.len(), 2);
}
#[cfg(feature = "json")]
#[tokio::test]
async fn it_appends_json_parts() {
let body = body_text(
Multipart::new()
.json("meta", &serde_json::json!({ "ok": true }))
.unwrap(),
)
.await;
assert!(body.contains("name=\"meta\""));
assert!(body.contains("Content-Type: application/json"));
assert!(body.contains(r#"{"ok":true}"#));
}
#[cfg(feature = "json")]
#[test]
fn it_returns_json_serialization_errors() {
let value = std::collections::HashMap::from([((1, 2), "not a string key")]);
let error = Multipart::new().json("meta", &value).unwrap_err();
assert_eq!(error.kind(), ErrorKind::Request);
}
#[tokio::test]
async fn it_file_parts_remain_streaming_after_async_open() {
let path = temp_file("tez-avatar-streaming.png", b"image-bytes");
let multipart = Multipart::new().file("avatar", &path).await.unwrap();
assert!(matches!(&multipart.parts[0].body, PartBody::File { .. }));
drop(multipart);
std::fs::remove_file(&path).unwrap();
}
#[tokio::test]
async fn it_file_parts_have_required_content_disposition() {
let path = temp_file("tez-avatar.png", b"image-bytes");
let multipart = Multipart::new().file("avatar", &path).await.unwrap();
let body = body_text(multipart).await;
std::fs::remove_file(&path).unwrap();
assert!(body.contains(
"Content-Disposition: form-data; name=\"avatar\"; filename=\"tez-avatar.png\""
));
}
}
mod describe_part_builder {
use super::*;
#[cfg(feature = "json")]
#[tokio::test]
async fn it_builds_text_byte_and_json_parts() {
let text = Part::text("name", "nous");
let bytes = Part::bytes("blob", b"abc".to_vec());
let json = Part::json("meta", &serde_json::json!({ "ok": true })).unwrap();
let body = body_text(Multipart::new().part(text).part(bytes).part(json)).await;
assert!(body.contains("name=\"name\""));
assert!(body.contains("nous"));
assert!(body.contains("name=\"blob\""));
assert!(body.contains("abc"));
assert!(body.contains("name=\"meta\""));
assert!(body.contains("Content-Type: application/json"));
assert!(body.contains(r#"{"ok":true}"#));
}
#[tokio::test]
async fn it_sets_file_name_and_content_type() {
let part = Part::bytes("avatar", b"image".to_vec())
.file_name("avatar.png")
.content_type("image/png")
.unwrap();
let body = body_text(Multipart::new().part(part)).await;
assert!(body.contains(
"Content-Disposition: form-data; name=\"avatar\"; filename=\"avatar.png\""
));
assert!(body.contains("Content-Type: image/png"));
}
#[tokio::test]
async fn it_streams_file_parts_with_inferred_metadata() {
let path = temp_file("tez-upload.txt", b"hello");
let part = Part::file("upload", &path).await.unwrap();
let body = body_text(Multipart::new().part(part)).await;
std::fs::remove_file(&path).unwrap();
assert!(body.contains(
"Content-Disposition: form-data; name=\"upload\"; filename=\"tez-upload.txt\""
));
assert!(body.contains("Content-Type: text/plain"));
assert!(body.contains("hello"));
}
#[tokio::test]
async fn it_returns_file_read_errors() {
let path = std::env::temp_dir()
.join(format!("tez-{}", std::process::id()))
.join("missing-upload.txt");
let error = Part::file("upload", path).await.unwrap_err();
assert_eq!(error.kind(), ErrorKind::BodyIo);
}
#[test]
fn it_file_open_without_a_runtime_returns_a_typed_error() {
use std::task::Waker;
let mut future = Box::pin(Part::file("upload", "not-opened"));
let mut context = Context::from_waker(Waker::noop());
let Poll::Ready(Err(error)) = Future::poll(future.as_mut(), &mut context) else {
panic!("runtime validation must finish on the first poll");
};
assert_eq!(error.kind(), ErrorKind::Runtime);
assert_eq!(
error.to_string(),
"runtime error: multipart file access requires an active asynchronous runtime"
);
assert!(!error.to_string().contains("tokio"));
}
#[tokio::test]
async fn it_rejects_non_file_paths() {
let path = std::env::temp_dir().join(format!("tez-{}", std::process::id()));
std::fs::create_dir_all(&path).unwrap();
let error = Part::file("upload", path).await.unwrap_err();
assert_eq!(
error.to_string(),
"invalid request: multipart file path must refer to a regular file"
);
}
#[tokio::test]
async fn it_preserves_repeated_allowed_custom_headers() {
let mut headers = HeaderMap::new();
headers.append("x-part", HeaderValue::from_static("one"));
headers.append("x-part", HeaderValue::from_static("two"));
let part = Part::text("field", "value")
.header("x-extra", "yes")
.unwrap()
.headers(headers);
let body = body_text(Multipart::new().part(part)).await;
assert!(body.contains("x-extra: yes"));
assert!(body.contains("x-part: one"));
assert!(body.contains("x-part: two"));
}
#[test]
fn it_returns_header_errors_from_custom_part_headers() {
let name_error = Part::text("field", "value")
.header("bad header", "value")
.unwrap_err();
let value_error = Part::text("field", "value")
.header("x-part", "bad\nvalue")
.unwrap_err();
assert_eq!(name_error.kind(), ErrorKind::Request);
assert_eq!(value_error.kind(), ErrorKind::Request);
}
#[test]
fn it_rejects_invalid_content_types() {
let error = Part::text("field", "value")
.content_type("not-a-media-type")
.unwrap_err();
assert_eq!(
error.to_string(),
"invalid request: multipart part content type must be a valid media type"
);
}
#[test]
fn it_validates_content_type_values_added_as_headers() {
let error = Part::text("field", "value")
.header(CONTENT_TYPE, "not-a-media-type")
.unwrap_err();
assert_eq!(
error.to_string(),
"invalid request: multipart part content type must be a valid media type"
);
}
#[test]
fn it_rejects_caller_content_disposition_headers() {
let error = Part::text("field", "value")
.header(CONTENT_DISPOSITION, "attachment")
.unwrap_err();
assert_eq!(
error.to_string(),
"invalid request: multipart Content-Disposition is generated from the part name"
);
}
#[test]
fn it_rejects_content_disposition_from_header_maps() {
let mut headers = HeaderMap::new();
headers.insert(CONTENT_DISPOSITION, HeaderValue::from_static("attachment"));
let error = Multipart::new()
.part(Part::text("field", "value").headers(headers))
.encode()
.unwrap_err();
assert_eq!(
error.to_string(),
"invalid request: multipart Content-Disposition is generated from the part name"
);
}
#[test]
fn it_rejects_unsupported_multipart_content_headers() {
let error = Part::text("field", "value")
.header("content-id", "part-one")
.unwrap_err();
assert_eq!(
error.to_string(),
"invalid request: multipart parts do not support other Content-* headers"
);
}
}
mod describe_encoding {
use super::*;
#[test]
fn it_generates_a_boundary_within_the_mime_limit() {
let first = fresh_boundary();
assert!(first.len() <= 70);
assert!(first.starts_with("tez-"));
assert!(
first
.bytes()
.all(|byte| byte.is_ascii_alphanumeric() || byte == b'-')
);
}
#[test]
fn it_generates_distinct_multipart_boundaries() {
let first = fresh_boundary();
let second = fresh_boundary();
assert_ne!(first, second);
}
#[tokio::test]
async fn it_shares_the_boundary_between_content_type_and_encoder() {
let (content_type, chunks, _) =
encode(Multipart::new().text("first", "1").text("second", "2")).await;
let boundary = content_type
.strip_prefix("multipart/form-data; boundary=")
.unwrap();
let body = String::from_utf8(chunks.concat()).unwrap();
assert!(body.starts_with(&format!("--{boundary}\r\n")));
assert!(body.ends_with(&format!("--{boundary}--\r\n")));
assert_eq!(body.matches(&format!("--{boundary}")).count(), 3);
}
#[tokio::test]
async fn it_escapes_quoted_parameters_without_header_injection() {
let body = body_text(
Multipart::new().part(
Part::text("field%\"\r\nnamé", "value")
.file_name("a\\b\"\né.txt")
.content_type("text/plain")
.unwrap(),
),
)
.await;
assert!(
body.contains(
r#"name="field%25\"%0D%0Anam%C3%A9"; filename="a\\b\"%0A%C3%A9.txt""#
)
);
}
#[test]
fn it_rejects_empty_part_names() {
let error = Multipart::new()
.part(Part::text("", "value"))
.encode()
.unwrap_err();
assert_eq!(
error.to_string(),
"invalid request: multipart field name is required"
);
}
#[tokio::test]
async fn it_uses_crlf_framing_and_a_closing_delimiter() {
let (content_type, chunks, _) = encode(Multipart::new().text("name", "nous")).await;
let boundary = content_type
.strip_prefix("multipart/form-data; boundary=")
.unwrap();
let body = chunks.concat();
let expected = format!(
"--{boundary}\r\nContent-Disposition: form-data; name=\"name\"\r\n\r\nnous\r\n--{boundary}--\r\n"
);
assert_eq!(body, expected.into_bytes());
}
#[tokio::test]
async fn it_preserves_repeated_fields_in_insertion_order() {
let body = body_text(Multipart::new().text("tag", "first").text("tag", "second")).await;
assert_eq!(body.matches("name=\"tag\"").count(), 2);
assert!(body.find("first").unwrap() < body.find("second").unwrap());
}
#[test]
fn it_excludes_boundaries_found_in_buffered_part_content() {
let colliding = format!("tez-{}", "a".repeat(64));
let safe = format!("tez-{}", "b".repeat(64));
let multipart = Multipart::new().text("field", format!("prefix-{colliding}-suffix"));
let mut candidates = VecDeque::from([colliding, safe.clone()]);
let selected = select_boundary_with(&multipart.parts, || {
candidates
.pop_front()
.expect("test provides a safe candidate")
});
assert_eq!(selected, safe);
assert!(candidates.is_empty());
}
#[tokio::test]
async fn it_multipart_round_trips_through_an_independent_wire_parser() {
let binary = vec![0, 0xff, b'\r', b'\n', b'-', b'x'];
let multipart = Multipart::new()
.text("tag", "first")
.text("tag", "second")
.part(
Part::bytes("blob", binary.clone())
.file_name("blob.bin")
.content_type("application/octet-stream")
.unwrap()
.header("x-part-id", "third")
.unwrap(),
);
let (content_type, chunks, _) = encode(multipart).await;
let encoded = chunks.concat();
let parts = parse_multipart_wire(&content_type, &encoded);
assert_eq!(parts.len(), 3);
assert_eq!(parts[0].disposition, "form-data; name=\"tag\"");
assert_eq!(parts[0].body, b"first");
assert_eq!(parts[1].disposition, "form-data; name=\"tag\"");
assert_eq!(parts[1].body, b"second");
assert_eq!(
parts[2].disposition,
"form-data; name=\"blob\"; filename=\"blob.bin\""
);
assert_eq!(
parts[2].header("content-type"),
Some("application/octet-stream")
);
assert_eq!(parts[2].header("x-part-id"), Some("third"));
assert_eq!(parts[2].body, binary);
}
#[tokio::test]
async fn it_multipart_replays_only_when_every_part_is_replayable() {
let (_, body) = Multipart::new()
.text("first", "one")
.bytes("second", b"two".to_vec())
.encode()
.unwrap();
let replay = body.try_clone().expect("buffered parts are replayable");
let original = body.collect_limited(usize::MAX).await.unwrap();
let replay = replay.collect_limited(usize::MAX).await.unwrap();
assert_eq!(original.as_bytes(), replay.as_bytes());
let source = UnknownLengthSource {
chunks: VecDeque::from([b"one-shot".to_vec()]),
};
let (_, body) = Multipart::new()
.part(Part::new("stream", Body::stream(source)))
.encode()
.unwrap();
assert!(body.try_clone().is_none());
}
#[tokio::test]
async fn it_reports_exact_length_only_when_every_segment_is_known() {
let path = temp_file("tez-length.bin", &[7; FILE_CHUNK_SIZE + 3]);
let multipart = Multipart::new()
.text("name", "nous")
.file("upload", &path)
.await
.unwrap();
let (content_type, chunks, length) = encode(multipart).await;
std::fs::remove_file(path).unwrap();
let body = chunks.concat();
assert!(content_type.starts_with("multipart/form-data; boundary="));
assert_eq!(length, Some(body.len() as u64));
}
#[tokio::test]
async fn it_omits_total_length_for_an_unknown_streaming_part() {
let source = UnknownLengthSource {
chunks: VecDeque::from([b"one".to_vec(), b"two".to_vec()]),
};
let (_, chunks, length) =
encode(Multipart::new().part(Part::new("stream", Body::stream(source)))).await;
assert_eq!(length, None);
assert!(
String::from_utf8(chunks.concat())
.unwrap()
.contains("onetwo")
);
}
#[tokio::test]
async fn it_streams_large_files_in_bounded_chunks() {
let path = temp_file("tez-chunks.bin", &vec![5; FILE_CHUNK_SIZE * 2 + 1]);
let multipart = Multipart::new().file("upload", &path).await.unwrap();
let (_, chunks, _) = encode(multipart).await;
std::fs::remove_file(path).unwrap();
assert!(
chunks
.iter()
.filter(|chunk| chunk.len() == FILE_CHUNK_SIZE)
.count()
>= 2
);
assert!(chunks.iter().all(|chunk| chunk.len() <= FILE_CHUNK_SIZE));
}
}
struct UnknownLengthSource {
chunks: VecDeque<Vec<u8>>,
}
#[derive(Debug)]
struct ParsedPart {
disposition: String,
headers: Vec<(String, String)>,
body: Vec<u8>,
}
impl ParsedPart {
fn header(&self, name: &str) -> Option<&str> {
self.headers
.iter()
.find(|(candidate, _)| candidate.eq_ignore_ascii_case(name))
.map(|(_, value)| value.as_str())
}
}
fn parse_multipart_wire(content_type: &str, wire: &[u8]) -> Vec<ParsedPart> {
let boundary = content_type
.strip_prefix("multipart/form-data; boundary=")
.expect("encoder emits a multipart boundary");
let delimiter = format!("--{boundary}").into_bytes();
let next_delimiter = [b"\r\n".as_slice(), delimiter.as_slice()].concat();
let mut remaining = wire;
let mut parts = Vec::new();
loop {
assert!(remaining.starts_with(&delimiter));
remaining = &remaining[delimiter.len()..];
if remaining.starts_with(b"--\r\n") {
assert_eq!(remaining, b"--\r\n");
break;
}
assert!(remaining.starts_with(b"\r\n"));
remaining = &remaining[2..];
let header_end =
find_bytes(remaining, b"\r\n\r\n").expect("part contains a header terminator");
let header_block =
std::str::from_utf8(&remaining[..header_end]).expect("multipart headers are ASCII");
remaining = &remaining[header_end + 4..];
let body_end =
find_bytes(remaining, &next_delimiter).expect("part is followed by a delimiter");
let body = remaining[..body_end].to_vec();
remaining = &remaining[body_end + 2..];
let mut disposition = None;
let mut headers = Vec::new();
for line in header_block.split("\r\n") {
let (name, value) = line
.split_once(": ")
.expect("part header uses colon-space framing");
if name.eq_ignore_ascii_case("content-disposition") {
disposition = Some(value.to_owned());
} else {
headers.push((name.to_owned(), value.to_owned()));
}
}
parts.push(ParsedPart {
disposition: disposition.expect("part has Content-Disposition"),
headers,
body,
});
}
parts
}
fn find_bytes(haystack: &[u8], needle: &[u8]) -> Option<usize> {
haystack
.windows(needle.len())
.position(|window| window == needle)
}
impl BodySource for UnknownLengthSource {
fn poll_frame(
mut self: Pin<&mut Self>,
_cx: &mut Context<'_>,
) -> Poll<Result<Option<BodyFrame>>> {
Poll::Ready(Ok(self
.chunks
.pop_front()
.map(BodyChunk::new)
.map(BodyFrame::Data)))
}
}
fn temp_file(name: &str, contents: &[u8]) -> std::path::PathBuf {
let directory = std::env::temp_dir().join(format!("tez-{}", std::process::id()));
std::fs::create_dir_all(&directory).unwrap();
let path = directory.join(name);
std::fs::write(&path, contents).unwrap();
path
}
}