rack-cache 0.3.0 → 0.4

data/lib/rack/cache/entitystore.rb

@@ -1,6 +1,7 @@
 require 'digest/sha1'
 
 module Rack::Cache
+
   # Entity stores are used to cache response bodies across requests. All
   # Implementations are required to calculate a SHA checksum of the data written
   # which becomes the response body's key.
@@ -13,7 +14,7 @@ module Rack::Cache
     def slurp(body)
       digest, size = Digest::SHA1.new, 0
       body.each do |part|
-        size += part.length
+        size += bytesize(part)
         digest << part
         yield part
       end
@@ -21,7 +22,13 @@ module Rack::Cache
       [ digest.hexdigest, size ]
     end
 
-    private :slurp
+    if ''.respond_to?(:bytesize)
+      def bytesize(string); string.bytesize; end
+    else
+      def bytesize(string); string.size; end
+    end
+
+    private :slurp, :bytesize
 
 
     # Stores entity bodies on the heap using a Hash object.
@@ -90,7 +97,7 @@ module Rack::Cache
       end
 
       def read(key)
-        File.read(body_path(key))
+        File.open(body_path(key), 'rb') { |f| f.read }
       rescue Errno::ENOENT
         nil
       end
@@ -241,7 +248,6 @@ module Rack::Cache
 
     MEMCACHE = MemCache
     MEMCACHED = MemCache
-
   end
 
 end

data/lib/rack/cache/key.rb

@@ -0,0 +1,52 @@
+require 'rack/utils'
+
+module Rack::Cache
+  class Key
+    include Rack::Utils
+
+    # Implement .call, since it seems like the "Rack-y" thing to do. Plus, it
+    # opens the door for cache key generators to just be blocks.
+    def self.call(request)
+      new(request).generate
+    end
+
+    def initialize(request)
+      @request = request
+    end
+
+    # Generate a normalized cache key for the request.
+    def generate
+      parts = []
+      parts << @request.scheme << "://"
+      parts << @request.host
+
+      if @request.scheme == "https" && @request.port != 443 ||
+          @request.scheme == "http" && @request.port != 80
+        parts << ":" << @request.port.to_s
+      end
+
+      parts << @request.script_name
+      parts << @request.path_info
+
+      if qs = query_string
+        parts << "?"
+        parts << qs
+      end
+
+      parts.join
+    end
+
+  private
+    # Build a normalized query string by alphabetizing all keys/values
+    # and applying consistent escaping.
+    def query_string
+      return nil if @request.query_string.nil?
+
+      @request.query_string.split(/[&;] */n).
+        map { |p| unescape(p).split('=', 2) }.
+        sort.
+        map { |k,v| "#{escape(k)}=#{escape(v)}" }.
+        join('&')
+    end
+  end
+end

data/lib/rack/cache/metastore.rb

@@ -1,6 +1,6 @@
-require 'rack'
 require 'fileutils'
 require 'digest/sha1'
+require 'rack/utils'
 
 module Rack::Cache
 
@@ -25,7 +25,8 @@ module Rack::Cache
     # 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)
+      key = cache_key(request)
+      entries = read(key)
 
       # bail out if we have nothing cached
       return nil if entries.empty?
@@ -37,9 +38,7 @@ module Rack::Cache
 
       req, res = match
       if body = entity_store.open(res['X-Content-Digest'])
-        response = Rack::Cache::Response.new(res['X-Status'].to_i, res, body)
-        response.activate!
-        response
+        restore_response(res, body)
       else
         # TODO the metastore referenced an entity that doesn't exist in
         # the entitystore. we definitely want to return nil but we should
@@ -50,21 +49,17 @@ module Rack::Cache
     # 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
+      key = cache_key(request)
       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?
+      if response.headers['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.headers['X-Content-Digest'] = digest
+        response.headers['Content-Length'] = size.to_s unless response.headers['Transfer-Encoding']
         response.body = entity_store.open(digest)
-        response.activate!
       end
 
       # read existing cache entries, remove non-varying, and add this one to
@@ -75,11 +70,41 @@ module Rack::Cache
           (vary == res['Vary']) &&
             requests_match?(vary, env, stored_env)
         end
-      entries.unshift [stored_env, {}.update(response.headers)]
+
+      headers = persist_response(response)
+      headers.delete 'Age'
+
+      entries.unshift [stored_env, headers]
       write key, entries
+      key
+    end
+
+    # Generate a cache key for the request.
+    def cache_key(request)
+      keygen = request.env['rack-cache.cache_key'] || Key
+      keygen.call(request)
+    end
+
+    # Invalidate all cache entries that match the request.
+    def invalidate(request, entity_store)
+      modified = false
+      key = cache_key(request)
+      entries =
+        read(key).map do |req, res|
+          response = restore_response(res)
+          if response.fresh?
+            response.expire!
+            modified = true
+            [req, persist_response(response)]
+          else
+            [req, res]
+          end
+        end
+      write key, entries if modified
     end
 
   private
+
     # Extract the environment Hash from +request+ while making any
     # necessary modifications in preparation for persistence. The Hash
     # returned must be marshalable.
@@ -89,6 +114,19 @@ module Rack::Cache
       env
     end
 
+    # Converts a stored response hash into a Response object. The caller
+    # is responsible for loading and passing the body if needed.
+    def restore_response(hash, body=nil)
+      status = hash.delete('X-Status').to_i
+      Rack::Cache::Response.new(status, hash, body)
+    end
+
+    def persist_response(response)
+      hash = response.headers.to_hash
+      hash['X-Status'] = response.status.to_s
+      hash
+    end
+
     # Determine whether the two environment hashes are non-varying based on
     # the vary response header value provided.
     def requests_match?(vary, env1, env2)
@@ -122,7 +160,6 @@ module Rack::Cache
     end
 
   private
-
     # Generate a SHA1 hex digest for the specified string. This is a
     # simple utility method for meta store implementations.
     def hexdigest(data)
@@ -130,7 +167,6 @@ module Rack::Cache
     end
 
   public
-
     # Concrete MetaStore implementation that uses a simple Hash to store
     # request/response pairs on the heap.
     class Heap < MetaStore

data/lib/rack/cache/options.rb

@@ -1,26 +1,28 @@
-require 'rack'
+require 'rack/cache/key'
 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) }
+    def self.option_accessor(key)
+      name = option_name(key)
+      define_method(key) { || options[name] }
+      define_method("#{key}=") { |value| options[name] = value }
+      define_method("#{key}?") { || !! options[name] }
+    end
+
+    def option_name(key)
+      case key
+      when Symbol ; "rack-cache.#{key}"
+      when String ; key
+      else raise ArgumentError
       end
     end
+    module_function :option_name
 
     # Enable verbose trace logging. This option is currently enabled by
     # default but is likely to be disabled in a future release.
@@ -44,9 +46,22 @@ module Rack::Cache
     # 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.
+    # A custom cache key generator, which can be anything that responds to :call.
+    # By default, this is the Rack::Cache::Key class, but you can implement your
+    # own generator. A cache key generator gets passed a request and generates the
+    # appropriate cache key.
+    #
+    # In addition to setting the generator to an object, you can just pass a block
+    # instead, which will act as the cache key generator:
+    #
+    #   set :cache_key do |request|
+    #     request.fullpath.replace(/\//, '-')
+    #   end
+    option_accessor :cache_key
+
+    # A URI specifying the entity-store implementation 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
@@ -70,6 +85,16 @@ module Rack::Cache
     # Default: ['Authorization', 'Cookie']
     option_accessor :private_headers
 
+    # Specifies whether the client can force a cache reload by including a
+    # Cache-Control "no-cache" directive in the request. This is enabled by
+    # default for compliance with RFC 2616.
+    option_accessor :allow_reload
+
+    # Specifies whether the client can force a cache revalidate by including
+    # a Cache-Control "max-age=0" directive in the request. This is enabled by
+    # default for compliance with RFC 2616.
+    option_accessor :allow_revalidate
+
     # 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
@@ -88,8 +113,10 @@ module Rack::Cache
     # 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
+    def set(option, value=self, &block)
+      if block_given?
+        write_option option, block
+      elsif value == self
         self.options = option.to_hash
       else
         write_option option, value
@@ -97,6 +124,21 @@ module Rack::Cache
     end
 
   private
+    def initialize_options(options={})
+      @default_options = {
+        'rack-cache.cache_key'        => Key,
+        'rack-cache.verbose'          => true,
+        'rack-cache.storage'          => Rack::Cache::Storage.instance,
+        'rack-cache.metastore'        => 'heap:/',
+        'rack-cache.entitystore'      => 'heap:/',
+        'rack-cache.default_ttl'      => 0,
+        'rack-cache.private_headers'  => ['Authorization', 'Cookie'],
+        'rack-cache.allow_reload'     => true,
+        'rack-cache.allow_revalidate' => true
+      }
+      self.options = options
+    end
+
     def read_option(key)
       options[option_name(key)]
     end
@@ -104,26 +146,5 @@ module Rack::Cache
     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,
-        'rack-cache.private_headers' => ['Authorization', 'Cookie']
-      }
-      self.options = options
-    end
   end
 end

data/lib/rack/cache/request.rb

@@ -1,19 +1,15 @@
 require 'rack/request'
-require 'rack/cache/headers'
-require 'rack/utils/environment_headers'
+require 'rack/cache/cachecontrol'
 
 module Rack::Cache
+
   # Provides access to the HTTP request. The +request+ and +original_request+
   # objects exposed by the Core caching engine are instances of this class.
   #
   # Request objects respond to a variety of convenience methods, including
   # everything defined by Rack::Request as well as the Headers and
   # RequestHeaders modules.
-
   class Request < Rack::Request
-    include Rack::Cache::Headers
-    include Rack::Cache::RequestHeaders
-
     # The HTTP request method. This is the standard implementation of this
     # method but is respecified here due to libraries that attempt to modify
     # the behavior to respect POST tunnel method specifiers. We always want
@@ -22,16 +18,16 @@ module Rack::Cache
       @env['REQUEST_METHOD']
     end
 
-    # Determine if the request's method matches any of the values
-    # provided:
-    #   if request.request_method?('GET', 'POST')
-    #     ...
-    #   end
-    def request_method?(*methods)
-      method = request_method
-      methods.any? { |test| test.to_s.upcase == method }
+    # A CacheControl instance based on the request's Cache-Control header.
+    def cache_control
+      @cache_control ||= CacheControl.new(env['HTTP_CACHE_CONTROL'])
     end
 
-    alias_method :method?, :request_method?
+    # True when the Cache-Control/no-cache directive is present or the
+    # Pragma header is set to no-cache.
+    def no_cache?
+      cache_control['no-cache'] ||
+        env['HTTP_PRAGMA'] == 'no-cache'
+    end
   end
 end

data/lib/rack/cache/response.rb

@@ -1,7 +1,11 @@
+require 'time'
 require 'set'
-require 'rack/cache/headers'
+require 'rack/response'
+require 'rack/utils'
+require 'rack/cache/cachecontrol'
 
 module Rack::Cache
+
   # Provides access to the response generated by the downstream application. The
   # +response+, +original_response+, and +entry+ objects exposed by the Core
   # caching engine are instances of this class.
@@ -14,21 +18,14 @@ module Rack::Cache
   # not perform many of the same initialization and finalization tasks. For
   # example, the body is not slurped during initialization and there are no
   # facilities for generating response output.
-
   class Response
     include Rack::Response::Helpers
-    include Rack::Cache::Headers
-    include Rack::Cache::ResponseHeaders
 
-    # The response's status code (integer).
-    attr_accessor :status
+    # Rack response tuple accessors.
+    attr_accessor :status, :headers, :body
 
-    # The response body. See the Rack spec for information on the behavior
-    # required by this object.
-    attr_accessor :body
-
-    # The response headers.
-    attr_reader :headers
+    # The time when the Response object was instantiated.
+    attr_reader :now
 
     # Create a Response instance given the response status code, header hash,
     # and body.
@@ -37,7 +34,7 @@ module Rack::Cache
       @headers = Rack::Utils::HeaderHash.new(headers)
       @body = body
       @now = Time.now
-      @headers['Date'] ||= now.httpdate
+      @headers['Date'] ||= @now.httpdate
     end
 
     def initialize_copy(other)
@@ -45,32 +42,226 @@ module Rack::Cache
       @headers = other.headers.dup
     end
 
-    # Return the value of the named response header.
-    def [](header_name)
-      headers[header_name]
+    # Return the status, headers, and body in a three-tuple.
+    def to_a
+      [status, headers.to_hash, body]
     end
 
-    # Set a response header value.
-    def []=(header_name, header_value)
-      headers[header_name] = header_value
+    # 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
+
+    # 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 ||= CacheControl.new(headers['Cache-Control'])
     end
 
-    # Called immediately after an object is loaded from the cache.
-    def activate!
-      headers['Age'] = age.to_i.to_s
+    # 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=(value)
+      if value.respond_to? :to_hash
+        cache_control.clear
+        cache_control.merge!(value)
+        value = cache_control.to_s
+      end
+
+      if value.nil? || value.empty?
+        headers.delete('Cache-Control')
+      else
+        headers['Cache-Control'] = value
+      end
     end
 
-    # Return the status, headers, and body in a three-tuple.
-    def to_a
-      [status, headers.to_hash, body]
+    # 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
 
-    # Freezes
-    def freeze
-      @headers.freeze
-      super
+    # Determine if the response is worth caching under any circumstance. Responses
+    # marked "private" with an explicit Cache-Control directive are considered
+    # uncacheable
+    #
+    # Responses with neither a freshness lifetime (Expires, max-age) nor cache
+    # validator (Last-Modified, ETag) are considered uncacheable.
+    def cacheable?
+      return false unless CACHEABLE_RESPONSE_CODES.include?(status)
+      return false if cache_control.no_store? || cache_control.private?
+      validateable? || fresh?
     end
 
-  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?
+      headers.key?('Last-Modified') || headers.key?('ETag')
+    end
+
+    # Mark the response "private", making it ineligible for serving other
+    # clients.
+    def private=(value)
+      value = value ? true : nil
+      self.cache_control = cache_control.
+        merge('public' => !value, 'private' => value)
+    end
+
+    # Indicates that the cache must not serve a stale response in any
+    # circumstance without first revalidating with the origin. When present,
+    # the TTL of the response should not be overriden to be greater than the
+    # value provided by the origin.
+    def must_revalidate?
+      cache_control.must_revalidate || cache_control.proxy_revalidate
+    end
+
+    # Mark the response stale by setting the Age header to be equal to the
+    # maximum age of the response.
+    def expire!
+      headers['Age'] = max_age.to_s if fresh?
+    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
+      (headers['Age'] ||  [(now - date).to_i, 0].max).to_i
+    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 s-maxage directive, then a max-age directive, and then fall
+    # back on an expires header; return nil when no maximum age can be
+    # established.
+    def max_age
+      cache_control.shared_max_age ||
+        cache_control.max_age ||
+        (expires && (expires - date))
+    end
+
+    # The value of the Expires header as a Time object.
+    def expires
+      headers['Expires'] && Time.httpdate(headers['Expires'])
+    end
 
+    # The number of seconds after which the response should no longer
+    # be considered fresh. Sets the Cache-Control max-age directive.
+    def max_age=(value)
+      self.cache_control = cache_control.merge('max-age' => value.to_s)
+    end
+
+    # Like #max_age= but sets the s-maxage directive, which applies only
+    # to shared caches.
+    def shared_max_age=(value)
+      self.cache_control = cache_control.merge('s-maxage' => value.to_s)
+    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 for shared caches to the specified number
+    # of seconds. This adjusts the Cache-Control/s-maxage directive.
+    def ttl=(seconds)
+      self.shared_max_age = age + seconds
+    end
+
+    # Set the response's time-to-live for private/client caches. This adjusts
+    # the Cache-Control/max-age directive.
+    def client_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
+
+    # The literal value of ETag HTTP header or nil if no ETag is specified.
+    def etag
+      headers['ETag']
+    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 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
+
+  end
 end