package http-multipart-formdata

  1. Overview
  2. Docs

Module Http_multipart_formdataSource

Http_multipart_formdata is a non-blocking, streaming HTTP multipart/formdata parser. Its design is based on two main ideas:

  • The parser should stream the results as soon as possible in a non-buffered, non-backtracking manner; and
  • The parser input must be non-blocking and incremental in nature.

The parser implements HTTP multipart/form-data standard as defined in RFC 7578.

Types

Sourcetype reader

reader represents a HTTP multipart formdata reader.

Sourceand read = [
  1. | `End
    (*

    The reader has completed reading.

    *)
  2. | `Header of part_header
    (*

    Multipart part header data.

    *)
  3. | `Body of Cstruct.t
    (*

    Multipart part body data.

    *)
  4. | `Body_end
    (*

    reader has completed reading the Multipart body data.

    *)
  5. | `Awaiting_input of [ `Cstruct of Cstruct.t | `Eof ] -> read
    (*

    The reader is waiting for it to be provided with input data. This is only returned when `Incremental is chosen as input.

    *)
  6. | `Error of string
    (*

    Represents an error in input data.

    *)
]

read represents both the current state and data read by a reader.

Sourceand input = [
  1. | `Cstruct of Cstruct.t
    (*

    A bigstring input.

    *)
  2. | `Incremental
    (*

    The caller of the library periodically provides input to the parser.

    *)
]
Sourceand part_header

Represents a parsed multipart part header data.

Sourceand boundary

Represents the multipart boundary value.

Sourceand field_name = string

A form field name

Sourceand part_body = string

A Multipart body

Mulipart Boundary parser

Sourceval boundary : string -> (boundary, string) result

boundary content_type parses content_type to extract boundary value. content_type is the HTTP request Content-Type header value.

  let content_type =
    "multipart/form-data; \
     boundary=---------------------------735323031399963166993862150"
  in
  Http_multipart_formdata.boundary content_type

Streaming Multipart

API to stream multipart parts. Use these functions when you have to handle HTTP form submissions which has large file uploads and at the same time be memory efficient.

Sourceval reader : ?read_buffer_size:int -> boundary -> input -> reader

reader ?read_buffer_size boundary input creates reader. The default value for read_buffer_size is 1KB.

Sourceval read : reader -> read

read reader returns data read by reader.

Sourceval unconsumed : reader -> Cstruct.t

unconsumed reader returns any leftover data still remaining after reader returns `End.

Non-Streaming Multipart

Use these functions if the HTTP form submission is of a relatively small size.

Sourceval parts : boundary -> string -> ((field_name * (part_header * part_body)) list, string) result

parts boundary http_body returns a list of HTTP multipart parts parsed in http_body.

The returned parts list is keyed to a form field name so that one can do:

  let parts_kv = parts boundary http_body in
  match List.assoc_opt "field1" parts_vk with
  | Some v -> ...
  | None -> ..

Part header

Sourceval name : part_header -> string

name t returns the form field name.

Sourceval content_type : part_header -> string

content_type t returns the part content-type.

Sourceval filename : part_header -> string option

filename t returns the uploaded filename if the multipart is a file.

Sourceval find : string -> part_header -> string option

find name t returns the multipart parameter value associated with name.

Pretty Printers

Sourceval pp_part_header : Format.formatter -> part_header -> unit
Sourceval pp_read_result : Format.formatter -> read -> unit
Sourceval pp_boundary : Format.formatter -> boundary -> unit