rack-cache 0.2.0

data/lib/rack/cache/context.rb

@@ -0,0 +1,95 @@
+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.
+
+  class Context
+    include Rack::Cache::Options
+    include Rack::Cache::Config
+    include Rack::Cache::Core
+
+    # The Rack application object immediately downstream.
+    attr_reader :backend
+
+    def initialize(backend, options={}, &block)
+      @errors = nil
+      @env = nil
+      @backend = backend
+      initialize_options options
+      initialize_core
+      initialize_config(&block)
+    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 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.
+    def call(env)
+      if env['rack.run_once']
+        call! env
+      else
+        clone.call! env
+      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
+    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
+    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)
+    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)
+    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
+    end
+
+    def info(*message, &bk)
+      log :info, *message, &bk
+    end
+
+    def warn(*message, &bk)
+      log :warn, *message, &bk
+    end
+
+    def trace(*message, &bk)
+      return unless verbose?
+      log :trace, *message, &bk
+    end
+  end
+
+end

data/lib/rack/cache/core.rb

@@ -0,0 +1,271 @@
+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
+
+  private
+    # Event handlers.
+    attr_reader :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
+    # Determine if the response's Last-Modified date matches the
+    # If-Modified-Since value provided in the original request.
+    def not_modified?
+      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)
+      @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'
+      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['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
+      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
+          trace "writing response to cache"
+          metastore.store(original_request, @entry, entitystore)
+          @response = @entry
+          :deliver
+        else
+          event
+        end
+      end
+    end
+
+    def perform_deliver
+      trace "delivering response ..."
+      if not_modified?
+        response.status = 304
+        response.body = []
+      end
+      transition(from=:deliver, to=[:finish, :error])
+    end
+
+    def perform_finish
+      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

data/lib/rack/cache/entitystore.rb

@@ -0,0 +1,224 @@
+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.
+  class EntityStore
+
+    # Read body calculating the SHA1 checksum and size while
+    # yielding each chunk to the block. If the body responds to close,
+    # call it after iteration is complete. Return a two-tuple of the form:
+    # [ hexdigest, size ].
+    def slurp(body)
+      digest, size = Digest::SHA1.new, 0
+      body.each do |part|
+        size += part.length
+        digest << part
+        yield part
+      end
+      body.close if body.respond_to? :close
+      [ digest.hexdigest, size ]
+    end
+
+    private :slurp
+
+
+    # Stores entity bodies on the heap using a Hash object.
+    class Heap < EntityStore
+
+      # Create the store with the specified backing Hash.
+      def initialize(hash={})
+        @hash = hash
+      end
+
+      # Determine whether the response body with the specified key (SHA1)
+      # exists in the store.
+      def exist?(key)
+        @hash.include?(key)
+      end
+
+      # Return an object suitable for use as a Rack response body for the
+      # specified key.
+      def open(key)
+        (body = @hash[key]) && body.dup
+      end
+
+      # Read all data associated with the given key and return as a single
+      # String.
+      def read(key)
+        (body = @hash[key]) && body.join
+      end
+
+      # Write the Rack response body immediately and return the SHA1 key.
+      def write(body)
+        buf = []
+        key, size = slurp(body) { |part| buf << part }
+        @hash[key] = buf
+        [key, size]
+      end
+
+      def self.resolve(uri)
+        new
+      end
+    end
+
+    HEAP = Heap
+    MEM  = Heap
+
+    # Stores entity bodies on disk at the specified path.
+    class Disk < EntityStore
+
+      # Path where entities should be stored. This directory is
+      # created the first time the store is instansiated if it does not
+      # already exist.
+      attr_reader :root
+
+      def initialize(root)
+        @root = root
+        FileUtils.mkdir_p root, :mode => 0755
+      end
+
+      def exist?(key)
+        File.exist?(body_path(key))
+      end
+
+      def read(key)
+        File.read(body_path(key))
+      rescue Errno::ENOENT
+        nil
+      end
+
+      # Open the entity body and return an IO object. The IO object's
+      # each method is overridden to read 8K chunks instead of lines.
+      def open(key)
+        io = File.open(body_path(key), 'rb')
+        def io.each
+          while part = read(8192)
+            yield part
+          end
+        end
+        io
+      rescue Errno::ENOENT
+        nil
+      end
+
+      def write(body)
+        filename = ['buf', $$, Thread.current.object_id].join('-')
+        temp_file = storage_path(filename)
+        key, size =
+          File.open(temp_file, 'wb') { |dest|
+            slurp(body) { |part| dest.write(part) }
+          }
+
+        path = body_path(key)
+        if File.exist?(path)
+          File.unlink temp_file
+        else
+          FileUtils.mkdir_p File.dirname(path), :mode => 0755
+          FileUtils.mv temp_file, path
+        end
+        [key, size]
+      end
+
+    protected
+      def storage_path(stem)
+        File.join root, stem
+      end
+
+      def spread(key)
+        key = key.dup
+        key[2,0] = '/'
+        key
+      end
+
+      def body_path(key)
+        storage_path spread(key)
+      end
+
+      def self.resolve(uri)
+        path = File.expand_path(uri.opaque || uri.path)
+        new path
+      end
+    end
+
+    DISK = Disk
+    FILE = Disk
+
+    # Stores entity bodies in memcached.
+    class MemCache < EntityStore
+
+      # The underlying Memcached instance used to communicate with the
+      # memcahced daemon.
+      attr_reader :cache
+
+      def initialize(server="localhost:11211", options={})
+        @cache =
+          if server.respond_to?(:stats)
+            server
+          else
+            require 'memcached'
+            Memcached.new(server, options)
+          end
+      end
+
+      def exist?(key)
+        cache.append(key, '')
+        true
+      rescue Memcached::NotStored
+        false
+      end
+
+      def read(key)
+        cache.get(key, false)
+      rescue Memcached::NotFound
+        nil
+      end
+
+      def open(key)
+        if data = read(key)
+          [data]
+        else
+          nil
+        end
+      end
+
+      def write(body)
+        buf = StringIO.new
+        key, size = slurp(body){|part| buf.write(part) }
+        cache.set(key, buf.string, 0, false)
+        [key, size]
+      end
+
+      extend Rack::Utils
+
+      # Create MemCache store for the given URI. The URI must specify
+      # a host and may specify a port, namespace, and options:
+      #
+      # memcached://example.com:11211/namespace?opt1=val1&opt2=val2
+      #
+      # Query parameter names and values are documented with the memcached
+      # library: http://tinyurl.com/4upqnd
+      def self.resolve(uri)
+        server = "#{uri.host}:#{uri.port || '11211'}"
+        options = parse_query(uri.query)
+        options.keys.each do |key|
+          value =
+            case value = options.delete(key)
+            when 'true' ; true
+            when 'false' ; false
+            else value.to_sym
+            end
+          options[k.to_sym] = value
+        end
+        options[:namespace] = uri.path.sub(/^\//, '')
+        new server, options
+      end
+    end
+
+    MEMCACHE = MemCache
+    MEMCACHED = MemCache
+
+  end
+
+end