/busboy

A streaming parser for HTML form data for node.js

Primary LanguageJavaScriptMIT LicenseMIT

Description

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

Requirements

Install

npm install busboy

Examples

  • Parsing (multipart) with default options:
var http = require('http'),
    inspect = require('util').inspect;

var Busboy = require('busboy');

http.createServer(function(req, res) {
  if (req.method === 'POST') {
    var busboy = new Busboy({ headers: req.headers });
    busboy.on('file', function(fieldname, file, filename, encoding, mimetype) {
      console.log('File [' + fieldname +']: filename: ' + filename + ', encoding: ' + encoding);
      file.on('data', function(data) {
        console.log('File [' + fieldname +'] got ' + data.length + ' bytes');
      });
      file.on('end', function() {
        console.log('File [' + fieldname +'] Finished');
      });
    });
    busboy.on('field', function(fieldname, val, valTruncated, keyTruncated) {
      console.log('Field [' + fieldname + ']: value: ' + inspect(val));
    });
    busboy.on('end', function() {
      console.log('Done parsing form!');
      res.writeHead(303, { Connection: 'close', Location: '/' });
      res.end();
    });
    req.pipe(busboy);
  } 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="text" name="textfield"><br />\
                <input type="file" name="filefield"><br />\
                <input type="submit">\
              </form>\
            </body></html>');
  }
}).listen(8000, function() {
  console.log('Listening for requests');
});

// Example output, using http://nodejs.org/images/ryan-speaker.jpg as the file:
//
// Listening for requests
// File [filefield]: filename: ryan-speaker.jpg, encoding: binary
// File [filefield] got 11971 bytes
// Field [textfield]: value: 'testing! :-)'
// File [filefield] Finished
// Done parsing form!
  • Parsing multipart/form-data & saving files. Keep track of the point where the files are all properly saved to disk.
http.createServer(function(req, res) {
  if (req.method === 'POST') {
    var infiles = 0, outfiles = 0, done = false,
        busboy = new Busboy({ headers: req.headers });
    console.log('Start parsing form ...');
    busboy.on('file', function(fieldname, file, filename, encoding, mimetype) {
      ++infiles;
      onFile(fieldname, file, filename, function() {
        ++outfiles;
        if (done)
          console.log(outfiles + '/' + infiles + ' parts written to disk');
        if (done && infiles === outfiles) {
          // ACTUAL EXIT CONDITION
          console.log('All parts written to disk');
          res.writeHead(200, { 'Connection': 'close' });
          res.end("That's all folks!");
        }
      });
    });
    busboy.on('end', function() {
      console.log('Done parsing form!');
      done = true;
    });
    req.pipe(busboy);
  }
}).listen(8000, function() {
  console.log('Listening for requests');
});

function onFile(fieldname, file, filename, next) {
  // or save at some other location
  var fstream = fs.createWriteStream(path.join(os.tmpDir(), path.basename(filename)));
  file.on('end', function() {
    console.log(fieldname + '(' + filename + ') EOF');
  });
  fstream.on('close', function() {
    console.log(fieldname + '(' + filename + ') written to disk');
    next();
  });
  console.log(fieldname + '(' + filename + ') start saving');
  file.pipe(fstream);
}
  • Parsing (urlencoded) with default options:
var http = require('http'),
    inspect = require('util').inspect;

var Busboy = require('busboy');

http.createServer(function(req, res) {
  if (req.method === 'POST') {
    var busboy = new Busboy({ headers: req.headers });
    busboy.on('file', function(fieldname, file, filename, encoding, mimetype) {
      console.log('File [' + fieldname +']: filename: ' + filename);
      file.on('data', function(data) {
        console.log('File [' + fieldname +'] got ' + data.length + ' bytes');
      });
      file.on('end', function() {
        console.log('File [' + fieldname +'] Finished');
      });
    });
    busboy.on('field', function(fieldname, val, valTruncated, keyTruncated) {
      console.log('Field [' + fieldname + ']: value: ' + inspect(val));
    });
    busboy.on('end', function() {
      console.log('Done parsing form!');
      res.writeHead(303, { Connection: 'close', Location: '/' });
      res.end();
    });
    req.pipe(busboy);
  } else if (req.method === 'GET') {
    res.writeHead(200, { Connection: 'close' });
    res.end('<html><head></head><body>\
               <form method="POST">\
                <input type="text" name="textfield"><br />\
                <select name="selectfield">\
                  <option value="1">1</option>\
                  <option value="10">10</option>\
                  <option value="100">100</option>\
                  <option value="9001">9001</option>\
                </select><br />\
                <input type="checkbox" name="checkfield">Node.js rules!<br />\
                <input type="submit">\
              </form>\
            </body></html>');
  }
}).listen(8000, function() {
  console.log('Listening for requests');
});

// Example output:
//
// Listening for requests
// Field [textfield]: value: 'testing! :-)'
// Field [selectfield]: value: '9001'
// Field [checkfield]: value: 'on'
// Done parsing form!

API

Busboy is a Writable stream

Busboy (special) events

  • 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. Notice that when no file is attached to the field, (typeof filename === 'undefined'), the stream is 0-length but still requires draining to signal that the event was handled, otherwise the 'end' event will not fire. call stream.resume() to drain the stream.

  • field(< string >fieldname, < string >value, < boolean >valueTruncated, < boolean >fieldnameTruncated) - Emitted for each new non-file field found.

Note: The stream passed in on the 'file' event will also emit a 'limit' event (no arguments) if the fileSize limit is reached. If this happens, no more data will be available on the stream.

Busboy methods

  • (constructor)(< object >config) - Creates and returns a new Busboy instance with the following valid config settings:

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

    • highWaterMark - integer - highWaterMark to use for this Busboy instance (Default: WritableStream default).

    • fileHwm - integer - highWaterMark to use for file streams (Default: ReadableStream default).

    • defCharset - string - Default character set to use when one isn't defined (Default: 'utf8').

    • limits - object - Various limits on incoming data. Valid properties are:

      • fieldNameSize - integer - Max field name size (Default: 100 bytes).

      • fieldSize - integer - Max field value size (Default: 1MB).

      • fields - integer - Max number of non-file fields (Default: Infinity).

      • fileSize - integer - For multipart forms, the max file size (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).