josh-rack-cache 0.5.1

data/lib/rack/cache/storage.rb

@@ -0,0 +1,62 @@
+require 'uri'
+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 = {}
+      @entitystores = {}
+    end
+
+    def resolve_metastore_uri(uri)
+      @metastores[uri.to_s] ||= create_store(MetaStore, uri)
+    end
+
+    def resolve_entitystore_uri(uri)
+      @entitystores[uri.to_s] ||= create_store(EntityStore, uri)
+    end
+
+    def clear
+      @metastores.clear
+      @entitystores.clear
+      nil
+    end
+
+  private
+    def create_store(type, uri)
+      if uri.respond_to?(:scheme) || uri.respond_to?(:to_str)
+        uri = URI.parse(uri) unless uri.respond_to?(:scheme)
+        if type.const_defined?(uri.scheme.upcase)
+          klass = type.const_get(uri.scheme.upcase)
+          klass.resolve(uri)
+        else
+          fail "Unknown storage provider: #{uri.to_s}"
+        end
+      else
+        # hack in support for passing a MemCache or Memcached object
+        # as the storage URI.
+        case
+        when defined?(::MemCache) && uri.kind_of?(::MemCache)
+          type.const_get(:MemCache).resolve(uri)
+        when defined?(::Memcached) && uri.respond_to?(:stats)
+          type.const_get(:MemCached).resolve(uri)
+        else
+          fail "Unknown storage provider: #{uri.to_s}"
+        end
+      end
+    end
+
+  public
+    @@singleton_instance = new
+    def self.instance
+      @@singleton_instance
+    end
+  end
+
+end

data/rack-cache.gemspec

@@ -0,0 +1,70 @@
+Gem::Specification.new do |s|
+  s.specification_version = 2 if s.respond_to? :specification_version=
+  s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
+
+  s.name = 'rack-cache'
+  s.version = '0.5.1'
+  s.date = '2009-06-06'
+
+  s.description = "HTTP Caching for Rack"
+  s.summary     = "HTTP Caching for Rack"
+
+  s.authors = ["Ryan Tomayko"]
+  s.email = "r@tomayko.com"
+
+  # = MANIFEST =
+  s.files = %w[
+    CHANGES
+    COPYING
+    README
+    Rakefile
+    TODO
+    doc/configuration.markdown
+    doc/faq.markdown
+    doc/index.markdown
+    doc/layout.html.erb
+    doc/license.markdown
+    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/appengine.rb
+    lib/rack/cache/cachecontrol.rb
+    lib/rack/cache/context.rb
+    lib/rack/cache/entitystore.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
+    rack-cache.gemspec
+    test/cache_test.rb
+    test/cachecontrol_test.rb
+    test/context_test.rb
+    test/entitystore_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
+  ]
+  # = MANIFEST =
+
+  s.test_files = s.files.select {|path| path =~ /^test\/.*_test.rb/}
+
+  s.extra_rdoc_files = %w[README COPYING TODO CHANGES]
+  s.add_dependency 'rack', '>= 0.4'
+
+  s.has_rdoc = true
+  s.homepage = "http://tomayko.com/src/rack-cache/"
+  s.rdoc_options = ["--line-numbers", "--inline-source", "--title", "Rack::Cache", "--main", "Rack::Cache"]
+  s.require_paths = %w[lib]
+  s.rubyforge_project = 'wink'
+  s.rubygems_version = '1.1.1'
+end

data/test/cache_test.rb

@@ -0,0 +1,38 @@
+require "#{File.dirname(__FILE__)}/spec_setup"
+
+def dumb_app(env)
+  body = block_given? ? [yield] : ['Hi']
+  [ 200, {'Content-Type' => 'text/plain'}, body ]
+end
+
+describe 'Rack::Cache::new' do
+  before { @app = method(:dumb_app) }
+
+  it 'takes a backend and returns a middleware component' do
+    Rack::Cache.new(@app).
+      should.respond_to :call
+  end
+
+  it 'takes an options Hash' do
+    lambda { Rack::Cache.new(@app, {}) }.
+      should.not.raise(ArgumentError)
+  end
+
+  it 'sets options provided in the options Hash' do
+    object = Rack::Cache.new(@app, :foo => 'bar', 'foo.bar' => 'bling')
+    object.options['foo.bar'].should.equal 'bling'
+    object.options['rack-cache.foo'].should.equal 'bar'
+  end
+
+  it 'takes a block; executes it during initialization' do
+    state, object  = 'not invoked', nil
+    instance =
+      Rack::Cache.new @app do |cache|
+        object = cache
+        state = 'invoked'
+        cache.should.respond_to :set
+      end
+    state.should.equal 'invoked'
+    object.should.be instance
+  end
+end

data/test/cachecontrol_test.rb

@@ -0,0 +1,139 @@
+require "#{File.dirname(__FILE__)}/spec_setup"
+require 'rack/cache/cachecontrol'
+
+describe 'Rack::Cache::CacheControl' do
+  it 'takes no args and initializes with an empty set of values' do
+    cache_control = Rack::Cache::CacheControl.new
+    cache_control.should.be.empty
+    cache_control.to_s.should.equal ''
+  end
+
+  it 'takes a String and parses it into a Hash when created' do
+    cache_control = Rack::Cache::CacheControl.new('max-age=600, foo')
+    cache_control['max-age'].should.equal '600'
+    cache_control['foo'].should.be true
+  end
+
+  it 'takes a String with a single name=value pair' do
+    cache_control = Rack::Cache::CacheControl.new('max-age=600')
+    cache_control['max-age'].should.equal '600'
+  end
+
+  it 'takes a String with multiple name=value pairs' do
+    cache_control = Rack::Cache::CacheControl.new('max-age=600, max-stale=300, min-fresh=570')
+    cache_control['max-age'].should.equal '600'
+    cache_control['max-stale'].should.equal '300'
+    cache_control['min-fresh'].should.equal '570'
+  end
+
+  it 'takes a String with a single flag value' do
+    cache_control = Rack::Cache::CacheControl.new('no-cache')
+    cache_control.should.include 'no-cache'
+    cache_control['no-cache'].should.be true
+  end
+
+  it 'takes a String with a bunch of all kinds of stuff' do
+    cache_control =
+      Rack::Cache::CacheControl.new('max-age=600,must-revalidate,min-fresh=3000,foo=bar,baz')
+    cache_control['max-age'].should.equal '600'
+    cache_control['must-revalidate'].should.be true
+    cache_control['min-fresh'].should.equal '3000'
+    cache_control['foo'].should.equal 'bar'
+    cache_control['baz'].should.be true
+  end
+
+  it 'strips leading and trailing spaces from header value' do
+    cache_control = Rack::Cache::CacheControl.new('   public,   max-age =   600  ')
+    cache_control.should.include 'public'
+    cache_control.should.include 'max-age'
+    cache_control['max-age'].should.equal '600'
+  end
+
+  it 'removes all directives with #clear' do
+    cache_control = Rack::Cache::CacheControl.new('max-age=600, must-revalidate')
+    cache_control.clear
+    cache_control.should.be.empty
+  end
+
+  it 'converts self into header String with #to_s' do
+    cache_control = Rack::Cache::CacheControl.new
+    cache_control['public'] = true
+    cache_control['max-age'] = '600'
+    cache_control.to_s.split(', ').sort.should.equal ['max-age=600', 'public']
+  end
+
+  it 'sorts alphabetically with boolean directives before value directives' do
+    cache_control = Rack::Cache::CacheControl.new('foo=bar, z, x, y, bling=baz, zoom=zib, b, a')
+    cache_control.to_s.should.equal 'a, b, x, y, z, bling=baz, foo=bar, zoom=zib'
+  end
+
+  it 'responds to #max_age with an integer when max-age directive present' do
+    cache_control = Rack::Cache::CacheControl.new('public, max-age=600')
+    cache_control.max_age.should.equal 600
+  end
+
+  it 'responds to #max_age with nil when no max-age directive present' do
+    cache_control = Rack::Cache::CacheControl.new('public')
+    cache_control.max_age.should.be nil
+  end
+
+  it 'responds to #shared_max_age with an integer when s-maxage directive present' do
+    cache_control = Rack::Cache::CacheControl.new('public, s-maxage=600')
+    cache_control.shared_max_age.should.equal 600
+  end
+
+  it 'responds to #shared_max_age with nil when no s-maxage directive present' do
+    cache_control = Rack::Cache::CacheControl.new('public')
+    cache_control.shared_max_age.should.be nil
+  end
+
+  it 'responds to #public? truthfully when public directive present' do
+    cache_control = Rack::Cache::CacheControl.new('public')
+    cache_control.should.be.public
+  end
+
+  it 'responds to #public? non-truthfully when no public directive present' do
+    cache_control = Rack::Cache::CacheControl.new('private')
+    cache_control.should.not.be.public
+  end
+
+  it 'responds to #private? truthfully when private directive present' do
+    cache_control = Rack::Cache::CacheControl.new('private')
+    cache_control.should.be.private
+  end
+
+  it 'responds to #private? non-truthfully when no private directive present' do
+    cache_control = Rack::Cache::CacheControl.new('public')
+    cache_control.should.not.be.private
+  end
+
+  it 'responds to #no_cache? truthfully when no-cache directive present' do
+    cache_control = Rack::Cache::CacheControl.new('no-cache')
+    cache_control.should.be.no_cache
+  end
+
+  it 'responds to #no_cache? non-truthfully when no no-cache directive present' do
+    cache_control = Rack::Cache::CacheControl.new('max-age=600')
+    cache_control.should.not.be.no_cache
+  end
+
+  it 'responds to #must_revalidate? truthfully when must-revalidate directive present' do
+    cache_control = Rack::Cache::CacheControl.new('must-revalidate')
+    cache_control.should.be.must_revalidate
+  end
+
+  it 'responds to #must_revalidate? non-truthfully when no must-revalidate directive present' do
+    cache_control = Rack::Cache::CacheControl.new('max-age=600')
+    cache_control.should.not.be.no_cache
+  end
+
+  it 'responds to #proxy_revalidate? truthfully when proxy-revalidate directive present' do
+    cache_control = Rack::Cache::CacheControl.new('proxy-revalidate')
+    cache_control.should.be.proxy_revalidate
+  end
+
+  it 'responds to #proxy_revalidate? non-truthfully when no proxy-revalidate directive present' do
+    cache_control = Rack::Cache::CacheControl.new('max-age=600')
+    cache_control.should.not.be.no_cache
+  end
+end

data/test/context_test.rb

@@ -0,0 +1,774 @@
+require "#{File.dirname(__FILE__)}/spec_setup"
+require 'rack/cache/context'
+
+describe 'Rack::Cache::Context' do
+  before(:each) { setup_cache_context }
+  after(:each)  { teardown_cache_context }
+
+  it 'passes on non-GET/HEAD requests' do
+    respond_with 200
+    post '/'
+
+    app.should.be.called
+    response.should.be.ok
+    cache.trace.should.include :pass
+    response.headers.should.not.include 'Age'
+  end
+
+  %w[post put delete].each do |request_method|
+    it "invalidates on #{request_method} requests" do
+      respond_with 200
+      request request_method, '/'
+
+      app.should.be.called
+      response.should.be.ok
+      cache.trace.should.include :invalidate
+      cache.trace.should.include :pass
+    end
+  end
+
+  it 'does not cache with Authorization request header and non public response' do
+    respond_with 200, 'ETag' => '"FOO"'
+    get '/', 'HTTP_AUTHORIZATION' => 'basic foobarbaz'
+
+    app.should.be.called
+    response.should.be.ok
+    response.headers['Cache-Control'].should.equal 'private'
+    cache.trace.should.include :miss
+    cache.trace.should.not.include :store
+    response.headers.should.not.include 'Age'
+  end
+
+  it 'does cache with Authorization request header and public response' do
+    respond_with 200, 'Cache-Control' => 'public', 'ETag' => '"FOO"'
+    get '/', 'HTTP_AUTHORIZATION' => 'basic foobarbaz'
+
+    app.should.be.called
+    response.should.be.ok
+    cache.trace.should.include :miss
+    cache.trace.should.include :store
+    response.headers.should.include 'Age'
+    response.headers['Cache-Control'].should.equal 'public'
+  end
+
+  it 'does not cache with Cookie header and non public response' do
+    respond_with 200, 'ETag' => '"FOO"'
+    get '/', 'HTTP_COOKIE' => 'foo=bar'
+
+    app.should.be.called
+    response.should.be.ok
+    response.headers['Cache-Control'].should.equal 'private'
+    cache.trace.should.include :miss
+    cache.trace.should.not.include :store
+    response.headers.should.not.include 'Age'
+  end
+
+  it 'does not cache requests with a Cookie header' do
+    respond_with 200
+    get '/', 'HTTP_COOKIE' => 'foo=bar'
+
+    response.should.be.ok
+    app.should.be.called
+    cache.trace.should.include :miss
+    cache.trace.should.not.include :store
+    response.headers.should.not.include 'Age'
+    response.headers['Cache-Control'].should.equal 'private'
+  end
+
+  it 'responds with 304 when If-Modified-Since matches Last-Modified' do
+    timestamp = Time.now.httpdate
+    respond_with do |req,res|
+      res.status = 200
+      res['Last-Modified'] = timestamp
+      res['Content-Type'] = 'text/plain'
+      res.body = ['Hello World']
+    end
+
+    get '/',
+      'HTTP_IF_MODIFIED_SINCE' => timestamp
+    app.should.be.called
+    response.status.should.equal 304
+    response.headers.should.not.include 'Content-Length'
+    response.headers.should.not.include 'Content-Type'
+    response.body.should.empty
+    cache.trace.should.include :miss
+    cache.trace.should.include :store
+  end
+
+  it 'responds with 304 when If-None-Match matches ETag' do
+    respond_with do |req,res|
+      res.status = 200
+      res['ETag'] = '12345'
+      res['Content-Type'] = 'text/plain'
+      res.body = ['Hello World']
+    end
+
+    get '/',
+      'HTTP_IF_NONE_MATCH' => '12345'
+    app.should.be.called
+    response.status.should.equal 304
+    response.headers.should.not.include 'Content-Length'
+    response.headers.should.not.include 'Content-Type'
+    response.headers.should.include 'ETag'
+    response.body.should.empty
+    cache.trace.should.include :miss
+    cache.trace.should.include :store
+  end
+
+  it 'stores responses when no-cache request directive present' do
+    respond_with 200, 'Expires' => (Time.now + 5).httpdate
+
+    get '/', 'HTTP_CACHE_CONTROL' => 'no-cache'
+    response.should.be.ok
+    cache.trace.should.include :store
+    response.headers.should.include 'Age'
+  end
+
+  it 'reloads responses when cache hits but no-cache request directive present ' +
+     'when allow_reload is set true' do
+    count = 0
+    respond_with 200, 'Cache-Control' => 'max-age=10000' do |req,res|
+      count+= 1
+      res.body = (count == 1) ? ['Hello World'] : ['Goodbye World']
+    end
+
+    get '/'
+    response.should.be.ok
+    response.body.should.equal 'Hello World'
+    cache.trace.should.include :store
+
+    get '/'
+    response.should.be.ok
+    response.body.should.equal 'Hello World'
+    cache.trace.should.include :fresh
+
+    get '/',
+      'rack-cache.allow_reload' => true,
+      'HTTP_CACHE_CONTROL' => 'no-cache'
+    response.should.be.ok
+    response.body.should.equal 'Goodbye World'
+    cache.trace.should.include :reload
+    cache.trace.should.include :store
+  end
+
+  it 'does not reload responses when allow_reload is set false (default)' do
+    count = 0
+    respond_with 200, 'Cache-Control' => 'max-age=10000' do |req,res|
+      count+= 1
+      res.body = (count == 1) ? ['Hello World'] : ['Goodbye World']
+    end
+
+    get '/'
+    response.should.be.ok
+    response.body.should.equal 'Hello World'
+    cache.trace.should.include :store
+
+    get '/'
+    response.should.be.ok
+    response.body.should.equal 'Hello World'
+    cache.trace.should.include :fresh
+
+    get '/',
+      'rack-cache.allow_reload' => false,
+      'HTTP_CACHE_CONTROL' => 'no-cache'
+    response.should.be.ok
+    response.body.should.equal 'Hello World'
+    cache.trace.should.not.include :reload
+
+    # test again without explicitly setting the allow_reload option to false
+    get '/',
+      'HTTP_CACHE_CONTROL' => 'no-cache'
+    response.should.be.ok
+    response.body.should.equal 'Hello World'
+    cache.trace.should.not.include :reload
+  end
+
+  it 'revalidates fresh cache entry when max-age request directive is exceeded ' +
+     'when allow_revalidate option is set true' do
+    count = 0
+    respond_with do |req,res|
+      count+= 1
+      res['Cache-Control'] = 'max-age=10000'
+      res['ETag'] = count.to_s
+      res.body = (count == 1) ? ['Hello World'] : ['Goodbye World']
+    end
+
+    get '/'
+    response.should.be.ok
+    response.body.should.equal 'Hello World'
+    cache.trace.should.include :store
+
+    get '/'
+    response.should.be.ok
+    response.body.should.equal 'Hello World'
+    cache.trace.should.include :fresh
+
+    get '/',
+      'rack-cache.allow_revalidate' => true,
+      'HTTP_CACHE_CONTROL' => 'max-age=0'
+    response.should.be.ok
+    response.body.should.equal 'Goodbye World'
+    cache.trace.should.include :stale
+    cache.trace.should.include :invalid
+    cache.trace.should.include :store
+  end
+
+  it 'does not revalidate fresh cache entry when enable_revalidate option is set false (default)' do
+    count = 0
+    respond_with do |req,res|
+      count+= 1
+      res['Cache-Control'] = 'max-age=10000'
+      res['ETag'] = count.to_s
+      res.body = (count == 1) ? ['Hello World'] : ['Goodbye World']
+    end
+
+    get '/'
+    response.should.be.ok
+    response.body.should.equal 'Hello World'
+    cache.trace.should.include :store
+
+    get '/'
+    response.should.be.ok
+    response.body.should.equal 'Hello World'
+    cache.trace.should.include :fresh
+
+    get '/',
+      'rack-cache.allow_revalidate' => false,
+      'HTTP_CACHE_CONTROL' => 'max-age=0'
+    response.should.be.ok
+    response.body.should.equal 'Hello World'
+    cache.trace.should.not.include :stale
+    cache.trace.should.not.include :invalid
+    cache.trace.should.include :fresh
+
+    # test again without explicitly setting the allow_revalidate option to false
+    get '/',
+      'HTTP_CACHE_CONTROL' => 'max-age=0'
+    response.should.be.ok
+    response.body.should.equal 'Hello World'
+    cache.trace.should.not.include :stale
+    cache.trace.should.not.include :invalid
+    cache.trace.should.include :fresh
+  end
+  it 'fetches response from backend when cache misses' do
+    respond_with 200, 'Expires' => (Time.now + 5).httpdate
+    get '/'
+
+    response.should.be.ok
+    cache.trace.should.include :miss
+    response.headers.should.include 'Age'
+  end
+
+  [(201..202),(204..206),(303..305),(400..403),(405..409),(411..417),(500..505)].each do |range|
+    range.each do |response_code|
+      it "does not cache #{response_code} responses" do
+        respond_with response_code, 'Expires' => (Time.now + 5).httpdate
+        get '/'
+
+        cache.trace.should.not.include :store
+        response.status.should.equal response_code
+        response.headers.should.not.include 'Age'
+      end
+    end
+  end
+
+  it "does not cache responses with explicit no-store directive" do
+    respond_with 200,
+      'Expires' => (Time.now + 5).httpdate,
+      'Cache-Control' => 'no-store'
+    get '/'
+
+    response.should.be.ok
+    cache.trace.should.not.include :store
+    response.headers.should.not.include 'Age'
+  end
+
+  it 'does not cache responses without freshness information or a validator' do
+    respond_with 200
+    get '/'
+
+    response.should.be.ok
+    cache.trace.should.not.include :store
+  end
+
+  it "caches responses with explicit no-cache directive" do
+    respond_with 200,
+      'Expires' => (Time.now + 5).httpdate,
+      'Cache-Control' => 'no-cache'
+    get '/'
+
+    response.should.be.ok
+    cache.trace.should.include :store
+    response.headers.should.include 'Age'
+  end
+
+  it 'caches responses with an Expiration header' do
+    respond_with 200, 'Expires' => (Time.now + 5).httpdate
+    get '/'
+
+    response.should.be.ok
+    response.body.should.equal 'Hello World'
+    response.headers.should.include 'Date'
+    response['Age'].should.not.be.nil
+    response['X-Content-Digest'].should.not.be.nil
+    cache.trace.should.include :miss
+    cache.trace.should.include :store
+    cache.metastore.to_hash.keys.length.should.equal 1
+  end
+
+  it 'caches responses with a max-age directive' do
+    respond_with 200, 'Cache-Control' => 'max-age=5'
+    get '/'
+
+    response.should.be.ok
+    response.body.should.equal 'Hello World'
+    response.headers.should.include 'Date'
+    response['Age'].should.not.be.nil
+    response['X-Content-Digest'].should.not.be.nil
+    cache.trace.should.include :miss
+    cache.trace.should.include :store
+    cache.metastore.to_hash.keys.length.should.equal 1
+  end
+
+  it 'caches responses with a s-maxage directive' do
+    respond_with 200, 'Cache-Control' => 's-maxage=5'
+    get '/'
+
+    response.should.be.ok
+    response.body.should.equal 'Hello World'
+    response.headers.should.include 'Date'
+    response['Age'].should.not.be.nil
+    response['X-Content-Digest'].should.not.be.nil
+    cache.trace.should.include :miss
+    cache.trace.should.include :store
+    cache.metastore.to_hash.keys.length.should.equal 1
+  end
+
+  it 'caches responses with a Last-Modified validator but no freshness information' do
+    respond_with 200, 'Last-Modified' => Time.now.httpdate
+    get '/'
+
+    response.should.be.ok
+    response.body.should.equal 'Hello World'
+    cache.trace.should.include :miss
+    cache.trace.should.include :store
+  end
+
+  it 'caches responses with an ETag validator but no freshness information' do
+    respond_with 200, 'ETag' => '"123456"'
+    get '/'
+
+    response.should.be.ok
+    response.body.should.equal 'Hello World'
+    cache.trace.should.include :miss
+    cache.trace.should.include :store
+  end
+
+  it 'hits cached response with Expires header' do
+    respond_with 200,
+      'Date' => (Time.now - 5).httpdate,
+      'Expires' => (Time.now + 5).httpdate
+
+    get '/'
+    app.should.be.called
+    response.should.be.ok
+    response.headers.should.include 'Date'
+    cache.trace.should.include :miss
+    cache.trace.should.include :store
+    response.body.should.equal 'Hello World'
+
+    get '/'
+    response.should.be.ok
+    app.should.not.be.called
+    response['Date'].should.equal responses.first['Date']
+    response['Age'].to_i.should.satisfy { |age| age > 0 }
+    response['X-Content-Digest'].should.not.be.nil
+    cache.trace.should.include :fresh
+    cache.trace.should.not.include :store
+    response.body.should.equal 'Hello World'
+  end
+
+  it 'hits cached response with max-age directive' do
+    respond_with 200,
+      'Date' => (Time.now - 5).httpdate,
+      'Cache-Control' => 'max-age=10'
+
+    get '/'
+    app.should.be.called
+    response.should.be.ok
+    response.headers.should.include 'Date'
+    cache.trace.should.include :miss
+    cache.trace.should.include :store
+    response.body.should.equal 'Hello World'
+
+    get '/'
+    response.should.be.ok
+    app.should.not.be.called
+    response['Date'].should.equal responses.first['Date']
+    response['Age'].to_i.should.satisfy { |age| age > 0 }
+    response['X-Content-Digest'].should.not.be.nil
+    cache.trace.should.include :fresh
+    cache.trace.should.not.include :store
+    response.body.should.equal 'Hello World'
+  end
+
+  it 'hits cached response with s-maxage directive' do
+    respond_with 200,
+      'Date' => (Time.now - 5).httpdate,
+      'Cache-Control' => 's-maxage=10, max-age=0'
+
+    get '/'
+    app.should.be.called
+    response.should.be.ok
+    response.headers.should.include 'Date'
+    cache.trace.should.include :miss
+    cache.trace.should.include :store
+    response.body.should.equal 'Hello World'
+
+    get '/'
+    response.should.be.ok
+    app.should.not.be.called
+    response['Date'].should.equal responses.first['Date']
+    response['Age'].to_i.should.satisfy { |age| age > 0 }
+    response['X-Content-Digest'].should.not.be.nil
+    cache.trace.should.include :fresh
+    cache.trace.should.not.include :store
+    response.body.should.equal 'Hello World'
+  end
+
+  it 'assigns default_ttl when response has no freshness information' do
+    respond_with 200
+
+    get '/', 'rack-cache.default_ttl' => 10
+    app.should.be.called
+    response.should.be.ok
+    cache.trace.should.include :miss
+    cache.trace.should.include :store
+    response.body.should.equal 'Hello World'
+    response['Cache-Control'].should.include 's-maxage=10'
+
+    get '/', 'rack-cache.default_ttl' => 10
+    response.should.be.ok
+    app.should.not.be.called
+    cache.trace.should.include :fresh
+    cache.trace.should.not.include :store
+    response.body.should.equal 'Hello World'
+  end
+
+  it 'does not assign default_ttl when response has must-revalidate directive' do
+    respond_with 200,
+      'Cache-Control' => 'must-revalidate'
+
+    get '/', 'rack-cache.default_ttl' => 10
+    app.should.be.called
+    response.should.be.ok
+    cache.trace.should.include :miss
+    cache.trace.should.not.include :store
+    response['Cache-Control'].should.not.include 's-maxage'
+    response.body.should.equal 'Hello World'
+  end
+
+  it 'fetches full response when cache stale and no validators present' do
+    respond_with 200, 'Expires' => (Time.now + 5).httpdate
+
+    # build initial request
+    get '/'
+    app.should.be.called
+    response.should.be.ok
+    response.headers.should.include 'Date'
+    response.headers.should.include 'X-Content-Digest'
+    response.headers.should.include 'Age'
+    cache.trace.should.include :miss
+    cache.trace.should.include :store
+    response.body.should.equal 'Hello World'
+
+    # go in and play around with the cached metadata directly ...
+    cache.metastore.to_hash.values.length.should.equal 1
+    cache.metastore.to_hash.values.first.first[1]['Expires'] = Time.now.httpdate
+
+    # build subsequent request; should be found but miss due to freshness
+    get '/'
+    app.should.be.called
+    response.should.be.ok
+    response['Age'].to_i.should.equal 0
+    response.headers.should.include 'X-Content-Digest'
+    cache.trace.should.include :stale
+    cache.trace.should.not.include :fresh
+    cache.trace.should.not.include :miss
+    cache.trace.should.include :store
+    response.body.should.equal 'Hello World'
+  end
+
+  it 'validates cached responses with Last-Modified and no freshness information' do
+    timestamp = Time.now.httpdate
+    respond_with do |req,res|
+      res['Last-Modified'] = timestamp
+      if req.env['HTTP_IF_MODIFIED_SINCE'] == timestamp
+        res.status = 304
+        res.body = []
+      end
+    end
+
+    # build initial request
+    get '/'
+    app.should.be.called
+    response.should.be.ok
+    response.headers.should.include 'Last-Modified'
+    response.headers.should.include 'X-Content-Digest'
+    response.body.should.equal 'Hello World'
+    cache.trace.should.include :miss
+    cache.trace.should.include :store
+    cache.trace.should.not.include :stale
+
+    # build subsequent request; should be found but miss due to freshness
+    get '/'
+    app.should.be.called
+    response.should.be.ok
+    response.headers.should.include 'Last-Modified'
+    response.headers.should.include 'X-Content-Digest'
+    response['Age'].to_i.should.equal 0
+    response.body.should.equal 'Hello World'
+    cache.trace.should.include :stale
+    cache.trace.should.include :valid
+    cache.trace.should.include :store
+    cache.trace.should.not.include :miss
+  end
+
+  it 'validates cached responses with ETag and no freshness information' do
+    timestamp = Time.now.httpdate
+    respond_with do |req,res|
+      res['ETAG'] = '"12345"'
+      if req.env['HTTP_IF_NONE_MATCH'] == res['Etag']
+        res.status = 304
+        res.body = []
+      end
+    end
+
+    # build initial request
+    get '/'
+    app.should.be.called
+    response.should.be.ok
+    response.headers.should.include 'ETag'
+    response.headers.should.include 'X-Content-Digest'
+    response.body.should.equal 'Hello World'
+    cache.trace.should.include :miss
+    cache.trace.should.include :store
+
+    # build subsequent request; should be found but miss due to freshness
+    get '/'
+    app.should.be.called
+    response.should.be.ok
+    response.headers.should.include 'ETag'
+    response.headers.should.include 'X-Content-Digest'
+    response['Age'].to_i.should.equal 0
+    response.body.should.equal 'Hello World'
+    cache.trace.should.include :stale
+    cache.trace.should.include :valid
+    cache.trace.should.include :store
+    cache.trace.should.not.include :miss
+  end
+
+  it 'replaces cached responses when validation results in non-304 response' do
+    timestamp = Time.now.httpdate
+    count = 0
+    respond_with do |req,res|
+      res['Last-Modified'] = timestamp
+      case (count+=1)
+      when 1 ; res.body = ['first response']
+      when 2 ; res.body = ['second response']
+      when 3
+        res.body = []
+        res.status = 304
+      end
+    end
+
+    # first request should fetch from backend and store in cache
+    get '/'
+    response.status.should.equal 200
+    response.body.should.equal 'first response'
+
+    # second request is validated, is invalid, and replaces cached entry
+    get '/'
+    response.status.should.equal 200
+    response.body.should.equal 'second response'
+
+    # third respone is validated, valid, and returns cached entry
+    get '/'
+    response.status.should.equal 200
+    response.body.should.equal 'second response'
+
+    count.should.equal 3
+  end
+
+  it 'passes HEAD requests through directly on pass' do
+    respond_with do |req,res|
+      res.status = 200
+      res.body = []
+      req.request_method.should.equal 'HEAD'
+    end
+
+    head '/', 'HTTP_EXPECT' => 'something ...'
+    app.should.be.called
+    response.body.should.equal ''
+  end
+
+  it 'uses cache to respond to HEAD requests when fresh' do
+    respond_with do |req,res|
+      res['Cache-Control'] = 'max-age=10'
+      res.body = ['Hello World']
+      req.request_method.should.not.equal 'HEAD'
+    end
+
+    get '/'
+    app.should.be.called
+    response.status.should.equal 200
+    response.body.should.equal 'Hello World'
+
+    head '/'
+    app.should.not.be.called
+    response.status.should.equal 200
+    response.body.should.equal ''
+    response['Content-Length'].should.equal 'Hello World'.length.to_s
+  end
+
+  it 'invalidates cached responses on POST' do
+    respond_with do |req,res|
+      if req.request_method == 'GET'
+        res.status = 200
+        res['Cache-Control'] = 'public, max-age=500'
+        res.body = ['Hello World']
+      elsif req.request_method == 'POST'
+        res.status = 303
+        res['Location'] = '/'
+        res.headers.delete('Cache-Control')
+        res.body = []
+      end
+    end
+
+    # build initial request to enter into the cache
+    get '/'
+    app.should.be.called
+    response.should.be.ok
+    response.body.should.equal 'Hello World'
+    cache.trace.should.include :miss
+    cache.trace.should.include :store
+
+    # make sure it is valid
+    get '/'
+    app.should.not.called
+    response.should.be.ok
+    response.body.should.equal 'Hello World'
+    cache.trace.should.include :fresh
+
+    # now POST to same URL
+    post '/'
+    app.should.be.called
+    response.should.be.redirect
+    response['Location'].should.equal '/'
+    cache.trace.should.include :invalidate
+    cache.trace.should.include :pass
+    response.body.should.equal ''
+
+    # now make sure it was actually invalidated
+    get '/'
+    app.should.be.called
+    response.should.be.ok
+    response.body.should.equal 'Hello World'
+    cache.trace.should.include :stale
+    cache.trace.should.include :invalid
+    cache.trace.should.include :store
+  end
+
+  describe 'with responses that include a Vary header' do
+    before(:each) do
+      count = 0
+      respond_with 200 do |req,res|
+        res['Vary'] = 'Accept User-Agent Foo'
+        res['Cache-Control'] = 'max-age=10'
+        res['X-Response-Count'] = (count+=1).to_s
+        res.body = [req.env['HTTP_USER_AGENT']]
+      end
+    end
+
+    it 'serves from cache when headers match' do
+      get '/',
+        'HTTP_ACCEPT' => 'text/html',
+        'HTTP_USER_AGENT' => 'Bob/1.0'
+      response.should.be.ok
+      response.body.should.equal 'Bob/1.0'
+      cache.trace.should.include :miss
+      cache.trace.should.include :store
+
+      get '/',
+        'HTTP_ACCEPT' => 'text/html',
+        'HTTP_USER_AGENT' => 'Bob/1.0'
+      response.should.be.ok
+      response.body.should.equal 'Bob/1.0'
+      cache.trace.should.include :fresh
+      cache.trace.should.not.include :store
+      response.headers.should.include 'X-Content-Digest'
+    end
+
+    it 'stores multiple responses when headers differ' do
+      get '/',
+        'HTTP_ACCEPT' => 'text/html',
+        'HTTP_USER_AGENT' => 'Bob/1.0'
+      response.should.be.ok
+      response.body.should.equal 'Bob/1.0'
+      response['X-Response-Count'].should.equal '1'
+
+      get '/',
+        'HTTP_ACCEPT' => 'text/html',
+        'HTTP_USER_AGENT' => 'Bob/2.0'
+      cache.trace.should.include :miss
+      cache.trace.should.include :store
+      response.body.should.equal 'Bob/2.0'
+      response['X-Response-Count'].should.equal '2'
+
+      get '/',
+        'HTTP_ACCEPT' => 'text/html',
+        'HTTP_USER_AGENT' => 'Bob/1.0'
+      cache.trace.should.include :fresh
+      response.body.should.equal 'Bob/1.0'
+      response['X-Response-Count'].should.equal '1'
+
+      get '/',
+        'HTTP_ACCEPT' => 'text/html',
+        'HTTP_USER_AGENT' => 'Bob/2.0'
+      cache.trace.should.include :fresh
+      response.body.should.equal 'Bob/2.0'
+      response['X-Response-Count'].should.equal '2'
+
+      get '/',
+        'HTTP_USER_AGENT' => 'Bob/2.0'
+      cache.trace.should.include :miss
+      response.body.should.equal 'Bob/2.0'
+      response['X-Response-Count'].should.equal '3'
+    end
+  end
+
+  it 'passes if there was a metastore exception' do
+    respond_with 200, 'Cache-Control' => 'max-age=10000' do |req,res|
+      res.body = ['Hello World']
+    end
+
+    get '/'
+    response.should.be.ok
+    response.body.should.equal 'Hello World'
+    cache.trace.should.include :store
+
+    get '/' do |cache|
+      cache.meta_def(:metastore) { raise Timeout::Error }
+    end
+    response.should.be.ok
+    response.body.should.equal 'Hello World'
+    cache.trace.should.include :pass
+
+    post '/' do |cache|
+      cache.meta_def(:metastore) { raise Timeout::Error }
+    end
+    response.should.be.ok
+    response.body.should.equal 'Hello World'
+    cache.trace.should.include :pass
+  end
+end