Merge pull request #1 from jkyberneees/initial-commit

initial commit

Author: jkyberneees

.travis.yml

@@ -0,0 +1,6 @@
+
+language: node_js
+node_js:
+  - "10"
+
+install: npm install

README.md

@@ -1,2 +1,124 @@
 # http-cache-middleware
-HTTP Cache Middleware
+High performance connect-like HTTP cache middleware for Node.js. 
+
+> Uses `cache-manager` as caching layer, so multiple
+storage engines are supported, i.e: Memory, Redis, ... https://www.npmjs.com/package/cache-manager
+
+## Install
+```js 
+npm i http-cache-middleware
+```
+
+## Usage
+```js
+const middleware = require('http-cache-middleware')()
+const service = require('restana')()
+service.use(middleware)
+
+service.get('/cache-on-get', (req, res) => {
+  setTimeout(() => {
+    // keep response in cache for 1 minute if not expired before
+    res.setHeader('x-cache-timeout', '1 minute')
+    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.end()
+})
+
+service.start(3000)
+```
+## Redis cache
+```js
+// redis setup
+const CacheManager = require('cache-manager')
+const redisStore = require('cache-manager-ioredis')
+const redisCache = CacheManager.caching({
+  store: redisStore,
+  db: 0,
+  host: 'localhost',
+  port: 6379,
+  ttl: 30
+})
+
+// middleware instance
+const middleware = require('http-cache-middleware')({
+  stores: [redisCache]
+})
+```
+
+## Why cache? 
+> Because caching is the last mile for low latency distributed systems!
+
+Enabling proper caching strategies will drastically reduce the latency of your system, as it reduces network round-trips, database calls and CPU processing.  
+For our services, we are talking here about improvements in response times from `X ms` to `~2ms`, as an example.
+
+### Enabling cache for service endpoints
+Enabling a response to be cached just requires the 
+`x-cache-timeout` header to be set:
+```js
+res.setHeader('x-cache-timeout', '1 hour')
+```
+> Here we use the [`ms`](`https://www.npmjs.com/package/ms`) package to convert timeout to seconds. Please note that `millisecond` unit is not supported!  
+
+Example on service using `restana`:
+```js
+service.get('/numbers', (req, res) => {
+  res.setHeader('x-cache-timeout', '1 hour')
+
+  res.send([
+    1, 2, 3
+  ])
+})
+```
+
+### 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')
+```
+> Here we use the [`matcher`](`https://www.npmjs.com/package/matcher`) package for matching patterns evaluation.
+
+Example on service using `restana`:
+```js
+service.patch('/numbers', (req, res) => {
+  // ...
+
+  res.setHeader('x-cache-expire', '*/numbers')
+  res.send(200)
+})
+```
+
+### Custom cache keys
+Cache keys are generated using: `req.method + req.url`, however, for indexing/segmenting requirements it makes sense to allow cache keys extensions.  
+
+For doing this, we simply recommend using middlewares to extend the keys before caching checks happen:
+```js
+service.use((req, res, next) => {
+  req.cacheAppendKey = (req) => req.user.id // here cache key will be: req.method + req.url + req.user.id  
+  return next()
+})
+```
+> In this example we also distinguish cache entries by `user.id`, very important for authorization reasons.
+
+### Disable cache for custom endpoints
+You can also disable cache checks for certain requests programmatically:
+```js
+service.use((req, res, next) => {
+  req.cacheDisabled = true
+  return next()
+})
+```
+
+## Want to contribute?
+This is your repo ;)  
+
+> Note: We aim to be 100% code coverage, please consider it on your pull requests.
+
+## Related projects
+- fast-gateway (https://www.npmjs.com/package/fast-gateway)

demos/basic.js

@@ -0,0 +1,21 @@
+const middleware = require('./../index')()
+const service = require('restana')()
+service.use(middleware)
+
+service.get('/cache-on-get', (req, res) => {
+  setTimeout(() => {
+    // keep response in cache for 1 minute if not expired before
+    res.setHeader('x-cache-timeout', '1 minute')
+    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.end()
+})
+
+service.start(3000)

get-keys.js

@@ -0,0 +1,14 @@
+const matcher = require('matcher')
+
+const getKeys = (cache, pattern) => new Promise((resolve) => {
+  if (pattern.indexOf('*') > -1) {
+    const args = [pattern, (_, res) => resolve(matcher(res, [pattern]))]
+    if (cache.store.name !== 'redis') {
+      args.shift()
+    }
+
+    cache.keys.apply(cache, args)
+  } else resolve([pattern])
+})
+
+module.exports = getKeys

index.js

@@ -0,0 +1,75 @@
+const CacheManager = require('cache-manager')
+const iu = require('middleware-if-unless')()
+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 middleware = (opts) => async (req, res, next) => {
+  opts = Object.assign({
+    stores: [CacheManager.caching({ store: 'memory', max: 1000, ttl: 30 })]
+  }, opts)
+
+  // creating multi-cache instance
+  const mcache = CacheManager.multiCaching(opts.stores)
+
+  if (req.cacheDisabled) return next()
+
+  let { url, cacheAppendKey = req => '' } = req
+  cacheAppendKey = await cacheAppendKey(req)
+
+  const key = req.method + url + cacheAppendKey
+  // ref cache key on req object
+  req.cacheKey = key
+
+  // try to retrieve cached response
+  const cached = await get(mcache, key)
+
+  if (cached) {
+    // respond from cache if there is a hit
+    let { status, headers, data } = JSON.parse(cached)
+    if (typeof data === 'object' && data.type === 'Buffer') {
+      data = Buffer.from(data.data)
+    }
+    headers[X_CACHE_HIT] = '1'
+
+    // set cached response headers
+    Object.keys(headers).forEach(header => res.setHeader(header, headers[header]))
+
+    // send cached payload
+    req.cacheHit = true
+    res.statusCode = status
+    res.end(data)
+
+    return
+  }
+
+  onEnd(res, (payload) => {
+    if (payload.headers[X_CACHE_EXPIRE]) {
+      // support service level expiration
+      const keysPattern = payload.headers[X_CACHE_EXPIRE]
+      // delete keys on all cache tiers
+      opts.stores.forEach(cache => getKeys(cache, keysPattern).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
+      })
+    }
+  })
+
+  return next()
+}
+
+const get = (cache, key) => new Promise((resolve) => {
+  cache.getAndPassUp(key, (_, res) => {
+    resolve(res)
+  })
+})
+
+module.exports = iu(middleware)