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.

119 lines
3.3 KiB

  1. # fresh
  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. HTTP response freshness testing
  8. ## Installation
  9. This is a [Node.js](https://nodejs.org/en/) module available through the
  10. [npm registry](https://www.npmjs.com/). Installation is done using the
  11. [`npm install` command](https://docs.npmjs.com/getting-started/installing-npm-packages-locally):
  12. ```
  13. $ npm install fresh
  14. ```
  15. ## API
  16. <!-- eslint-disable no-unused-vars -->
  17. ```js
  18. var fresh = require('fresh')
  19. ```
  20. ### fresh(reqHeaders, resHeaders)
  21. Check freshness of the response using request and response headers.
  22. When the response is still "fresh" in the client's cache `true` is
  23. returned, otherwise `false` is returned to indicate that the client
  24. cache is now stale and the full response should be sent.
  25. When a client sends the `Cache-Control: no-cache` request header to
  26. indicate an end-to-end reload request, this module will return `false`
  27. to make handling these requests transparent.
  28. ## Known Issues
  29. This module is designed to only follow the HTTP specifications, not
  30. to work-around all kinda of client bugs (especially since this module
  31. typically does not recieve enough information to understand what the
  32. client actually is).
  33. There is a known issue that in certain versions of Safari, Safari
  34. will incorrectly make a request that allows this module to validate
  35. freshness of the resource even when Safari does not have a
  36. representation of the resource in the cache. The module
  37. [jumanji](https://www.npmjs.com/package/jumanji) can be used in
  38. an Express application to work-around this issue and also provides
  39. links to further reading on this Safari bug.
  40. ## Example
  41. ### API usage
  42. <!-- eslint-disable no-redeclare, no-undef -->
  43. ```js
  44. var reqHeaders = { 'if-none-match': '"foo"' }
  45. var resHeaders = { 'etag': '"bar"' }
  46. fresh(reqHeaders, resHeaders)
  47. // => false
  48. var reqHeaders = { 'if-none-match': '"foo"' }
  49. var resHeaders = { 'etag': '"foo"' }
  50. fresh(reqHeaders, resHeaders)
  51. // => true
  52. ```
  53. ### Using with Node.js http server
  54. ```js
  55. var fresh = require('fresh')
  56. var http = require('http')
  57. var server = http.createServer(function (req, res) {
  58. // perform server logic
  59. // ... including adding ETag / Last-Modified response headers
  60. if (isFresh(req, res)) {
  61. // client has a fresh copy of resource
  62. res.statusCode = 304
  63. res.end()
  64. return
  65. }
  66. // send the resource
  67. res.statusCode = 200
  68. res.end('hello, world!')
  69. })
  70. function isFresh (req, res) {
  71. return fresh(req.headers, {
  72. 'etag': res.getHeader('ETag'),
  73. 'last-modified': res.getHeader('Last-Modified')
  74. })
  75. }
  76. server.listen(3000)
  77. ```
  78. ## License
  79. [MIT](LICENSE)
  80. [npm-image]: https://img.shields.io/npm/v/fresh.svg
  81. [npm-url]: https://npmjs.org/package/fresh
  82. [node-version-image]: https://img.shields.io/node/v/fresh.svg
  83. [node-version-url]: https://nodejs.org/en/
  84. [travis-image]: https://img.shields.io/travis/jshttp/fresh/master.svg
  85. [travis-url]: https://travis-ci.org/jshttp/fresh
  86. [coveralls-image]: https://img.shields.io/coveralls/jshttp/fresh/master.svg
  87. [coveralls-url]: https://coveralls.io/r/jshttp/fresh?branch=master
  88. [downloads-image]: https://img.shields.io/npm/dm/fresh.svg
  89. [downloads-url]: https://npmjs.org/package/fresh