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