http-cache

An extensible caching interface for HTTP traffic.

npm install http-cache
1 downloads in the last day
1 downloads in the last week
49 downloads in the last month

http-cache

Build Status NPM version

Install

npm install http-cache

https://npmjs.org/package/http-cache

What is it?

A simple HTTP caching interface with extensible provider support.

Getting Started with Connect/Express

Using Connect or Express?

var
    connect = require("connect"),
    http = require("http"),
    HttpCache = require("http-cache")
;

var app = connect()
    .use(new HttpCache({ }))
    .use(function(req, res) {
        res.end("Cache this response! Time=" + new Date().getTime());
    });

http.createServer(app).listen(8392);

Getting Started with HTTP

Real coders use no middleware? We've got you covered...

var
    http = require("http"),
    HttpCache = require("http-cache")
;

var httpcache = new HttpCache({ });
http.createServer(function(req, res) {
    httpcache(req, res, function() {
        res.end("Cache this response! Time=" + new Date().getTime());
    });
}).listen(8392);

HttpCache Options

Options may be provided when constructing your HttpCache object...

var HttpCache = require("http-cache");
var httpcache = new HttpCache({ /* my options go here */ });

Options include:

  • ttl (default: 600) - Time (in seconds) before cache object will be purged.
  • provider (default: require("lib/providers/InProcProvider")) - Alternate providers may be specified, including your own Custom Provider.
  • headersToExclude (default: see code) - You may optionally manage which HTTP headers are included/excluded via this object.
  • rules (default: []) - An optional set of custom caching rules. See Custom Rules.
  • varyByHeader (default: []) - An array of strings that will cache key by specific header fields.
  • varyByParam (default: []) - An array of strings that will cache key by specific querystring parameters.
  • purgeAll (default: false) - If true, will clear all cache objects from the provider. Typically only useful during testing.
  • confirmCacheBeforeEnd (default: false) - If set to true, will confirm successful cache writes before ending response. Typically only used for unit tests to avoid race conditions. Should not be used in a production setting.

Custom Rules

Both synchronous and asynchronous rules may be provided:

httpcache({
    rules: function(req, res) {
        // do not cache users folder
        return (/\/users\//i.test(req.url) === false);
    }
});

Async rules leverage cb instead of returning...

httpcache({
    rules: function(req, res, cb) {
        setTimeout(function() {
            // do not cache users folder
            cb(null, /\/users\//i.test(req.url) === false);
        }, 100);
    }
});

Multiple rules may be provided as well... (will be processed in parallel)

httpcache({
    rules: [ rule1, rule2, rule3 ]
});

Custom Provider

Providers are intended to be very simple and extensible, so feel free to contribute your own providers if what is provided does not suite your needs.

  • provider.isTTLManaged - If set to true, http-cache will not be responsible for purging expired entries. Reserved for distributed providers that have internal support for TTL that will be more reliable.
  • provider.get(key, cb) - Returns object via callback. If no object found, null or undefined should be returned, NOT an error.
  • provider.set(key, cache, cb) - Stores a JavaScript object in whatever means necessary.
  • provider.remove(key, cb) - Removes cache entry if it exists.
  • provider.clear(cb) - Purges all cache entries.

See lib/providers/in-proc-provider.js to see how to create your own provider.

Available Providers

If you build your own custom provider, feel free to issue a pull request so we can reference your provider as well.

Tests & Code Coverage

Download and install:

git clone https://github.com/godaddy/node-http-cache.git
cd node-http-cache
npm install

Now test:

npm test

View code coverage in any browser:

coverage/lcov-report/index.html

License

MIT

TODO

  • Add FileSystem Provider
  • Add sliding TTL support? (Possible performance impact)
  • Add per-request TTL customization? (Possible performance impact)
  • Add support for array based header values (part of node spec), i.e.
    • res.writeHead(200, { "set-cookie": [cookie1, cookie2] });
npm loves you