cache_rules 0.1.1

data/Rakefile

@@ -0,0 +1,14 @@
+desc "Run the tests"
+task :test do
+  run_test
+end
+
+def run_test
+  require 'rake/testtask'
+
+  Rake::TestTask.new do |t|
+    t.libs << "test"
+    t.test_files = FileList['test/helper.rb', 'test/test_*.rb']
+  end
+
+end

data/cache_rules.gemspec

@@ -0,0 +1,34 @@
+#!/usr/bin/env gem build
+# encoding: utf-8
+
+require "base64"
+require 'date'
+
+Gem::Specification.new do |s|
+  s.name        = 'cache_rules'
+  s.version     = '0.1.1'
+
+  s.date        = Date.today.to_s
+
+  s.summary     = "CacheRules validates requests and responses for cached HTTP data based on RFCs 7230-7235"
+  s.description = "#{s.summary}. The goal is to faciliate implementation of well-behaved caching solutions which adhere to RFC standards."
+
+  s.author      = 'Alexander Williams'
+  s.email       = Base64.decode64("YXdpbGxpYW1zQGFsZXh3aWxsaWFtcy5jYQ==\n")
+
+  s.homepage    = 'https://unscramble.co.jp'
+
+  s.require_paths = ["lib"]
+  s.files       = `git ls-files`.split("\n")
+
+  # Tests
+  s.add_development_dependency "fakeweb",            '~> 1.3'
+  s.add_development_dependency 'minitest',           '~> 5.5.0'
+  s.add_development_dependency 'minitest-reporters', '~> 1.0.0'
+  s.add_development_dependency 'simplecov'
+
+  license = 'MPL-2.0'
+  s.required_ruby_version = ::Gem::Requirement.new("~> 1.9")
+
+  s.post_install_message = "C.R.E.A.M."
+end

data/lib/actions.rb

@@ -0,0 +1,40 @@
+# 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-2015 Alexander Williams, Unscramble <license@unscramble.jp>
+
+module CacheRules
+  extend self
+
+  # HTTP Header Actions
+
+  def action_revalidate(result)
+    result[:value]
+  end
+
+  # Generate an age equal to the current cached entry's age
+  # source: https://tools.ietf.org/html/rfc7234#section-4
+  def action_add_age(result)
+    current_age = helper_current_age Time.now.gmtime.to_i, result[:cached]
+
+    {'Age' => current_age}
+  end
+
+  def action_add_x_cache(result)
+    {'Cache-Lookup' => result[:value]}
+  end
+
+  def action_add_warning(result)
+    {'Warning' => result[:value]}
+  end
+
+  def action_add_status(result)
+    result[:value]
+  end
+
+  def action_return_body(result)
+    result[:value]
+  end
+
+end

data/lib/cache_rules.rb

@@ -0,0 +1,188 @@
+# 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-2015 Alexander Williams, Unscramble <license@unscramble.jp>
+#
+# Original Source:  https://github.com/aw/CacheRules
+#
+#
+# This library validates requests and responses for cached HTTP data.
+#
+# Rules based on RFCs 7230-7235 - https://tools.ietf.org/wg/httpbis/
+#
+# Usage:
+# => CacheRules.validate(url, request_headers, cached_headers)
+#
+# If you grew up on the crime side:
+# => CacheRules::Everything::Around::Me.validate(url, request_headers, cached_headers)
+
+require 'net/http'
+require 'date'
+require 'time'
+require 'uri'
+
+require 'actions.rb'
+require 'formatting.rb'
+require 'helpers.rb'
+require 'validations.rb'
+
+module CacheRules
+  extend self
+
+  HEADERS_NO_CACHE = %w(
+    Set-Cookie Cookie
+    Accept-Ranges Range If-Range Content-Range
+    Referer From
+    Authorization Proxy-Authorization
+  )
+
+  HEADERS_HTTPDATE = %w(
+    Last-Modified If-Modified-Since If-Unmodified-Since
+    Expires Date
+    X-Cache-Req-Date X-Cache-Res-Date
+  )
+
+  HEADERS_CSV = %w(
+    Connection Trailer Transfer-Encoding Upgrade Via
+    Accept Accept-Charset Accept-Encoding Accept-Language Allow
+    Content-Encoding Content-Language Vary
+    Cache-Control Warning Pragma If-Match If-None-Match
+  )
+
+  HEADERS_NUMBER = %w(
+    Age Content-Length Max-Forwards
+  )
+
+  HEADERS_304 = %w(Cache-Control Content-Location Date ETag Expires Vary)
+
+  OPTIONS_CACHE = HEADERS_CSV.select {|header| header == 'Cache-Control' }
+  OPTIONS_CSV   = HEADERS_CSV.reject {|header| header == 'Cache-Control' }
+  OPTIONS_RETRY = %w(Retry-After)
+
+  X = nil
+
+  # Decision table for request/cached headers
+  REQUEST_TABLE = {
+    :conditions => {
+      'cached'          => [0, 0, 1, 1, 1, 1, 1, 1, 1],
+      'must_revalidate' => [X, X, X, X, 0, 0, 0, 1, X],
+      'no_cache'        => [X, X, 0, 0, 0, 0, 0, 0, 1],
+      'precond_match'   => [X, X, 0, 1, 0, 1, X, X, X],
+      'expired'         => [X, X, 0, 0, 1, 1, 1, 1, X],
+      'only_if_cached'  => [0, 1, X, X, X, X, X, X, X],
+      'allow_stale'     => [X, X, X, X, 1, 1, 0, X, X]
+    },
+    :actions => {
+      'revalidate'      => [X, X, X, X, X, X, X, 1, 1],
+      'add_age'         => [X, X, 1, 1, 1, 1],
+      'add_x_cache'     => %w(MISS MISS HIT HIT STALE STALE EXPIRED),
+      'add_warning'     => [X, X, X, X, '110 - "Response is Stale"', '110 - "Response is Stale"'],
+      'add_status'      => [307, 504, 200, 304, 200, 304, 504],
+      'return_body'     => [X, 'Gateway Timeout', 'cached', X, 'stale', X, 'Gateway Timeout']
+    }
+  }
+
+  # Decision table for revalidated responses
+  RESPONSE_TABLE = {
+    :conditions => {
+      'is_error'        => [0, 0, 1, 1, 1, 0],
+      'expired'         => [0, 0, X, X, X, 1],
+      'allow_stale'     => [X, X, 0, 1, 1, X],
+      'validator_match' => [0, 1, X, 0, 1, X]
+    },
+    :actions => {
+      'revalidate'      => [],
+      'add_age'         => [1, 1, X, 1, 1],
+      'add_x_cache'     => %w(REVALIDATED REVALIDATED EXPIRED STALE STALE EXPIRED),
+      'add_warning'     => [X, X, X, '111 - "Revalidation Failed"', '111 - "Revalidation Failed"'],
+      'add_status'      => [200, 304, 504, 200, 304, 307],
+      'return_body'     => ['cached', X, 'Gateway Timeout', 'stale', X]
+    }
+  }
+
+  # Build the map tables in advance for faster lookups i.e: O(1)
+  REQUEST_MAP   = helper_table_map(REQUEST_TABLE[:conditions])
+  RESPONSE_MAP  = helper_table_map(RESPONSE_TABLE[:conditions])
+
+  # Public: Validate a URL and the request/cached/response headers
+  # TODO: validate the required parameters to ensure they are set correctly
+  def validate(url, request_headers, cached_headers = {})
+    # 1. normalize the request headers
+    normalized_headers = normalize.call request_headers
+    actions            = REQUEST_TABLE[:actions]
+
+    # 2. get the column matching the request headers
+    column = REQUEST_MAP[helper_run_validate.call(REQUEST_TABLE[:conditions], normalized_headers, cached_headers).join]
+    response    = Proc.new { helper_response url, actions, column, cached_headers }
+    revalidate  = Proc.new { revalidate_response url, normalized_headers, cached_headers }
+
+    # 3. return the response or revalidate
+    actions['revalidate'][column] == 1 ? revalidate.call : response.call
+  end
+
+  # Revalidates a response by fetching headers from the origin server
+  def revalidate_response(url, request_headers, cached_headers)
+    request_date      = Time.now.gmtime.httpdate
+    response          = make_request.call(url, request_headers, cached_headers).call
+    response_date     = Time.now.gmtime.httpdate
+    response_headers  = normalize.(response.to_hash.map &:flatten)
+
+    response_headers['Date'] = response_date if response_headers['Date']
+    response_headers['X-Cache-Req-Date'] = request_date
+    response_headers['X-Cache-Res-Date'] = response_date
+    response_headers['Status'] = response.code
+
+    # 1. get the column
+    column = RESPONSE_MAP[helper_run_validate.call(RESPONSE_TABLE[:conditions], request_headers, cached_headers, response_headers).join]
+
+    # 2. return the response
+    helper_response url, RESPONSE_TABLE[:actions], column, cached_headers
+  rescue => error
+    {:code => 504, :body => 'Gateway Timeout', :headers => [], :error => error.message, :debug => error}
+  end
+
+  # Returns a net/http response Object
+  def make_request
+    ->(url, request_headers, cached_headers) {
+      uri               = URI.parse url
+      http              = Net::HTTP.new uri.host, uri.port
+      http.open_timeout = 2
+      http.read_timeout = 60
+      http.use_ssl      = uri.scheme == 'https'
+      http.verify_mode  = OpenSSL::SSL::VERIFY_PEER
+
+      request           = Net::HTTP::Head.new uri.request_uri
+
+      # Two possible validators: entity tags and timestamp
+      # source: https://tools.ietf.org/html/rfc7234#section-4.3.1
+      entity_tags = Proc.new { helper_combine_etags request_headers, cached_headers }.call
+      timestamp   = Proc.new { helper_timestamp     request_headers, cached_headers }
+
+      # Set the precondition header before making the request
+      request['If-None-Match'] = entity_tags if entity_tags
+      ts = timestamp.call unless entity_tags
+      request['If-Modified-Since'] = ts if ts && !entity_tags
+
+      # Make the HTTP(s) request
+      helper_make_request http, request
+    }
+  end
+
+end
+
+module CacheRules
+  module Everything
+    module Around
+      module Me
+        extend CacheRules
+
+        # C.R.E.A.M.
+        def self.get_the_money
+          "Dolla Dolla Bill Y'all"
+        end
+
+      end
+    end
+  end
+end

data/lib/formatting.rb

@@ -0,0 +1,161 @@
+# 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-2015 Alexander Williams, Unscramble <license@unscramble.jp>
+
+module CacheRules
+  extend self
+
+  # HTTP Header Formatting
+
+  # Create a normalized Hash of HTTP headers
+  def normalize
+    ->(headers) {
+      Hash[normalize_fields.(combine.(clean.(Array(headers).map &format_key)))]
+    }
+  end
+
+  # Format the key to look like this: Last-Modified
+  def format_key
+    Proc.new {|key, value|
+      k = key.downcase == 'etag' ? 'ETag' : key.split('-').map(&:capitalize).join('-')
+      [ k, value ]
+    }
+  end
+
+  # Intentionally drop these headers to avoid caching them
+  # If-Modified-Since should be dropped if the date isn't valid
+  # source: https://tools.ietf.org/html/rfc7232#section-3.3
+  def clean
+    ->(headers) {
+      Array(headers).reject {|key, value|
+        HEADERS_NO_CACHE.include?(key) || helper_is_if_modified_error?(key, value)
+      }
+    }
+  end
+
+  # Combine headers with a comma if the field-names are duplicate
+  def combine
+    ->(headers) {
+      Array(headers).group_by {|h, _| h }.map {|k, v|
+        v = HEADERS_CSV.include?(k) ? v.map {|_, x| x }.join(', ') : v[0][1] # OPTIMIZE
+        [ k, v ]
+      }
+    }
+  end
+
+  # Normalizes the value (field-value) of each header
+  def normalize_fields
+    ->(headers) {
+      Array(headers).map &format_field
+    }
+  end
+
+  # Returns a Hash of Strings
+  def unnormalize_fields
+    ->(headers) {
+      Array(headers).reduce({}) {|hash, (key, value)|
+        hash.merge Hash[[format_field.call(key, value, true)]]
+      }
+    }
+  end
+
+  # Returns a Hash, Array, Integer or String based on the supplied arguments
+  def format_field
+    Proc.new {|key, header, stringify|
+      f = format_value header, stringify
+
+      value = case key
+        when *HEADERS_HTTPDATE then f.call('httpdate')      # => Hash
+        when *OPTIONS_CACHE    then f.call('cache_control') # => Array
+        when *OPTIONS_CSV      then f.call('csv')           # => Array
+        when *OPTIONS_RETRY    then f.call('retry_after')   # => Hash or Integer
+        else header                                         # => String
+      end
+      [ key, value ]
+    }
+  end
+
+  # Returns the value of the field
+  def format_value(header, stringify = nil)
+    Proc.new {|field|
+      stringify ? send("#{ field }_string", header) : send("#{ field }", header)
+    }
+  end
+
+  def httpdate(header)
+    timestamp = httpdate_helper header
+
+    {
+      'httpdate'  => Time.at(timestamp).gmtime.httpdate,
+      'timestamp' => timestamp
+    }
+  end
+
+  def httpdate_string(header)
+    timestamp = httpdate_helper header['httpdate']
+
+    Time.at(timestamp).gmtime.httpdate
+  end
+
+  # Correctly parse the 3 Date/Time formats and convert to GMT
+  # source: https://tools.ietf.org/html/rfc7234#section-4.2
+  def httpdate_helper(header)
+    # source: https://tools.ietf.org/html/rfc7231#section-7.1.1.1
+    DateTime.parse(header).to_time.to_i
+  rescue => e
+    # If the supplied date is invalid, use a time in the past (5 minutes ago)
+    # source: https://tools.ietf.org/html/rfc7234#section-5.3
+    Time.now.gmtime.to_i - 300
+  end
+
+  # OPTIMIZE: this regex is copied from JavaScript, could be greatly simplified
+  # Returns a Hash with the directive as key, token (or nil), quoted-string (or nil)
+  def cache_control(header = '')
+    result = header.scan /(?:^|(?:\s*\,\s*))([^\x00-\x20\(\)<>@\,;\:\\"\/\[\]\?\=\{\}\x7F]+)(?:\=(?:([^\x00-\x20\(\)<>@\,;\:\\"\/\[\]\?\=\{\}\x7F]+)|(?:\"((?:[^"\\]|\\.)*)\")))?/
+    result.reduce({}) {|hash, x|
+      hash.merge({
+        x[0].downcase => {
+          'token'         => x[1],
+          'quoted_string' => x[2]
+        }
+      })
+    }
+  end
+
+  # Parses the Cache-Control header and returns a comma-separated String
+  def cache_control_string(header)
+    Array(header).map {|x|
+      token     = x[1]['token']
+      quote     = x[1]['quoted_string']
+      directive = x[0]
+
+      if    token && quote.nil? then "#{ directive }=#{ token }"
+      elsif token.nil? && quote then "#{ directive }=\"#{ quote }\""
+      else  directive
+      end
+    }.join ', '
+  end
+
+  def csv(header = '')
+    header.split(',').map(&:strip)
+  end
+
+  def csv_string(header)
+    Array(header).join ', '
+  end
+
+  # "The value of this field can be either an HTTP-date or a number of seconds..."
+  # source: https://tools.ietf.org/html/rfc7234#section-7.1.3
+  def retry_after(header)
+    Integer(header).abs
+  rescue => e
+    httpdate header
+  end
+
+  def retry_after_string(header)
+    header.to_s
+  end
+
+end

data/lib/helpers.rb

@@ -0,0 +1,326 @@
+# 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-2015 Alexander Williams, Unscramble <license@unscramble.jp>
+
+module CacheRules
+  extend self
+
+  # Create a map with all possible combinations
+  def helper_table_map(conditions)
+    (2**conditions.length).times.map(&helper_row_col_hash(conditions)).reduce(:merge)
+  end
+
+  # Returns a hash representing a row/column, for the table map
+  def helper_row_col_hash(conditions)
+    Proc.new {|index|
+      row = helper_bit_string conditions.length, index
+      col = helper_parse_conditions({:conditions => conditions, :answers => row.chars.map(&:to_i)})
+
+      {row => col}
+    }
+  end
+
+  # Returns a string of 0s and 1s
+  def helper_bit_string(num_conditions, index)
+    index.to_s(2).rjust num_conditions, '0'
+  end
+
+  # Returns the matching column number, or nil
+  def helper_parse_conditions(table)
+    # Loop through each answer and hope to end up with the exact column match
+    result = table[:answers].each_index.map(&helper_loop_conditions(table)).reduce(:&).compact
+    result[0] if result.length == 1
+  end
+
+  # Loop through each condition and see if the answer matches
+  def helper_loop_conditions(table)
+    Proc.new {|index|
+      table[:conditions].values[index].map.each_with_index {|x, i|
+        i if x == table[:answers][index] || x.nil?
+      }
+    }
+  end
+
+  # Returns a bit Array of answers for the conditions
+  def helper_run_validate
+    Proc.new {|table, request, cached, response|
+      table.keys.map {|x|
+        headers = {:request => request, :cached => cached, :response => response}
+        send("validate_#{ x }?", headers)
+      }
+    }
+  end
+
+  # Returns an Array of actions to be performed based on the column number
+  def helper_run_action(actions, column, cached)
+    actions.map {|key, value|
+      send("action_#{ key }", {:value => value[column], :cached => cached}) unless value[column].nil?
+    }
+  end
+
+  # Returns the response body, code and headers based on the actions results
+  def helper_response(url, actions, column, cached)
+    _, age, x_cache, warning, status, body = helper_run_action actions, column, cached
+
+    headers_304   = helper_headers_304.call(cached) if status == 304
+    headers_url   = {'Location' => url}             if status == 307
+
+    headers       = [age, warning, x_cache, headers_304, headers_url].compact.reduce &:merge
+
+    {:body => body, :code => status, :headers => headers}
+  end
+
+  # Returns a Boolean after trying to parse the If-Modified-Since, or nil
+  def helper_is_if_modified_error?(key, value)
+    if key == 'If-Modified-Since'
+      begin
+        false if DateTime.parse(value)
+      rescue ArgumentError => e
+        true
+      end
+    end
+  end
+
+  # Generate the same headers if they exist for 304 responses
+  # source: https://tools.ietf.org/html/rfc7232#section-4.1
+  def helper_headers_304
+    Proc.new {|cached|
+      unnormalize_fields.call cached.select {|x| HEADERS_304.include? x }
+    }
+  end
+
+  # Header can be a String or Array
+  def helper_has_star(header)
+    header && header.include?("*")
+  end
+
+  # Combine entity tags if they exist
+  # source: https://tools.ietf.org/html/rfc7234#section-4.3.2
+  def helper_combine_etags(request, cached)
+    return "*" if helper_has_star(request['If-None-Match'])
+
+    request['If-None-Match'] ? request['If-None-Match'].push(cached['ETag']).uniq.compact.join(', ') : cached['ETag']
+  end
+
+  # Use the last modified date if it exists
+  # source: https://tools.ietf.org/html/rfc7234#section-4.3.2
+  def helper_timestamp(request, cached)
+    return request['If-Modified-Since']['httpdate'] if request['If-Modified-Since']
+
+    cached['Last-Modified']['httpdate'] if cached['Last-Modified']
+  end
+
+  # source: https://tools.ietf.org/html/rfc7232#section-2.3
+  def helper_weak_compare
+    etag = /^(W\/)?(\"\w+\")$/
+
+    ->(etag1, etag2) {
+      # source: https://tools.ietf.org/html/rfc7232#section-2.3.2
+      opaque_tag1 = etag.match etag1
+      opaque_tag2 = etag.match etag2
+
+      return false if opaque_tag1.nil? || opaque_tag2.nil?
+
+      opaque_tag1[2] == opaque_tag2[2]
+    }
+  end
+
+  # Must use the 'weak comparison' function
+  # source: https://tools.ietf.org/html/rfc7232#section-3.2
+  def helper_etag_match(request, cached)
+    return unless request && cached
+
+    request.any? {|x|
+      helper_weak_compare.call(x, cached)
+    }
+  end
+
+  # It is not possible for a response's ETag to contain a "star", don't check for it
+  # source: https://tools.ietf.org/html/rfc7232#section-2.3.2
+  def helper_etag(request, cached)
+    helper_has_star(request['If-None-Match']) || helper_etag_match(request['If-None-Match'], cached['ETag'])
+  end
+
+  # source: https://tools.ietf.org/html/rfc7232#section-3.3
+  def helper_last_modified(request, cached)
+    rules = {
+      :response_time         => cached['X-Cache-Res-Date']['timestamp'],   # Required
+      :date_value            => (cached['Date']['timestamp']               if cached['Date']),
+      :cached_last_modified  => (cached['Last-Modified']['timestamp']      if cached['Last-Modified']),
+      :if_modified_since     => (request['If-Modified-Since']['timestamp'] if request['If-Modified-Since'])
+    }
+    return unless rules[:if_modified_since]
+
+    return true if
+      helper_304_rule1(rules) ||
+      helper_304_rule2(rules) ||
+      helper_304_rule3(rules) ||
+      helper_304_rule4(rules)
+
+  end
+
+  # "A cache recipient SHOULD generate a 304 (Not Modified) response if..."
+  # source: https://tools.ietf.org/html/rfc7234#section-4.3.2
+  def helper_304_rule1(rules)
+    rules[:cached_last_modified] &&
+    rules[:cached_last_modified] <= rules[:if_modified_since]
+  end
+
+  def helper_304_rule2(rules)
+    rules[:cached_last_modified].nil? &&
+    rules[:date_value] &&
+    rules[:date_value] <= rules[:if_modified_since]
+  end
+
+  def helper_304_rule3(rules)
+    rules[:date_value].nil? &&
+    rules[:cached_last_modified].nil? &&
+    rules[:response_time] <= rules[:if_modified_since]
+  end
+
+  # "The presented Last-Modified time is at least 60 seconds before the Date value." ¯\_(ツ)_/¯
+  # source: https://tools.ietf.org/html/rfc7232#section-2.2.2
+  def helper_304_rule4(rules)
+    rules[:if_modified_since] &&
+    rules[:date_value] &&
+    rules[:if_modified_since] <= (rules[:date_value] - 60)
+  end
+
+  # Don't allow stale if no-cache or no-store headers exist
+  # source: https://tools.ietf.org/html/rfc7234#section-4.2.4
+  def helper_validate_allow_stale(request_headers, cached_headers)
+    return true if (( request = request_headers['Cache-Control'] )) &&
+      ( request['no-cache'] || request['no-store'] )
+
+    return true if (( cached = cached_headers['Cache-Control'] )) &&
+      ( cached['no-cache'] ||
+        cached['no-store'] ||
+        cached['must-revalidate'] ||
+        cached['s-maxage'] ||
+        cached['proxy-revalidate'] )
+
+    # Legacy support for HTTP/1.0 Pragma header
+    # source: https://tools.ietf.org/html/rfc7234#section-5.4
+    return true if request_headers['Pragma'] == 'no-cache'
+  end
+
+  def helper_apparent_age(response_time, date_value)
+    Proc.new {
+      [0, (response_time - date_value)].max
+    }
+  end
+
+  def helper_corrected_age_value(response_time, request_time, age_value)
+    Proc.new {
+      # NOTE: It's technically IMPOSSIBLE for response_time to be LOWER THAN request_time
+      response_delay = response_time - request_time
+      age_value + response_delay
+    }
+  end
+
+  def helper_corrected_initial_age(cached, corrected_age_value, apparent_age)
+    Proc.new {
+      if cached['Via'] && cached['Age'] && cached['Via'].none? {|x| x.match /1\.0/ }
+        # corrected_age_value.call
+        [0, corrected_age_value.call].max # safeguard just in case
+      else
+        [apparent_age.call, corrected_age_value.call].max
+    end
+    }
+  end
+
+  # Calculate the current_age of the cached response
+  # source: https://tools.ietf.org/html/rfc7234#section-4.2.3
+  def helper_current_age(now, cached)
+    date_value            = cached['Date']['timestamp']             # Required
+    request_time          = cached['X-Cache-Req-Date']['timestamp'] # Required
+    response_time         = cached['X-Cache-Res-Date']['timestamp'] # Required
+    age_value             = cached['Age'].nil? ? 0 : cached['Age']['timestamp']
+
+    apparent_age          = helper_apparent_age           response_time, date_value
+    corrected_age_value   = helper_corrected_age_value    response_time, request_time, age_value
+    corrected_initial_age = helper_corrected_initial_age  cached, corrected_age_value, apparent_age
+
+    resident_time = now - response_time
+    corrected_initial_age.call + resident_time
+  end
+
+  # Calculate the Freshness Lifetime of the cached response
+  # source: https://tools.ietf.org/html/rfc7234#section-4.2.1
+  def helper_freshness_lifetime
+    now = Time.now.gmtime.to_i
+
+    ->(cached) {
+      current_age = helper_current_age now, cached
+
+      # source: https://tools.ietf.org/html/rfc7234#section-4.2
+      freshness_lifetime = helper_explicit(cached) || helper_heuristic(now, cached, current_age)
+
+      [freshness_lifetime, current_age]
+    }
+  end
+
+  # If the expire times are explicitly declared
+  # source: https://tools.ietf.org/html/rfc7234#section-4.2.1
+  def helper_explicit(cached_headers)
+    if (( cached = cached_headers['Cache-Control'] ))
+      return cached['s-maxage']['token'] if cached['s-maxage']
+      return cached['max-age']['token']  if cached['max-age']
+    end
+
+    return (cached_headers['Expires']['timestamp'] - cached_headers['Date']['timestamp']) if cached_headers['Expires']
+  end
+
+  # Calculate Heuristic Freshness if there's not explicit expiration time
+  # source: https://tools.ietf.org/html/rfc7234#section-4.2.2
+  def helper_heuristic(now, cached, current_age)
+    # Use 10% only if the response is public and there's a Last-Modified header
+    # source: https://tools.ietf.org/html/rfc7234#section-4.2.2
+    if cached['Cache-Control'] && cached['Cache-Control']['public'] && cached['Last-Modified']
+      result = (now - cached['Last-Modified']['timestamp']) / 10
+
+      # Don't cache heuristic responses more than 24 hours old, and avoid sending a 113 Warning ;)
+      # source: https://tools.ietf.org/html/rfc7234#section-4.2.2
+      current_age > 86400 ? 0 : result
+    else
+      0
+    end
+  end
+
+  # source: https://tools.ietf.org/html/rfc7234#section-5.2.1.2
+  def helper_max_stale
+    Proc.new {|request, freshness_lifetime, current_age|
+      if request && request['max-stale']
+        token = request['max-stale']['token']
+        token ? (freshness_lifetime.to_i + token.to_i) > current_age : true
+      end
+    }
+  end
+
+  # source: https://tools.ietf.org/html/rfc7234#section-5.2.1.3
+  def helper_min_fresh
+    Proc.new {|request, freshness_lifetime, current_age|
+      if request && request['min-fresh']
+        token = request['min-fresh']['token']
+        freshness_lifetime.to_i >= (current_age + token.to_i)
+      end
+    }
+  end
+
+  # source: https://tools.ietf.org/html/rfc7234#section-5.2.2.2
+  def helper_no_cache
+    Proc.new {|cached_headers|
+      nocache = cached_headers['Cache-Control']['no-cache']
+      # "If the no-cache response directive specifies one or more field-names..."
+      (nocache && nocache['quoted_string']) &&
+        nocache['quoted_string'].split(',').map(&:strip).length > 0
+    }
+  end
+
+  def helper_make_request(http, request)
+    Proc.new { http.request request }
+  end
+
+end