raw-body

What is raw-body?

The raw-body npm package is used to obtain the raw body of an incoming stream and supports decoding, parsing, and handling of different encodings. It is commonly used in the context of HTTP server handling, where it can be used to read and parse request bodies before they are processed by request handlers or middleware.

What are raw-body's main functionalities?

Getting raw body from a stream

This code creates an HTTP server that uses raw-body to read the request body as a string. It takes into account the content length and encoding specified in the request headers.

const http = require('http');
const getRawBody = require('raw-body');

http.createServer((req, res) => {
  getRawBody(req, {
    length: req.headers['content-length'],
    encoding: 'utf8'
  }, function (err, string) {
    if (err) return res.end('Error');
    res.end('Received: ' + string);
  });
}).listen(3000);

Handling different encodings

This code demonstrates how to use raw-body to handle different text encodings by specifying the encoding option. The promise interface is used for asynchronous handling.

const getRawBody = require('raw-body');

function handleRequest(req) {
  return getRawBody(req, {
    encoding: 'utf8'
  }).then(body => {
    // body is now a string in utf8 encoding
  }).catch(err => {
    // handle error
  });
}

Limiting body size

This code shows how to limit the size of the request body using raw-body by setting a limit option, which can help prevent denial of service attacks or other resource exhaustion issues.

const getRawBody = require('raw-body');

function handleRequest(req) {
  return getRawBody(req, {
    limit: '1mb'
  }).then(body => {
    // body will not be larger than 1mb
  }).catch(err => {
    // handle error if body is too large
  });
}

Other packages similar to raw-body

body-parser

body-parser is a popular Express middleware that parses incoming request bodies before your handlers, available under the req.body property. It wraps around raw-body and adds additional parsing capabilities for JSON, URL-encoded, and other formats. Unlike raw-body, which provides the raw buffer, body-parser converts the body into more usable formats.

co-body

co-body is a body parser for koa and express, built on top of raw-body, designed to work with co for generator-based flow control. It supports json, form and text types of bodies, but is more tailored for use with Koa and generators.

busboy

busboy is a streaming parser for HTML form data for node.js. It handles multipart/form-data, which is primarily used for uploading files. It differs from raw-body in that it's specialized for file uploads and form submissions, whereas raw-body is more about getting the entire raw request body.

README

raw-body

Gets the entire buffer of a stream either as a Buffer or a string. Validates the stream's length against an expected length and maximum limit. Ideal for parsing request bodies.

API

var getRawBody = require('raw-body')

getRawBody(stream, [options], [callback])

Returns a promise if no callback specified and global Promise exists.

Options:

• length - The length of the stream. If the contents of the stream do not add up to this length, an 400 error code is returned.
• limit - The byte limit of the body. If the body ends up being larger than this limit, a 413 error code is returned.
• encoding - The requested encoding. By default, a Buffer instance will be returned. Most likely, you want utf8. You can use any type of encoding supported by iconv-lite.

You can also pass a string in place of options to just specify the encoding.

callback(err, res):

• err - the following attributes will be defined if applicable:

  • limit - the limit in bytes
  • length and expected - the expected length of the stream
  • received - the received bytes
  • encoding - the invalid encoding
  • status and statusCode - the corresponding status code for the error
  • type - either entity.too.large, request.aborted, request.size.invalid, stream.encoding.set, or encoding.unsupported

• res - the result, either as a String if an encoding was set or a Buffer otherwise.

If an error occurs, the stream will be paused, everything unpiped, and you are responsible for correctly disposing the stream. For HTTP requests, no handling is required if you send a response. For streams that use file descriptors, you should stream.destroy() or stream.close() to prevent leaks.

Examples

Simple Express example

var getRawBody = require('raw-body')
var typer = require('media-typer')

app.use(function (req, res, next) {
  getRawBody(req, {
    length: req.headers['content-length'],
    limit: '1mb',
    encoding: typer.parse(req.headers['content-type']).parameters.charset
  }, function (err, string) {
    if (err) return next(err)
    req.text = string
    next()
  })
})

Simple Koa example

app.use(function* (next) {
  var string = yield getRawBody(this.req, {
    length: this.length,
    limit: '1mb',
    encoding: this.charset
  })
})

Using as a promise

To use this library as a promise, simply omit the callback and a promise is returned, provided that a global Promise is defined.

var getRawBody = require('raw-body')
var http = require('http')

var server = http.createServer(function (req, res) {
  getRawBody(req)
  .then(function (buf) {
    res.statusCode = 200
    res.end(buf.length + ' bytes submitted')
  })
  .catch(function (err) {
    res.statusCode = 500
    res.end(err.message)
  })
})

server.listen(3000)

License

MIT