1# Description 2 3A node.js module for parsing incoming HTML form data. 4 5Changes (breaking or otherwise) in v1.0.0 can be found [here](https://github.com/mscdex/busboy/issues/266). 6 7# Requirements 8 9* [node.js](http://nodejs.org/) -- v10.16.0 or newer 10 11 12# Install 13 14 npm install busboy 15 16 17# Examples 18 19* Parsing (multipart) with default options: 20 21```js 22const http = require('http'); 23 24const busboy = require('busboy'); 25 26http.createServer((req, res) => { 27 if (req.method === 'POST') { 28 console.log('POST request'); 29 const bb = busboy({ headers: req.headers }); 30 bb.on('file', (name, file, info) => { 31 const { filename, encoding, mimeType } = info; 32 console.log( 33 `File [${name}]: filename: %j, encoding: %j, mimeType: %j`, 34 filename, 35 encoding, 36 mimeType 37 ); 38 file.on('data', (data) => { 39 console.log(`File [${name}] got ${data.length} bytes`); 40 }).on('close', () => { 41 console.log(`File [${name}] done`); 42 }); 43 }); 44 bb.on('field', (name, val, info) => { 45 console.log(`Field [${name}]: value: %j`, val); 46 }); 47 bb.on('close', () => { 48 console.log('Done parsing form!'); 49 res.writeHead(303, { Connection: 'close', Location: '/' }); 50 res.end(); 51 }); 52 req.pipe(bb); 53 } else if (req.method === 'GET') { 54 res.writeHead(200, { Connection: 'close' }); 55 res.end(` 56 <html> 57 <head></head> 58 <body> 59 <form method="POST" enctype="multipart/form-data"> 60 <input type="file" name="filefield"><br /> 61 <input type="text" name="textfield"><br /> 62 <input type="submit"> 63 </form> 64 </body> 65 </html> 66 `); 67 } 68}).listen(8000, () => { 69 console.log('Listening for requests'); 70}); 71 72// Example output: 73// 74// Listening for requests 75// < ... form submitted ... > 76// POST request 77// File [filefield]: filename: "logo.jpg", encoding: "binary", mime: "image/jpeg" 78// File [filefield] got 11912 bytes 79// Field [textfield]: value: "testing! :-)" 80// File [filefield] done 81// Done parsing form! 82``` 83 84* Save all incoming files to disk: 85 86```js 87const { randomFillSync } = require('crypto'); 88const fs = require('fs'); 89const http = require('http'); 90const os = require('os'); 91const path = require('path'); 92 93const busboy = require('busboy'); 94 95const random = (() => { 96 const buf = Buffer.alloc(16); 97 return () => randomFillSync(buf).toString('hex'); 98})(); 99 100http.createServer((req, res) => { 101 if (req.method === 'POST') { 102 const bb = busboy({ headers: req.headers }); 103 bb.on('file', (name, file, info) => { 104 const saveTo = path.join(os.tmpdir(), `busboy-upload-${random()}`); 105 file.pipe(fs.createWriteStream(saveTo)); 106 }); 107 bb.on('close', () => { 108 res.writeHead(200, { 'Connection': 'close' }); 109 res.end(`That's all folks!`); 110 }); 111 req.pipe(bb); 112 return; 113 } 114 res.writeHead(404); 115 res.end(); 116}).listen(8000, () => { 117 console.log('Listening for requests'); 118}); 119``` 120 121 122# API 123 124## Exports 125 126`busboy` exports a single function: 127 128**( _function_ )**(< _object_ >config) - Creates and returns a new _Writable_ form parser stream. 129 130* Valid `config` properties: 131 132 * **headers** - _object_ - These are the HTTP headers of the incoming request, which are used by individual parsers. 133 134 * **highWaterMark** - _integer_ - highWaterMark to use for the parser stream. **Default:** node's _stream.Writable_ default. 135 136 * **fileHwm** - _integer_ - highWaterMark to use for individual file streams. **Default:** node's _stream.Readable_ default. 137 138 * **defCharset** - _string_ - Default character set to use when one isn't defined. **Default:** `'utf8'`. 139 140 * **defParamCharset** - _string_ - For multipart forms, the default character set to use for values of part header parameters (e.g. filename) that are not extended parameters (that contain an explicit charset). **Default:** `'latin1'`. 141 142 * **preservePath** - _boolean_ - If paths in filenames from file parts in a `'multipart/form-data'` request shall be preserved. **Default:** `false`. 143 144 * **limits** - _object_ - Various limits on incoming data. Valid properties are: 145 146 * **fieldNameSize** - _integer_ - Max field name size (in bytes). **Default:** `100`. 147 148 * **fieldSize** - _integer_ - Max field value size (in bytes). **Default:** `1048576` (1MB). 149 150 * **fields** - _integer_ - Max number of non-file fields. **Default:** `Infinity`. 151 152 * **fileSize** - _integer_ - For multipart forms, the max file size (in bytes). **Default:** `Infinity`. 153 154 * **files** - _integer_ - For multipart forms, the max number of file fields. **Default:** `Infinity`. 155 156 * **parts** - _integer_ - For multipart forms, the max number of parts (fields + files). **Default:** `Infinity`. 157 158 * **headerPairs** - _integer_ - For multipart forms, the max number of header key-value pairs to parse. **Default:** `2000` (same as node's http module). 159 160This function can throw exceptions if there is something wrong with the values in `config`. For example, if the Content-Type in `headers` is missing entirely, is not a supported type, or is missing the boundary for `'multipart/form-data'` requests. 161 162## (Special) Parser stream events 163 164* **file**(< _string_ >name, < _Readable_ >stream, < _object_ >info) - Emitted for each new file found. `name` contains the form field name. `stream` is a _Readable_ stream containing the file's data. No transformations/conversions (e.g. base64 to raw binary) are done on the file's data. `info` contains the following properties: 165 166 * `filename` - _string_ - If supplied, this contains the file's filename. **WARNING:** You should almost _never_ use this value as-is (especially if you are using `preservePath: true` in your `config`) as it could contain malicious input. You are better off generating your own (safe) filenames, or at the very least using a hash of the filename. 167 168 * `encoding` - _string_ - The file's `'Content-Transfer-Encoding'` value. 169 170 * `mimeType` - _string_ - The file's `'Content-Type'` value. 171 172 **Note:** If you listen for this event, you should always consume the `stream` whether you care about its contents or not (you can simply do `stream.resume();` if you want to discard/skip the contents), otherwise the `'finish'`/`'close'` event will never fire on the busboy parser stream. 173 However, if you aren't accepting files, you can either simply not listen for the `'file'` event at all or set `limits.files` to `0`, and any/all files will be automatically skipped (these skipped files will still count towards any configured `limits.files` and `limits.parts` limits though). 174 175 **Note:** If a configured `limits.fileSize` limit was reached for a file, `stream` will both have a boolean property `truncated` set to `true` (best checked at the end of the stream) and emit a `'limit'` event to notify you when this happens. 176 177* **field**(< _string_ >name, < _string_ >value, < _object_ >info) - Emitted for each new non-file field found. `name` contains the form field name. `value` contains the string value of the field. `info` contains the following properties: 178 179 * `nameTruncated` - _boolean_ - Whether `name` was truncated or not (due to a configured `limits.fieldNameSize` limit) 180 181 * `valueTruncated` - _boolean_ - Whether `value` was truncated or not (due to a configured `limits.fieldSize` limit) 182 183 * `encoding` - _string_ - The field's `'Content-Transfer-Encoding'` value. 184 185 * `mimeType` - _string_ - The field's `'Content-Type'` value. 186 187* **partsLimit**() - Emitted when the configured `limits.parts` limit has been reached. No more `'file'` or `'field'` events will be emitted. 188 189* **filesLimit**() - Emitted when the configured `limits.files` limit has been reached. No more `'file'` events will be emitted. 190 191* **fieldsLimit**() - Emitted when the configured `limits.fields` limit has been reached. No more `'field'` events will be emitted. 192
