File: README — Documentation for cache

What is CacheRules

CacheRules is a well-behaved HTTP caching library aimed at being RFC 7234 compliant.

This library does not actually cache anything, and it is not a proxy. It validates HTTP headers and returns the appropriate response to determine if a request can be served from the cache.

It is up to the HTTP Cache implementation to store the cached results and serve responses from the cache if necessary.

Getting started

Add this line to your Gemfile: gem 'cache_rules'

Install with: gem install cache_rules

Usage

There is only 1 public API call when using this library: validate().

require 'cache_rules'

url     = 'https://status.rubygems.org'
request = {'Version' => 'HTTP/1.1'}
cached  = {}

CacheRules.validate url, request, cached

=>  {:body=>nil, :code=>307, :headers=>{"Cache-Lookup"=>"MISS", "Location"=>"https://status.rubygems.org"}}

The request headers must be a Ruby Hash or Array of 2-element Arrays. The cached headers must already have been normalized by this caching library.

Decision tables

There are two decision tables to help figure out how to process each type of HTTP Caching request.

Request/Cache Table

cached

Revalidation Table

revalidation

RFC compliance

This HTTP Caching library aims to be RFC 7230-7235 compliant. It is a best effort attempt to correctly interpret these documents. Some errors may exist, so please notify me if something isn't processed correctly according to the RFCs.

Feature list

Normalizing header names and field values (ex: Last-Modified)
Ensuring date fields are correctly formatted (ex: Fri, 31 Dec 1999 23:59:59 GMT)
Merging duplicate header fields
Interop with HTTP/1.0 clients (ex: Pragma: no-cache)
Weak entity-tag matching (ex: If-None-Match: "W/abc123")
Last modified date matching (ex: If-Modified-Since: Thu, 01 Jan 2015 07:03:45 GMT)
Various header validation including Cache-Control headers
Cache-Control directives with quoted strings (ex: no-cache="Cookie")
Removing non-cacheable headers (ex: Authorization)
Correctly calculating freshness and current age of cached responses
Explicit and Heuristic freshness calculation
Returning 110 and 111 Warning headers when serving stale responses
Revalidating expired responses with the origin server (using HEAD)
Returning the correct status code based on validation/revalidation results
Lots more little things sprinkled throughout the RFCs...
Written in purely functional Ruby (mostly) with 100% unit/integration test coverage

Custom headers

Custom headers are generated to help with testing and compliance validation.

These are somewhat based on CloudFlare's cache headers:

Cache-Lookup: HIT: resource is in cache and still valid. Serving from the cache.
Cache-Lookup: MISS: resource is not in cache. Redirecting to the origin server.
Cache-Lookup: EXPIRED: resource is in cache, but expired. Redirecting to the origin server or serving an error message.
Cache-Lookup: STALE: resource is in cache and expired, but the origin server wasn't contacted successfully to revalidate the request. Serving stale response from the cache.
Cache-Lookup: REVALIDATED: resource is in cache, was expired, but was revalidated successfully at the origin server. Serving from the cache.

Tests

To run the tests, type:

bundle exec rake test

TODO

Validation of s-maxage response header
Handling Vary header and different representations for the same resource
Handling 206 (Partial) and Range headers for resuming downloads
Handling Cache-Control: private headers
Caching other cacheable responses such as 404 and 501

What is C.R.E.A.M. ?

C.R.E.A.M. is an influencial lyrical masterpiece from the 90s performed by the Wu-Tang Clan

It's also the premise of this troll video

LICENSE

This Source Code Form is subject to the terms of the Mozilla Public License, v. 2.0. If a copy of the MPL was not distributed with this file, You can obtain one at http://mozilla.org/MPL/2.0/.