#moon-multipart

#特性

• RFC 7578 合规 — 完整支持 multipart/form-data 编码格式
• 流式解析 — 增量处理上传数据，PartData 逐块输出，不将整个文件加载到内存
• 跨分块边界检测 — 正确处理被网络分块拆分的 boundary 分隔符
• 安全限制 — 6 维度可配置限制（part 数量、header 大小、字段大小、文件大小、总大小、文件名长度）
• 路径穿越防护 — 检测并拒绝 ../、\、盘符、null 字节等危险文件名
• 安全文件名工具 — safe_filename()、validate_filename()、unique_filename()
• 严格/兼容双模式 — Strict 模式拒绝非标准扩展（如 filename*），Compatible 模式宽松接受
• 流式 Writer — StreamingWriter 支持 begin_part / write_chunk / end_part 分块添加数据；真正恒定内存输出计划在 v0.3.0 引入 Sink/回调接口
• 高层 API — parse_all() 一键解析返回 MultipartForm，支持同名字段/多文件

#快速开始

#安装

moon add Songyz002/moon-multipart

#解析 multipart 请求体（高层 API）

let content_type = "multipart/form-data; boundary=----WebKitFormBoundary"
let boundary = parse_boundary_from_content_type(content_type)?
let form = parse_all(body, boundary, ParseOptions::default())?
// 读取字段
let username = form.field("username")
// 读取同名多值
let tags = form.field_values("tag")
// 读取文件
match form.file("avatar") {
  Some(part) => { let data = part.data(); let fname = part.filename() }
  None => { }
}
// 读取同名多文件
let images = form.files("image")

#解析 multipart 请求体（流式低层 API）

let boundary = parse_boundary_from_content_type(content_type)?
let parser = Parser::new(boundary, ParseOptions::default())
for chunk in incoming_chunks {
  let events = parser.feed(chunk)?
  for event in events {
    match event {
      PartBegin(name, filename, content_type) => { /* 新 part 开始 */ }
      PartData(data) => { /* body 数据块，直接写文件/哈希 */ }
      PartEnd => { /* part 结束 */ }
      Finished => { /* 解析完成 */ }
    }
  }
}
parser.finish()?

#生成 multipart 请求体（基础 API）

let writer = MultipartWriter::new()
writer.add_field("username", "alice")
writer.add_file("avatar", "photo.png", Some("image/png"), image_bytes)
let (boundary, body) = writer.finish()
// Content-Type: multipart/form-data; boundary=<boundary>

#生成 multipart 请求体（流式 API）

let sw = StreamingWriter::new(boundary)
sw.begin_part("file", Some("large.bin"), Some("application/octet-stream"))
for chunk in read_file_in_chunks("large.bin") {
  sw.write_chunk(chunk)
}
sw.end_part()
let body = sw.finish()

#安全文件名处理

// 验证
validate_filename("photo.jpg", 255)?

// 清理危险字符
let safe = safe_filename("../../../etc/passwd")  // → "______etc_passwd"

// 生成唯一名称
let unique = unique_filename("photo.jpg")  // → "photo_3A7F2C1D.jpg"

#API 参考

#类型

#核心函数

• parse_boundary_from_content_type(content_type) -> Result[String, MultipartError]
• validate_boundary(boundary) -> Result[String, MultipartError]

• parse_content_disposition(header, ParseOptions) -> Result[(String, String?), MultipartError]
• parse_header_line(line) -> (String, String)?

• Parser::new(boundary, ParseOptions) -> Parser
• Parser::feed(self, chunk) -> Result[Array[ParseEvent], MultipartError]
• Parser::finish(self) -> Result[Array[ParseEvent], MultipartError]
• parse_all(body, boundary, ParseOptions) -> Result[MultipartForm, MultipartError]

• MultipartWriter::new() -> MultipartWriter
• MultipartWriter::with_boundary(boundary) -> MultipartWriter
• MultipartWriter::add_field(self, name, value) -> Unit
• MultipartWriter::add_file(self, name, filename, content_type?, data) -> Unit
• MultipartWriter::finish(self) -> (String, Bytes)

• StreamingWriter::new(boundary) -> StreamingWriter
• StreamingWriter::begin_part(self, name, filename?, content_type?) -> Unit
• StreamingWriter::write_chunk(self, data) -> Unit
• StreamingWriter::end_part(self) -> Unit
• StreamingWriter::finish(self) -> Bytes

• is_dangerous_filename(filename) -> Bool
• validate_filename(filename, max_len) -> Result[String, MultipartError]
• safe_filename(original) -> String
• unique_filename(original) -> String

#安全限制

#项目规模

• 3,650 行有效 MoonBit 代码
• 87 个测试用例
• 8 个源码模块

#RFC 7578 合规矩阵

#许可证