Name: js-handler/node_modules/restify/node_modules/formidable/Readme.md 
1:
# Formidable
2:
 
3:
[![Build Status](https://secure.travis-ci.org/felixge/node-formidable.png?branch=master)](http://travis-ci.org/felixge/node-formidable)
4:
 
5:
## Purpose
6:
 
7:
A node.js module for parsing form data, especially file uploads.
8:
 
9:
## Current status
10:
 
11:
This module was developed for [Transloadit](http://transloadit.com/), a service focused on uploading
12:
and encoding images and videos. It has been battle-tested against hundreds of GB of file uploads from
13:
a large variety of clients and is considered production-ready.
14:
 
15:
## Features
16:
 
17:
* Fast (~500mb/sec), non-buffering multipart parser
18:
* Automatically writing file uploads to disk
19:
* Low memory footprint
20:
* Graceful error handling
21:
* Very high test coverage
22:
 
23:
## Installation
24:
 
25:
Via [npm](http://github.com/isaacs/npm):
26:
```
27:
npm install [email protected]
28:
```
29:
Manually:
30:
```
31:
git clone git://github.com/felixge/node-formidable.git formidable
32:
vim my.js
33:
# var formidable = require('./formidable');
34:
```
35:
 
36:
Note: Formidable requires [gently](http://github.com/felixge/node-gently) to run the unit tests, but you won't need it for just using the library.
37:
 
38:
## Example
39:
 
40:
Parse an incoming file upload.
41:
```javascript
42:
var formidable = require('formidable'),
43:
    http = require('http'),
44:
    util = require('util');
45:
 
46:
http.createServer(function(req, res) {
47:
  if (req.url == '/upload' && req.method.toLowerCase() == 'post') {
48:
    // parse a file upload
49:
    var form = new formidable.IncomingForm();
50:
 
51:
    form.parse(req, function(err, fields, files) {
52:
      res.writeHead(200, {'content-type': 'text/plain'});
53:
      res.write('received upload:\n\n');
54:
      res.end(util.inspect({fields: fields, files: files}));
55:
    });
56:
 
57:
    return;
58:
  }
59:
 
60:
  // show a file upload form
61:
  res.writeHead(200, {'content-type': 'text/html'});
62:
  res.end(
63:
    '<form action="/upload" enctype="multipart/form-data" method="post">'+
64:
    '<input type="text" name="title"><br>'+
65:
    '<input type="file" name="upload" multiple="multiple"><br>'+
66:
    '<input type="submit" value="Upload">'+
67:
    '</form>'
68:
  );
69:
}).listen(8080);
70:
```
71:
## API
72:
 
73:
### Formidable.IncomingForm
74:
```javascript
75:
var form = new formidable.IncomingForm()
76:
```
77:
Creates a new incoming form.
78:
 
79:
```javascript
80:
form.encoding = 'utf-8';
81:
```
82:
Sets encoding for incoming form fields.
83:
 
84:
```javascript
85:
form.uploadDir = process.env.TMP || process.env.TMPDIR || process.env.TEMP || '/tmp' || process.cwd();
86:
```
87:
The directory for placing file uploads in. You can move them later on using
88:
`fs.rename()`. The default directory is picked at module load time depending on
89:
the first existing directory from those listed above.
90:
 
91:
```javascript
92:
form.keepExtensions = false;
93:
```
94:
If you want the files written to `form.uploadDir` to include the extensions of the original files, set this property to `true`.
95:
 
96:
```javascript
97:
form.type
98:
```
99:
Either 'multipart' or 'urlencoded' depending on the incoming request.
100:
 
101:
```javascript
102:
form.maxFieldsSize = 2 * 1024 * 1024;
103:
```
104:
Limits the amount of memory a field (not file) can allocate in bytes.
105:
If this value is exceeded, an `'error'` event is emitted. The default
106:
size is 2MB.
107:
 
108:
```javascript
109:
form.maxFields = 0;
110:
```
111:
Limits the number of fields that the querystring parser will decode. Defaults
112:
to 0 (unlimited).
113:
 
114:
```javascript
115:
form.hash = false;
116:
```
117:
If you want checksums calculated for incoming files, set this to either `'sha1'` or `'md5'`.
118:
 
119:
```javascript
120:
form.bytesReceived
121:
```
122:
The amount of bytes received for this form so far.
123:
 
124:
```javascript
125:
form.bytesExpected
126:
```
127:
The expected number of bytes in this form.
128:
 
129:
```javascript
130:
form.parse(request, [cb]);
131:
```
132:
Parses an incoming node.js `request` containing form data. If `cb` is provided, all fields an files are collected and passed to the callback:
133:
 
134:
 
135:
```javascript
136:
form.parse(req, function(err, fields, files) {
137:
  // ...
138:
});
139:
 
140:
form.onPart(part);
141:
```
142:
You may overwrite this method if you are interested in directly accessing the multipart stream. Doing so will disable any `'field'` / `'file'` events  processing which would occur otherwise, making you fully responsible for handling the processing.
143:
 
144:
```javascript
145:
form.onPart = function(part) {
146:
  part.addListener('data', function() {
147:
    // ...
148:
  });
149:
}
150:
```
151:
If you want to use formidable to only handle certain parts for you, you can do so:
152:
```javascript
153:
form.onPart = function(part) {
154:
  if (!part.filename) {
155:
    // let formidable handle all non-file parts
156:
    form.handlePart(part);
157:
  }
158:
}
159:
```
160:
Check the code in this method for further inspiration.
161:
 
162:
 
163:
### Formidable.File
164:
```javascript
165:
file.size = 0
166:
```
167:
The size of the uploaded file in bytes. If the file is still being uploaded (see `'fileBegin'` event), this property says how many bytes of the file have been written to disk yet.
168:
```javascript
169:
file.path = null
170:
```
171:
The path this file is being written to. You can modify this in the `'fileBegin'` event in
172:
case you are unhappy with the way formidable generates a temporary path for your files.
173:
```javascript
174:
file.name = null
175:
```
176:
The name this file had according to the uploading client.
177:
```javascript
178:
file.type = null
179:
```
180:
The mime type of this file, according to the uploading client.
181:
```javascript
182:
file.lastModifiedDate = null
183:
```
184:
A date object (or `null`) containing the time this file was last written to. Mostly
185:
here for compatibility with the [W3C File API Draft](http://dev.w3.org/2006/webapi/FileAPI/).
186:
```javascript
187:
file.hash = null
188:
```
189:
If hash calculation was set, you can read the hex digest out of this var.
190:
 
191:
#### Formidable.File#toJSON()
192:
 
193:
  This method returns a JSON-representation of the file, allowing you to
194:
  `JSON.stringify()` the file which is useful for logging and responding
195:
  to requests.
196:
 
197:
### Events
198:
 
199:
 
200:
#### 'progress'
201:
```javascript
202:
form.on('progress', function(bytesReceived, bytesExpected) {
203:
});
204:
```
205:
Emitted after each incoming chunk of data that has been parsed. Can be used to roll your own progress bar.
206:
 
207:
 
208:
 
209:
#### 'field'
210:
```javascript
211:
form.on('field', function(name, value) {
212:
});
213:
```
214:
 
215:
#### 'fileBegin'
216:
 
217:
Emitted whenever a field / value pair has been received.
218:
```javascript
219:
form.on('fileBegin', function(name, file) {
220:
});
221:
```
222:
 
223:
#### 'file'
224:
 
225:
Emitted whenever a new file is detected in the upload stream. Use this even if
226:
you want to stream the file to somewhere else while buffering the upload on
227:
the file system.
228:
 
229:
Emitted whenever a field / file pair has been received. `file` is an instance of `File`.
230:
```javascript
231:
form.on('file', function(name, file) {
232:
});
233:
```
234:
 
235:
#### 'error'
236:
 
237:
Emitted when there is an error processing the incoming form. A request that experiences an error is automatically paused, you will have to manually call `request.resume()` if you want the request to continue firing `'data'` events.
238:
```javascript
239:
form.on('error', function(err) {
240:
});
241:
```
242:
 
243:
#### 'aborted'
244:
 
245:
 
246:
Emitted when the request was aborted by the user. Right now this can be due to a 'timeout' or 'close' event on the socket. In the future there will be a separate 'timeout' event (needs a change in the node core).
247:
```javascript
248:
form.on('aborted', function() {
249:
});
250:
```
251:
 
252:
##### 'end'
253:
```javascript
254:
form.on('end', function() {
255:
});
256:
```
257:
Emitted when the entire request has been received, and all contained files have finished flushing to disk. This is a great place for you to send your response.
258:
 
259:
 
260:
 
261:
## Changelog
262:
 
263:
### v1.0.14
264:
 
265:
* Add failing hash tests. (Ben Trask)
266:
* Enable hash calculation again (Eugene Girshov)
267:
* Test for immediate data events (Tim Smart)
268:
* Re-arrange IncomingForm#parse (Tim Smart)
269:
 
270:
### v1.0.13
271:
 
272:
* Only update hash if update method exists (Sven Lito)
273:
* According to travis v0.10 needs to go quoted (Sven Lito)
274:
* Bumping build node versions (Sven Lito)
275:
* Additional fix for empty requests (Eugene Girshov)
276:
* Change the default to 1000, to match the new Node behaviour. (OrangeDog)
277:
* Add ability to control maxKeys in the querystring parser. (OrangeDog)
278:
* Adjust test case to work with node 0.9.x (Eugene Girshov)
279:
* Update package.json (Sven Lito)
280:
* Path adjustment according to eb4468b (Markus Ast)
281:
 
282:
### v1.0.12
283:
 
284:
* Emit error on aborted connections (Eugene Girshov)
285:
* Add support for empty requests (Eugene Girshov)
286:
* Fix name/filename handling in Content-Disposition (jesperp)
287:
* Tolerate malformed closing boundary in multipart (Eugene Girshov)
288:
* Ignore preamble in multipart messages (Eugene Girshov)
289:
* Add support for application/json (Mike Frey, Carlos Rodriguez)
290:
* Add support for Base64 encoding (Elmer Bulthuis)
291:
* Add File#toJSON (TJ Holowaychuk)
292:
* Remove support for Node.js 0.4 & 0.6 (Andrew Kelley)
293:
* Documentation improvements (Sven Lito, Andre Azevedo)
294:
* Add support for application/octet-stream (Ion Lupascu, Chris Scribner)
295:
* Use os.tmpDir() to get tmp directory (Andrew Kelley)
296:
* Improve package.json (Andrew Kelley, Sven Lito)
297:
* Fix benchmark script (Andrew Kelley)
298:
* Fix scope issue in incoming_forms (Sven Lito)
299:
* Fix file handle leak on error (OrangeDog)
300:
 
301:
### v1.0.11
302:
 
303:
* Calculate checksums for incoming files (sreuter)
304:
* Add definition parameters to "IncomingForm" as an argument (Math-)
305:
 
306:
### v1.0.10
307:
 
308:
* Make parts to be proper Streams (Matt Robenolt)
309:
 
310:
### v1.0.9
311:
 
312:
* Emit progress when content length header parsed (Tim Koschützki)
313:
* Fix Readme syntax due to GitHub changes (goob)
314:
* Replace references to old 'sys' module in Readme with 'util' (Peter Sugihara)
315:
 
316:
### v1.0.8
317:
 
318:
* Strip potentially unsafe characters when using `keepExtensions: true`.
319:
* Switch to utest / urun for testing
320:
* Add travis build
321:
 
322:
### v1.0.7
323:
 
324:
* Remove file from package that was causing problems when installing on windows. (#102)
325:
* Fix typos in Readme (Jason Davies).
326:
 
327:
### v1.0.6
328:
 
329:
* Do not default to the default to the field name for file uploads where
330:
  filename="".
331:
 
332:
### v1.0.5
333:
 
334:
* Support filename="" in multipart parts
335:
* Explain unexpected end() errors in parser better
336:
 
337:
**Note:** Starting with this version, formidable emits 'file' events for empty
338:
file input fields. Previously those were incorrectly emitted as regular file
339:
input fields with value = "".
340:
 
341:
### v1.0.4
342:
 
343:
* Detect a good default tmp directory regardless of platform. (#88)
344:
 
345:
### v1.0.3
346:
 
347:
* Fix problems with utf8 characters (#84) / semicolons in filenames (#58)
348:
* Small performance improvements
349:
* New test suite and fixture system
350:
 
351:
### v1.0.2
352:
 
353:
* Exclude node\_modules folder from git
354:
* Implement new `'aborted'` event
355:
* Fix files in example folder to work with recent node versions
356:
* Make gently a devDependency
357:
 
358:
[See Commits](https://github.com/felixge/node-formidable/compare/v1.0.1...v1.0.2)
359:
 
360:
### v1.0.1
361:
 
362:
* Fix package.json to refer to proper main directory. (#68, Dean Landolt)
363:
 
364:
[See Commits](https://github.com/felixge/node-formidable/compare/v1.0.0...v1.0.1)
365:
 
366:
### v1.0.0
367:
 
368:
* Add support for multipart boundaries that are quoted strings. (Jeff Craig)
369:
 
370:
This marks the beginning of development on version 2.0 which will include
371:
several architectural improvements.
372:
 
373:
[See Commits](https://github.com/felixge/node-formidable/compare/v0.9.11...v1.0.0)
374:
 
375:
### v0.9.11
376:
 
377:
* Emit `'progress'` event when receiving data, regardless of parsing it. (Tim Koschützki)
378:
* Use [W3C FileAPI Draft](http://dev.w3.org/2006/webapi/FileAPI/) properties for File class
379:
 
380:
**Important:** The old property names of the File class will be removed in a
381:
future release.
382:
 
383:
[See Commits](https://github.com/felixge/node-formidable/compare/v0.9.10...v0.9.11)
384:
 
385:
### Older releases
386:
 
387:
These releases were done before starting to maintain the above Changelog:
388:
 
389:
* [v0.9.10](https://github.com/felixge/node-formidable/compare/v0.9.9...v0.9.10)
390:
* [v0.9.9](https://github.com/felixge/node-formidable/compare/v0.9.8...v0.9.9)
391:
* [v0.9.8](https://github.com/felixge/node-formidable/compare/v0.9.7...v0.9.8)
392:
* [v0.9.7](https://github.com/felixge/node-formidable/compare/v0.9.6...v0.9.7)
393:
* [v0.9.6](https://github.com/felixge/node-formidable/compare/v0.9.5...v0.9.6)
394:
* [v0.9.5](https://github.com/felixge/node-formidable/compare/v0.9.4...v0.9.5)
395:
* [v0.9.4](https://github.com/felixge/node-formidable/compare/v0.9.3...v0.9.4)
396:
* [v0.9.3](https://github.com/felixge/node-formidable/compare/v0.9.2...v0.9.3)
397:
* [v0.9.2](https://github.com/felixge/node-formidable/compare/v0.9.1...v0.9.2)
398:
* [v0.9.1](https://github.com/felixge/node-formidable/compare/v0.9.0...v0.9.1)
399:
* [v0.9.0](https://github.com/felixge/node-formidable/compare/v0.8.0...v0.9.0)
400:
* [v0.9.0](https://github.com/felixge/node-formidable/compare/v0.8.0...v0.9.0)
401:
* [v0.9.0](https://github.com/felixge/node-formidable/compare/v0.8.0...v0.9.0)
402:
* [v0.9.0](https://github.com/felixge/node-formidable/compare/v0.8.0...v0.9.0)
403:
* [v0.9.0](https://github.com/felixge/node-formidable/compare/v0.8.0...v0.9.0)
404:
* [v0.9.0](https://github.com/felixge/node-formidable/compare/v0.8.0...v0.9.0)
405:
* [v0.9.0](https://github.com/felixge/node-formidable/compare/v0.8.0...v0.9.0)
406:
* [v0.9.0](https://github.com/felixge/node-formidable/compare/v0.8.0...v0.9.0)
407:
* [v0.1.0](https://github.com/felixge/node-formidable/commits/v0.1.0)
408:
 
409:
## License
410:
 
411:
Formidable is licensed under the MIT license.
412:
 
413:
## Ports
414:
 
415:
* [multipart-parser](http://github.com/FooBarWidget/multipart-parser): a C++ parser based on formidable
416:
 
417:
## Credits
418:
 
419:
* [Ryan Dahl](http://twitter.com/ryah) for his work on [http-parser](http://github.com/ry/http-parser) which heavily inspired multipart_parser.js