🥮 mooncakes.io
    Sign in

    moonpart

    Streaming-oriented multipart/form-data parser and encoder for MoonBit.

    multipart
    form-data
    http
    upload
    rfc7578
    Download zip
    Author
    Version
    0.1.0
    License
    Apache-2.0
    Repository
    Last updated
    last month
    Downloads
    24

    No dependencies

    #MoonPart

    CI License

    MoonPart is a pure MoonBit multipart/form-data core library. It implements a small, strict RFC 7578-oriented parser and encoder for HTTP form bodies.

    #Installation

    After the 0.1.0 release is published to mooncakes.io:

    moon add eisem/moonpart@0.1.0

    Before publication, clone this repository and run the example and tests from the repository root.

    #Current status

    The library includes both a convenient text collector and StreamingParser, a byte-preserving event parser. StreamingParser::feed_bytes accepts arbitrary network chunks and emits PartBegin, PartData, PartEnd, and Finished events as soon as they are known. It keeps only a possible-boundary suffix, rather than retaining whole uploaded files.

    StreamingEncoder performs the inverse operation. It converts the same events into immediately writable Bytes chunks and passes PartData through without text conversion or whole-body buffering.

    StreamLimits bounds the complete wire body, header blocks, number of parts, and each part body. This is suitable for HTTP handlers that must reject hostile or accidental oversized uploads early.

    Each decoded Part retains headers and exposes name, filename, is_file, and content_type convenience accessors. Missing part Content-Type values use the RFC 7578 text/plain default.

    For uploaded files, prefer decode_bytes. It returns StreamEvent values and keeps every part body as Bytes, so arbitrary binary data is preserved:

    ///|
    test "read a binary file field" {
      let body = b"--bin\r\nContent-Disposition: form-data; name=\"file\"; filename=\"raw.bin\"\r\n\r\n\x00\xff\r\n--bin--\r\n"
      match @moonpart.decode_bytes("bin", body) {
        Ok(
          [
            @moonpart.StreamEvent::PartBegin(_),
            @moonpart.StreamEvent::PartData(data),
            ..,
          ]
        ) => assert_eq(data.length(), 2)
        _ => fail("invalid multipart body")
      }
    }

    #Example

    ///|
    test "parse one field" {
      let parser = @moonpart.Parser::new("MyBoundary")
      ignore(
        parser.feed(
          "--MyBoundary\r\nContent-Disposition: form-data; name=\"title\"\r\n\r\nMoonBit\r\n--MyBoundary--\r\n",
        ),
      )
      match parser.finish() {
        Ok(parts) => println(parts[0].body)
        Err(_) => println("invalid multipart body")
      }
    }

    #Streaming an upload

    ///|
    test "handle an upload incrementally" {
      let parser = @moonpart.StreamingParser::from_content_type(
        "multipart/form-data; boundary=upload",
      )
      guard parser is Ok(parser) else { fail("invalid content type") }
      let chunks = [
        b"--upload\r\nContent-Disposition: form-data; name=\"file\"; filename=\"a.bin\"\r\n\r\nabc",
        b"\r\n--upload--\r\n",
      ]
      for chunk in chunks {
        guard parser.feed_bytes(chunk) is Ok(events) else {
          fail("invalid multipart body")
        }
        for event in events {
          match event {
            @moonpart.StreamEvent::PartData(data) =>
              // Write data to a file, socket, or other application sink here.
              assert_true(data.length() > 0)
            _ => ()
          }
        }
      }
      assert_true(parser.finish() is Ok(_))
    }

    For small forms, feed the same events to FormDataCollector; it preserves the wire order and repeated field names while exposing text fields and raw file bytes. Its configurable per-part memory limit makes its buffering explicit.

    Submitted filenames are untrusted input. filename_basename removes Unix and Windows directory components, but applications should still generate their own server-side storage paths rather than writing directly to a submitted name.

    For large uploads, use StreamingFormCollector. Its callback receives FileSinkEvent::Begin, incremental Data(Bytes) chunks, and End. The collector retains text fields and file metadata only; applications can forward file chunks directly to a filesystem, object store, hash function, or network sink without constructing the complete file in memory.

    StreamingFormDecoder connects content-type boundary parsing, incremental body decoding, limits, field validation, and sink delivery behind one feed_bytes API for HTTP handlers.

    Use FieldSizeLimit when a specific field needs a stricter cap than the global text or file limit, for example a short title alongside a larger asset.

    #Streaming an encoded body

    Create StreamEvent values in wire order and write each returned chunk directly to an HTTP request body, file, or application sink:

    ///|
    test "encode binary data incrementally" {
      let encoder = @moonpart.StreamingEncoder::new("out")
      let chunks = []
      let events = [
        @moonpart.StreamEvent::PartBegin([
          @moonpart.Header::{
            name: "Content-Disposition",
            value: "form-data; name=\"file\"; filename=\"a.bin\"",
          },
        ]),
        @moonpart.StreamEvent::PartData(b"\x00\xff"),
        @moonpart.StreamEvent::PartEnd,
        @moonpart.StreamEvent::Finished,
      ]
      for event in events {
        guard encoder.push(event) is Ok(chunk) else {
          fail("invalid encoder event")
        }
        chunks.push(chunk)
      }
      assert_true(chunks[1] == b"\x00\xff")
      assert_true(chunks[3] == b"--out--\r\n")
    }

    StreamingEncoder::content_type returns the matching quoted Content-Type value. Invalid boundaries, unsafe headers, and out-of-order events are rejected; after an error the encoder remains failed.

    #Choosing an API

    Use caseAPIBody storage
    Small text-oriented formsParserComplete body as String
    Binary body decoded at oncedecode_bytesEvents contain raw Bytes
    Incremental protocol parsingStreamingParserPossible-boundary suffix only
    Small forms collected in memoryFormDataCollectorText and file bodies
    Large files sent to a sinkStreamingFormDecoderText fields and file metadata
    Incremental binary encodingStreamingEncoderCurrent header chunk only

    Run the complete streaming example with:

    moon run cmd/main

    #Scope and non-goals

    MoonPart owns multipart/form-data boundary parsing, strict part-header parsing, encoding, resource limits, form collection, and sink-oriented file delivery. It deliberately does not provide an HTTP server/client, asynchronous filesystem I/O, temporary-file management, MIME sniffing, antivirus scanning, or trusted storage paths. Integrations should supply request chunks and decide how emitted file bytes are persisted.

    The current release targets RFC 7578 form-data behavior. It is not a general recursive MIME message parser and does not decode content-transfer encodings.

    #Security

    All limits should be selected for the surrounding HTTP service. Submitted filenames, media types, headers, and text values remain untrusted. See SECURITY.md for the supported security model and vulnerability reporting process.

    #Development

    moon fmt
moon info
moon check --target all
moon build --target all
moon test --target all
moon coverage analyze
moon bench --target native
moon run cmd/main

    Continuous integration checks formatting and generated interfaces, then builds and tests the Wasm, Wasm-GC, JavaScript, and native backends. It also runs MoonBit's coverage analyzer on every push and pull request.

    The implementation design is documented in docs/DESIGN.md. See CONTRIBUTING.md for the change workflow and CHANGELOG.md for release notes. The latest reproducible competition checklist is in docs/ACCEPTANCE.md.

    The implementation is original and takes RFC 7578 and RFC 2046 as behavioral references. It is licensed under Apache-2.0.

    MultipartError

    source
    pub(all) suberror MultipartError {
      InvalidBoundary
      InvalidContentType
      BodyTooLarge(Int)
      MissingOpeningBoundary
      MissingHeaderTerminator
      InvalidHeader(String)
      DuplicateHeader(String)
      MissingContentDisposition
      InvalidContentDisposition
      MissingFieldName
      HeaderTooLarge(Int)
      HeaderCountExceeded(Int)
      PartCountExceeded(Int)
      PartTooLarge(Int)
      InvalidStreamEvent
      FieldTooLarge(Int)
      FileTooLarge(Int)
      FieldCountExceeded(Int)
      FileCountExceeded(Int)
      UnexpectedField(String)
      SinkFailure(String)
      MissingClosingBoundary
      UnexpectedBoundary
    } derive(
    Debug    )

    Errors reported when a multipart body is malformed or exceeds its limit.

    EncoderState

    source
    type EncoderState

    FieldSizeLimit

    source
    pub(all) struct FieldSizeLimit {
      name : String
      max_size : Int
    } derive(Eq, 
    Debug    )

    A size override for one named form field. It applies to both text and file parts and can only make the corresponding global limit stricter.

    FileSinkEvent

    source
    pub(all) enum FileSinkEvent {
      Begin(StreamedFile)
      Data(Bytes)
      End
    } derive(
    Debug    )

    Events sent to an application-provided file sink. Each Begin is followed by zero or more Data events and exactly one End event.

    FormData

    source
    pub(all) struct FormData {
      entries : Array[FormEntry]
    } derive(
    Debug    )

    Collected multipart/form-data entries in original wire order.

    FormData::file

    source
    fn FormData::file(self : FormData, name : String) -> UploadedFile?

    Returns the first uploaded file with the supplied field name.

    FormData::files

    source
    fn FormData::files(self : FormData, name : String) -> Array[UploadedFile]

    Returns every uploaded file with the supplied field name in wire order.

    FormData::text

    source
    fn FormData::text(self : FormData, name : String) -> String?

    Returns the first text value with the supplied field name.

    FormData::text_all

    source
    fn FormData::text_all(self : FormData, name : String) -> Array[String]

    Returns every text value with the supplied field name in wire order.

    FormDataCollector

    source
    pub struct FormDataCollector {
      entries : Array[FormEntry]
      buffer : 
    Buffer
      limits : FormDataLimits
      allowed_fields : Array[String]?
      field_size_limits : Array[FieldSizeLimit]
      current_part : FormPartMetadata?
      current_size : Int
      field_count : Int
      file_count : Int
      finished : Bool
    }

    Event consumer that builds an in-memory FormData value from a StreamingParser. Use a future sink-based collector for very large files.

    FormDataCollector::finish

    source

    Returns the final collected data once the Finished event has been consumed.

    FormDataCollector::new

    source

    FormDataCollector::push

    source
    fn FormDataCollector::push(self : FormDataCollector, event : StreamEvent) -> Result[Unit, MultipartError]

    Consumes one streaming event.

    FormDataCollector::with_allowed_fields

    source
    fn FormDataCollector::with_allowed_fields(allowed_fields : Array[String], limits? : FormDataLimits) -> FormDataCollector

    Creates a collector that rejects any part whose form field name is not in allowed_fields. Repeated occurrences of an allowed name remain valid.

    FormDataCollector::with_field_size_limits

    source
    fn FormDataCollector::with_field_size_limits(limits : FormDataLimits, field_size_limits : Array[FieldSizeLimit]) -> FormDataCollector

    Creates a collector with global limits plus stricter per-field size limits.

    FormDataCollector::with_file_size_limit

    source
    fn FormDataCollector::with_file_size_limit(max_file_size : Int) -> FormDataCollector

    Creates an in-memory collector with a maximum size for one part body.

    FormDataCollector::with_limits

    source

    Creates an in-memory collector with separate text-field and file limits.

    FormDataLimits

    source
    pub(all) struct FormDataLimits {
      max_field_size : Int
      max_file_size : Int
      max_field_count : Int
      max_file_count : Int
    }

    Resource bounds for the in-memory form collector. Text and file limits are separate because applications commonly accept many small fields but only a small number of larger uploads.

    FormDataLimits::default

    source

    FormEntry

    source
    pub(all) enum FormEntry {
      Text(TextField)
      File(UploadedFile)
    } derive(
    Debug    )

    A form entry in original wire order. Repeated names are intentionally kept.

    FormPartMetadata

    source
    type FormPartMetadata

    Validated form-data metadata cached for the lifetime of one part.
    pub(all) struct Header {
      name : String
      value : String
    } derive(Eq, 
    Debug    )

    A header belonging to one multipart body part. Header names are preserved as received; use Part::header for case-insensitive lookup.

    Parser

    source
    pub struct Parser {
      boundary : String
      max_body_size : Int
      max_part_count : Int
      max_header_size : Int
      max_header_count : Int
      buffer : String
      failed : MultipartError?
    }

    An incremental multipart collector. Chunks may be supplied at arbitrary boundaries; parsing happens on finish so a delimiter split across chunks is handled exactly like an unsplit delimiter.

    Parser::feed

    source
    fn Parser::feed(self : Parser, chunk : String) -> Result[Unit, MultipartError]

    Adds a body chunk. Chunks can be split at any character boundary.

    Parser::finish

    source
    fn Parser::finish(self : Parser) -> Result[Array[Part], MultipartError]

    Parses all supplied chunks and returns body parts in wire order.

    Parser::from_content_type

    source
    fn Parser::from_content_type(content_type : String, max_body_size? : Int) -> Result[Parser, MultipartError]

    Creates a parser directly from an HTTP Content-Type value.

    Parser::new

    source
    fn Parser::new(boundary : String, max_body_size? : Int) -> Parser

    Creates a parser for the supplied boundary. The boundary must be the raw value from the Content-Type parameter, without the leading --.

    Parser::with_limits

    source
    fn Parser::with_limits(boundary : String, max_body_size? : Int, max_part_count? : Int, max_header_size? : Int, max_header_count? : Int) -> Parser

    Creates a parser with explicit resource limits. The parser rejects a body once any configured bound is exceeded.

    Part

    source
    pub(all) struct Part {
      headers : Array[Header]
      body : String
    } derive(Eq, 
    Debug    )

    One decoded multipart body part. body is text in this first core API; the parser never interprets its contents.

    Part::content_type

    source
    fn Part::content_type(self : Part) -> String

    Returns the part media type. RFC 7578 defaults an omitted Content-Type to text/plain for form fields.

    Part::disposition_parameter

    source
    fn Part::disposition_parameter(self : Part, parameter : String) -> String?

    Returns a parameter from Content-Disposition, such as name or filename. Quoted parameter values are unquoted.

    Part::filename

    source
    fn Part::filename(self : Part) -> String?

    Convenience accessor for the submitted file name, when present.

    Part::filename_basename

    source
    fn Part::filename_basename(self : Part) -> String?

    Returns the submitted filename without directory components.

    Part::header

    source
    fn Part::header(self : Part, name : String) -> String?

    Returns a header value using ASCII case-insensitive comparison.

    Part::is_file

    source
    fn Part::is_file(self : Part) -> Bool

    Reports whether this part carries a submitted file name.

    Part::name

    source
    fn Part::name(self : Part) -> String?

    Convenience accessor for the form field name.

    StreamEvent

    source
    pub(all) enum StreamEvent {
      PartBegin(Array[Header])
      PartData(Bytes)
      PartEnd
      Finished
    } derive(
    Debug    )

    Events emitted by the binary multipart decoder. Part bodies remain Bytes, so file contents are never decoded as text.

    StreamLimits

    source
    pub(all) struct StreamLimits {
      max_body_size : Int
      max_part_count : Int
      max_header_size : Int
      max_header_count : Int
      max_part_size : Int
    }

    Resource bounds for the incremental decoder. They mirror the limits that production multipart readers use to prevent unbounded header or body buffering.

    StreamLimits::default

    source
    fn StreamLimits::default() -> StreamLimits

    StreamState

    source
    type StreamState derive(
    Debug    )

    Internal state of an incremental binary multipart decoder.

    StreamedFile

    source
    pub(all) struct StreamedFile {
      field_name : String
      filename : String
      content_type : String
      headers : Array[Header]
    } derive(Eq, 
    Debug    )

    Metadata for a streamed file part. File contents are delivered separately as FileSinkEvent::Data and are never retained by StreamingFormCollector.

    StreamedFile::filename_basename

    source
    fn StreamedFile::filename_basename(self : StreamedFile) -> String

    Returns the submitted filename without Unix or Windows directory parts.

    StreamedFormData

    source
    pub(all) struct StreamedFormData {
      fields : Array[TextField]
      files : Array[StreamedFile]
    } derive(
    Debug    )

    Result of sink-based form collection. Text fields are retained in memory; files contain metadata only because their bytes have already reached the sink.

    StreamingEncoder

    source
    pub struct StreamingEncoder {
      boundary : String
      state : EncoderState
      failed : MultipartError?
    }

    Incrementally converts multipart events into binary wire chunks. The encoder retains only its state and the boundary; returned chunks can be written directly to an HTTP body sink.

    StreamingEncoder::content_type

    source
    fn StreamingEncoder::content_type(self : StreamingEncoder) -> String

    Returns a Content-Type value suitable for the encoded body.

    StreamingEncoder::from_content_type

    source
    fn StreamingEncoder::from_content_type(content_type : String) -> Result[StreamingEncoder, MultipartError]

    Creates an encoder from an HTTP multipart/form-data Content-Type value.

    StreamingEncoder::new

    source
    fn StreamingEncoder::new(boundary : String) -> StreamingEncoder

    Creates an encoder for a raw multipart boundary. Invalid boundaries are reported by the first push call.

    StreamingEncoder::push

    source
    fn StreamingEncoder::push(self : StreamingEncoder, event : StreamEvent) -> Result[Bytes, MultipartError]

    Encodes one event. PartBegin emits a boundary and headers, PartData returns the original binary payload without text conversion, PartEnd emits the required CRLF, and Finished emits the closing boundary.

    Events must follow PartBegin, zero or more PartData, PartEnd, then another part or Finished. Any error is terminal.

    StreamingFormCollector

    source
    pub struct StreamingFormCollector {
      fields : Array[TextField]
      files : Array[StreamedFile]
      text_buffer : 
    Buffer
      limits : FormDataLimits
      allowed_fields : Array[String]
      field_size_limits : Array[FieldSizeLimit]
      sink : (FileSinkEvent) -> Result[Unit, MultipartError]
      current_part : FormPartMetadata?
      current_size : Int
      field_count : Int
      file_count : Int
      finished : Bool
      failed : MultipartError?
    }

    Consumes multipart events while forwarding file bytes to a callback. An empty allowed_fields list accepts every field name.

    StreamingFormCollector::finish

    source

    Returns collected text fields and streamed file metadata after Finished.

    StreamingFormCollector::new

    source
    fn StreamingFormCollector::new(sink : (FileSinkEvent) -> Result[Unit, MultipartError], limits? : FormDataLimits, allowed_fields? : Array[String], field_size_limits? : Array[FieldSizeLimit]) -> StreamingFormCollector

    StreamingFormCollector::push

    source
    fn StreamingFormCollector::push(self : StreamingFormCollector, event : StreamEvent) -> Result[Unit, MultipartError]

    Consumes one event produced by StreamingParser.

    StreamingFormDecoder

    source
    pub struct StreamingFormDecoder {
      parser : StreamingParser
      collector : StreamingFormCollector
      failed : MultipartError?
    }

    End-to-end multipart/form-data decoder that connects StreamingParser to a StreamingFormCollector. File bytes go directly to the supplied sink.

    StreamingFormDecoder::feed_bytes

    source
    fn StreamingFormDecoder::feed_bytes(self : StreamingFormDecoder, chunk : Bytes) -> Result[Unit, MultipartError]

    Feeds an arbitrary network body chunk through the parser and file sink.

    StreamingFormDecoder::finish

    source

    Validates the closing boundary and returns text fields plus file metadata.

    StreamingFormDecoder::from_content_type

    source
    fn StreamingFormDecoder::from_content_type(content_type : String, sink : (FileSinkEvent) -> Result[Unit, MultipartError], stream_limits? : StreamLimits, form_limits? : FormDataLimits, allowed_fields? : Array[String], field_size_limits? : Array[FieldSizeLimit]) -> Result[StreamingFormDecoder, MultipartError]

    Creates a decoder directly from an HTTP Content-Type value.

    StreamingFormDecoder::new

    source
    fn StreamingFormDecoder::new(boundary : String, sink : (FileSinkEvent) -> Result[Unit, MultipartError], stream_limits? : StreamLimits, form_limits? : FormDataLimits, allowed_fields? : Array[String], field_size_limits? : Array[FieldSizeLimit]) -> StreamingFormDecoder

    Creates a decoder from a raw multipart boundary.

    StreamingParser

    source
    pub struct StreamingParser {
      boundary : String
      opening : Bytes
      marker : Bytes
      limits : StreamLimits
      pending : Bytes
      state : StreamState
      received_size : Int
      part_count : Int
      current_part_size : Int
      failed : MultipartError?
    }

    Incremental multipart decoder. feed_bytes emits completed protocol events as soon as they are known, retaining only a short possible-boundary suffix.

    StreamingParser::feed_bytes

    source
    fn StreamingParser::feed_bytes(self : StreamingParser, chunk : Bytes) -> Result[Array[StreamEvent], MultipartError]

    Feeds one arbitrary body chunk and returns events now known to be complete.

    StreamingParser::finish

    source

    Finishes the stream. A complete body must already have emitted Finished.

    StreamingParser::from_content_type

    source
    fn StreamingParser::from_content_type(content_type : String, limits? : StreamLimits) -> Result[StreamingParser, MultipartError]

    Creates an incremental decoder from a multipart/form-data Content-Type value, including a quoted boundary parameter.

    StreamingParser::new

    source
    fn StreamingParser::new(boundary : String) -> StreamingParser

    StreamingParser::with_limits

    source
    fn StreamingParser::with_limits(boundary : String, limits : StreamLimits) -> StreamingParser

    Creates an incremental decoder with explicit bounds for the complete wire body, each header block, the part count, and each individual part body.

    TextField

    source
    pub(all) struct TextField {
      name : String
      value : String
    } derive(Eq, 
    Debug    )

    A decoded text form field.

    UploadedFile

    source
    pub(all) struct UploadedFile {
      field_name : String
      filename : String
      content_type : String
      data : Bytes
    } derive(
    Debug    )

    A decoded uploaded file. data preserves the original file bytes.

    UploadedFile::filename_basename

    source
    fn UploadedFile::filename_basename(self : UploadedFile) -> String

    Returns the submitted filename without Unix or Windows directory components. Generate a separate server-side storage path for the file.

    boundary_from_content_type

    source
    fn boundary_from_content_type(content_type : String) -> Result[String, MultipartError]

    Extracts and validates the boundary parameter from a multipart/form-data Content-Type header. Quoted boundary values are accepted.

    decode_bytes

    source
    fn decode_bytes(boundary : String, body : Bytes) -> Result[Array[StreamEvent], MultipartError]

    Decodes a complete multipart body into binary-preserving events. This is the one-shot companion to the upcoming incremental byte state machine.

    encode

    source
    fn encode(boundary : String, parts : Array[Part]) -> String

    Encodes parts as a multipart body using the supplied boundary.

    filename_basename

    source
    fn filename_basename(filename : String) -> String

    Returns the submitted filename with both Unix and Windows directory components removed. An empty string is returned for . and ..; callers should still generate their own storage path rather than trusting a name.

    Source Files

    Powered by MoonBit

    Site sourceReport issuePackagesBuild queueSkillsStatistics

    © 2026 mooncakes.io