multipart
multipart/form-data request bodies (RFC 7578) in pure Louise: the form
an HTML page posts when it has a file input (ADR 0080).
import multipart.{Form, Limits, FileTooLarge, TooManyFiles}
fn upload :: req: Request -> Response
{
match multipart.from_request req Limits(..multipart.defaults (), max_files: 3)
{ Ok(Form(fields, files)) -> saved fields files
, Error(TooManyFiles) | Error(FileTooLarge(_)) -> http.text 413 "too large"
, Error(_) -> http.text 400 "not a form"
}
}
The server reads the whole body before the handler runs, so give the
upload routes a larger body limit than the rest of the site with
http.Settings' large_bodies (ADR 0012, Revision 5):
Settings(..http.defaults (), large_bodies: [("/uploads", 50 * 1048576)])
API
pub type Limits { Limits(max_files: Int, max_file_bytes: Int, max_fields: Int,
max_field_bytes: Int, max_part_head: Int) }
pub fn defaults :: -> Limits // 10 files of 10 MiB, 100 fields of 1 MiB, 8 KiB of part headers
pub type Upload { Upload(name: String, filename: String, content_type: String, data: Bytes) }
pub type Form { Form(fields: List<(String, String)>, files: List<Upload>) }
pub type Error
{ NotMultipart | BadBoundary | Malformed(at: Int, reason: String)
| TooManyFiles | FileTooLarge(String) | TooManyFields | FieldTooLarge(String) }
pub fn boundary :: content_type: String -> Result<String, Error>
pub fn parse :: body: Bytes boundary: String limits: Limits -> Result<Form, Error>
pub fn from_request :: req: Request limits: Limits -> Result<Form, Error>
- Fields and files keep the order they were sent in; a name can repeat.
FileTooLargenames the file name,FieldTooLargethe field name.Malformed'satis a byte offset in the body.
How a body is read
- The boundary comes from
Content-Type: multipart/form-data; boundary=...(quoted or not): 1 to 70 of RFC 2046's characters, not ending in a space. Anything else isBadBoundary; another media type isNotMultipart. - The preamble and the epilogue (before the first boundary, after the
last) are ignored. The body must end with the closing boundary
(
--boundary--). - A part's headers must end within
max_part_headbytes. OnlyContent-Disposition(which must beform-datawith aname) andContent-Typeare read; every other header is ignored, includingContent-Transfer-Encoding, which RFC 7578 deprecates. - A part with a
filenameparameter is a file. Its name is cut to the last segment after/or\(C:\a\b.pngisb.png,../../etc/passwdispasswd), and refused if it has a control character. It is still untrusted: it may be empty,.or.., or anything else a file system would not like. Its type isapplication/octet-streamwhen the part has none. - A file input left empty (an empty file name and no data, which browsers send for it) is dropped and does not count as a file.
- A field (no
filename) must be UTF-8. - Refused: a part whose type is itself
multipart/...(nested multipart, which RFC 7578 no longer allows). - Not supported:
filename*(RFC 5987), which RFC 7578 tells senders not to use, is ignored. A quoted parameter ends at the next", and a backslash is kept as it is (browsers percent-encode a"in a file name).
Cost
The parts are found with a Boyer-Moore-Horspool search for the delimiter, so a long boundary (browsers use 30 to 40 characters) skips most of a file's bytes. Each file's data is one slice of the body (one copy). The whole body is in memory first: the server's body limit is what bounds it.