www.aleph1.co.uk Git - yaffs-website/blob - node_modules/raw-body/README.md

   1 # raw-body
   2
   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][travis-image]][travis-url]
   7 [![Test coverage][coveralls-image]][coveralls-url]
   8
   9 Gets the entire buffer of a stream either as a `Buffer` or a string.
  10 Validates the stream's length against an expected length and maximum limit.
  11 Ideal for parsing request bodies.
  12
  13 ## API
  14
  15 ```js
  16 var getRawBody = require('raw-body')
  17 ```
  18
  19 ### getRawBody(stream, [options], [callback])
  20
  21 **Returns a promise if no callback specified and global `Promise` exists.**
  22
  23 Options:
  24
  25 - `length` - The length of the stream.
  26   If the contents of the stream do not add up to this length,
  27   an `400` error code is returned.
  28 - `limit` - The byte limit of the body.
  29   If the body ends up being larger than this limit,
  30   a `413` error code is returned.
  31 - `encoding` - The requested encoding.
  32   By default, a `Buffer` instance will be returned.
  33   Most likely, you want `utf8`.
  34   You can use any type of encoding supported by [iconv-lite](https://www.npmjs.org/package/iconv-lite#readme).
  35
  36 You can also pass a string in place of options to just specify the encoding.
  37
  38 `callback(err, res)`:
  39
  40 - `err` - the following attributes will be defined if applicable:
  41
  42     - `limit` - the limit in bytes
  43     - `length` and `expected` - the expected length of the stream
  44     - `received` - the received bytes
  45     - `encoding` - the invalid encoding
  46     - `status` and `statusCode` - the corresponding status code for the error
  47     - `type` - either `entity.too.large`, `request.aborted`, `request.size.invalid`, `stream.encoding.set`, or `encoding.unsupported`
  48
  49 - `res` - the result, either as a `String` if an encoding was set or a `Buffer` otherwise.
  50
  51 If an error occurs, the stream will be paused, everything unpiped,
  52 and you are responsible for correctly disposing the stream.
  53 For HTTP requests, no handling is required if you send a response.
  54 For streams that use file descriptors, you should `stream.destroy()` or `stream.close()` to prevent leaks.
  55
  56 ## Examples
  57
  58 ### Simple Express example
  59
  60 ```js
  61 var getRawBody = require('raw-body')
  62 var typer = require('media-typer')
  63
  64 app.use(function (req, res, next) {
  65   getRawBody(req, {
  66     length: req.headers['content-length'],
  67     limit: '1mb',
  68     encoding: typer.parse(req.headers['content-type']).parameters.charset
  69   }, function (err, string) {
  70     if (err) return next(err)
  71     req.text = string
  72     next()
  73   })
  74 })
  75 ```
  76
  77 ### Simple Koa example
  78
  79 ```js
  80 app.use(function* (next) {
  81   var string = yield getRawBody(this.req, {
  82     length: this.length,
  83     limit: '1mb',
  84     encoding: this.charset
  85   })
  86 })
  87 ```
  88
  89 ### Using as a promise
  90
  91 To use this library as a promise, simply omit the `callback` and a promise is
  92 returned, provided that a global `Promise` is defined.
  93
  94 ```js
  95 var getRawBody = require('raw-body')
  96 var http = require('http')
  97
  98 var server = http.createServer(function (req, res) {
  99   getRawBody(req)
 100   .then(function (buf) {
 101     res.statusCode = 200
 102     res.end(buf.length + ' bytes submitted')
 103   })
 104   .catch(function (err) {
 105     res.statusCode = 500
 106     res.end(err.message)
 107   })
 108 })
 109
 110 server.listen(3000)
 111 ```
 112
 113 ## License
 114
 115 [MIT](LICENSE)
 116
 117 [npm-image]: https://img.shields.io/npm/v/raw-body.svg
 118 [npm-url]: https://npmjs.org/package/raw-body
 119 [node-version-image]: https://img.shields.io/node/v/raw-body.svg
 120 [node-version-url]: http://nodejs.org/download/
 121 [travis-image]: https://img.shields.io/travis/stream-utils/raw-body/master.svg
 122 [travis-url]: https://travis-ci.org/stream-utils/raw-body
 123 [coveralls-image]: https://img.shields.io/coveralls/stream-utils/raw-body/master.svg
 124 [coveralls-url]: https://coveralls.io/r/stream-utils/raw-body?branch=master
 125 [downloads-image]: https://img.shields.io/npm/dm/raw-body.svg
 126 [downloads-url]: https://npmjs.org/package/raw-body