rack-client 0.1.1 → 0.3.0

data/lib/rack/client/cache/metastore.rb

@@ -0,0 +1,133 @@
+module Rack
+  module Client
+    module Cache
+      class MetaStore
+
+        def lookup(request, entity_store)
+          key = cache_key(request)
+          entries = read(key)
+
+          # bail out if we have nothing cached
+          return nil if entries.empty?
+
+          # find a cached entry that matches the request.
+          env = request.env
+          match = entries.detect{|req,res| requests_match?(res['Vary'], env, req)}
+          return nil if match.nil?
+
+          req, res = match
+          if body = entity_store.open(res['X-Content-Digest'])
+            restore_response(res, body)
+          else
+            # TODO the metastore referenced an entity that doesn't exist in
+            # the entitystore. we definitely want to return nil but we should
+            # also purge the entry from the meta-store when this is detected.
+          end
+        end
+
+        # Write a cache entry to the store under the given key. Existing
+        # entries are read and any that match the response are removed.
+        # This method calls #write with the new list of cache entries.
+        def store(request, response, entity_store)
+          key = cache_key(request)
+          stored_env = persist_request(request)
+
+          # write the response body to the entity store if this is the
+          # original response.
+          if response.headers['X-Content-Digest'].nil?
+            digest, size = entity_store.write(response.body)
+            response.headers['X-Content-Digest'] = digest
+            response.headers['Content-Length'] = size.to_s unless response.headers['Transfer-Encoding']
+            response.body = entity_store.open(digest)
+          end
+
+          # read existing cache entries, remove non-varying, and add this one to
+          # the list
+          vary = response.vary
+          entries =
+            read(key).reject do |env,res|
+            (vary == res['Vary']) &&
+              requests_match?(vary, env, stored_env)
+            end
+
+          headers = persist_response(response)
+          headers.delete 'Age'
+
+          entries.unshift [stored_env, headers]
+          write key, entries
+          key
+        end
+
+        def cache_key(request)
+          keygen = request.env['rack-client-cache.cache_key'] || Key
+          keygen.call(request)
+        end
+
+        # Extract the environment Hash from +request+ while making any
+        # necessary modifications in preparation for persistence. The Hash
+        # returned must be marshalable.
+        def persist_request(request)
+          env = request.env.dup
+          env.reject! { |key,val| key =~ /[^0-9A-Z_]/ }
+          env
+        end
+
+        def persist_response(response)
+          hash = response.headers.to_hash
+          hash['X-Status'] = response.status.to_s
+          hash
+        end
+
+        # Converts a stored response hash into a Response object. The caller
+        # is responsible for loading and passing the body if needed.
+        def restore_response(hash, body=nil)
+          status = hash.delete('X-Status').to_i
+          Rack::Client::Cache::Response.new(status, hash, body)
+        end
+
+        # Determine whether the two environment hashes are non-varying based on
+        # the vary response header value provided.
+        def requests_match?(vary, env1, env2)
+          return true if vary.nil? || vary == ''
+          vary.split(/[\s,]+/).all? do |header|
+            key = "HTTP_#{header.upcase.tr('-', '_')}"
+            env1[key] == env2[key]
+          end
+        end
+
+        class Heap < MetaStore
+          def initialize(hash={})
+            @hash = hash
+          end
+
+          def read(key)
+            @hash.fetch(key, []).collect do |req,res|
+              [req.dup, res.dup]
+            end
+          end
+
+          def write(key, entries)
+            @hash[key] = entries
+          end
+
+          def purge(key)
+            @hash.delete(key)
+            nil
+          end
+
+          def to_hash
+            @hash
+          end
+
+          def self.resolve(uri)
+            new
+          end
+        end
+
+        HEAP = Heap
+        MEM = HEAP
+
+      end
+    end
+  end
+end

data/lib/rack/client/cache/options.rb

@@ -0,0 +1,147 @@
+module Rack
+  module Client
+    module Cache
+      # vendored, originally from rack-cache.
+      module Options
+        def self.option_accessor(key)
+          name = option_name(key)
+          define_method(key) { || options[name] }
+          define_method("#{key}=") { |value| options[name] = value }
+          define_method("#{key}?") { || !! options[name] }
+        end
+
+        def option_name(key)
+          case key
+          when Symbol ; "rack-client-cache.#{key}"
+          when String ; key
+          else raise ArgumentError
+          end
+        end
+        module_function :option_name
+
+        # 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 custom cache key generator, which can be anything that responds to :call.
+        # By default, this is the Rack::Cache::Key class, but you can implement your
+        # own generator. A cache key generator gets passed a request and generates the
+        # appropriate cache key.
+        #
+        # In addition to setting the generator to an object, you can just pass a block
+        # instead, which will act as the cache key generator:
+        #
+        #   set :cache_key do |request|
+        #     request.fullpath.replace(/\//, '-')
+        #   end
+        option_accessor :cache_key
+
+        # A URI specifying the entity-store implementation 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
+
+        # Set of request headers that trigger "private" cache-control behavior
+        # on responses that don't explicitly state whether the response is
+        # public or private via a Cache-Control directive. Applications that use
+        # cookies for authorization may need to add the 'Cookie' header to this
+        # list.
+        #
+        # Default: ['Authorization', 'Cookie']
+        option_accessor :private_headers
+
+        # Specifies whether the client can force a cache reload by including a
+        # Cache-Control "no-cache" directive in the request. This is enabled by
+        # default for compliance with RFC 2616.
+        option_accessor :allow_reload
+
+        # Specifies whether the client can force a cache revalidate by including
+        # a Cache-Control "max-age=0" directive in the request. This is enabled by
+        # default for compliance with RFC 2616.
+        option_accessor :allow_revalidate
+
+        # 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, &block)
+          if block_given?
+            write_option option, block
+          elsif value == self
+            self.options = option.to_hash
+          else
+            write_option option, value
+          end
+        end
+
+        private
+        def initialize_options(options={})
+          @default_options = {
+        'rack-client-cache.cache_key'        => Key,
+        'rack-client-cache.verbose'          => true,
+        'rack-client-cache.storage'          => Storage.instance,
+        'rack-client-cache.metastore'        => 'heap:/',
+        'rack-client-cache.entitystore'      => 'heap:/',
+        'rack-client-cache.default_ttl'      => 0,
+        'rack-client-cache.private_headers'  => ['Authorization', 'Cookie'],
+        'rack-client-cache.allow_reload'     => false,
+        'rack-client-cache.allow_revalidate' => false
+          }
+          self.options = options
+        end
+
+        def read_option(key)
+          options[option_name(key)]
+        end
+
+        def write_option(key, value)
+          options[option_name(key)] = value
+        end
+      end
+    end
+  end
+end

data/lib/rack/client/cache/request.rb

@@ -0,0 +1,46 @@
+module Rack
+  module Client
+    module Cache
+      class Request < Rack::Request
+        include Options
+
+        def cacheable?
+          request_method == 'GET'
+        end
+
+        def env
+          return super if @calculating_headers
+          cache_control_headers.merge(super)
+        end
+
+        def cache_control_headers
+          @calculating_headers = true
+          return {} unless cacheable?
+          entry = metastore.lookup(self, entitystore)
+
+          if entry
+            headers_for(entry)
+          else
+            {}
+          end
+        ensure
+          @calculating_headers = nil
+        end
+
+        def headers_for(response)
+          return 'HTTP_If-None-Match' => response.etag
+        end
+
+        def metastore
+          uri = options['rack-client-cache.metastore']
+          storage.resolve_metastore_uri(uri)
+        end
+
+        def entitystore
+          uri = options['rack-client-cache.entitystore']
+          storage.resolve_entitystore_uri(uri)
+        end
+      end
+    end
+  end
+end

data/lib/rack/client/cache/response.rb

@@ -0,0 +1,62 @@
+module Rack
+  module Client
+    module Cache
+      class Response < Rack::Client::Response
+        include Rack::Response::Helpers
+
+        def not_modified?
+          status == 304
+        end
+
+        alias_method :finish, :to_a
+
+        # Status codes of responses that MAY be stored by a cache or used in reply
+        # to a subsequent request.
+        #
+        # http://tools.ietf.org/html/rfc2616#section-13.4
+        CACHEABLE_RESPONSE_CODES = [
+          200, # OK
+          203, # Non-Authoritative Information
+          300, # Multiple Choices
+          301, # Moved Permanently
+          302, # Found
+          404, # Not Found
+          410  # Gone
+        ].to_set
+
+        # A Hash of name=value pairs that correspond to the Cache-Control header.
+        # Valueless parameters (e.g., must-revalidate, no-store) have a Hash value
+        # of true. This method always returns a Hash, empty if no Cache-Control
+        # header is present.
+        def cache_control
+          @cache_control ||= CacheControl.new(headers['Cache-Control'])
+        end
+
+        def cacheable?
+          return false unless CACHEABLE_RESPONSE_CODES.include?(status)
+          return false if cache_control.no_store? || cache_control.private?
+          validateable? || fresh?
+        end
+
+        # The literal value of ETag HTTP header or nil if no ETag is specified.
+        def etag
+          headers['ETag']
+        end
+
+        def validateable?
+          headers.key?('Last-Modified') || headers.key?('ETag')
+        end
+
+        # The literal value of the Vary header, or nil when no header is present.
+        def vary
+          headers['Vary']
+        end
+
+        # Does the response include a Vary header?
+        def vary?
+          ! vary.nil?
+        end
+      end
+    end
+  end
+end

data/lib/rack/client/cache/storage.rb

@@ -0,0 +1,43 @@
+module Rack
+  module Client
+    module Cache
+      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 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
+          end
+        end
+
+        def clear
+          @metastores.clear
+          @entitystores.clear
+          nil
+        end
+
+        @@singleton_instance = new
+        def self.instance
+          @@singleton_instance
+        end
+      end
+    end
+  end
+end

data/lib/rack/client/cookie_jar.rb

@@ -0,0 +1,17 @@
+module Rack
+  module Client
+    module CookieJar
+      def self.new(app, &b)
+        Context.new(app, &b)
+      end
+    end
+  end
+end
+
+require 'rack/client/cookie_jar/options'
+require 'rack/client/cookie_jar/cookie'
+require 'rack/client/cookie_jar/cookiestore'
+require 'rack/client/cookie_jar/context'
+require 'rack/client/cookie_jar/request'
+require 'rack/client/cookie_jar/response'
+require 'rack/client/cookie_jar/storage'