rack-cache 0.2.0

data/lib/rack/cache/options.rb

@@ -0,0 +1,119 @@
+require 'rack'
+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.
+
+  module Options
+    class << self
+      private
+      def option_accessor(key)
+        define_method(key) { || read_option(key) }
+        define_method("#{key}=") { |value| write_option(key, value) }
+        define_method("#{key}?") { || !! read_option(key) }
+      end
+    end
+
+    # Enable verbose trace logging. This option is currently enabled by
+    # default but is likely to be disabled in a future release.
+    option_accessor :verbose
+
+    # The storage resolver. Defaults to the Rack::Cache.storage singleton instance
+    # of Rack::Cache::Storage. This object is responsible for resolving metastore
+    # and entitystore URIs to an implementation instances.
+    option_accessor :storage
+
+    # A URI specifying the meta-store implementation that should be used to store
+    # request/response meta information. The following URIs schemes are
+    # supported:
+    #
+    # * heap:/
+    # * file:/absolute/path or file:relative/path
+    # * memcached://localhost:11211[/namespace]
+    #
+    # If no meta store is specified the 'heap:/' store is assumed. This
+    # implementation has significant draw-backs so explicit configuration is
+    # recommended.
+    option_accessor :metastore
+
+    # 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.
+    #
+    # If no entity store is specified the 'heap:/' store is assumed. This
+    # implementation has significant draw-backs so explicit configuration is
+    # recommended.
+    option_accessor :entitystore
+
+    # The number of seconds that a cache entry should be considered
+    # "fresh" when no explicit freshness information is provided in
+    # a response. Explicit Cache-Control or Expires headers
+    # override this value.
+    #
+    # Default: 0
+    option_accessor :default_ttl
+
+    # 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
+    # the Rack environment before each request is processed.
+    def options
+      @env || @default_options
+    end
+
+    # Set multiple options.
+    def options=(hash={})
+      hash.each { |key,value| write_option(key, value) }
+    end
+
+    # Set an option. When +option+ is a Symbol, it is set in the Rack
+    # Environment as "rack-cache.option". When +option+ is a String, it
+    # 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
+        self.options = option.to_hash
+      else
+        write_option option, value
+      end
+    end
+
+  private
+    def read_option(key)
+      options[option_name(key)]
+    end
+
+    def write_option(key, value)
+      options[option_name(key)] = value
+    end
+
+    def option_name(key)
+      case key
+      when Symbol ; "rack-cache.#{key}"
+      when String ; key
+      else raise ArgumentError
+      end
+    end
+
+  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
+      }
+      self.options = options
+    end
+  end
+end

data/lib/rack/cache/request.rb

@@ -0,0 +1,37 @@
+require 'rack/request'
+require 'rack/cache/headers'
+require 'rack/utils/environment_headers'
+
+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
+    # the real request method.
+    def request_method
+      @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 }
+    end
+
+    alias_method :method?, :request_method?
+  end
+end

data/lib/rack/cache/response.rb

@@ -0,0 +1,76 @@
+require 'set'
+require 'rack/cache/headers'
+
+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.
+  #
+  # Response objects respond to a variety of convenience methods, including
+  # those defined in Rack::Response::Helpers, Rack::Cache::Headers,
+  # and Rack::Cache::ResponseHeaders.
+  #
+  # Note that Rack::Cache::Response is not a subclass of Rack::Response and does
+  # 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
+
+    # 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
+
+    # Create a Response instance given the response status code, header hash,
+    # and body.
+    def initialize(status, headers, body)
+      @status = status
+      @headers = headers
+      @body = body
+      @now = Time.now
+      @headers['Date'] ||= now.httpdate
+    end
+
+    def initialize_copy(other)
+      super
+      @headers = other.headers.dup
+    end
+
+    # Return the value of the named response header.
+    def [](header_name)
+      headers[header_name]
+    end
+
+    # Set a response header value.
+    def []=(header_name, header_value)
+      headers[header_name] = header_value
+    end
+
+    # Called immediately after an object is loaded from the cache.
+    def activate!
+      headers['Age'] = age.to_i.to_s
+    end
+
+    # Return the status, headers, and body in a three-tuple.
+    def to_a
+      [status, headers, body]
+    end
+
+    # Freezes
+    def freeze
+      @headers.freeze
+      super
+    end
+
+  end
+
+end

data/lib/rack/cache/storage.rb

@@ -0,0 +1,50 @@
+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
+
+    # Clear store instances.
+    def clear
+      @metastores.clear
+      @entitystores.clear
+      nil
+    end
+
+  private
+    def create_store(type, uri)
+      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
+    end
+
+  public
+    @@singleton_instance = new
+    def self.instance
+      @@singleton_instance
+    end
+  end
+
+end

data/lib/rack/utils/environment_headers.rb

@@ -0,0 +1,78 @@
+require 'rack/utils'
+
+module Rack::Utils #:nodoc:
+  # A facade over a Rack Environment Hash that gives access to headers
+  # using their normal RFC 2616 names.
+
+  class EnvironmentHeaders
+    include Enumerable
+
+    # Create the facade over the given Rack Environment Hash.
+    def initialize(env)
+      @env = env
+    end
+
+    # Return the value of the specified header. The +header_name+ should
+    # be as specified by RFC 2616 (e.g., "Content-Type", "Accept", etc.)
+    def [](header_name)
+      @env[env_name(header_name)]
+    end
+
+    # Set the value of the specified header. The +header_name+ should
+    # be as specified by RFC 2616 (e.g., "Content-Type", "Accept", etc.)
+    def []=(header_name, value)
+      @env[env_name(header_name)] = value
+    end
+
+    # Determine if the underlying Rack Environment includes a header
+    # of the given name.
+    def include?(header_name)
+      @env.include?(env_name(header_name))
+    end
+
+    # Iterate over all headers yielding a (name, value) tuple to the
+    # block. Rack Environment keys that do not map to an header are not
+    # included.
+    def each
+      @env.each do |key,value|
+        next unless key =~ /^(HTTP_|CONTENT_)/
+        yield header_name(key), value
+      end
+    end
+
+    # Delete the entry in the underlying Rack Environment that corresponds
+    # to the given RFC 2616 header name.
+    def delete(header_name)
+      @env.delete(env_name(header_name))
+    end
+
+    # Return the underlying Rack Environment Hash.
+    def to_env
+      @env
+    end
+
+    alias_method :to_hash, :to_env
+
+  private
+
+    # Return the Rack Environment key for the given RFC 2616 header name.
+    def env_name(header_name)
+      case header_name = header_name.upcase
+      when 'CONTENT-TYPE'   then 'CONTENT_TYPE'
+      when 'CONTENT-LENGTH' then 'CONTENT_LENGTH'
+      else "HTTP_#{header_name.tr('-', '_')}"
+      end
+    end
+
+    # Return the RFC 2616 header name for the given Rack Environment key.
+    def header_name(env_name)
+      env_name.
+        sub(/^HTTP_/, '').
+        downcase.
+        capitalize.
+        gsub(/_(.)/) { '-' + $1.upcase }
+    end
+
+  end
+
+end

data/rack-cache.gemspec

@@ -0,0 +1,74 @@
+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.2.0'
+  s.date = '2008-10-24'
+
+  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/events.dot
+    doc/faq.markdown
+    doc/index.markdown
+    doc/layout.html.erb
+    doc/license.markdown
+    doc/rack-cache.css
+    doc/storage.markdown
+    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/context.rb
+    lib/rack/cache/core.rb
+    lib/rack/cache/entitystore.rb
+    lib/rack/cache/headers.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/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/metastore_test.rb
+    test/options_test.rb
+    test/pony.jpg
+    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[COPYING]
+  s.add_dependency 'rack', '~> 0.4'
+
+  s.has_rdoc = true
+  s.homepage = "http://github.com/rtomayko/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,35 @@
+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.be == 'bling'
+    object.options['rack-cache.foo'].should.be == 'bar'
+  end
+  it 'takes a block; executes it during initialization' do
+    state, block_scope = 'not invoked', nil
+    object =
+      Rack::Cache.new @app do
+        block_scope = self
+        state = 'invoked'
+        should.respond_to :on
+      end
+    state.should.be == 'invoked'
+    object.should.be block_scope
+  end
+end