Skip to content
This repository has been archived by the owner on Dec 3, 2019. It is now read-only.


Switch branches/tags

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?

Latest commit


Git stats


Failed to load latest commit information.
Latest commit message
Commit time

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.

Build Status Coverage Status Gem Version

Getting started

Add this line to your Gemfile: gem 'cache_rules'


Install with: gem install cache_rules


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

require 'cache_rules'

# test without cached response
url     = ''
request = {'Version' => 'HTTP/1.1'}
cached  = {}

CacheRules.validate url, request, cached

=> {:body=>nil, :code=>307, :headers=>{"Cache-Lookup"=>"MISS", "Location"=>""}}

# test with cached response (status code 200 because no ETag or If-None-Match supplied)
cached  = { "Date" => {"timestamp"=>1420095825}, "X-Cache-Req-Date"  => {"timestamp"=>1420268625}, "X-Cache-Res-Date"  => {"timestamp"=>1420268625} }

CacheRules.validate url, request, cached

=> {:body=>"stale", :code=>200, :headers=>{"Date"=>"Wed, 21 Feb 2018 05:09:27 GMT", "Age"=>"99094242", "Warning"=>"110 - \"Response is Stale\"", "Cache-Lookup"=>"STALE"}}

# test with cached response (status code 304 because If-None-Match supplied)
request = {"Version"=>"HTTP/1.1", "If-None-Match"=>"*"}
cached  = { "Date" => {"timestamp"=>1519190160}, "X-Cache-Req-Date"  => {"timestamp"=>1519190160}, "X-Cache-Res-Date"  => {"timestamp"=>1519190160} }

CacheRules.validate url, request, cached

=> {:body=>nil, :code=>304, :headers=>{"Date"=>"Wed, 21 Feb 2018 05:15:01 GMT", "Age"=>"241", "Warning"=>"110 - \"Response is Stale\"", "Cache-Lookup"=>"STALE"}}

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, i.e: they must include array keys:

  • Date['timestamp']
  • X-Cache-Req-Date['timestamp']
  • X-Cache-Res-Date['timestamp']

See test/ directory for more examples.

Decision tables

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

Request/Cache Table


Revalidation Table


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.


To run the tests, type:

bundle exec rake test


  • 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

Further reading

Some useful articles explaining HTTP Caching:


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

Copyright (c) 2014-2018 Alexander Williams, Unscramble