Coder Social home page Coder Social logo

cacherules's Introduction

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'

or

Install with: gem install cache_rules

Usage

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

require 'cache_rules'

# test without cached response
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"}}

# 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

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

Further reading

Some useful articles explaining HTTP Caching:

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/.

Copyright (c) 2014-2018 Alexander Williams, Unscramble

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    ๐Ÿ–– Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. ๐Ÿ“Š๐Ÿ“ˆ๐ŸŽ‰

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google โค๏ธ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.