rtomayko-rack-cache 0.2.0

data/lib/rack/cache/headers.rb

@@ -0,0 +1,277 @@
+require 'set'
+require 'rack/utils/environment_headers'
+
+module Rack::Cache
+  # Generic HTTP header helper methods. Provides access to headers that can be
+  # included in requests and responses. This can be mixed into any object that
+  # responds to #headers by returning a Hash.
+
+  module Headers
+    # Determine if any of the header names exist:
+    #   if header?('Authorization', 'Cookie')
+    #     ...
+    #   end
+    def header?(*names)
+      names.any? { |name| headers.include?(name) }
+    end
+
+    # A Hash of name=value pairs that correspond to the Cache-Control header.
+    # Valueless parameters (e.g., must-revalidate, no-store) have a Hash value
+    # of true. This method always returns a Hash, empty if no Cache-Control
+    # header is present.
+    def cache_control
+      @cache_control ||=
+        (headers['Cache-Control'] || '').split(/\s*,\s*/).inject({}) {|hash,token|
+          name, value = token.split(/\s*=\s*/, 2)
+          hash[name.downcase] = (value || true) unless name.empty?
+          hash
+        }.freeze
+    end
+
+    # Set the Cache-Control header to the values specified by the Hash. See
+    # the #cache_control method for information on expected Hash structure.
+    def cache_control=(hash)
+      value =
+        hash.collect { |key,value|
+          next nil unless value
+          next key if value == true
+          "#{key}=#{value}"
+        }.compact.join(', ')
+      if value.empty?
+        headers.delete('Cache-Control')
+        @cache_control = {}
+      else
+        headers['Cache-Control'] = value
+        @cache_control = hash.dup.freeze
+      end
+    end
+
+    # The literal value of the ETag HTTP header or nil if no ETag is specified.
+    def etag
+      headers['Etag']
+    end
+  end
+
+  # HTTP request header helpers. When included in Rack::Cache::Request, headers
+  # may be accessed by their standard RFC 2616 names using the #headers Hash.
+  module RequestHeaders
+    include Rack::Cache::Headers
+
+    # A Hash-like object providing access to HTTP request headers.
+    def headers
+      @headers ||= Rack::Utils::EnvironmentHeaders.new(env)
+    end
+
+    # The literal value of the If-Modified-Since request header or nil when
+    # no If-Modified-Since header is present.
+    def if_modified_since
+      headers['If-Modified-Since']
+    end
+
+    # The literal value of the If-None-Match request header or nil when
+    # no If-None-Match header is present.
+    def if_none_match
+      headers['If-None-Match']
+    end
+  end
+
+  # HTTP response header helper methods.
+  module ResponseHeaders
+    include Rack::Cache::Headers
+
+    # Status codes of responses that MAY be stored by a cache or used in reply
+    # to a subsequent request.
+    #
+    # http://tools.ietf.org/html/rfc2616#section-13.4
+    CACHEABLE_RESPONSE_CODES = [
+      200, # OK
+      203, # Non-Authoritative Information
+      300, # Multiple Choices
+      301, # Moved Permanently
+      302, # Found
+      404, # Not Found
+      410  # Gone
+    ].to_set
+
+    # Determine if the response is "fresh". Fresh responses may be served from
+    # cache without any interaction with the origin. A response is considered
+    # fresh when it includes a Cache-Control/max-age indicator or Expiration
+    # header and the calculated age is less than the freshness lifetime.
+    def fresh?
+      ttl && ttl > 0
+    end
+
+    # Determine if the response is "stale". Stale responses must be validated
+    # with the origin before use. This is the inverse of #fresh?.
+    def stale?
+      !fresh?
+    end
+
+    # Determine if the response is worth caching under any circumstance. An
+    # object that is cacheable may not necessary be served from cache without
+    # first validating the response with the origin.
+    #
+    # An object that includes no freshness lifetime (Expires, max-age) and that
+    # does not include a validator (Last-Modified, Etag) serves no purpose in a
+    # cache that only serves fresh or valid objects.
+    def cacheable?
+      return false unless CACHEABLE_RESPONSE_CODES.include?(status)
+      return false if no_store?
+      validateable? || fresh?
+    end
+
+    # The response includes specific information about its freshness. True when
+    # a +Cache-Control+ header with +max-age+ value is present or when the
+    # +Expires+ header is set.
+    def freshness_information?
+      header?('Expires') || !cache_control['max-age'].nil?
+    end
+
+    # Determine if the response includes headers that can be used to validate
+    # the response with the origin using a conditional GET request.
+    def validateable?
+      header?('Last-Modified') || header?('Etag')
+    end
+
+    # Indicates that the response should not be served from cache without first
+    # revalidating with the origin. Note that this does not necessary imply that
+    # a caching agent ought not store the response in its cache.
+    def no_cache?
+      !cache_control['no-cache'].nil?
+    end
+
+    # Indicates that the response should not be stored under any circumstances.
+    def no_store?
+      cache_control['no-store']
+    end
+
+    # The date, as specified by the Date header. When no Date header is present,
+    # set the Date header to Time.now and return.
+    def date
+      if date = headers['Date']
+        Time.httpdate(date)
+      else
+        headers['Date'] = now.httpdate unless headers.frozen?
+        now
+      end
+    end
+
+    # The age of the response.
+    def age
+      [(now - date).to_i, 0].max
+    end
+
+    # The number of seconds after the time specified in the response's Date
+    # header when the the response should no longer be considered fresh. First
+    # check for a Cache-Control max-age value, and fall back on an expires
+    # header; return nil when no maximum age can be established.
+    def max_age
+      if age = cache_control['max-age']
+        age.to_i
+      elsif headers['Expires']
+        Time.httpdate(headers['Expires']) - date
+      end
+    end
+
+    # Sets the number of seconds after which the response should no longer
+    # be considered fresh. This sets the Cache-Control max-age value.
+    def max_age=(value)
+      self.cache_control = cache_control.merge('max-age' => value.to_s)
+    end
+
+    # The Time when the response should be considered stale. With a
+    # Cache-Control/max-age value is present, this is calculated by adding the
+    # number of seconds specified to the responses #date value. Falls back to
+    # the time specified in the Expires header or returns nil if neither is
+    # present.
+    def expires_at
+      if max_age = cache_control['max-age']
+        date + max_age.to_i
+      elsif time = headers['Expires']
+        Time.httpdate(time)
+      end
+    end
+
+    # The response's time-to-live in seconds, or nil when no freshness
+    # information is present in the response. When the responses #ttl
+    # is <= 0, the response may not be served from cache without first
+    # revalidating with the origin.
+    def ttl
+      max_age - age if max_age
+    end
+
+    # Set the response's time-to-live to the specified number of seconds. This
+    # adjusts the Cache-Control/max-age value.
+    def ttl=(seconds)
+      self.max_age = age + seconds
+    end
+
+    # The String value of the Last-Modified header exactly as it appears
+    # in the response (i.e., no date parsing / conversion is performed).
+    def last_modified
+      headers['Last-Modified']
+    end
+
+    # Determine if the response was last modified at the time provided.
+    # time_value is the exact string provided in an origin response's
+    # Last-Modified header.
+    def last_modified_at?(time_value)
+      time_value && last_modified == time_value
+    end
+
+    # Determine if response's ETag matches the etag value provided. Return
+    # false when either value is nil.
+    def etag_matches?(etag)
+      etag && self.etag == etag
+    end
+
+    # Headers that MUST NOT be included with 304 Not Modified responses.
+    #
+    # http://tools.ietf.org/html/rfc2616#section-10.3.5
+    NOT_MODIFIED_OMIT_HEADERS = %w[
+      Allow
+      Content-Encoding
+      Content-Language
+      Content-Length
+      Content-Md5
+      Content-Type
+      Last-Modified
+    ].to_set
+
+    # Modify the response so that it conforms to the rules defined for
+    # '304 Not Modified'. This sets the status, removes the body, and
+    # discards any headers that MUST NOT be included in 304 responses.
+    #
+    # http://tools.ietf.org/html/rfc2616#section-10.3.5
+    def not_modified!
+      self.status = 304
+      self.body = []
+      NOT_MODIFIED_OMIT_HEADERS.each { |name| headers.delete(name) }
+      nil
+    end
+
+    # The literal value of the Vary header, or nil when no Vary header is
+    # present.
+    def vary
+      headers['Vary']
+    end
+
+    # Does the response include a Vary header?
+    def vary?
+      ! vary.nil?
+    end
+
+    # An array of header names given in the Vary header or an empty
+    # array when no Vary header is present.
+    def vary_header_names
+      return [] unless vary = headers['Vary']
+      vary.split(/[\s,]+/)
+    end
+
+  private
+    def now
+      @now ||= Time.now
+    end
+  end
+
+end

data/lib/rack/cache/metastore.rb

@@ -0,0 +1,292 @@
+require 'rack'
+require 'fileutils'
+require 'digest/sha1'
+
+module Rack::Cache
+
+  # The MetaStore is responsible for storing meta information about a
+  # request/response pair keyed by the request's URL.
+  #
+  # The meta store keeps a list of request/response pairs for each canonical
+  # request URL. A request/response pair is a two element Array of the form:
+  #   [request, response]
+  #
+  # The +request+ element is a Hash of Rack environment keys. Only protocol
+  # keys (i.e., those that start with "HTTP_") are stored. The +response+
+  # element is a Hash of cached HTTP response headers for the paired request.
+  #
+  # The MetaStore class is abstract and should not be instanstiated
+  # directly. Concrete subclasses should implement the protected #read,
+  # #write, and #purge methods. Care has been taken to keep these low-level
+  # methods dumb and straight-forward to implement.
+  class MetaStore
+
+    # Locate a cached response for the request provided. Returns a
+    # Rack::Cache::Response object if the cache hits or nil if no cache entry
+    # was found.
+    def lookup(request, entity_store)
+      entries = read(request.fullpath)
+
+      # bail out if we have nothing cached
+      return nil if entries.empty?
+
+      # find a cached entry that matches the request.
+      env = request.env
+      match = entries.detect{ |req,res| requests_match?(res['Vary'], env, req)}
+      if match
+        # TODO what if body doesn't exist in entity store?
+        # reconstruct response object
+        req, res = match
+        status = res['X-Status']
+        body = entity_store.open(res['X-Content-Digest'])
+        response = Rack::Cache::Response.new(status.to_i, res, body)
+        response.activate!
+
+        # Return the cached response
+        response
+      end
+    end
+
+    # Write a cache entry to the store under the given key. Existing
+    # entries are read and any that match the response are removed.
+    # This method calls #write with the new list of cache entries.
+    #--
+    # TODO canonicalize URL key
+    def store(request, response, entity_store)
+      key = request.fullpath
+      stored_env = persist_request(request)
+
+      # write the response body to the entity store if this is the
+      # original response.
+      response['X-Status'] = response.status.to_s
+      if response['X-Content-Digest'].nil?
+        digest, size = entity_store.write(response.body)
+        response['X-Content-Digest'] = digest
+        response['Content-Length'] = size.to_s unless response['Transfer-Encoding']
+        response.body = entity_store.open(digest)
+        response.activate!
+      end
+
+      # read existing cache entries, remove non-varying, and add this one to
+      # the list
+      vary = response.vary
+      entries =
+        read(key).reject do |env,res|
+          (vary == res['Vary']) &&
+            requests_match?(vary, env, stored_env)
+        end
+      entries.unshift [stored_env, response.headers.dup]
+      write key, entries
+    end
+
+  private
+    # Extract the environment Hash from +request+ while making any
+    # necessary modifications in preparation for persistence. The Hash
+    # returned must be marshalable.
+    def persist_request(request)
+      env = request.env.dup
+      env.reject! { |key,val| key =~ /[^0-9A-Z_]/ }
+      env
+    end
+
+    # Determine whether the two environment hashes are non-varying based on
+    # the vary response header value provided.
+    def requests_match?(vary, env1, env2)
+      return true if vary.nil? || vary == ''
+      vary.split(/[\s,]+/).all? do |header|
+        key = "HTTP_#{header.upcase.tr('-', '_')}"
+        env1[key] == env2[key]
+      end
+    end
+
+  protected
+    # Locate all cached request/response pairs that match the specified
+    # URL key. The result must be an Array of all cached request/response
+    # pairs. An empty Array must be returned if nothing is cached for
+    # the specified key.
+    def read(key)
+      raise NotImplemented
+    end
+
+    # Store an Array of request/response pairs for the given key. Concrete
+    # implementations should not attempt to filter or concatenate the
+    # list in any way.
+    def write(key, negotiations)
+      raise NotImplemented
+    end
+
+    # Remove all cached entries at the key specified. No error is raised
+    # when the key does not exist.
+    def purge(key)
+      raise NotImplemented
+    end
+
+  private
+
+    # Generate a SHA1 hex digest for the specified string. This is a
+    # simple utility method for meta store implementations.
+    def hexdigest(data)
+      Digest::SHA1.hexdigest(data)
+    end
+
+  public
+
+    # Concrete MetaStore implementation that uses a simple Hash to store
+    # request/response pairs on the heap.
+    class Heap < MetaStore
+      def initialize(hash={})
+        @hash = hash
+      end
+
+      def read(key)
+        @hash.fetch(key, []).collect do |req,res|
+          [req.dup, res.dup]
+        end
+      end
+
+      def write(key, entries)
+        @hash[key] = entries
+      end
+
+      def purge(key)
+        @hash.delete(key)
+        nil
+      end
+
+      def to_hash
+        @hash
+      end
+
+      def self.resolve(uri)
+        new
+      end
+    end
+
+    HEAP = Heap
+    MEM = HEAP
+
+    # Concrete MetaStore implementation that stores request/response
+    # pairs on disk.
+    class Disk < MetaStore
+      attr_reader :root
+
+      def initialize(root="/tmp/rack-cache/meta-#{ARGV[0]}")
+        @root = File.expand_path(root)
+        FileUtils.mkdir_p(root, :mode => 0755)
+      end
+
+      def read(key)
+        path = key_path(key)
+        File.open(path, 'rb') { |io| Marshal.load(io) }
+      rescue Errno::ENOENT
+        []
+      end
+
+      def write(key, entries)
+        path = key_path(key)
+        File.open(path, 'wb') { |io| Marshal.dump(entries, io, -1) }
+      rescue Errno::ENOENT
+        Dir.mkdir(File.dirname(path), 0755)
+        retry
+      end
+
+      def purge(key)
+        path = key_path(key)
+        File.unlink(path)
+        nil
+      rescue Errno::ENOENT
+        nil
+      end
+
+    private
+      def key_path(key)
+        File.join(root, spread(hexdigest(key)))
+      end
+
+      def spread(sha, n=2)
+        sha = sha.dup
+        sha[n,0] = '/'
+        sha
+      end
+
+    public
+      def self.resolve(uri)
+        path = File.expand_path(uri.opaque || uri.path)
+        new path
+      end
+
+    end
+
+    DISK = Disk
+    FILE = Disk
+
+    # Stores request/response pairs in memcached. Keys are not stored
+    # directly since memcached has a 250-byte limit on key names. Instead,
+    # the SHA1 hexdigest of the key is used.
+    class MemCache < MetaStore
+
+      # The Memcached instance used to communicated with the memcached
+      # daemon.
+      attr_reader :cache
+
+      def initialize(server="localhost:11211", options={})
+        @cache =
+          if server.respond_to?(:stats)
+            server
+          else
+            require 'memcached'
+            Memcached.new(server, options)
+          end
+      end
+
+      def read(key)
+        key = hexdigest(key)
+        cache.get(key)
+      rescue Memcached::NotFound
+        []
+      end
+
+      def write(key, entries)
+        key = hexdigest(key)
+        cache.set(key, entries)
+      end
+
+      def purge(key)
+        key = hexdigest(key)
+        cache.delete(key)
+        nil
+      rescue Memcached::NotFound
+        nil
+      end
+
+      extend Rack::Utils
+
+      # Create MemCache store for the given URI. The URI must specify
+      # a host and may specify a port, namespace, and options:
+      #
+      # memcached://example.com:11211/namespace?opt1=val1&opt2=val2
+      #
+      # Query parameter names and values are documented with the memcached
+      # library: http://tinyurl.com/4upqnd
+      def self.resolve(uri)
+        server = "#{uri.host}:#{uri.port || '11211'}"
+        options = parse_query(uri.query)
+        options.keys.each do |key|
+          value =
+            case value = options.delete(key)
+            when 'true' ; true
+            when 'false' ; false
+            else value.to_sym
+            end
+          options[k.to_sym] = value
+        end
+        options[:namespace] = uri.path.sub(/^\//, '')
+        new server, options
+      end
+    end
+
+    MEMCACHE = MemCache
+    MEMCACHED = MemCache
+  end
+
+end

data/lib/rack/cache/options.rb

@@ -0,0 +1,119 @@
+require 'rack'
+require 'rack/cache/storage'
+
+module Rack::Cache
+  # Configuration options and utility methods for option access. Rack::Cache
+  # uses the Rack Environment to store option values. All options documented
+  # below are stored in the Rack Environment as "rack-cache.<option>", where
+  # <option> is the option name.
+  #
+  # The #set method can be used within an event or a top-level configuration
+  # block to configure a option values. When #set is called at the top-level,
+  # the value applies to all requests; when called from within an event, the
+  # values applies only to the request being processed.
+
+  module Options
+    class << self
+      private
+      def option_accessor(key)
+        define_method(key) { || read_option(key) }
+        define_method("#{key}=") { |value| write_option(key, value) }
+        define_method("#{key}?") { || !! read_option(key) }
+      end
+    end
+
+    # Enable verbose trace logging. This option is currently enabled by
+    # default but is likely to be disabled in a future release.
+    option_accessor :verbose
+
+    # The storage resolver. Defaults to the Rack::Cache.storage singleton instance
+    # of Rack::Cache::Storage. This object is responsible for resolving metastore
+    # and entitystore URIs to an implementation instances.
+    option_accessor :storage
+
+    # A URI specifying the meta-store implementation that should be used to store
+    # request/response meta information. The following URIs schemes are
+    # supported:
+    #
+    # * heap:/
+    # * file:/absolute/path or file:relative/path
+    # * memcached://localhost:11211[/namespace]
+    #
+    # If no meta store is specified the 'heap:/' store is assumed. This
+    # implementation has significant draw-backs so explicit configuration is
+    # recommended.
+    option_accessor :metastore
+
+    # A URI specifying the entity-store implement that should be used to store
+    # response bodies. See the metastore option for information on supported URI
+    # schemes.
+    #
+    # If no entity store is specified the 'heap:/' store is assumed. This
+    # implementation has significant draw-backs so explicit configuration is
+    # recommended.
+    option_accessor :entitystore
+
+    # The number of seconds that a cache entry should be considered
+    # "fresh" when no explicit freshness information is provided in
+    # a response. Explicit Cache-Control or Expires headers
+    # override this value.
+    #
+    # Default: 0
+    option_accessor :default_ttl
+
+    # The underlying options Hash. During initialization (or outside of a
+    # request), this is a default values Hash. During a request, this is the
+    # Rack environment Hash. The default values Hash is merged in underneath
+    # the Rack environment before each request is processed.
+    def options
+      @env || @default_options
+    end
+
+    # Set multiple options.
+    def options=(hash={})
+      hash.each { |key,value| write_option(key, value) }
+    end
+
+    # Set an option. When +option+ is a Symbol, it is set in the Rack
+    # Environment as "rack-cache.option". When +option+ is a String, it
+    # exactly as specified. The +option+ argument may also be a Hash in
+    # which case each key/value pair is merged into the environment as if
+    # the #set method were called on each.
+    def set(option, value=self)
+      if value == self
+        self.options = option.to_hash
+      else
+        write_option option, value
+      end
+    end
+
+  private
+    def read_option(key)
+      options[option_name(key)]
+    end
+
+    def write_option(key, value)
+      options[option_name(key)] = value
+    end
+
+    def option_name(key)
+      case key
+      when Symbol ; "rack-cache.#{key}"
+      when String ; key
+      else raise ArgumentError
+      end
+    end
+
+  private
+    def initialize_options(options={})
+      @default_options = {
+        'rack-cache.verbose'     => true,
+        'rack-cache.storage'     => Rack::Cache::Storage.instance,
+        'rack-cache.metastore'   => 'heap:/',
+        'rack-cache.entitystore' => 'heap:/',
+        'rack-cache.default_ttl' => 0
+      }
+      self.options = options
+    end
+  end
+end