You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

154 lines
4.8 KiB

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