rtomayko-rack-cache 0.3.0 → 0.3.9

data/lib/rack/cache/context.rb

@@ -1,40 +1,47 @@
-require 'rack/cache/config'
 require 'rack/cache/options'
-require 'rack/cache/core'
 require 'rack/cache/request'
 require 'rack/cache/response'
 require 'rack/cache/storage'
 
 module Rack::Cache
   # Implements Rack's middleware interface and provides the context for all
-  # cache logic. This class includes the Options, Config, and Core modules
-  # to provide much of its core functionality.
-
+  # cache logic, including the core logic engine.
   class Context
     include Rack::Cache::Options
-    include Rack::Cache::Config
-    include Rack::Cache::Core
+
+    # Array of trace Symbols
+    attr_reader :trace
 
     # The Rack application object immediately downstream.
     attr_reader :backend
 
     def initialize(backend, options={}, &block)
-      @errors = nil
-      @env = nil
       @backend = backend
+      @trace = []
       initialize_options options
-      initialize_core
-      initialize_config(&block)
+      instance_eval(&block) if block_given?
+
+      @private_header_keys =
+        private_headers.map { |name| "HTTP_#{name.upcase.tr('-', '_')}" }
     end
 
-    # The call! method is invoked on the duplicate context instance.
-    # process_request is defined in Core.
-    alias_method :call!, :process_request
-    protected :call!
+    # The configured MetaStore instance. Changing the rack-cache.metastore
+    # value effects the result of this method immediately.
+    def metastore
+      uri = options['rack-cache.metastore']
+      storage.resolve_metastore_uri(uri)
+    end
+
+    # The configured EntityStore instance. Changing the rack-cache.entitystore
+    # value effects the result of this method immediately.
+    def entitystore
+      uri = options['rack-cache.entitystore']
+      storage.resolve_entitystore_uri(uri)
+    end
 
-    # The Rack call interface. The receiver acts as a prototype and runs each
-    # request in a duplicate object, unless the +rack.run_once+ variable is set
-    # in the environment.
+    # The Rack call interface. The receiver acts as a prototype and runs
+    # each request in a dup object unless the +rack.run_once+ variable is
+    # set in the environment.
     def call(env)
       if env['rack.run_once']
         call! env
@@ -43,53 +50,183 @@ module Rack::Cache
       end
     end
 
-  public
-    # IO-like object that receives log, warning, and error messages;
-    # defaults to the rack.errors environment variable.
-    def errors
-      @errors || (@env && (@errors = @env['rack.errors'])) || STDERR
+    # The real Rack call interface. The caching logic is performed within
+    # the context of the receiver.
+    def call!(env)
+      @trace = []
+      @env = @default_options.merge(env)
+      @request = Request.new(@env.dup.freeze)
+
+      response =
+        if @request.get? || @request.head?
+          if !@env['HTTP_EXPECT']
+            lookup
+          else
+            pass
+          end
+        else
+          invalidate
+        end
+
+      # log trace and set X-Rack-Cache tracing header
+      trace = @trace.join(', ')
+      response.headers['X-Rack-Cache'] = trace
+
+      # write log message to rack.errors
+      if verbose?
+        message = "cache: [%s %s] %s\n" %
+          [@request.request_method, @request.fullpath, trace]
+        @env['rack.errors'].write(message)
+      end
+
+      # tidy up response a bit
+      response.not_modified! if not_modified?(response)
+      response.body = [] if @request.head?
+      response.to_a
     end
 
-    # Set the output stream for log messages, warnings, and errors.
-    def errors=(ioish)
-      fail "stream must respond to :write" if ! ioish.respond_to?(:write)
-      @errors = ioish
+  private
+
+    # Record that an event took place.
+    def record(event)
+      @trace << event
     end
 
-    # The configured MetaStore instance. Changing the rack-cache.metastore
-    # environment variable effects the result of this method immediately.
-    def metastore
-      uri = options['rack-cache.metastore']
-      storage.resolve_metastore_uri(uri)
+    # Does the request include authorization or other sensitive information
+    # that should cause the response to be considered private by default?
+    # Private responses are not stored in the cache.
+    def private_request?
+      @private_header_keys.any? { |key| @env.key?(key) }
     end
 
-    # The configured EntityStore instance. Changing the rack-cache.entitystore
-    # environment variable effects the result of this method immediately.
-    def entitystore
-      uri = options['rack-cache.entitystore']
-      storage.resolve_entitystore_uri(uri)
+    # Determine if the #response validators (ETag, Last-Modified) matches
+    # a conditional value specified in #request.
+    def not_modified?(response)
+      response.etag_matches?(@request.env['HTTP_IF_NONE_MATCH']) ||
+        response.last_modified_at?(@request.env['HTTP_IF_MODIFIED_SINCE'])
     end
 
-  protected
-    # Write a log message to the errors stream. +level+ is a symbol
-    # such as :error, :warn, :info, or :trace.
-    def log(level, message=nil, *params)
-      errors.write("[cache] #{level}: #{message}\n" % params)
-      errors.flush
+    # Whether the cache entry is "fresh enough" to satisfy the request.
+    def fresh_enough?(entry)
+      if entry.fresh?
+        if max_age = @request.cache_control.max_age
+          max_age > 0 && max_age >= entry.age
+        else
+          true
+        end
+      end
     end
 
-    def info(*message, &bk)
-      log :info, *message, &bk
+    # Delegate the request to the backend and create the response.
+    def forward
+      Response.new(*backend.call(@env))
     end
 
-    def warn(*message, &bk)
-      log :warn, *message, &bk
+    # The request is sent to the backend, and the backend's response is sent
+    # to the client, but is not entered into the cache.
+    def pass
+      record :pass
+      forward
     end
 
-    def trace(*message, &bk)
-      return unless verbose?
-      log :trace, *message, &bk
+    # Invalidate POST, PUT, DELETE and all methods not understood by this cache
+    # See RFC2616 13.10
+    def invalidate
+      record :invalidate
+      metastore.invalidate(@request, entitystore)
+      pass
     end
-  end
 
+    # Try to serve the response from cache. When a matching cache entry is
+    # found and is fresh, use it as the response without forwarding any
+    # request to the backend. When a matching cache entry is found but is
+    # stale, attempt to #validate the entry with the backend using conditional
+    # GET. When no matching cache entry is found, trigger #miss processing.
+    def lookup
+      if @request.no_cache?
+        record :reload
+        fetch
+      elsif entry = metastore.lookup(@request, entitystore)
+        if fresh_enough?(entry)
+          record :fresh
+          entry.headers['Age'] = entry.age.to_s
+          entry
+        else
+          record :stale
+          validate(entry)
+        end
+      else
+        record :miss
+        fetch
+      end
+    end
+
+    # Validate that the cache entry is fresh. The original request is used
+    # as a template for a conditional GET request with the backend.
+    def validate(entry)
+      # send no head requests because we want content
+      @env['REQUEST_METHOD'] = 'GET'
+
+      # add our cached validators to the environment
+      @env['HTTP_IF_MODIFIED_SINCE'] = entry.last_modified
+      @env['HTTP_IF_NONE_MATCH'] = entry.etag
+
+      backend_response = forward
+
+      response =
+        if backend_response.status == 304
+          record :valid
+          entry = entry.dup
+          entry.headers.delete('Date')
+          %w[Date Expires Cache-Control ETag Last-Modified].each do |name|
+            next unless value = backend_response.headers[name]
+            entry.headers[name] = value
+          end
+          entry
+        else
+          record :invalid
+          backend_response
+        end
+
+      store(response) if response.cacheable?
+
+      response
+    end
+
+    # The cache missed or a reload is required. Forward the request to the
+    # backend and determine whether the response should be stored.
+    def fetch
+      # send no head requests because we want content
+      @env['REQUEST_METHOD'] = 'GET'
+
+      # avoid that the backend sends no content
+      @env.delete('HTTP_IF_MODIFIED_SINCE')
+      @env.delete('HTTP_IF_NONE_MATCH')
+
+      response = forward
+
+      # Mark the response as explicitly private if any of the private
+      # request headers are present and the response was not explicitly
+      # declared public.
+      if private_request? && !response.cache_control.public?
+        response.private = true
+      elsif default_ttl > 0 && response.ttl.nil? && !response.cache_control.must_revalidate?
+        # assign a default TTL for the cache entry if none was specified in
+        # the response; the must-revalidate cache control directive disables
+        # default ttl assigment.
+        response.ttl = default_ttl
+      end
+
+      store(response) if response.cacheable?
+
+      response
+    end
+
+    # Write the response to the cache.
+    def store(response)
+      record :store
+      metastore.store(@request, response, entitystore)
+      response.headers['Age'] = response.age.to_s
+    end
+  end
 end

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