1 | [![Build Status](https://travis-ci.org/andrewrk/node-multiparty.png?branch=master)](https://travis-ci.org/andrewrk/node-multiparty)
|
2 | # multiparty
|
3 |
|
4 | Parse http requests with content-type `multipart/form-data`, also known as file uploads.
|
5 |
|
6 | See also [busboy](https://github.com/mscdex/busboy) - a
|
7 | [faster](https://github.com/mscdex/dicer/wiki/Benchmarks) alternative
|
8 | which may be worth looking into.
|
9 |
|
10 | ### Why the fork?
|
11 |
|
12 | * This module uses the Node.js v0.10 streams properly, *even in Node.js v0.8*
|
13 | * It will not create a temp file for you unless you want it to.
|
14 | * Counts bytes and does math to help you figure out the `Content-Length` of
|
15 | each part.
|
16 | * You can easily stream uploads to s3 with
|
17 | [knox](https://github.com/LearnBoost/knox), for [example](examples/s3.js).
|
18 | * Less bugs. This code is simpler, has all deprecated functionality removed,
|
19 | has cleaner tests, and does not try to do anything beyond multipart stream
|
20 | parsing.
|
21 |
|
22 | ## Installation
|
23 |
|
24 | ```
|
25 | npm install multiparty
|
26 | ```
|
27 |
|
28 | ## Usage
|
29 |
|
30 | * See [examples](examples).
|
31 |
|
32 | Parse an incoming `multipart/form-data` request.
|
33 |
|
34 | ```js
|
35 | var multiparty = require('multiparty')
|
36 | , http = require('http')
|
37 | , util = require('util')
|
38 |
|
39 | http.createServer(function(req, res) {
|
40 | if (req.url === '/upload' && req.method === 'POST') {
|
41 | // parse a file upload
|
42 | var form = new multiparty.Form();
|
43 |
|
44 | form.parse(req, function(err, fields, files) {
|
45 | res.writeHead(200, {'content-type': 'text/plain'});
|
46 | res.write('received upload:\n\n');
|
47 | res.end(util.inspect({fields: fields, files: files}));
|
48 | });
|
49 |
|
50 | return;
|
51 | }
|
52 |
|
53 | // show a file upload form
|
54 | res.writeHead(200, {'content-type': 'text/html'});
|
55 | res.end(
|
56 | '<form action="/upload" enctype="multipart/form-data" method="post">'+
|
57 | '<input type="text" name="title"><br>'+
|
58 | '<input type="file" name="upload" multiple="multiple"><br>'+
|
59 | '<input type="submit" value="Upload">'+
|
60 | '</form>'
|
61 | );
|
62 | }).listen(8080);
|
63 | ```
|
64 |
|
65 | ## API
|
66 |
|
67 | ### multiparty.Form
|
68 | ```js
|
69 | var form = new multiparty.Form(options)
|
70 | ```
|
71 | Creates a new form. Options:
|
72 |
|
73 | * `encoding` - sets encoding for the incoming form fields. Defaults to `utf8`.
|
74 | * `maxFieldsSize` - Limits the amount of memory a field (not a file) can
|
75 | allocate in bytes. If this value is exceeded, an `error` event is emitted.
|
76 | The default size is 2MB.
|
77 | * `maxFields` - Limits the number of fields that will be parsed before
|
78 | emitting an `error` event. A file counts as a field in this case.
|
79 | Defaults to 1000.
|
80 | * `maxFilesSize` - Only relevant when `autoFiles` is `true`. Limits the
|
81 | total bytes accepted for all files combined. If this value is exceeded,
|
82 | an `error` event is emitted. The default is `Infinity`.
|
83 | * `autoFields` - Enables `field` events. This is automatically set to `true`
|
84 | if you add a `field` listener.
|
85 | * `autoFiles` - Enables `file` events. This is automatically set to `true`
|
86 | if you add a `file` listener.
|
87 | * `uploadDir` - Only relevant when `autoFiles` is `true`. The directory for
|
88 | placing file uploads in. You can move them later using `fs.rename()`.
|
89 | Defaults to `os.tmpDir()`.
|
90 | * `hash` - Only relevant when `autoFiles` is `true`. If you want checksums
|
91 | calculated for incoming files, set this to either `sha1` or `md5`.
|
92 | Defaults to off.
|
93 |
|
94 | #### form.parse(request, [cb])
|
95 |
|
96 | Parses an incoming node.js `request` containing form data. If `cb` is
|
97 | provided, `autoFields` and `autoFiles` are set to `true` and all fields and
|
98 | files are collected and passed to the callback:
|
99 |
|
100 | ```js
|
101 | form.parse(req, function(err, fields, files) {
|
102 | // ...
|
103 | });
|
104 | ```
|
105 |
|
106 | `fields` is an object where the property names are field names and the values
|
107 | are arrays of field values.
|
108 |
|
109 | `files` is an object where the property names are field names and the values
|
110 | are arrays of file objects.
|
111 |
|
112 | #### form.bytesReceived
|
113 |
|
114 | The amount of bytes received for this form so far.
|
115 |
|
116 | #### form.bytesExpected
|
117 |
|
118 | The expected number of bytes in this form.
|
119 |
|
120 | ### Events
|
121 |
|
122 | #### 'error' (err)
|
123 |
|
124 | Unless you supply a callback to `form.parse`, you definitely want to handle
|
125 | this event. Otherwise your server *will* crash when users submit bogus
|
126 | multipart requests!
|
127 |
|
128 | Only one 'error' event can ever be emitted, and if an 'error' event is
|
129 | emitted, then 'close' will not be emitted.
|
130 |
|
131 | #### 'part' (part)
|
132 |
|
133 | Emitted when a part is encountered in the request. `part` is a
|
134 | `ReadableStream`. It also has the following properties:
|
135 |
|
136 | * `headers` - the headers for this part. For example, you may be interested
|
137 | in `content-type`.
|
138 | * `name` - the field name for this part
|
139 | * `filename` - only if the part is an incoming file
|
140 | * `byteOffset` - the byte offset of this part in the request body
|
141 | * `byteCount` - assuming that this is the last part in the request,
|
142 | this is the size of this part in bytes. You could use this, for
|
143 | example, to set the `Content-Length` header if uploading to S3.
|
144 | If the part had a `Content-Length` header then that value is used
|
145 | here instead.
|
146 |
|
147 | #### 'aborted'
|
148 |
|
149 | Emitted when the request is aborted. This event will be followed shortly
|
150 | by an `error` event. In practice you do not need to handle this event.
|
151 |
|
152 | #### 'progress' (bytesReceived, bytesExpected)
|
153 |
|
154 | #### 'close'
|
155 |
|
156 | Emitted after all parts have been parsed and emitted. Not emitted if an `error`
|
157 | event is emitted. This is typically when you would send your response.
|
158 |
|
159 | #### 'file' (name, file)
|
160 |
|
161 | **By default multiparty will not touch your hard drive.** But if you add this
|
162 | listener, multiparty automatically sets `form.autoFiles` to `true` and will
|
163 | stream uploads to disk for you.
|
164 |
|
165 | **The max bytes accepted per request can be specified with `maxFilesSize`.**
|
166 |
|
167 | * `name` - the field name for this file
|
168 | * `file` - an object with these properties:
|
169 | - `fieldName` - same as `name` - the field name for this file
|
170 | - `originalFilename` - the filename that the user reports for the file
|
171 | - `path` - the absolute path of the uploaded file on disk
|
172 | - `headers` - the HTTP headers that were sent along with this file
|
173 | - `size` - size of the file in bytes
|
174 |
|
175 | If you set the `form.hash` option, then `file` will also contain a `hash`
|
176 | property which is the checksum of the file.
|
177 |
|
178 | #### 'field' (name, value)
|
179 |
|
180 | * `name` - field name
|
181 | * `value` - string field value
|
182 |
|