Merge pull request #3 from jkyberneees/cache-control-support

Cache-Control header support

Author: jkyberneees

README.md

@@ -1,5 +1,5 @@
 # http-cache-middleware
-High performance connect-like HTTP cache middleware for Node.js. 
+High performance connect-like HTTP cache middleware for Node.js. So your latency can decrease to single digit milliseconds 🚀 
 
 > Uses `cache-manager` as caching layer, so multiple
 storage engines are supported, i.e: Memory, Redis, ... https://www.npmjs.com/package/cache-manager
@@ -77,7 +77,34 @@ service.get('/numbers', (req, res) => {
 })
 ```
 
-### Invalidating caches
+### Caching on the browser side (304 status codes)
+> From version `1.2.x` you can also use the HTTP compatible `Cache-Control` header: https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Cache-Control
+When using the Cache-Control header, you can omit the custom `x-cache-timeout` header as the timeout can be passed using the `max-age` directive. 
+
+#### Direct usage: 
+```js 
+res.setHeader('cache-control', 'private, no-cache, max-age=300')
+res.setHeader('etag', '1')
+
+res.end('5 minutes cacheable content here....')
+```
+
+#### Indirect usage:
+When using:
+```js
+res.setHeader('x-cache-timeout', '5 minutes')
+```
+The middleware will now transparently generate default `Cache-Control` and `ETag` headers as described below:
+```js 
+res.setHeader('cache-control', 'private, no-cache, max-age=300')
+res.setHeader('etag', '1')
+```
+This will enable browser clients to keep a copy of the cache on their side, but still being forced to validate 
+the cache state on the server before using the cached response, therefore supporting gateway based cache invalidation. 
+
+> NOTE: In order to fetch the generated `Cache-Control` and `ETag` headers, there have to be at least one cache hit.
+
+### Invalidating caches 
 Services can easily expire cache entries on demand, i.e: when the data state changes. Here we use the `x-cache-expire` header to indicate the cache entries to expire using a matching pattern:
 ```js
 res.setHeader('x-cache-expire', '*/numbers')

demos/basic.js

@@ -10,11 +10,19 @@ service.get('/cache-on-get', (req, res) => {
   }, 50)
 })
 
+service.get('/cache-control', (req, res) => {
+  setTimeout(() => {
+    // keep response in cache for 1 minute if not expired before
+    res.setHeader('cache-control', 'private, no-cache, max-age=60')
+    res.send('this supposed to be a cacheable response')
+  }, 50)
+})
+
 service.delete('/cache', (req, res) => {
   // ... the logic here changes the cache state
 
   // expire the cache keys using pattern
-  res.setHeader('x-cache-expire', '*/cache-on-get')
+  res.setHeader('x-cache-expire', '*/cache-*')
   res.end()
 })
 

index.js

@@ -1,12 +1,16 @@
 const CacheManager = require('cache-manager')
 const iu = require('middleware-if-unless')()
+const { parse: cacheControl } = require('@tusbar/cache-control')
 const ms = require('ms')
 const onEnd = require('on-http-end')
 const getKeys = require('./get-keys')
 
 const X_CACHE_EXPIRE = 'x-cache-expire'
 const X_CACHE_TIMEOUT = 'x-cache-timeout'
 const X_CACHE_HIT = 'x-cache-hit'
+const CACHE_ETAG = 'etag'
+const CACHE_CONTROL = 'cache-control'
+const CACHE_IF_NONE_MATCH = 'if-none-match'
 
 const middleware = (opts) => async (req, res, next) => {
   opts = Object.assign({
@@ -31,6 +35,16 @@ const middleware = (opts) => async (req, res, next) => {
   if (cached) {
     // respond from cache if there is a hit
     let { status, headers, data } = JSON.parse(cached)
+
+    // pre-checking If-None-Match header
+    if (req.headers[CACHE_IF_NONE_MATCH] === headers[CACHE_ETAG]) {
+      res.setHeader('content-length', '0')
+      res.statusCode = 304
+      res.end()
+
+      return // exit because client cache state matches
+    }
+
     if (typeof data === 'object' && data.type === 'Buffer') {
       data = Buffer.from(data.data)
     }
@@ -53,17 +67,28 @@ const middleware = (opts) => async (req, res, next) => {
       const keysPattern = payload.headers[X_CACHE_EXPIRE].replace(/\s/g, '')
       const patterns = keysPattern.split(',')
       // delete keys on all cache tiers
-      patterns.forEach(pattern =>
-        opts.stores.forEach(cache =>
-          getKeys(cache, pattern).then(keys =>
-            mcache.del(keys))))
-    } else if (payload.headers[X_CACHE_TIMEOUT]) {
-      // we need to cache response
-      mcache.set(req.cacheKey, JSON.stringify(payload), {
-        // @NOTE: cache-manager uses seconds as TTL unit
-        // restrict to min value "1 second"
-        ttl: Math.max(ms(payload.headers[X_CACHE_TIMEOUT]), 1000) / 1000
-      })
+      patterns.forEach(pattern => opts.stores.forEach(store => getKeys(store, pattern).then(keys => mcache.del(keys))))
+    } else if (payload.headers[X_CACHE_TIMEOUT] || payload.headers[CACHE_CONTROL]) {
+      // extract cache ttl
+      let ttl = 0
+      if (payload.headers[CACHE_CONTROL]) {
+        ttl = cacheControl(payload.headers[CACHE_CONTROL]).maxAge
+      }
+      if (!ttl) {
+        ttl = Math.max(ms(payload.headers[X_CACHE_TIMEOUT]), 1000) / 1000 // min value: 1 second
+      }
+
+      // setting cache-control header if absent
+      if (!payload.headers[CACHE_CONTROL]) {
+        payload.headers[CACHE_CONTROL] = `private, no-cache, max-age=${ttl}`
+      }
+      // setting ETag if absent
+      if (!payload.headers[CACHE_ETAG]) {
+        payload.headers[CACHE_ETAG] = '1'
+      }
+
+      // cache response
+      mcache.set(req.cacheKey, JSON.stringify(payload), { ttl })
     }
   })
 

package-lock.json

@@ -1,6 +1,6 @@
 {
   "name": "http-cache-middleware",
-  "version": "1.1.1",
+  "version": "1.2.0",
   "description": "HTTP Cache Middleware",
   "main": "index.js",
   "scripts": {
@@ -30,6 +30,7 @@
     "standard": "^12.0.1"
   },
   "dependencies": {
+    "@tusbar/cache-control": "^0.3.1",
     "cache-manager": "^2.9.1",
     "matcher": "^2.0.0",
     "middleware-if-unless": "^1.2.1",

package.json

@@ -37,10 +37,18 @@ describe('cache middleware', () => {
     server.get('/cache-buffer', (req, res) => {
       setTimeout(() => {
         res.setHeader('x-cache-timeout', '1 minute')
+        res.setHeader('etag', '1')
+        res.setHeader('cache-control', 'no-cache')
         res.send(Buffer.from('world'))
       }, 50)
     })
 
+    server.get('/cache-control', (req, res) => {
+      res.setHeader('cache-control', 'max-age=60')
+      res.setHeader('etag', '1')
+      res.send('cache')
+    })
+
     server.delete('/cache', (req, res) => {
       res.setHeader('x-cache-expire', '*/cache')
       res.end()
@@ -94,6 +102,35 @@ describe('cache middleware', () => {
     const res = await got('http://localhost:3000/cache-buffer')
     expect(res.body).to.equal('world')
     expect(res.headers['x-cache-hit']).to.equal('1')
+    expect(res.headers['cache-control']).to.equal('no-cache')
+    expect(res.headers['etag']).to.equal('1')
+  })
+
+  it('cache hit (buffer) - Etag', async () => {
+    const res = await got('http://localhost:3000/cache-buffer')
+    expect(res.body).to.equal('world')
+    expect(res.headers['x-cache-hit']).to.equal('1')
+    expect(res.headers['etag']).to.equal('1')
+  })
+
+  it('cache hit (buffer) - If-None-Match', async () => {
+    const res = await got('http://localhost:3000/cache-buffer', {
+      headers: {
+        'If-None-Match': '1'
+      }
+    })
+    expect(res.statusCode).to.equal(304)
+  })
+
+  it('cache create - cache-control', async () => {
+    const res = await got('http://localhost:3000/cache-control')
+    expect(res.body).to.equal('cache')
+  })
+
+  it('cache hit - cache-control', async () => {
+    const res = await got('http://localhost:3000/cache-control')
+    expect(res.body).to.equal('cache')
+    expect(res.headers['x-cache-hit']).to.equal('1')
   })
 
   it('close', async () => {