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')
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()
  })
})

or in a Koa generator:

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

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

Returns a thunk for yielding with generators.

Options:

• length - The length 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.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, 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.

License

The MIT License (MIT)

Copyright (c) 2013 Jonathan Ong [e-mail]

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.