hurley-http-cache 0.1.0.beta

data/lib/hurley/http_cache/request.rb

@@ -0,0 +1,51 @@
+require 'delegate'
+require 'hurley/header'
+require 'hurley/http_cache/cache_control'
+
+module Hurley
+  class HttpCache
+    # Internal: Delegator that extends the Hurley::Request class with some
+    # behavior required for the HTTP caching mechanism.
+    class Request < DelegateClass(Hurley::Request)
+
+      # Internal: Check if the request can be cached.
+      #
+      # Returns true or false.
+      def cacheable?
+        return false if verb != :get && verb != :head
+        return false if cache_control.no_store?
+        true
+      end
+
+      # Internal: Check if the request can't be cached, accordingly to the
+      # 'Cache-Control' header.
+      #
+      # Returns true or false.
+      def no_cache?
+        cache_control.no_cache?
+      end
+
+      # Internal: Get a Hash that represents the request that can be properly
+      # serialized.
+      #
+      # Returns a Hash.
+      def serializable_hash
+        {
+          'verb' => verb.to_s,
+          'url' => url,
+          'header' => header.to_hash
+        }
+      end
+
+      private
+
+      # Internal: Get a CacheControl object to inspect the directives in the
+      # 'Cache-Control' header.
+      #
+      # Returns a CacheControl object.
+      def cache_control
+        @cache_control ||= CacheControl.new(header['Cache-Control'])
+      end
+    end
+  end
+end

data/lib/hurley/http_cache/response.rb

@@ -0,0 +1,186 @@
+require 'time'
+require 'delegate'
+require 'hurley/http_cache/cache_control'
+
+module Hurley
+  class HttpCache
+    # Internal: Delegator that extends the Hurley::Response class with some
+    # behavior required for the HTTP caching mechanism.
+    class Response < DelegateClass(Hurley::Response)
+
+      # Internal: List of status codes that can be cached:
+      # * 200 - 'OK'
+      # * 203 - 'Non-Authoritative Information'
+      # * 300 - 'Multiple Choices'
+      # * 301 - 'Moved Permanently'
+      # * 302 - 'Found'
+      # * 404 - 'Not Found'
+      # * 410 - 'Gone'
+      CACHEABLE_STATUS_CODES = [200, 203, 300, 301, 302, 404, 410]
+
+      # Internal: Initialize a new Response object, and sets the 'Date' header
+      # if its missing.
+      def initialize(response)
+        super(response)
+        @now = Time.now
+        header['Date'] ||= @now.httpdate
+      end
+
+      # Internal: Recreate a Response object from a Hurley::Request and a
+      # serialized response retrieved from the cache.
+      # a
+      #
+      # request - A Hurley::Request instance of an incoming request.
+      # response - A Hash of a persisted response object.
+      #
+      # Returns a Hurley::HttpCache::Response object.
+      def self.restore(request, response)
+        instance = Hurley::Response.new(request) do |res|
+          res.status_code = response['status_code']
+          res.header.update(response['header'])
+          res.body = response['body']
+        end
+
+        new(instance)
+      end
+
+      # Internal: Check if the response can be cached by the client when the
+      # client is acting as a shared cache per RFC 2616. This is validated by
+      # the 'Cache-Control' directives, the response status code and it's
+      # freshness or validation status.
+      #
+      # Returns false if the 'Cache-Control' says that we can't store the
+      # response, or it can be stored in private caches only, or if isn't fresh
+      # or it can't be revalidated with the origin server. Otherwise, returns
+      # true.
+      def cacheable_in_shared_cache?
+        cacheable?(shared: true)
+      end
+
+      # Internal: Check if the response can be cached by the client when the
+      # client is acting as a private cache per RFC 2616. This is validated by
+      # the 'Cache-Control' directives, the response status code and it's
+      # freshness or validation status.
+      #
+      # Returns false if the 'Cache-Control' says that we can't store the
+      # response, or if isn't fresh or it can't be revalidated with the origin
+      # server. Otherwise, returns true.
+      def cacheable_in_private_cache?
+        cacheable?(shared: false)
+      end
+
+      # Internal: Check if the Response returned a 'Not Modified' status code.
+      #
+      # Returns true if the response status code is 304.
+      def not_modified?
+        status_code == 304
+      end
+
+      # Internal: Check the response freshness based on expiration header.
+      # The calculated 'ttl' should be present and bigger than 0.
+      #
+      # Returns true if the response is fresh, otherwise false.
+      def fresh?
+        ttl && ttl > 0
+      end
+
+      # Internal: Get the 'ETag' header.
+      def etag
+        header['ETag']
+      end
+
+      # Internal: Get the 'Last-Modified' header.
+      def last_modified
+        header['Last-Modified']
+      end
+
+      # Internal: Get a Hash that represents the response that can be properly
+      # serialized.
+      #
+      # Returns a Hash.
+      def serializable_hash
+        {
+          'status_code' => status_code,
+          'header' => header.to_hash,
+          'body' => body
+        }
+      end
+
+      private
+
+      # Internal: Parse the 'Date' header back into a Time object.
+      #
+      # Returns the Time object.
+      def date
+        Time.httpdate(header['Date'])
+      end
+
+      # Internal: Get the response max age.
+      # The max age is extracted from one of the following:
+      # * The shared max age directive from the 'Cache-Control' header;
+      # * The max age directive from the 'Cache-Control' header;
+      # * The difference between the 'Expires' header and the response
+      #   date.
+      #
+      # Returns the max age value in seconds or nil if all options above fails.
+      def max_age
+        cache_control.shared_max_age ||
+          cache_control.max_age ||
+          (expires && (expires - @now))
+      end
+
+      # Internal: Get the response age in seconds.
+      #
+      # Returns the 'Age' header if present, or subtracts the response 'date'
+      # from the current time.
+      def age
+        (header['Age'] || (@now - date)).to_i
+      end
+
+      # Internal: Calculate the 'Time to live' left on the Response.
+      #
+      # Returns the remaining seconds for the response, or nil the 'max_age'
+      # isn't present.
+      def ttl
+        max_age - age if max_age
+      end
+
+      # Internal: Check if this response can be revalidated.
+      #
+      # Returns true if the 'headers' contains a 'Last-Modified' or an 'ETag'
+      # entry.
+      def validateable?
+        header.key?('Last-Modified') || header.key?('ETag')
+      end
+
+      # Internal: The logic behind cacheable_in_private_cache? and
+      # cacheable_in_shared_cache? The logic is the same except for the
+      # treatment of the private Cache-Control directive.
+      def cacheable?(shared:)
+        return false if (cache_control.private? && shared) || cache_control.no_store?
+
+        cacheable_status_code? && (validateable? || fresh?)
+      end
+
+      # Internal: Validate the response status against the
+      # `CACHEABLE_STATUS_CODES' constant.
+      #
+      # Returns true if the constant includes the response status code.
+      def cacheable_status_code?
+        CACHEABLE_STATUS_CODES.include?(status_code)
+      end
+
+      # Internal: Get the 'Expires' in a Time object.
+      #
+      # Returns the Time object, or nil if the header isn't present.
+      def expires
+        header['Expires'] && Time.httpdate(header['Expires'])
+      end
+
+      # Internal: Gets the 'CacheControl' object.
+      def cache_control
+        @cache_control ||= CacheControl.new(header['Cache-Control'])
+      end
+    end
+  end
+end

data/lib/hurley/http_cache/storage.rb

@@ -0,0 +1,182 @@
+require 'json'
+require 'digest/sha1'
+
+require 'hurley/header'
+
+module Hurley
+  class HttpCache
+    # Internal: A Storage class to manage the caching of request and responses.
+    #
+    # Examples
+    #
+    #   # Create a Storage object using Rails default cache store.
+    #   Hurley::HttpCache::Storage.new(store: Rails.cache)
+    #
+    #   # Create a new Storage using Marshal for serialization.
+    #   Hurley::HttpCache::Storage.new(store: Rails.cache, serializer: Marshal)
+    class Storage
+      # Public: Get the underlying cache store object.
+      attr_reader :cache
+
+      # Internal: Initialize a new Storage object with a cache backend.
+      #
+      # :logger     - A Logger object to be used to emit warnings.
+      # :store      - An cache store object that should respond to 'dump' and
+      #               'load'.
+      # :serializer - A serializer object that should respond to 'dump' and
+      #               'load'.
+      def initialize(store: nil, serializer: nil, logger: nil)
+        @cache = store || MemoryStore.new
+        @serializer = serializer || JSON
+        @logger = logger
+        assert_valid_store!
+      end
+
+      # Internal: Store a response inside the cache.
+      #
+      # request  - A Hurley::HttpCache::::Request instance of the executed HTTP
+      #            request.
+      # response - The Hurley::HttpCache::Response instance to be stored.
+      #
+      # Returns nothing.
+      def write(request, response)
+        key = cache_key_for(request.url)
+        entry = serialize_entry(request.serializable_hash, response.serializable_hash)
+
+        entries = cache.read(key) || []
+
+        entries.reject! do |(cached_request, cached_response)|
+          response_matches?(request, cached_request, cached_response)
+        end
+
+        entries << entry
+        cache.write(key, entries)
+      rescue Encoding::UndefinedConversionError => e
+        warn { "Response could not be serialized: #{e.message}. Try using Marshal to serialize." }
+        raise e
+      end
+
+      # Internal: Attempt to retrieve an stored response that suits the incoming
+      # HTTP request.
+      #
+      # request  - A Hurley::HttpCache::::Request instance of the incoming HTTP
+      #            request.
+      #
+      # Returns a Hash.
+      def read(request)
+        cache_key = cache_key_for(request.url)
+        entries = cache.read(cache_key)
+        lookup_response(request, entries)
+      end
+
+      def delete(url)
+        cache_key = cache_key_for(url)
+        cache.delete(cache_key)
+      end
+
+      private
+
+      # Internal: Retrieve a response Hash from the list of entries that match
+      # the given request.
+      #
+      # request  - A Hurley::HttpCache::::Request instance of the incoming HTTP
+      #            request.
+      # entries  - An Array of pairs of Hashes (request, response).
+      #
+      # Returns a Hash or nil.
+      def lookup_response(request, entries)
+        if entries
+          entries = entries.map { |entry| deserialize_entry(*entry) }
+          _, response = entries.find { |req, res| response_matches?(request, req, res) }
+          response
+        end
+      end
+
+      # Internal: Check if a cached response and request matches the given
+      # request.
+      #
+      # request         - A Hurley::HttpCache::::Request instance of the
+      #                   current HTTP request.
+      # cached_request  - The Hash of the request that was cached.
+      # cached_response - The Hash of the response that was cached.
+      #
+      # Returns true or false.
+      def response_matches?(request, cached_request, cached_response)
+        request.verb.to_s == cached_request['verb'] &&
+          vary_matches?(cached_response, request, cached_request)
+      end
+
+      def vary_matches?(cached_response, request, cached_request)
+        headers = Hurley::Header.new(cached_response['header'])
+        vary = headers['Vary'].to_s
+
+        vary.empty? || (vary != '*' && vary.split(/[\s,]+/).all? do |header|
+          request.header[header] == cached_request['header'][header]
+        end)
+      end
+
+      def serialize_entry(*objects)
+        objects.map { |object| serialize_object(object) }
+      end
+
+      def serialize_object(object)
+        @serializer.dump(object)
+      end
+
+      def deserialize_entry(*objects)
+        objects.map { |object| deserialize_object(object) }
+      end
+
+      def deserialize_object(object)
+        @serializer.load(object)
+      end
+
+      # Internal: Computes the cache key for a specific request, taking in
+      # account the current serializer to avoid cross serialization issues.
+      #
+      # url - The request URL.
+      #
+      # Returns a String.
+      def cache_key_for(url)
+        prefix = (@serializer.is_a?(Module) ? @serializer : @serializer.class).name
+        Digest::SHA1.hexdigest("#{prefix}#{url}")
+      end
+
+      # Internal: Checks if the given cache object supports the
+      # expect API ('read' and 'write').
+      #
+      # Raises an 'ArgumentError'.
+      #
+      # Returns nothing.
+      def assert_valid_store!
+        unless cache.respond_to?(:read) && cache.respond_to?(:write) && cache.respond_to?(:delete)
+          raise ArgumentError.new("#{cache.inspect} is not a valid cache store as it does not responds to 'read', 'write' or 'delete'.")
+        end
+      end
+
+      def warn
+        @logger.warn { yield } if @logger
+      end
+    end
+
+    # Internal: A Hash based store to be used by the 'Storage' class
+    # when a 'store' is not provided for the middleware setup.
+    class MemoryStore
+      def initialize
+        @cache = {}
+      end
+
+      def read(key)
+        @cache[key]
+      end
+
+      def delete(key)
+        @cache.delete(key)
+      end
+
+      def write(key, value)
+        @cache[key] = value
+      end
+    end
+  end
+end

data/test/http_cache/cache_control_test.rb

@@ -0,0 +1,79 @@
+require File.expand_path('../../test_helper', __FILE__)
+
+class CacheControlTest < MiniTest::Test
+  def test_parse_cache_control_pairs
+    cache_control = Hurley::HttpCache::CacheControl.new('max-age=600, max-stale=300, min-fresh=570')
+    assert_equal cache_control.max_age, 600
+  end
+
+  def test_parse_cache_control_flags
+    cache_control = Hurley::HttpCache::CacheControl.new('no-cache')
+
+    assert_predicate cache_control, :no_cache?
+  end
+
+  def test_parse_cache_control
+    cache_control =
+      Hurley::HttpCache::CacheControl.new('max-age=600,must-revalidate,min-fresh=3000,foo=bar,baz')
+
+    assert_equal cache_control.max_age, 600
+    assert_predicate cache_control, :must_revalidate?
+  end
+
+  def test_strip_leading_and_trailing_spaces
+    cache_control = Hurley::HttpCache::CacheControl.new('   public,   max-age =   600  ')
+
+    assert_predicate cache_control, :public?
+    assert_equal cache_control.max_age, 600
+  end
+
+  def test_ignore_blank_segments
+    cache_control = Hurley::HttpCache::CacheControl.new('max-age=600,,s-maxage=300')
+
+    assert_equal cache_control.max_age, 600
+    assert_equal cache_control.shared_max_age, 300
+  end
+
+  def test_sort_directives
+    cache_control = Hurley::HttpCache::CacheControl.new('foo=bar, z, x, y, bling=baz, zoom=zib, b, a')
+
+    assert_equal cache_control.to_s, 'a, b, x, y, z, bling=baz, foo=bar, zoom=zib'
+  end
+
+  def test_parses_max_age_directive
+    cache_control = Hurley::HttpCache::CacheControl.new('public, max-age=600')
+
+    assert_equal cache_control.max_age, 600
+  end
+
+  def test_parse_shared_max_age_directive
+    cache_control = Hurley::HttpCache::CacheControl.new('public, s-maxage=600')
+
+    assert_equal cache_control.shared_max_age, 600
+  end
+
+  def test_parse_public_directive
+    cache_control = Hurley::HttpCache::CacheControl.new('public')
+    assert_predicate cache_control, :public?
+  end
+
+  def test_parse_private_directive
+    cache_control = Hurley::HttpCache::CacheControl.new('private')
+    assert_predicate cache_control, :private?
+  end
+
+  def test_parse_no_cache_directive
+    cache_control = Hurley::HttpCache::CacheControl.new('no-cache')
+    assert_predicate cache_control, :no_cache?
+  end
+
+  def test_parse_must_revalidate_directive
+    cache_control = Hurley::HttpCache::CacheControl.new('must-revalidate')
+    assert_predicate cache_control, :must_revalidate?
+  end
+
+  def test_parse_proxy_revalidate_directive
+    cache_control = Hurley::HttpCache::CacheControl.new('proxy-revalidate')
+    assert_predicate cache_control, :proxy_revalidate?
+  end
+end