rack-cache 0.3.0 → 0.4

data/test/spec_setup.rb

@@ -1,5 +1,6 @@
 require 'pp'
 require 'tmpdir'
+require 'stringio'
 
 [ STDOUT, STDERR ].each { |io| io.sync = true }
 
@@ -27,6 +28,7 @@ rescue LoadError => boom
   $memcached = false
   false
 rescue => boom
+  STDERR.puts "memcached not working. related tests will be skipped."
   $memcached = false
   false
 end
@@ -192,4 +194,9 @@ class Object
   def class_def name, &blk
     class_eval { define_method name, &blk }
   end
+
+  # True when the Object is neither false or nil.
+  def truthy?
+    !!self
+  end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: rack-cache
 version: !ruby/object:Gem::Version 
-  version: 0.3.0
+  version: "0.4"
 platform: ruby
 authors: 
 - Ryan Tomayko
@@ -9,7 +9,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2008-12-28 00:00:00 -08:00
+date: 2009-03-16 00:00:00 -07:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -40,7 +40,6 @@ files:
 - Rakefile
 - TODO
 - doc/configuration.markdown
-- doc/events.dot
 - doc/faq.markdown
 - doc/index.markdown
 - doc/layout.html.erb
@@ -48,33 +47,28 @@ files:
 - 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
@@ -111,14 +105,12 @@ specification_version: 2
 summary: HTTP Caching for Rack
 test_files: 
 - 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/request_test.rb
 - test/response_test.rb
 - test/storage_test.rb

data/doc/events.dot

@@ -1,27 +0,0 @@
-digraph cache_logic {
-  nodesep=1.25;
-  center=true;
-
-  node[fontname="Lucida Sans Unicode",labelloc=c,margin=0.10,0.03]
-  edge[fontname="Lucida Sans Unicode",fontcolor="#444444",labeldistance=20];
-
-  receive -> pass[label="uncacheable request",color=grey];
-  receive -> lookup[label="cacheable request"];
-
-  pass -> deliver[label="",color=grey];
-
-  lookup -> hit[label="fresh"];
-  lookup -> fetch[label="stale (needs validation)"];
-  lookup -> miss[label="uncached"];
-
-  hit -> deliver[label="sizzling"];
-  hit -> pass[label="bailing...",color=grey];
-
-  miss -> fetch[label=""];
-  miss -> pass[color=grey];
-
-  fetch -> store[label="cacheable"];
-  fetch -> deliver[label="not cacheable",color=grey];
-
-  store -> deliver[label="KTHX"];
-}

data/lib/rack/cache/config.rb

@@ -1,65 +0,0 @@
-require 'set'
-
-module Rack::Cache
-  # Provides cache configuration methods. This module is included in the cache
-  # context object.
-
-  module Config
-    # Evaluate a block of configuration code within the scope of receiver.
-    def configure(&block)
-      instance_eval(&block) if block_given?
-    end
-
-    # Import the configuration file specified. This has the same basic semantics
-    # as Ruby's built-in +require+ statement but always evaluates the source
-    # file within the scope of the receiver. The file may exist anywhere on the
-    # $LOAD_PATH.
-    def import(file)
-      return false if imported_features.include?(file)
-      path = add_file_extension(file, 'rb')
-      if path = locate_file_on_load_path(path)
-        source = File.read(path)
-        imported_features.add(file)
-        instance_eval source, path, 1
-        true
-      else
-        raise LoadError, 'no such file to load -- %s' % [file]
-      end
-    end
-
-  private
-    # Load the default configuration and evaluate the block provided within
-    # the scope of the receiver.
-    def initialize_config(&block)
-      import 'rack/cache/config/default'
-      configure(&block)
-    end
-
-    # Set of files that have been imported.
-    def imported_features
-      @imported_features ||= Set.new
-    end
-
-    # Attempt to expand +file+ to a full path by possibly adding an .rb
-    # extension and traversing the $LOAD_PATH looking for matches.
-    def locate_file_on_load_path(file)
-      if file[0,1] == '/'
-        file if File.exist?(file)
-      else
-        $LOAD_PATH.
-          map { |base| File.join(base, file) }.
-          detect { |p| File.exist?(p) }
-      end
-    end
-
-    # Add an extension to the filename provided if the file doesn't
-    # already have extension.
-    def add_file_extension(file, extension='rb')
-      if file =~ /\.\w+$/
-        file
-      else
-        "#{file}.#{extension}"
-      end
-    end
-  end
-end

data/lib/rack/cache/config/busters.rb

@@ -1,16 +0,0 @@
-# Adds a very long max-age response header when the requested url
-# looks like it includes a cache busting timestamp. Cache busting
-# URLs look like this:
-#   http://HOST/PATH?DIGITS
-#
-# DIGITS is typically the number of seconds since some epoch but
-# this can theoretically be any set of digits. Example:
-#   http://example.com/css/foo.css?7894387283
-#
-on :fetch do
-  next if response.freshness_information?
-  if request.url =~ /\?\d+$/
-    trace 'adding huge max-age to response for cache busting URL'
-    response.ttl = 100000000000000
-  end
-end

data/lib/rack/cache/config/default.rb

@@ -1,133 +0,0 @@
-# Called at the beginning of request processing, after the complete
-# request has been fully received. Its purpose is to decide whether or
-# not to serve the request and how to do it.
-#
-# The request should not be modified.
-#
-# Possible transitions from receive:
-#
-#   * pass! - pass the request to the backend the response upstream,
-#     bypassing all caching features.
-#
-#   * lookup! - attempt to locate the entry in the cache. Control will
-#     pass to the +hit+, +miss+, or +fetch+ event based on the result of
-#     the cache lookup.
-#
-#   * error! - return the error code specified, abandoning the request.
-#
-on :receive do
-  pass! unless request.method? 'GET', 'HEAD'
-  pass! if request.header? 'Expect'
-  lookup!
-end
-
-# Called upon entering pass mode. The request is sent to the backend,
-# and the backend's response is sent to the client, but is not entered
-# into the cache. The event is triggered immediately after the response
-# is received from the backend but before the it has been sent upstream.
-#
-# Possible transitions from pass:
-#
-#   * finish! - deliver the response upstream.
-#
-#   * error! - return the error code specified, abandoning the request.
-#
-on :pass do
-  finish!
-end
-
-# Called after a cache lookup when no matching entry is found in the
-# cache. Its purpose is to decide whether or not to attempt to retrieve
-# the response from the backend and in what manner.
-#
-# Possible transitions from miss:
-#
-#   * fetch! - retrieve the requested document from the backend with
-#     caching features enabled.
-#
-#   * pass! - pass the request to the backend and the response upstream,
-#     bypassing all caching features.
-#
-#   * error! - return the error code specified and abandon request.
-#
-# The default configuration transfers control to the fetch event.
-on :miss do
-  fetch!
-end
-
-# Called after a cache lookup when the requested document is found in
-# the cache and is fresh.
-#
-# Possible transitions from hit:
-#
-#   * deliver! - transfer control to the deliver event, sending the cached
-#     response upstream.
-#
-#   * pass! - abandon the cache entry and transfer to pass mode. The
-#     original request is sent to the backend and the response sent
-#     upstream, bypassing all caching features.
-#
-#   * error! - return the error code specified and abandon request.
-#
-on :hit do
-  deliver!
-end
-
-# Called after a document is successfully retrieved from the backend
-# application or after a cache entry is validated with the backend.
-# During validation, the original request is used as a template for a
-# conditional GET request with the backend. The +original_response+
-# object contains the response as received from the backend and +entry+
-# is set to the cached response that triggered validation.
-#
-# Possible transitions from fetch:
-#
-#   * store! - store the fetched response in the cache or, when
-#     validating, update the cached response with validated results.
-#
-#   * deliver! - deliver the response upstream without entering it
-#     into the cache.
-#
-#   * error! return the error code specified and abandon request.
-#
-on :fetch do
-  store! if response.cacheable?
-  deliver!
-end
-
-# Called immediately before an entry is written to the underlying
-# cache. The +entry+ object may be modified.
-#
-# Possible transitions from store:
-#
-#   * persist! - commit the object to cache and transfer control to
-#     the deliver event.
-#
-#   * deliver! - transfer control to the deliver event without committing
-#     the object to cache.
-#
-#   * error! - return the error code specified and abandon request.
-#
-on :store do
-  trace 'store backend response in cache (ttl: %ds)', entry.ttl
-  persist!
-end
-
-# Called immediately before +response+ is delivered upstream. +response+
-# may be modified at this point but the changes will not effect the
-# cache since the entry has already been persisted.
-#
-#   * finish! - complete processing and send the response upstream
-#
-#   * error! - return the error code specified and abandon request.
-#
-on :deliver do
-  finish!
-end
-
-# Called when an error! transition is triggered. The +response+ has the
-# error code, headers, and body that will be delivered to upstream and
-# may be modified if needed.
-on :error do
-  finish!
-end

data/lib/rack/cache/config/no-cache.rb

@@ -1,13 +0,0 @@
-# The default configuration ignores the `Cache-Control: no-cache` directive on
-# requests. Per RFC 2616, the presence of the no-cache directive should cause
-# intermediaries to process requests as if no cached version were available.
-# However, this directive is most often targetted at shared proxy caches, not
-# gateway caches, and so we've chosen to break with the spec in our default
-# configuration.
-#
-# Import 'rack/cache/config/no-cache' to enable standards-based
-# processing.
-
-on :receive do
-  pass! if request.header['Cache-Control'] =~ /no-cache/
-end

data/lib/rack/cache/core.rb

@@ -1,299 +0,0 @@
-require 'rack/cache/request'
-require 'rack/cache/response'
-
-module Rack::Cache
-  # Raised when an attempt is made to transition to an event that can
-  # not be transitioned from the current event.
-  class IllegalTransition < Exception
-  end
-
-  # The core logic engine and state machine. When a request is received,
-  # the engine begins transitioning from state to state based on the
-  # advice given by events. Each transition performs some piece of core
-  # logic, calls out to an event handler, and then kicks off the next
-  # transition.
-  #
-  # Five objects of interest are made available during execution:
-  #
-  # * +original_request+ - The request as originally received. This object
-  #   is never modified.
-  # * +request+ - The request that may eventually be sent downstream in
-  #   case of pass or miss. This object defaults to the +original_request+
-  #   but may be modified or replaced entirely.
-  # * +original_response+ - The response exactly as specified by the
-  #   downstream application; +nil+ on cache hit.
-  # * +entry+ - The response loaded from cache or stored to cache. This
-  #   object becomes +response+ if the cached response is valid.
-  # * +response+ - The response that will be delivered upstream after
-  #   processing is complete. This object may be modified as necessary.
-  #
-  # These objects can be accessed and modified from within event handlers
-  # to perform various types of request/response manipulation.
-  module Core
-
-    # The request exactly as received. The object is an instance of the
-    # Rack::Cache::Request class, which includes many utility methods for
-    # inspecting the state of the request.
-    #
-    # This object cannot be modified. If the request requires modification
-    # before being delivered to the downstream application, use the
-    # #request object.
-    attr_reader :original_request
-
-    # The response exactly as received from the downstream application. The
-    # object is an instance of the Rack::Cache::Response class, which includes
-    # utility methods for inspecting the state of the response.
-    #
-    # The original response should not be modified. Use the #response object to
-    # access the response to be sent back upstream.
-    attr_reader :original_response
-
-    # A response object retrieved from cache, or the response that is to be
-    # saved to cache, or nil if no cached response was found. The object is
-    # an instance of the Rack::Cache::Response class.
-    attr_reader :entry
-
-    # The request that will be made downstream on the application. This
-    # defaults to the request exactly as received (#original_request). The
-    # object is an instance of the Rack::Cache::Request class, which includes
-    # utility methods for inspecting and modifying various aspects of the
-    # HTTP request.
-    attr_reader :request
-
-    # The response that will be sent upstream. Defaults to the response
-    # received from the downstream application (#original_response) but
-    # is set to the cached #entry when valid. In any case, the object
-    # is an instance of the Rack::Cache::Response class, which includes a
-    # variety of utility methods for inspecting and modifying the HTTP
-    # response.
-    attr_reader :response
-
-    # Has the given event been performed at any time during the
-    # request life-cycle? Useful for testing.
-    def performed?(event)
-      @triggered.include?(event)
-    end
-
-    # Event handlers.
-    attr_reader :events
-    private :events
-
-  public
-    # Attach custom logic to one or more events.
-    def on(*events, &block)
-      events.each { |event| @events[event].unshift(block) }
-      nil
-    end
-
-  private
-    # Transitioning statements
-
-    def pass!      ; throw(:transition, [:pass])    ; end
-    def lookup!    ; throw(:transition, [:lookup])  ; end
-    def store!     ; throw(:transition, [:store])   ; end
-    def fetch!     ; throw(:transition, [:fetch])   ; end
-    def persist!   ; throw(:transition, [:persist]) ; end
-    def deliver!   ; throw(:transition, [:deliver]) ; end
-    def finish!    ; throw(:transition, [:finish])  ; end
-
-    def error!(code=500, headers={}, body=nil)
-      throw(:transition, [:error, code, headers, body])
-    end
-
-  private
-    # 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?
-      request.header?(*private_headers)
-    end
-
-    # Determine if the #response validators (ETag, Last-Modified) matches
-    # a conditional value specified in #original_request.
-    def not_modified?
-      response.etag_matches?(original_request.if_none_match) ||
-        response.last_modified_at?(original_request.if_modified_since)
-    end
-
-    # Delegate the request to the backend and create the response.
-    def fetch_from_backend
-      status, headers, body = backend.call(request.env)
-      response = Response.new(status, headers, body)
-      @response = response.dup
-      @original_response = response.freeze
-    end
-
-  private
-    def perform_receive
-      @original_request = Request.new(@env.dup.freeze)
-      @env['REQUEST_METHOD'] = 'GET' if @original_request.head?
-      @request = Request.new(@env)
-      info "%s %s", @original_request.request_method, @original_request.fullpath
-      transition(from=:receive, to=[:pass, :lookup, :error])
-    end
-
-    def perform_pass
-      trace 'passing'
-      request.env['REQUEST_METHOD'] = @original_request.request_method
-      fetch_from_backend
-      transition(from=:pass, to=[:pass, :finish, :error]) do |event|
-        if event == :pass
-          :finish
-        else
-          event
-        end
-      end
-    end
-
-    def perform_error(code=500, headers={}, body=nil)
-      body, headers = headers, {} unless headers.is_a?(Hash)
-      headers = {} if headers.nil?
-      body = [] if body.nil? || body == ''
-      @response = Rack::Cache::Response.new(code, headers, body)
-      transition(from=:error, to=[:finish])
-    end
-
-    def perform_lookup
-      if @entry = metastore.lookup(original_request, entitystore)
-        if @entry.fresh?
-          trace 'cache hit (ttl: %ds)', @entry.ttl
-          transition(from=:hit, to=[:deliver, :pass, :error]) do |event|
-            @response = @entry if event == :deliver
-            event
-          end
-        else
-          trace 'cache stale (ttl: %ds), validating...', @entry.ttl
-          perform_validate
-        end
-      else
-        trace 'cache miss'
-        transition(from=:miss, to=[:fetch, :pass, :error])
-      end
-    end
-
-    def perform_validate
-      # add our cached validators to the backend request
-      request.headers['If-Modified-Since'] = entry.last_modified
-      request.headers['If-None-Match'] = entry.etag
-      fetch_from_backend
-
-      if original_response.status == 304
-        trace "cache entry valid"
-        @response = entry.dup
-        @response.headers.delete('Age')
-        @response.headers.delete('Date')
-        @response.headers['X-Origin-Status'] = '304'
-        %w[Date Expires Cache-Control Etag Last-Modified].each do |name|
-          next unless value = original_response.headers[name]
-          @response[name] = value
-        end
-        @response.activate!
-      else
-        trace "cache entry invalid"
-        @entry = nil
-      end
-      transition(from=:fetch, to=[:store, :deliver, :error])
-    end
-
-    def perform_fetch
-      trace "fetching response from backend"
-      request.env.delete('HTTP_IF_MODIFIED_SINCE')
-      request.env.delete('HTTP_IF_NONE_MATCH')
-      fetch_from_backend
-
-      # 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.public?
-        @response.private = true
-      else
-        # 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.
-        if default_ttl > 0 && @response.ttl.nil? && !@response.must_revalidate?
-          @response.ttl = default_ttl
-        end
-      end
-      transition(from=:fetch, to=[:store, :deliver, :error])
-    end
-
-    def perform_store
-      @entry = @response
-      transition(from=:store, to=[:persist, :deliver, :error]) do |event|
-        if event == :persist
-          if @response.private?
-            warn 'forced to store response marked as private.'
-          else
-            trace "storing response in cache"
-          end
-          metastore.store(original_request, @entry, entitystore)
-          @response = @entry
-          :deliver
-        else
-          event
-        end
-      end
-    end
-
-    def perform_deliver
-      trace "delivering response ..."
-      response.not_modified! if not_modified?
-      response.body = [] if @original_request.head?
-      transition(from=:deliver, to=[:finish, :error])
-    end
-
-    def perform_finish
-      response.headers.delete 'X-Status'
-      response.to_a
-    end
-
-  private
-    # Transition from the currently processing event to another event
-    # after triggering event handlers.
-    def transition(from, to)
-      ev, *args = trigger(from)
-      raise IllegalTransition, "No transition to :#{ev}" unless to.include?(ev)
-      ev = yield ev if block_given?
-      send "perform_#{ev}", *args
-    end
-
-    # Trigger processing of the event specified and return an array containing
-    # the name of the next transition and any arguments provided to the
-    # transitioning statement.
-    def trigger(event)
-      if @events.include? event
-        @triggered << event
-        catch(:transition) do
-          @events[event].each { |block| instance_eval(&block) }
-          nil
-        end
-      else
-        raise NameError, "No such event: #{event}"
-      end
-    end
-
-  private
-    # Setup the core prototype. The object's state after execution
-    # of this method will be duped and used for individual request.
-    def initialize_core
-      @triggered = []
-      @events = Hash.new { |h,k| h[k.to_sym] = [] }
-
-      # initialize some instance variables; we won't use them until we dup to
-      # process a request.
-      @request = nil
-      @response = nil
-      @original_request = nil
-      @original_response = nil
-      @entry = nil
-    end
-
-    # Process a request. This method is compatible with Rack's #call
-    # interface.
-    def process_request(env)
-      @triggered = []
-      @env = @default_options.merge(env)
-      perform_receive
-    end
-  end
-end