README.md (4886B)
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