josh-rack-cache 0.5.1

data/lib/rack/cache/context.rb

@@ -0,0 +1,253 @@
+require 'rack/cache/options'
+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, including the core logic engine.
+  class Context
+    include Rack::Cache::Options
+
+    # Array of trace Symbols
+    attr_reader :trace
+
+    # The Rack application object immediately downstream.
+    attr_reader :backend
+
+    def initialize(backend, options={})
+      @backend = backend
+      @trace = []
+
+      initialize_options options
+      yield self if block_given?
+
+      @private_header_keys =
+        private_headers.map { |name| "HTTP_#{name.upcase.tr('-', '_')}" }
+    end
+
+    # 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 dup 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
+
+    # 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
+
+  private
+
+    # Record that an event took place.
+    def record(event)
+      @trace << event
+    end
+
+    # 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
+
+    # 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
+
+    # Whether the cache entry is "fresh enough" to satisfy the request.
+    def fresh_enough?(entry)
+      if entry.fresh?
+        if allow_revalidate? && max_age = @request.cache_control.max_age
+          max_age > 0 && max_age >= entry.age
+        else
+          true
+        end
+      end
+    end
+
+    # Delegate the request to the backend and create the response.
+    def forward
+      Response.new(*backend.call(@env))
+    end
+
+    # 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
+
+    # Invalidate POST, PUT, DELETE and all methods not understood by this cache
+    # See RFC2616 13.10
+    def invalidate
+      metastore.invalidate(@request, entitystore)
+    rescue Exception => e
+      log_error(e)
+      pass
+    else
+      record :invalidate
+      pass
+    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? && allow_reload?
+        record :reload
+        fetch
+      else
+        begin
+          entry = metastore.lookup(@request, entitystore)
+        rescue Exception => e
+          log_error(e)
+          return pass
+        end
+        if entry
+          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
+    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)
+      metastore.store(@request, response, entitystore)
+      response.headers['Age'] = response.age.to_s
+    rescue Exception => e
+      log_error(e)
+      nil
+    else
+      record :store
+    end
+
+    def log_error(exception)
+      @env['rack.errors'].write("cache error: #{exception.message}\n#{exception.backtrace.join("\n")}\n")
+    end
+  end
+end

data/lib/rack/cache/entitystore.rb

@@ -0,0 +1,339 @@
+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 += bytesize(part)
+        digest << part
+        yield part
+      end
+      body.close if body.respond_to? :close
+      [digest.hexdigest, size]
+    end
+
+    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.
+    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
+
+      # Remove the body corresponding to key; return nil.
+      def purge(key)
+        @hash.delete(key)
+        nil
+      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.open(body_path(key), 'rb') { |f| f.read }
+      rescue Errno::ENOENT
+        nil
+      end
+
+      class Body < ::File #:nodoc:
+        def each
+          while part = read(8192)
+            yield part
+          end
+        end
+        alias_method :to_path, :path
+      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)
+        Body.open(body_path(key), 'rb')
+      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
+
+      def purge(key)
+        File.unlink body_path(key)
+        nil
+      rescue Errno::ENOENT
+        nil
+      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
+
+    # Base class for memcached entity stores.
+    class MemCacheBase < EntityStore
+      # The underlying Memcached instance used to communicate with the
+      # memcached daemon.
+      attr_reader :cache
+
+      extend Rack::Utils
+
+      def open(key)
+        data = read(key)
+        data && [data]
+      end
+
+      def self.resolve(uri)
+        if uri.respond_to?(:scheme)
+          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
+        else
+          # if the object provided is not a URI, pass it straight through
+          # to the underlying implementation.
+          new uri
+        end
+      end
+    end
+
+    # Uses the memcache-client ruby library. This is the default unless
+    # the memcached library has already been required.
+    class MemCache < MemCacheBase
+      def initialize(server="localhost:11211", options={})
+        @cache =
+          if server.respond_to?(:stats)
+            server
+          else
+            require 'memcache'
+            ::MemCache.new(server, options)
+          end
+      end
+
+      def exist?(key)
+        !cache.get(key).nil?
+      end
+
+      def read(key)
+        cache.get(key)
+      end
+
+      def write(body)
+        buf = StringIO.new
+        key, size = slurp(body){|part| buf.write(part) }
+        [key, size] if cache.set(key, buf.string)
+      end
+
+      def purge(key)
+        cache.delete(key)
+        nil
+      end
+    end
+
+    # Uses the memcached client library. The ruby based memcache-client is used
+    # in preference to this store unless the memcached library has already been
+    # required.
+    class MemCached < MemCacheBase
+      def initialize(server="localhost:11211", options={})
+        options[:prefix_key] ||= options.delete(:namespace) if options.key?(:namespace)
+        @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 write(body)
+        buf = StringIO.new
+        key, size = slurp(body){|part| buf.write(part) }
+        cache.set(key, buf.string, 0, false)
+        [key, size]
+      end
+
+      def purge(key)
+        cache.delete(key)
+        nil
+      rescue ::Memcached::NotFound
+        nil
+      end
+    end
+
+    MEMCACHE =
+      if defined?(::Memcached)
+        MemCached
+      else
+        MemCache
+      end
+
+    MEMCACHED = MEMCACHE
+
+    class GAEStore < EntityStore
+      attr_reader :cache
+
+      def initialize(options = {})
+        require 'rack/cache/appengine'
+        @cache = Rack::Cache::AppEngine::MemCache.new(options)
+      end
+
+      def exist?(key)
+        cache.contains?(key)
+      end
+
+      def read(key)
+        cache.get(key)
+      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.put(key, buf.string)
+        [key, size]
+      end
+
+      def purge(key)
+        cache.delete(key)
+        nil
+      end
+
+      def self.resolve(uri)
+        self.new(:namespace => uri.host)
+      end
+
+    end
+
+    GAECACHE = GAEStore
+    GAE = GAEStore
+
+  end
+
+end