www.aleph1.co.uk Git - yaffs-website/blob - node_modules/on-finished/README.md

   1 # on-finished
   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 Execute a callback when a HTTP request closes, finishes, or errors.
  10
  11 ## Install
  12
  13 ```sh
  14 $ npm install on-finished
  15 ```
  16
  17 ## API
  18
  19 ```js
  20 var onFinished = require('on-finished')
  21 ```
  22
  23 ### onFinished(res, listener)
  24
  25 Attach a listener to listen for the response to finish. The listener will
  26 be invoked only once when the response finished. If the response finished
  27 to an error, the first argument will contain the error. If the response
  28 has already finished, the listener will be invoked.
  29
  30 Listening to the end of a response would be used to close things associated
  31 with the response, like open files.
  32
  33 Listener is invoked as `listener(err, res)`.
  34
  35 ```js
  36 onFinished(res, function (err, res) {
  37   // clean up open fds, etc.
  38   // err contains the error is request error'd
  39 })
  40 ```
  41
  42 ### onFinished(req, listener)
  43
  44 Attach a listener to listen for the request to finish. The listener will
  45 be invoked only once when the request finished. If the request finished
  46 to an error, the first argument will contain the error. If the request
  47 has already finished, the listener will be invoked.
  48
  49 Listening to the end of a request would be used to know when to continue
  50 after reading the data.
  51
  52 Listener is invoked as `listener(err, req)`.
  53
  54 ```js
  55 var data = ''
  56
  57 req.setEncoding('utf8')
  58 res.on('data', function (str) {
  59   data += str
  60 })
  61
  62 onFinished(req, function (err, req) {
  63   // data is read unless there is err
  64 })
  65 ```
  66
  67 ### onFinished.isFinished(res)
  68
  69 Determine if `res` is already finished. This would be useful to check and
  70 not even start certain operations if the response has already finished.
  71
  72 ### onFinished.isFinished(req)
  73
  74 Determine if `req` is already finished. This would be useful to check and
  75 not even start certain operations if the request has already finished.
  76
  77 ## Special Node.js requests
  78
  79 ### HTTP CONNECT method
  80
  81 The meaning of the `CONNECT` method from RFC 7231, section 4.3.6:
  82
  83 > The CONNECT method requests that the recipient establish a tunnel to
  84 > the destination origin server identified by the request-target and,
  85 > if successful, thereafter restrict its behavior to blind forwarding
  86 > of packets, in both directions, until the tunnel is closed.  Tunnels
  87 > are commonly used to create an end-to-end virtual connection, through
  88 > one or more proxies, which can then be secured using TLS (Transport
  89 > Layer Security, [RFC5246]).
  90
  91 In Node.js, these request objects come from the `'connect'` event on
  92 the HTTP server.
  93
  94 When this module is used on a HTTP `CONNECT` request, the request is
  95 considered "finished" immediately, **due to limitations in the Node.js
  96 interface**. This means if the `CONNECT` request contains a request entity,
  97 the request will be considered "finished" even before it has been read.
  98
  99 There is no such thing as a response object to a `CONNECT` request in
 100 Node.js, so there is no support for for one.
 101
 102 ### HTTP Upgrade request
 103
 104 The meaning of the `Upgrade` header from RFC 7230, section 6.1:
 105
 106 > The "Upgrade" header field is intended to provide a simple mechanism
 107 > for transitioning from HTTP/1.1 to some other protocol on the same
 108 > connection.
 109
 110 In Node.js, these request objects come from the `'upgrade'` event on
 111 the HTTP server.
 112
 113 When this module is used on a HTTP request with an `Upgrade` header, the
 114 request is considered "finished" immediately, **due to limitations in the
 115 Node.js interface**. This means if the `Upgrade` request contains a request
 116 entity, the request will be considered "finished" even before it has been
 117 read.
 118
 119 There is no such thing as a response object to a `Upgrade` request in
 120 Node.js, so there is no support for for one.
 121
 122 ## Example
 123
 124 The following code ensures that file descriptors are always closed
 125 once the response finishes.
 126
 127 ```js
 128 var destroy = require('destroy')
 129 var http = require('http')
 130 var onFinished = require('on-finished')
 131
 132 http.createServer(function onRequest(req, res) {
 133   var stream = fs.createReadStream('package.json')
 134   stream.pipe(res)
 135   onFinished(res, function (err) {
 136     destroy(stream)
 137   })
 138 })
 139 ```
 140
 141 ## License
 142
 143 [MIT](LICENSE)
 144
 145 [npm-image]: https://img.shields.io/npm/v/on-finished.svg
 146 [npm-url]: https://npmjs.org/package/on-finished
 147 [node-version-image]: https://img.shields.io/node/v/on-finished.svg
 148 [node-version-url]: http://nodejs.org/download/
 149 [travis-image]: https://img.shields.io/travis/jshttp/on-finished/master.svg
 150 [travis-url]: https://travis-ci.org/jshttp/on-finished
 151 [coveralls-image]: https://img.shields.io/coveralls/jshttp/on-finished/master.svg
 152 [coveralls-url]: https://coveralls.io/r/jshttp/on-finished?branch=master
 153 [downloads-image]: https://img.shields.io/npm/dm/on-finished.svg
 154 [downloads-url]: https://npmjs.org/package/on-finished