rack-cache 0.2.0 → 0.3.0

data/lib/rack/cache/entitystore.rb

@@ -58,6 +58,12 @@ module Rack::Cache
         [key, size]
       end
 
+      # Remove the body corresponding to key; return nil.
+      def purge(key)
+        @hash.delete(key)
+        nil
+      end
+
       def self.resolve(uri)
         new
       end
@@ -89,16 +95,19 @@ module Rack::Cache
         nil
       end
 
-      # Open the entity body and return an IO object. The IO object's
-      # each method is overridden to read 8K chunks instead of lines.
-      def open(key)
-        io = File.open(body_path(key), 'rb')
-        def io.each
+      class Body < ::File #:nodoc:
+        def each
           while part = read(8192)
             yield part
           end
         end
-        io
+        alias_method :to_path, :path
+      end
+
+      # Open the entity body and return an IO object. The IO object's
+      # each method is overridden to read 8K chunks instead of lines.
+      def open(key)
+        Body.open(body_path(key), 'rb')
       rescue Errno::ENOENT
         nil
       end
@@ -121,6 +130,13 @@ module Rack::Cache
         [key, size]
       end
 
+      def purge(key)
+        File.unlink body_path(key)
+        nil
+      rescue Errno::ENOENT
+        nil
+      end
+
     protected
       def storage_path(stem)
         File.join root, stem
@@ -190,6 +206,13 @@ module Rack::Cache
         [key, size]
       end
 
+      def purge(key)
+        cache.delete(key)
+        nil
+      rescue Memcached::NotFound
+        nil
+      end
+
       extend Rack::Utils
 
       # Create MemCache store for the given URI. The URI must specify

data/lib/rack/cache/headers.rb

@@ -21,7 +21,7 @@ module Rack::Cache
     # header is present.
     def cache_control
       @cache_control ||=
-        (headers['Cache-Control'] || '').split(/\s*,\s*/).inject({}) {|hash,token|
+        headers['Cache-Control'].to_s.split(/\s*[,;]\s*/).inject({}) {|hash,token|
           name, value = token.split(/\s*=\s*/, 2)
           hash[name.downcase] = (value || true) unless name.empty?
           hash
@@ -79,9 +79,19 @@ module Rack::Cache
   module ResponseHeaders
     include Rack::Cache::Headers
 
-    # Set of HTTP response codes of messages that can be cached, per
-    # RFC 2616.
-    CACHEABLE_RESPONSE_CODES = Set.new([200, 203, 300, 301, 302, 404, 410])
+    # 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
@@ -97,16 +107,15 @@ module Rack::Cache
       !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.
+    # Determine if the response is worth caching under any circumstance. Responses
+    # marked "private" with an explicit Cache-Control directive are considered
+    # uncacheable
     #
-    # 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.
+    # 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 no_store?
+      return false if no_store? || private?
       validateable? || fresh?
     end
 
@@ -114,7 +123,8 @@ module Rack::Cache
     # 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?
+      header?('Expires') ||
+        !!(cache_control['s-maxage'] || cache_control['max-age'])
     end
 
     # Determine if the response includes headers that can be used to validate
@@ -127,7 +137,7 @@ module Rack::Cache
     # 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?
+      cache_control['no-cache']
     end
 
     # Indicates that the response should not be stored under any circumstances.
@@ -135,16 +145,51 @@ module Rack::Cache
       cache_control['no-store']
     end
 
+    # True when the response has been explicitly marked "public".
+    def public?
+      cache_control['public']
+    end
+
+    # Mark the response "public", making it eligible for other clients. Note
+    # that responses are considered "public" by default unless the request
+    # includes private headers (Authorization, Cookie).
+    def public=(value)
+      value = value ? true : nil
+      self.cache_control = cache_control.
+        merge('public' => value, 'private' => !value)
+    end
+
+    # True when the response has been marked "private" explicitly.
+    def private?
+      cache_control['private']
+    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
+
     # 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
-      @date ||=
-        if date = headers['Date']
-          Time.httpdate(date)
-        else
-          headers['Date'] = now.httpdate unless headers.frozen?
-          now
-        end
+      if date = headers['Date']
+        Time.httpdate(date)
+      else
+        headers['Date'] = now.httpdate unless headers.frozen?
+        now
+      end
     end
 
     # The age of the response.
@@ -154,29 +199,36 @@ module Rack::Cache
 
     # 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.
+    # 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
-      if age = cache_control['max-age']
+      if age = (cache_control['s-maxage'] || 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.
+    # 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 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']
+      if max_age = (cache_control['s-maxage'] || cache_control['max-age'])
         date + max_age.to_i
       elsif time = headers['Expires']
         Time.httpdate(time)
@@ -191,9 +243,15 @@ module Rack::Cache
       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.
+    # 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
 
@@ -210,8 +268,38 @@ module Rack::Cache
       time_value && last_modified == time_value
     end
 
-    # The literal value of the Vary header, or nil when no Vary header is
-    # present.
+    # 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

data/lib/rack/cache/metastore.rb

@@ -21,18 +21,6 @@ module Rack::Cache
   # methods dumb and straight-forward to implement.
   class MetaStore
 
-    # Headers that should not be stored in cache (from RFC 2616).
-    HEADER_BLACKLIST = Set.new(%w[
-      Connection
-      Keep-Alive
-      Proxy-Authenticate
-      Proxy-Authorization
-      TE
-      Trailers
-      Transfer-Encoding
-      Upgrade
-    ])
-
     # 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.
@@ -44,18 +32,18 @@ module Rack::Cache
 
       # 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!
+      match = entries.detect{|req,res| requests_match?(res['Vary'], env, req)}
+      return nil if match.nil?
 
-        # Return the cached response
+      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
+      else
+        # TODO the metastore referenced an entity that doesn't exist in
+        # the entitystore. we definitely want to return nil but we should
+        # also purge the entry from the meta-store when this is detected.
       end
     end
 
@@ -67,25 +55,27 @@ module Rack::Cache
     def store(request, response, entity_store)
       key = request.fullpath
       stored_env = persist_request(request)
-      stored_response = persist_response(response)
 
       # write the response body to the entity store if this is the
       # original response.
-      if stored_response['X-Content-Digest'].nil?
+      response['X-Status'] = response.status.to_s
+      if response['X-Content-Digest'].nil?
         digest, size = entity_store.write(response.body)
-        stored_response['X-Content-Digest'] = digest
-        stored_response['Content-Length'] = size.to_s
+        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 = stored_response['Vary']
+      vary = response.vary
       entries =
         read(key).reject do |env,res|
-          (vary == res['Vary']) && requests_match?(vary, env, stored_env)
+          (vary == res['Vary']) &&
+            requests_match?(vary, env, stored_env)
         end
-      entries.unshift [stored_env, stored_response]
+      entries.unshift [stored_env, {}.update(response.headers)]
       write key, entries
     end
 
@@ -99,15 +89,6 @@ module Rack::Cache
       env
     end
 
-    # Extract the headers Hash from +response+ while making any
-    # necessary modifications in preparation for persistence. The Hash
-    # returned must be marshalable.
-    def persist_response(response)
-      headers = response.headers.reject { |k,v| HEADER_BLACKLIST.include?(k) }
-      headers['X-Status'] = response.status.to_s
-      headers
-    end
-
     # Determine whether the two environment hashes are non-varying based on
     # the vary response header value provided.
     def requests_match?(vary, env1, env2)
@@ -158,7 +139,9 @@ module Rack::Cache
       end
 
       def read(key)
-        @hash.fetch(key, [])
+        @hash.fetch(key, []).collect do |req,res|
+          [req.dup, res.dup]
+        end
       end
 
       def write(key, entries)

data/lib/rack/cache/options.rb

@@ -61,6 +61,15 @@ module Rack::Cache
     # Default: 0
     option_accessor :default_ttl
 
+    # Set of request headers that trigger "private" cache-control behavior
+    # on responses that don't explicitly state whether the response is
+    # public or private via a Cache-Control directive. Applications that use
+    # cookies for authorization may need to add the 'Cookie' header to this
+    # list.
+    #
+    # Default: ['Authorization', 'Cookie']
+    option_accessor :private_headers
+
     # 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
@@ -111,7 +120,8 @@ module Rack::Cache
         'rack-cache.storage'     => Rack::Cache::Storage.instance,
         'rack-cache.metastore'   => 'heap:/',
         'rack-cache.entitystore' => 'heap:/',
-        'rack-cache.default_ttl' => 0
+        'rack-cache.default_ttl' => 0,
+        'rack-cache.private_headers' => ['Authorization', 'Cookie']
       }
       self.options = options
     end

data/lib/rack/cache/response.rb

@@ -34,7 +34,7 @@ module Rack::Cache
     # and body.
     def initialize(status, headers, body)
       @status = status
-      @headers = headers
+      @headers = Rack::Utils::HeaderHash.new(headers)
       @body = body
       @now = Time.now
       @headers['Date'] ||= now.httpdate
@@ -62,7 +62,7 @@ module Rack::Cache
 
     # Return the status, headers, and body in a three-tuple.
     def to_a
-      [status, headers, body]
+      [status, headers.to_hash, body]
     end
 
     # Freezes