An extensible caching interface for HTTP traffic.
JavaScript
Switch branches/tags
Nothing to show
Latest commit 9d33107 Nov 25, 2013 @asilvas asilvas do not add suo files
Permalink
Failed to load latest commit information.
lib
test
vs
.gitattributes
.gitignore
.travis.yml
LICENSE.txt initial commit Nov 1, 2013
README.md
index.js
package.json

README.md

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] });