kapouerupcache
Caching proxy having cache keys configured by the upstream application, by setting http response headers.
Upcache has several ways of changing the cache keys:
- tag, version resources by zones
- lock, vary on client json web token grants
- vary, vary by grouping selected request headers
- map, maps a request uri to another request uri
Breaking change: server.d/upcache.conf is now server.d/upcache-memcached.conf
Requirements
In debian/12 these packages are easy to install:
- nginx
- libnginx-mod-http-srcache-filter
- libnginx-mod-http-set-misc
- libnginx-mod-http-memc (if using memcached, or for running the test suite
- memcached or redis
- lua-resty-core
lua-resty-lrucache
a Node.js express app
Install
The Node.js app need the module
npm install upcacheThe nginx configuration need the module
luarocks install upcachenginx is easily configured with the set of files described in (depending on
where npm installs the module) ./node_modules/upcache/nginx/README.md.
Usage
Once installed, load appropriate helpers with
const app = express();
const { tag, lock } = require('upcache');
const mlock = lock(config);
app.get('/route', tag('ugc', 'global'), mlock.restrict('logged'), ...);
app.post('/route', tag(), mlock.restrict('logged'), ...);
See README-tag.md and README-lock.md for documentation, and test/ for more examples.
Mind that srcache module honours cache control headers - if the application
sends responses with Cache-Control: max-age=0, the resource is not cached,
and tag().for() is a facility for doing cache control.
To cache something, resources must be tagged, so lock/vary won't work without tag.
Detection by upstream
Upcache adds a X-Upcache: <version> header to requests, so upstream application
can detect it is enabled, and which features are available.
Testing
A pre-configured nginx environment is available for testing a Node.js application that listens on port 3000, with nginx on port 3001 and memcached on port 3002, simply by launching (depending on ./node_modules/.bin being on PATH or not)
npm run upcachewhich also has an option for filtering output -g <regexp pattern>.
mocha relies on it for integration tests. No root permissions are needed.
License
See LICENSE file.