README.md
1# busboy
2
3<div align="center">
4
5[](https://github.com/fastify/busboy/actions)
6[](https://coveralls.io/r/fastify/busboy?branch=master)
7[](https://standardjs.com/)
8[](https://github.com/fastify/.github/blob/main/SECURITY.md)
9
10</div>
11
12<div align="center">
13
14[](https://www.npmjs.com/package/@fastify/busboy)
15[](https://www.npmjs.com/package/@fastify/busboy)
16
17</div>
18
19Description
20===========
21
22A Node.js module for parsing incoming HTML form data.
23
24This is an officially supported fork by [fastify](https://github.com/fastify/) organization of the amazing library [originally created](https://github.com/mscdex/busboy) by Brian White,
25aimed at addressing long-standing issues with it.
26
27Benchmark (Mean time for 500 Kb payload, 2000 cycles, 1000 cycle warmup):
28
29| Library | Version | Mean time in nanoseconds (less is better) |
30|-----------------------|---------|-------------------------------------------|
31| busboy | 0.3.1 | `340114` |
32| @fastify/busboy | 1.0.0 | `270984` |
33
34[Changelog](https://github.com/fastify/busboy/blob/master/CHANGELOG.md) since busboy 0.31.
35
36Requirements
37============
38
39* [Node.js](http://nodejs.org/) 10+
40
41
42Install
43=======
44
45 npm i @fastify/busboy
46
47
48Examples
49========
50
51* Parsing (multipart) with default options:
52
53```javascript
54const http = require('node:http');
55const { inspect } = require('node:util');
56const Busboy = require('busboy');
57
58http.createServer((req, res) => {
59 if (req.method === 'POST') {
60 const busboy = new Busboy({ headers: req.headers });
61 busboy.on('file', (fieldname, file, filename, encoding, mimetype) => {
62 console.log(`File [${fieldname}]: filename: ${filename}, encoding: ${encoding}, mimetype: ${mimetype}`);
63 file.on('data', data => {
64 console.log(`File [${fieldname}] got ${data.length} bytes`);
65 });
66 file.on('end', () => {
67 console.log(`File [${fieldname}] Finished`);
68 });
69 });
70 busboy.on('field', (fieldname, val, fieldnameTruncated, valTruncated, encoding, mimetype) => {
71 console.log(`Field [${fieldname}]: value: ${inspect(val)}`);
72 });
73 busboy.on('finish', () => {
74 console.log('Done parsing form!');
75 res.writeHead(303, { Connection: 'close', Location: '/' });
76 res.end();
77 });
78 req.pipe(busboy);
79 } else if (req.method === 'GET') {
80 res.writeHead(200, { Connection: 'close' });
81 res.end(`<html><head></head><body>
82 <form method="POST" enctype="multipart/form-data">
83 <input type="text" name="textfield"><br>
84 <input type="file" name="filefield"><br>
85 <input type="submit">
86 </form>
87 </body></html>`);
88 }
89}).listen(8000, () => {
90 console.log('Listening for requests');
91});
92
93// Example output, using http://nodejs.org/images/ryan-speaker.jpg as the file:
94//
95// Listening for requests
96// File [filefield]: filename: ryan-speaker.jpg, encoding: binary
97// File [filefield] got 11971 bytes
98// Field [textfield]: value: 'testing! :-)'
99// File [filefield] Finished
100// Done parsing form!
101```
102
103* Save all incoming files to disk:
104
105```javascript
106const http = require('node:http');
107const path = require('node:path');
108const os = require('node:os');
109const fs = require('node:fs');
110
111const Busboy = require('busboy');
112
113http.createServer(function(req, res) {
114 if (req.method === 'POST') {
115 const busboy = new Busboy({ headers: req.headers });
116 busboy.on('file', function(fieldname, file, filename, encoding, mimetype) {
117 var saveTo = path.join(os.tmpdir(), path.basename(fieldname));
118 file.pipe(fs.createWriteStream(saveTo));
119 });
120 busboy.on('finish', function() {
121 res.writeHead(200, { 'Connection': 'close' });
122 res.end("That's all folks!");
123 });
124 return req.pipe(busboy);
125 }
126 res.writeHead(404);
127 res.end();
128}).listen(8000, function() {
129 console.log('Listening for requests');
130});
131```
132
133* Parsing (urlencoded) with default options:
134
135```javascript
136const http = require('node:http');
137const { inspect } = require('node:util');
138
139const Busboy = require('busboy');
140
141http.createServer(function(req, res) {
142 if (req.method === 'POST') {
143 const busboy = new Busboy({ headers: req.headers });
144 busboy.on('file', function(fieldname, file, filename, encoding, mimetype) {
145 console.log('File [' + fieldname + ']: filename: ' + filename);
146 file.on('data', function(data) {
147 console.log('File [' + fieldname + '] got ' + data.length + ' bytes');
148 });
149 file.on('end', function() {
150 console.log('File [' + fieldname + '] Finished');
151 });
152 });
153 busboy.on('field', function(fieldname, val, fieldnameTruncated, valTruncated) {
154 console.log('Field [' + fieldname + ']: value: ' + inspect(val));
155 });
156 busboy.on('finish', function() {
157 console.log('Done parsing form!');
158 res.writeHead(303, { Connection: 'close', Location: '/' });
159 res.end();
160 });
161 req.pipe(busboy);
162 } else if (req.method === 'GET') {
163 res.writeHead(200, { Connection: 'close' });
164 res.end('<html><head></head><body>\
165 <form method="POST">\
166 <input type="text" name="textfield"><br />\
167 <select name="selectfield">\
168 <option value="1">1</option>\
169 <option value="10">10</option>\
170 <option value="100">100</option>\
171 <option value="9001">9001</option>\
172 </select><br />\
173 <input type="checkbox" name="checkfield">Node.js rules!<br />\
174 <input type="submit">\
175 </form>\
176 </body></html>');
177 }
178}).listen(8000, function() {
179 console.log('Listening for requests');
180});
181
182// Example output:
183//
184// Listening for requests
185// Field [textfield]: value: 'testing! :-)'
186// Field [selectfield]: value: '9001'
187// Field [checkfield]: value: 'on'
188// Done parsing form!
189```
190
191
192API
193===
194
195_Busboy_ is a _Writable_ stream
196
197Busboy (special) events
198-----------------------
199
200* **file**(< _string_ >fieldname, < _ReadableStream_ >stream, < _string_ >filename, < _string_ >transferEncoding, < _string_ >mimeType) - Emitted for each new file form field found. `transferEncoding` contains the 'Content-Transfer-Encoding' value for the file stream. `mimeType` contains the 'Content-Type' value for the file stream.
201 * Note: if you listen for this event, you should always handle the `stream` no matter if you care about the file contents or not (e.g. you can simply just do `stream.resume();` if you want to discard the contents), otherwise the 'finish' event will never fire on the Busboy instance. However, if you don't care about **any** incoming files, you can simply not listen for the 'file' event at all and any/all files will be automatically and safely discarded (these discarded files do still count towards `files` and `parts` limits).
202 * If a configured file size limit was reached, `stream` will both have a boolean property `truncated` (best checked at the end of the stream) and emit a 'limit' event to notify you when this happens.
203 * The property `bytesRead` informs about the number of bytes that have been read so far.
204
205* **field**(< _string_ >fieldname, < _string_ >value, < _boolean_ >fieldnameTruncated, < _boolean_ >valueTruncated, < _string_ >transferEncoding, < _string_ >mimeType) - Emitted for each new non-file field found.
206
207* **partsLimit**() - Emitted when specified `parts` limit has been reached. No more 'file' or 'field' events will be emitted.
208
209* **filesLimit**() - Emitted when specified `files` limit has been reached. No more 'file' events will be emitted.
210
211* **fieldsLimit**() - Emitted when specified `fields` limit has been reached. No more 'field' events will be emitted.
212
213
214Busboy methods
215--------------
216
217* **(constructor)**(< _object_ >config) - Creates and returns a new Busboy instance.
218
219 * The constructor takes the following valid `config` settings:
220
221 * **headers** - _object_ - These are the HTTP headers of the incoming request, which are used by individual parsers.
222
223 * **autoDestroy** - _boolean_ - Whether this stream should automatically call .destroy() on itself after ending. (Default: false).
224
225 * **highWaterMark** - _integer_ - highWaterMark to use for this Busboy instance (Default: WritableStream default).
226
227 * **fileHwm** - _integer_ - highWaterMark to use for file streams (Default: ReadableStream default).
228
229 * **defCharset** - _string_ - Default character set to use when one isn't defined (Default: 'utf8').
230
231 * **preservePath** - _boolean_ - If paths in the multipart 'filename' field shall be preserved. (Default: false).
232
233 * **isPartAFile** - __function__ - Use this function to override the default file detection functionality. It has following parameters:
234
235 * fieldName - __string__ The name of the field.
236
237 * contentType - __string__ The content-type of the part, e.g. `text/plain`, `image/jpeg`, `application/octet-stream`
238
239 * fileName - __string__ The name of a file supplied by the part.
240
241 (Default: `(fieldName, contentType, fileName) => (contentType === 'application/octet-stream' || fileName !== undefined)`)
242
243 * **limits** - _object_ - Various limits on incoming data. Valid properties are:
244
245 * **fieldNameSize** - _integer_ - Max field name size (in bytes) (Default: 100 bytes).
246
247 * **fieldSize** - _integer_ - Max field value size (in bytes) (Default: 1 MiB, which is 1024 x 1024 bytes).
248
249 * **fields** - _integer_ - Max number of non-file fields (Default: Infinity).
250
251 * **fileSize** - _integer_ - For multipart forms, the max file size (in bytes) (Default: Infinity).
252
253 * **files** - _integer_ - For multipart forms, the max number of file fields (Default: Infinity).
254
255 * **parts** - _integer_ - For multipart forms, the max number of parts (fields + files) (Default: Infinity).
256
257 * **headerPairs** - _integer_ - For multipart forms, the max number of header key=>value pairs to parse **Default:** 2000
258
259 * **headerSize** - _integer_ - For multipart forms, the max size of a multipart header **Default:** 81920.
260
261 * The constructor can throw errors:
262
263 * **Busboy expected an options-Object.** - Busboy expected an Object as first parameters.
264
265 * **Busboy expected an options-Object with headers-attribute.** - The first parameter is lacking of a headers-attribute.
266
267 * **Limit $limit is not a valid number** - Busboy expected the desired limit to be of type number. Busboy throws this Error to prevent a potential security issue by falling silently back to the Busboy-defaults. Potential source for this Error can be the direct use of environment variables without transforming them to the type number.
268
269 * **Unsupported Content-Type.** - The `Content-Type` isn't one Busboy can parse.
270
271 * **Missing Content-Type-header.** - The provided headers don't include `Content-Type` at all.
272
