AK-21/Graphite-Industrial-Intelligence

1# raw-body2 3[![NPM Version][npm-image]][npm-url]4[![NPM Downloads][downloads-image]][downloads-url]5[![Node.js Version][node-version-image]][node-version-url]6[![Build status][github-actions-ci-image]][github-actions-ci-url]7[![Test coverage][coveralls-image]][coveralls-url]8 9Gets the entire buffer of a stream either as a `Buffer` or a string.10Validates the stream's length against an expected length and maximum limit.11Ideal for parsing request bodies.12 13## Install14 15This is a [Node.js](https://nodejs.org/en/) module available through the16[npm registry](https://www.npmjs.com/). Installation is done using the17[`npm install` command](https://docs.npmjs.com/getting-started/installing-npm-packages-locally):18 19```sh20$ npm install raw-body21```22 23### TypeScript24 25This module includes a [TypeScript](https://www.typescriptlang.org/)26declaration file to enable auto complete in compatible editors and type27information for TypeScript projects. This module depends on the Node.js28types, so install `@types/node`:29 30```sh31$ npm install @types/node32```33 34## API35 36```js37var getRawBody = require('raw-body')38```39 40### getRawBody(stream, [options], [callback])41 42**Returns a promise if no callback specified and global `Promise` exists.**43 44Options:45 46- `length` - The length of the stream.47  If the contents of the stream do not add up to this length,48  an `400` error code is returned.49- `limit` - The byte limit of the body.50  This is the number of bytes or any string format supported by51  [bytes](https://www.npmjs.com/package/bytes),52  for example `1000`, `'500kb'` or `'3mb'`.53  If the body ends up being larger than this limit,54  a `413` error code is returned.55- `encoding` - The encoding to use to decode the body into a string.56  By default, a `Buffer` instance will be returned when no encoding is specified.57  Most likely, you want `utf-8`, so setting `encoding` to `true` will decode as `utf-8`.58  You can use any type of encoding supported by [iconv-lite](https://www.npmjs.org/package/iconv-lite#readme).59 60You can also pass a string in place of options to just specify the encoding.61 62If an error occurs, the stream will be paused, everything unpiped,63and you are responsible for correctly disposing the stream.64For HTTP requests, you may need to finish consuming the stream if65you want to keep the socket open for future requests. For streams66that use file descriptors, you should `stream.destroy()` or67`stream.close()` to prevent leaks.68 69## Errors70 71This module creates errors depending on the error condition during reading.72The error may be an error from the underlying Node.js implementation, but is73otherwise an error created by this module, which has the following attributes:74 75  * `limit` - the limit in bytes76  * `length` and `expected` - the expected length of the stream77  * `received` - the received bytes78  * `encoding` - the invalid encoding79  * `status` and `statusCode` - the corresponding status code for the error80  * `type` - the error type81 82### Types83 84The errors from this module have a `type` property which allows for the programmatic85determination of the type of error returned.86 87#### encoding.unsupported88 89This error will occur when the `encoding` option is specified, but the value does90not map to an encoding supported by the [iconv-lite](https://www.npmjs.org/package/iconv-lite#readme)91module.92 93#### entity.too.large94 95This error will occur when the `limit` option is specified, but the stream has96an entity that is larger.97 98#### request.aborted99 100This error will occur when the request stream is aborted by the client before101reading the body has finished.102 103#### request.size.invalid104 105This error will occur when the `length` option is specified, but the stream has106emitted more bytes.107 108#### stream.encoding.set109 110This error will occur when the given stream has an encoding set on it, making it111a decoded stream. The stream should not have an encoding set and is expected to112emit `Buffer` objects.113 114#### stream.not.readable115 116This error will occur when the given stream is not readable.117 118## Examples119 120### Simple Express example121 122```js123var contentType = require('content-type')124var express = require('express')125var getRawBody = require('raw-body')126 127var app = express()128 129app.use(function (req, res, next) {130  getRawBody(req, {131    length: req.headers['content-length'],132    limit: '1mb',133    encoding: contentType.parse(req).parameters.charset134  }, function (err, string) {135    if (err) return next(err)136    req.text = string137    next()138  })139})140 141// now access req.text142```143 144### Simple Koa example145 146```js147var contentType = require('content-type')148var getRawBody = require('raw-body')149var koa = require('koa')150 151var app = koa()152 153app.use(function * (next) {154  this.text = yield getRawBody(this.req, {155    length: this.req.headers['content-length'],156    limit: '1mb',157    encoding: contentType.parse(this.req).parameters.charset158  })159  yield next160})161 162// now access this.text163```164 165### Using as a promise166 167To use this library as a promise, simply omit the `callback` and a promise is168returned, provided that a global `Promise` is defined.169 170```js171var getRawBody = require('raw-body')172var http = require('http')173 174var server = http.createServer(function (req, res) {175  getRawBody(req)176    .then(function (buf) {177      res.statusCode = 200178      res.end(buf.length + ' bytes submitted')179    })180    .catch(function (err) {181      res.statusCode = 500182      res.end(err.message)183    })184})185 186server.listen(3000)187```188 189### Using with TypeScript190 191```ts192import * as getRawBody from 'raw-body';193import * as http from 'http';194 195const server = http.createServer((req, res) => {196  getRawBody(req)197  .then((buf) => {198    res.statusCode = 200;199    res.end(buf.length + ' bytes submitted');200  })201  .catch((err) => {202    res.statusCode = err.statusCode;203    res.end(err.message);204  });205});206 207server.listen(3000);208```209 210## License211 212[MIT](LICENSE)213 214[npm-image]: https://img.shields.io/npm/v/raw-body.svg215[npm-url]: https://npmjs.org/package/raw-body216[node-version-image]: https://img.shields.io/node/v/raw-body.svg217[node-version-url]: https://nodejs.org/en/download/218[coveralls-image]: https://img.shields.io/coveralls/stream-utils/raw-body/master.svg219[coveralls-url]: https://coveralls.io/r/stream-utils/raw-body?branch=master220[downloads-image]: https://img.shields.io/npm/dm/raw-body.svg221[downloads-url]: https://npmjs.org/package/raw-body222[github-actions-ci-image]: https://img.shields.io/github/actions/workflow/status/stream-utils/raw-body/ci.yml?branch=master&label=ci223[github-actions-ci-url]: https://github.com/jshttp/stream-utils/raw-body?query=workflow%3Aci224