rtomayko-rack-cache 0.3.0 → 0.3.9

data/lib/rack/cache/options.rb

@@ -1,17 +1,17 @@
-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.
-
+  # The #set method can be used to configure a option values. When #set is
+  # called outside of request scope, the value applies to all requests; when
+  # called from within a request context, applies only to the request being
+  # processed.
   module Options
     class << self
       private
@@ -44,6 +44,19 @@ module Rack::Cache
     # recommended.
     option_accessor :metastore
 
+    # 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 implement that should be used to store
     # response bodies. See the metastore option for information on supported URI
     # schemes.
@@ -88,8 +101,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
@@ -116,11 +131,12 @@ module Rack::Cache
   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.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']
       }
       self.options = options

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

data/lib/rack/cache/storage.rb

@@ -3,11 +3,11 @@ require 'rack/cache/metastore'
 require 'rack/cache/entitystore'
 
 module Rack::Cache
+
   # Maintains a collection of MetaStore and EntityStore instances keyed by
   # URI. A single instance of this class can be used across a single process
   # to ensure that only a single instance of a backing store is created per
   # unique storage URI.
-
   class Storage
     def initialize
       @metastores = {}
@@ -22,7 +22,6 @@ module Rack::Cache
       @entitystores[uri.to_s] ||= create_store(EntityStore, uri)
     end
 
-    # Clear store instances.
     def clear
       @metastores.clear
       @entitystores.clear

data/rack-cache.gemspec

@@ -3,8 +3,8 @@ Gem::Specification.new do |s|
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
 
   s.name = 'rack-cache'
-  s.version = '0.3.0'
-  s.date = '2008-12-28'
+  s.version = '0.3.9'
+  s.date = '2009-03-07'
 
   s.description = "HTTP Caching for Rack"
   s.summary     = "HTTP Caching for Rack"
@@ -28,33 +28,28 @@ Gem::Specification.new do |s|
     doc/rack-cache.css
     doc/server.ru
     doc/storage.markdown
+    example/sinatra/app.rb
+    example/sinatra/views/index.erb
     lib/rack/cache.rb
-    lib/rack/cache/config.rb
-    lib/rack/cache/config/busters.rb
-    lib/rack/cache/config/default.rb
-    lib/rack/cache/config/no-cache.rb
+    lib/rack/cache/cachecontrol.rb
     lib/rack/cache/context.rb
-    lib/rack/cache/core.rb
     lib/rack/cache/entitystore.rb
-    lib/rack/cache/headers.rb
+    lib/rack/cache/key.rb
     lib/rack/cache/metastore.rb
     lib/rack/cache/options.rb
     lib/rack/cache/request.rb
     lib/rack/cache/response.rb
     lib/rack/cache/storage.rb
-    lib/rack/utils/environment_headers.rb
     rack-cache.gemspec
     test/cache_test.rb
-    test/config_test.rb
+    test/cachecontrol_test.rb
     test/context_test.rb
-    test/core_test.rb
     test/entitystore_test.rb
-    test/environment_headers_test.rb
-    test/headers_test.rb
-    test/logging_test.rb
+    test/key_test.rb
     test/metastore_test.rb
     test/options_test.rb
     test/pony.jpg
+    test/request_test.rb
     test/response_test.rb
     test/spec_setup.rb
     test/storage_test.rb