Accessing multipart form data
This note describes the properties of a single entry within a multipart/form-data payload.
_multipartFormData property is an array of
MultipartEntry objects, one for each section of the multipart/form-data payload.
These objects are parsed from the requestBody by the server. Here is what they look like, in a nutshell:
// parsing privates
// parsing intermediates
// public data
The rest of this note provides details useful to anyone working with multipart/form-data.
Each multipart entry carries the value of one HTML form input element. Elements of
type=file are binary Buffers holding the full contents of a file. Elements of
type=text, and other textual inputs, are simple string values.
Here is a sample HTML page that will trigger the creation of multipartEntries:
<form enctype='multipart/form-data' method=post action='/upload-pics'>
<input name=pictureDesc type=text>
<input name=pictureFile type=file>
<input type=submit value=Submit>
The server is responsible for parsing internal multipart payloads into userland entries. This occurs before any plugin is invoked.
Several private variables are used in this process:
endsAt define the offset, into the requestBodyBytes, of the localBuffer for the section.
dataEndsAt variables define the offset into that localBuffer of the payload itself, excluding any headers.
Each multipart consists of headers and payload. Two headers are allowed by the IETF RFC 7578 spec:
content-disposition (which is required) and
content-type (which is optional).
This holds the full text of the
content-disposition header for this entry. It will contain these subparts:
form-data: a string identifier confirming that this is multipart data.
name: the text value of the "name" assigned to the HTML form's
inputelement by the web page developer.
filename: the name of the file, without leading directory path, of the file being uploaded. This is optional and omitted when the payload is not a file, but from an input element
When present, it will contain the full text of the
content-type header for this entry. It is a mime type, plus an optional charset value.
A string value extracted from the
content-disposition header containing the "name" attribute of the HTML form's
A string value extracted from the
content-disposition header containing the base filename of the file being uploaded. It does not include any path directory.
This will be an empty string if the multipart is from an HTML input element that is not
The mime type of the file, as determined by the browser. This will be an empty string if the multipart is not a file.
The character set encoding of the file. Assumed to be UTF-8 for any "text" mime type, and BINARY for anything else (image/png, image/jpeg, etc.).
A Buffer object containing the file's contents. For safe access, use the binary accessor
dataBytes or the string accessor
Provides safe access to the entry's data Buffer.
Converts the entry's data Buffer to a string using the value of the
The length of the data Buffer, in bytes.
This property is not set by the server. It may be used by plugins to set the httpStatus of the operation being performed for the user.
This can be used, for example, when the overall HTTP response status code is 207 "Multi Status", and the response payload is a JSON object containing the separate response codes for each file being uploaded.
Key points for successfully using multipartEntry objects:
- Multipart form data may be used to safely transfer binary resources (images, PDFs, data) to the server.
- Access to the underlying binary Buffer is through the
- Access to text data is through the