bus

busboy

A streaming parser for HTML form data for node.js

Showing:

Popularity

Downloads/wk

3.6M

GitHub Stars

2.2K

Maintenance

Last Commit

1mo ago

Contributors

12

Package

Dependencies

1

License

Type Definitions

Tree-Shakeable

No?

Readme

Description

A node.js module for parsing incoming HTML form data.

Changes (breaking or otherwise) in v1.0.0 can be found here.

Requirements

Install

npm install busboy

Examples

  • Parsing (multipart) with default options:
const http = require('http'),

const busboy = require('busboy');

http.createServer((req, res) => {
  if (req.method === 'POST') {
    console.log('POST request');
    const bb = busboy({ headers: req.headers });
    bb.on('file', (name, file, info) => {
      const { filename, encoding, mime } = info;
      console.log(
        `File [${name}]: filename: %j, encoding: %j, mime: %j`,
        filename,
        encoding,
        mime
      );
      file.on('data', (data) => {
        console.log(`File [${name}] got ${data.length} bytes`);
      }).on('close', () => {
        console.log(`File [${name}] done`);
      });
    });
    bb.on('field', (name, val, info) => {
      console.log(`Field [${name}]: value: %j`, val);
    });
    bb.on('close', () => {
      console.log('Done parsing form!');
      res.writeHead(303, { Connection: 'close', Location: '/' });
      res.end();
    });
    req.pipe(bb);
  } else if (req.method === 'GET') {
    res.writeHead(200, { Connection: 'close' });
    res.end(`
      <html>
        <head></head>
        <body>
          <form method="POST" enctype="multipart/form-data">
            <input type="file" name="filefield"><br />
            <input type="text" name="textfield"><br />
            <input type="submit">
          </form>
        </body>
      </html>
    `);
  }
}).listen(8000, () => {
  console.log('Listening for requests');
});

// Example output:
//
// Listening for requests
//   < ... form submitted ... >
// POST request
// File [filefield]: filename: "logo.jpg", encoding: "binary", mime: "image/jpeg"
// File [filefield] got 11912 bytes
// Field [textfield]: value: "testing! :-)"
// File [filefield] done
// Done parsing form!
  • Save all incoming files to disk:
const { randomFillSync } = require('crypto');
const fs = require('fs');
const http = require('http');
const os = require('os');
const path = require('path');

const busboy = require('busboy');

const random = (() => {
  const buf = Buffer.alloc(16);
  return () => randomFillSync(buf).toString('hex');
})();

http.createServer((req, res) => {
  if (req.method === 'POST') {
    const bb = busboy({ headers: req.headers });
    bb.on('file', (name, file, info) => {
      const saveTo = path.join(os.tmpDir(), `busboy-upload-${random()}`);
      file.pipe(fs.createWriteStream(saveTo));
    });
    bb.on('close', () => {
      res.writeHead(200, { 'Connection': 'close' });
      res.end(`That's all folks!`);
    });
    req.pipe(bb);
    return;
  }
  res.writeHead(404);
  res.end();
}).listen(8000, () => {
  console.log('Listening for requests');
});

API

Exports

busboy exports a single function:

( function )(< object >config) - Creates and returns a new Writable form parser stream.

* Valid `config` properties:

    * **headers** - _object_ - These are the HTTP headers of the incoming request, which are used by individual parsers.

    * **highWaterMark** - _integer_ - highWaterMark to use for the parser stream. **Default:** node's _stream.Writable_ default.

    * **fileHwm** - _integer_ - highWaterMark to use for individual file streams. **Default:** node's _stream.Readable_ default.

    * **defCharset** - _string_ - Default character set to use when one isn't defined. **Default:** `'utf8'`.

    * **preservePath** - _boolean_ - If paths in filenames from file parts in a `'multipart/form-data'` request shall be preserved. **Default:** `false`.

    * **limits** - _object_ - Various limits on incoming data. Valid properties are:

        * **fieldNameSize** - _integer_ - Max field name size (in bytes). **Default:** `100`.

        * **fieldSize** - _integer_ - Max field value size (in bytes). **Default:** `1048576` (1MB).

        * **fields** - _integer_ - Max number of non-file fields. **Default:** `Infinity`.

        * **fileSize** - _integer_ - For multipart forms, the max file size (in bytes). **Default:** `Infinity`.

        * **files** - _integer_ - For multipart forms, the max number of file fields. **Default:** `Infinity`.

        * **parts** - _integer_ - For multipart forms, the max number of parts (fields + files). **Default:** `Infinity`.

        * **headerPairs** - _integer_ - For multipart forms, the max number of header key-value pairs to parse. **Default:** `2000` (same as node's http module).

This 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.

(Special) Parser stream events

  • 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:

    • 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.

    • encoding - string - The file's 'Content-Transfer-Encoding' value.

    • mimeType - string - The file's 'Content-Type' value.

      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. 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).

      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.

  • 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:

    • nameTruncated - boolean - Whether name was truncated or not (due to a configured limits.fieldNameSize limit)

    • valueTruncated - boolean - Whether value was truncated or not (due to a configured limits.fieldSize limit)

    • encoding - string - The field's 'Content-Transfer-Encoding' value.

    • mimeType - string - The field's 'Content-Type' value.

  • partsLimit() - Emitted when the configured limits.parts limit has been reached. No more 'file' or 'field' events will be emitted.

  • filesLimit() - Emitted when the configured limits.files limit has been reached. No more 'file' events will be emitted.

  • fieldsLimit() - Emitted when the configured limits.fields limit has been reached. No more 'field' events will be emitted.

Rate & Review

Great Documentation0
Easy to Use0
Performant0
Highly Customizable0
Bleeding Edge0
Responsive Maintainers0
Poor Documentation0
Hard to Use0
Slow0
Buggy0
Abandoned0
Unwelcoming Community0
100
No reviews found
Be the first to rate

Alternatives

webtorrent⚡️ Streaming torrent client for the web
User Rating
4.6/ 5
52
Top Feedback
2Easy to Use
2Performant
1Highly Customizable
GitHub Stars
25K
Weekly Downloads
18K
scramjetSimple yet powerful live data computation framework
User Rating
5.0/ 5
2
Top Feedback
1Great Documentation
1Easy to Use
1Performant
GitHub Stars
208
Weekly Downloads
4K
archivera streaming interface for archive generation
User Rating
3.5/ 5
2
Top Feedback
2Easy to Use
1Great Documentation
1Poor Documentation
GitHub Stars
2K
Weekly Downloads
7M
nms
node-media-serverA Node.js implementation of RTMP/HTTP-FLV/WS-FLV/HLS/DASH/MP4 Media Server
User Rating
5.0/ 5
1
Top Feedback
1Slow
GitHub Stars
4K
Weekly Downloads
2K
hig
highlandHigh-level streams library for Node.js and the browser
User Rating
5.0/ 5
1
Top Feedback
N/A
GitHub Stars
3K
Weekly Downloads
46K
twi
twitTwitter API Client for node (REST & Streaming API)
User Rating
5.0/ 5
1
Top Feedback
1Easy to Use
GitHub Stars
4K
Weekly Downloads
36K
See 18 Alternatives

Tutorials

No tutorials found
Add a tutorial