http.multipart

import http.multipart

http lifts part of this module out to its own top level; each name below is shown with the path that reaches it. Anything still spelled http.multipart.* needs import http.multipart.

multipart/form-data, in both directions.

MultipartData and UploadedFile are what a parsed upload arrives as; MultipartBuilder constructs one for sending. Parsing streams rather than buffering, so an upload larger than memory is still an upload.

Functions

parse()

http.multipart.parse(body, boundary: string, options: ?dict) -> MultipartData

Parses a multipart/form-data body (RFC 7578).

The boundary comes from the Content-Type header’s boundary parameter and must be given; a body cannot be parsed without it.

Parameters

• body (bytes)
• boundary (string)
• options (?dict) — max_parts (default 1000) and max_file_size (default: unlimited)

Returns MultipartData

Raises ProtocolError if the body is not a well-formed multipart message

Raises TooLargeError if a limit is exceeded

Classes

UploadedFile

class http.UploadedFile

One file received in a multipart/form-data body.

The content is held in memory. HttpServer’s max_body_size is what bounds how much that can be, so a service accepting large uploads should raise that limit deliberately rather than by accident.

• printable — has a @to_string(), so echo and print() show something useful

Fields

Constructor

http.UploadedFile(name, filename, content_type, headers, content)

UploadedFile.size()

http.UploadedFile.size() -> number

The size of the uploaded content in bytes.

Returns number

UploadedFile.safe_name()

http.UploadedFile.safe_name() -> string

The client’s filename reduced to a single path-safe segment: any directory component is dropped, and anything outside letters, digits, ., - and _ becomes an underscore. A name that reduces to nothing, or to a leading run of dots, comes back as 'unnamed'.

Returns string

UploadedFile.save_to()

http.UploadedFile.save_to(path: string)

Writes the content to path.

Parameters

• path (string)

Returns — number: the number of bytes written

UploadedFile.to_text()

http.UploadedFile.to_text() -> string

The content decoded as UTF-8 text.

Returns string

UploadedFile.to_string()

http.UploadedFile.to_string()

MultipartData

class http.MultipartData

The result of parsing a multipart/form-data body.

Fields

Constructor

http.MultipartData()

MultipartData.field()

http.MultipartData.field(name: string, fallback) -> any

The first value submitted for the field name, or fallback.

Parameters

• name (string)
• fallback (?any)

Returns any

MultipartData.file()

http.MultipartData.file(name: string) -> ?UploadedFile

The first file submitted under name, or nil.

Parameters

• name (string)

Returns ?UploadedFile

MultipartData.to_dict()

http.MultipartData.to_dict() -> dict

The plain fields as a flat name -> value dictionary, keeping the first value of any repeated name. Convenient when a form is known not to repeat names.

Returns dict

MultipartBuilder

class http.MultipartBuilder

Builds a multipart/form-data request body.

The boundary is generated from the platform’s secure random source rather than a counter or a timestamp, since a boundary a peer can predict is a boundary a peer can inject into a field value and thereby forge extra parts.

var form = http.MultipartBuilder()
form.add_field('title', 'Holiday')
form.add_file('photo', 'beach.jpg', photo_bytes, 'image/jpeg')

client.post(url, form.build(), { 'Content-Type': form.content_type() })

Constructor

http.MultipartBuilder(boundary)

MultipartBuilder.content_type()

http.MultipartBuilder.content_type() -> string

The Content-Type header value this body must be sent with, boundary parameter included.

Returns string

MultipartBuilder.boundary()

http.MultipartBuilder.boundary() -> string

The boundary string in use.

Returns string

MultipartBuilder.add_field()

http.MultipartBuilder.add_field(name: string, value)

Adds a plain form field.

Parameters

• name (string)
• value (string|number|bool)

Returns — MultipartBuilder: this same instance, for chaining

MultipartBuilder.add_file()

http.MultipartBuilder.add_file(name: string, filename: string, content, content_type: ?string)

Adds a file part.

A filename that is not plain ASCII is additionally sent as an RFC 5987 filename* parameter, which is how a non-ASCII name survives the trip; the plain filename is kept alongside it for recipients that only understand that one.

Parameters

• name (string) — the form field name
• filename (string)
• content (bytes|string)
• content_type (?string) — defaults to 'application/octet-stream'

Returns — MultipartBuilder: this same instance, for chaining

MultipartBuilder.build()

http.MultipartBuilder.build() -> bytes

Serialises every part added so far into a complete body.

Returns bytes

MultipartBuilder.length()

http.MultipartBuilder.length() -> number

How many parts have been added.

Returns number

2026, Richard Ore and Zuri contributors