open-net 0.3.5

A cross-platform async networking library for Rust with HTTP and WebSocket clients, network status monitoring, configurable retries, WebSocket reconnection and heartbeats, and managed client lifecycles. Reuse common networking infrastructure across applications to avoid repeated implementation and debugging, helping save development time and AI coding tokens.
Documentation
//! A small, transport-independent buffered `multipart/form-data` builder.
//!
//! The request worker still consumes `Bytes`, so this API intentionally reads
//! file parts before request admission.  Streaming and one-shot upload bodies
//! belong to the HTTP body work planned separately from these codecs.

use crate::api::error::{ErrorKind, ErrorStage, NetError};
use bytes::Bytes;
use http::HeaderValue;
use std::fmt;
use std::path::Path;

const BOUNDARY_BYTES: usize = 18;

#[derive(Clone)]
enum Part {
    Text {
        name: String,
        value: String,
    },
    Bytes {
        name: String,
        filename: Option<String>,
        value: Bytes,
    },
}

/// A buffered multipart form whose wire representation is independent of
/// reqwest.  The boundary and all part values are owned by this value.
#[derive(Clone)]
pub struct Multipart {
    boundary: String,
    parts: Vec<Part>,
}

impl Default for Multipart {
    fn default() -> Self {
        Self::new()
    }
}

impl fmt::Debug for Multipart {
    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
        let parts = self
            .parts
            .iter()
            .map(|part| match part {
                Part::Text { .. } => "text",
                Part::Bytes { .. } => "bytes",
            })
            .collect::<Vec<_>>();
        formatter
            .debug_struct("Multipart")
            .field("boundary_len", &self.boundary.len())
            .field("part_count", &self.parts.len())
            .field("part_kinds", &parts)
            .finish()
    }
}

impl Multipart {
    /// Create an empty multipart form with an SDK-generated boundary.
    pub fn new() -> Self {
        Self {
            boundary: make_boundary().unwrap_or_else(|_| "open-net-boundary-fallback".to_owned()),
            parts: Vec::new(),
        }
    }

    /// Add a UTF-8 text field.
    pub fn text(
        mut self,
        name: impl Into<String>,
        value: impl Into<String>,
    ) -> Result<Self, NetError> {
        let name = validate_token("multipart.name", name.into())?;
        self.parts.push(Part::Text {
            name,
            value: value.into(),
        });
        Ok(self)
    }

    /// Add a binary field without a filename.
    pub fn bytes(
        mut self,
        name: impl Into<String>,
        value: impl Into<Bytes>,
    ) -> Result<Self, NetError> {
        let name = validate_token("multipart.name", name.into())?;
        self.parts.push(Part::Bytes {
            name,
            filename: None,
            value: value.into(),
        });
        Ok(self)
    }

    /// Add an in-memory file field with a caller-provided filename.
    pub fn file_bytes(
        mut self,
        name: impl Into<String>,
        filename: impl Into<String>,
        value: impl Into<Bytes>,
    ) -> Result<Self, NetError> {
        let name = validate_token("multipart.name", name.into())?;
        let filename = validate_filename(filename.into())?;
        self.parts.push(Part::Bytes {
            name,
            filename: Some(filename),
            value: value.into(),
        });
        Ok(self)
    }

    /// Read a file and add it as a replayable buffered file field.
    pub fn file(self, name: impl Into<String>, path: impl AsRef<Path>) -> Result<Self, NetError> {
        let path = path.as_ref();
        let filename = path
            .file_name()
            .and_then(|value| value.to_str())
            .ok_or_else(|| NetError::input("multipart.filename", "file path has no filename"))?;
        let filename = validate_filename(filename.to_owned())?;
        let value = std::fs::read(path).map_err(|error| {
            NetError::with_source(ErrorKind::Io, error).with_stage(ErrorStage::RequestBuild)
        })?;
        self.file_bytes(name, filename, Bytes::from(value))
    }

    /// Encode this form into a replayable body and its SDK-owned content type.
    pub(crate) fn encode(self) -> Result<(Bytes, HeaderValue), NetError> {
        let mut boundary = self.boundary;
        let mut attempts = 0;
        while self_contains_boundary(&self.parts, &boundary) && attempts < 8 {
            boundary = make_boundary().map_err(|error| {
                NetError::with_source(ErrorKind::Io, error).with_stage(ErrorStage::RequestBuild)
            })?;
            attempts += 1;
        }
        if self_contains_boundary(&self.parts, &boundary) {
            return Err(NetError::input(
                "multipart.boundary",
                "multipart boundary collides with a part",
            ));
        }

        let mut body = Vec::new();
        for part in self.parts {
            body.extend_from_slice(b"--");
            body.extend_from_slice(boundary.as_bytes());
            body.extend_from_slice(b"\r\n");
            match part {
                Part::Text { name, value } => {
                    write_disposition(&mut body, &name, None)?;
                    body.extend_from_slice(b"Content-Type: text/plain; charset=utf-8\r\n\r\n");
                    body.extend_from_slice(value.as_bytes());
                }
                Part::Bytes {
                    name,
                    filename,
                    value,
                } => {
                    write_disposition(&mut body, &name, filename.as_deref())?;
                    body.extend_from_slice(b"Content-Type: application/octet-stream\r\n\r\n");
                    body.extend_from_slice(value.as_ref());
                }
            }
            body.extend_from_slice(b"\r\n");
        }
        body.extend_from_slice(b"--");
        body.extend_from_slice(boundary.as_bytes());
        body.extend_from_slice(b"--\r\n");

        let content_type = HeaderValue::from_str(&format!(
            "multipart/form-data; boundary={boundary}"
        ))
        .map_err(|_| NetError::input("multipart.content-type", "invalid generated boundary"))?;
        Ok((Bytes::from(body), content_type))
    }
}

fn validate_token(field: &'static str, value: String) -> Result<String, NetError> {
    if value.is_empty() || value.chars().any(|character| character.is_control()) {
        return Err(NetError::input(
            field,
            "multipart field name must not be empty or contain control characters",
        ));
    }
    Ok(value)
}

fn validate_filename(value: String) -> Result<String, NetError> {
    if value.is_empty()
        || value.chars().any(|character| character.is_control())
        || value.contains('/')
        || value.contains('\\')
    {
        return Err(NetError::input(
            "multipart.filename",
            "multipart filename must be a single non-empty path component",
        ));
    }
    Ok(value)
}

fn write_disposition(
    body: &mut Vec<u8>,
    name: &str,
    filename: Option<&str>,
) -> Result<(), NetError> {
    body.extend_from_slice(b"Content-Disposition: form-data; name=\"");
    write_quoted(body, name)?;
    body.extend_from_slice(b"\"");
    if let Some(filename) = filename {
        body.extend_from_slice(b"; filename=\"");
        write_quoted(body, filename)?;
        body.extend_from_slice(b"\"");
    }
    body.extend_from_slice(b"\r\n");
    Ok(())
}

fn write_quoted(body: &mut Vec<u8>, value: &str) -> Result<(), NetError> {
    for character in value.chars() {
        if character == '\r' || character == '\n' || character == '\0' || character.is_control() {
            return Err(NetError::input(
                "multipart.header",
                "multipart header value contains a control character",
            ));
        }
        match character {
            '\\' | '"' => body.push(b'\\'),
            _ => {}
        }
        let mut encoded = [0_u8; 4];
        body.extend_from_slice(character.encode_utf8(&mut encoded).as_bytes());
    }
    Ok(())
}

fn self_contains_boundary(parts: &[Part], boundary: &str) -> bool {
    let marker = boundary.as_bytes();
    parts.iter().any(|part| match part {
        Part::Text { name, value } => {
            name.as_bytes()
                .windows(marker.len())
                .any(|window| window == marker)
                || value
                    .as_bytes()
                    .windows(marker.len())
                    .any(|window| window == marker)
        }
        Part::Bytes {
            name,
            filename,
            value,
        } => {
            name.as_bytes()
                .windows(marker.len())
                .any(|window| window == marker)
                || filename.as_ref().is_some_and(|filename| {
                    filename
                        .as_bytes()
                        .windows(marker.len())
                        .any(|window| window == marker)
                })
                || value
                    .as_ref()
                    .windows(marker.len())
                    .any(|window| window == marker)
        }
    })
}

fn make_boundary() -> Result<String, getrandom::Error> {
    let mut bytes = [0_u8; BOUNDARY_BYTES];
    getrandom::fill(&mut bytes)?;
    let mut boundary = String::with_capacity(2 + BOUNDARY_BYTES * 2);
    boundary.push_str("open-net-");
    for byte in bytes {
        use std::fmt::Write;
        let _ = write!(&mut boundary, "{byte:02x}");
    }
    Ok(boundary)
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn encodes_text_binary_and_file_parts_without_leaking_debug_values() {
        let form = Multipart::new()
            .text("message", "中文")
            .unwrap()
            .file_bytes("asset", "demo.bin", Bytes::from_static(&[0, 1, 255]))
            .unwrap();
        let debug = format!("{form:?}");
        assert!(!debug.contains("中文") && !debug.contains("demo.bin"));
        let (body, content_type) = form.encode().unwrap();
        assert!(content_type
            .to_str()
            .unwrap()
            .starts_with("multipart/form-data; boundary="));
        assert!(body
            .windows("Content-Disposition".len())
            .any(|window| window == b"Content-Disposition"));
        assert!(body.windows(3).any(|window| window == [0, 1, 255]));
        assert!(body
            .windows("中文".len())
            .any(|window| window == "中文".as_bytes()));
    }

    #[test]
    fn rejects_header_injection() {
        let result = Multipart::new().text("bad\r\nname", "value");
        assert!(result.is_err());
    }

    #[test]
    fn accepts_empty_parts_and_rejects_invalid_names_and_filenames() {
        let form = Multipart::new()
            .text("empty-text", "")
            .unwrap()
            .bytes("empty-bytes", Bytes::new())
            .unwrap();
        let (body, _) = form.encode().unwrap();
        assert!(body
            .windows(b"name=\"empty-text\"".len())
            .any(|window| { window == b"name=\"empty-text\"" }));
        assert!(body
            .windows(b"name=\"empty-bytes\"".len())
            .any(|window| { window == b"name=\"empty-bytes\"" }));

        assert!(Multipart::new().text("", "value").is_err());
        assert!(Multipart::new().bytes("bad\0name", Bytes::new()).is_err());
        assert!(Multipart::new()
            .file_bytes("asset", "nested/path.bin", Bytes::new())
            .is_err());
        assert!(Multipart::new()
            .file_bytes("asset", "nested\\path.bin", Bytes::new())
            .is_err());
        assert!(Multipart::new()
            .file_bytes("asset", "bad\nname.bin", Bytes::new())
            .is_err());
    }

    #[test]
    fn missing_files_return_io_errors_and_large_buffered_parts_are_replayable() {
        let missing_path = std::env::temp_dir().join(format!(
            "open-net-missing-{}-{}-asset.bin",
            std::process::id(),
            std::time::SystemTime::now()
                .duration_since(std::time::UNIX_EPOCH)
                .unwrap()
                .as_nanos()
        ));
        let missing = Multipart::new().file("asset", &missing_path);
        let error = missing.expect_err("missing file must fail during construction");
        assert_eq!(error.kind(), crate::api::error::ErrorKind::Io);
        assert_eq!(error.io_kind(), Some(std::io::ErrorKind::NotFound));

        let value = Bytes::from(vec![0xA5; 1024 * 1024]);
        let (body, _) = Multipart::new()
            .bytes("large", value.clone())
            .unwrap()
            .encode()
            .unwrap();
        assert!(body.len() >= value.len());
        assert!(body
            .windows(value.len())
            .any(|window| window == value.as_ref()));
    }

    #[test]
    fn regenerates_a_boundary_when_the_initial_boundary_is_in_a_part() {
        let form = Multipart {
            boundary: "fixed-boundary".to_owned(),
            parts: vec![Part::Text {
                name: "field".to_owned(),
                value: "contains fixed-boundary".to_owned(),
            }],
        };
        let (body, content_type) = form.encode().unwrap();
        let content_type = content_type.to_str().unwrap();
        assert!(!content_type.ends_with("fixed-boundary"));
        assert!(body
            .windows(b"contains fixed-boundary".len())
            .any(|window| { window == b"contains fixed-boundary" }));
    }
}