faraday-http-cache 0.0.1.dev

data/LICENSE

@@ -0,0 +1,13 @@
+Copyright 2012 Plataformatec.
+
+  Licensed under the Apache License, Version 2.0 (the "License");
+  you may not use this file except in compliance with the License.
+  You may obtain a copy of the License at
+
+      http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing, software
+  distributed under the License is distributed on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  See the License for the specific language governing permissions and
+  limitations under the License.

data/README.md

@@ -0,0 +1,73 @@
+# Faraday Http Cache
+a [Faraday](https://github.com/technoweenie/faraday) middleware that respects HTTP cache,
+by checking expiration and validation of the stored responses.
+
+## Installation
+
+Add it to your Gemfile:
+
+```ruby
+gem 'faraday-http-cache'
+```
+
+## Usage and configuration
+
+You have to use the middleware in the Faraday instance that you want to. You can use the new
+shortcut using a symbol or passing the middleware class
+
+```ruby
+client = Faraday.new do |builder|
+  builder.use :http_cache
+  # or
+  builder.use Faraday::HttpCache
+
+  builder.adapter Faraday.default_adapter
+end
+```
+
+The middleware uses the `ActiveSupport::Cache` API to record the responses from the targeted
+endpoints, and any extra configuration option will be used to setup the cache store.
+
+```ruby
+# Connect the middleware to a Memcache instance.
+client = Faraday.new do |builder|
+  builder.use :http_cache, :mem_cache_store, "localhost:11211"
+  builder.adapter Faraday.default_adapter
+end
+
+# Or use the Rails.cache instance inside your Rails app.
+client = Faraday.new do |builder|
+  builder.use :http_cache, Rails.cache
+  builder.adapter Faraday.default_adapter
+end
+```
+
+The default store provided by ActiveSupport is the `MemoryStore` one, so it's important to
+configure a proper one for your production environment.
+
+### Logging
+
+You can provide a `:logger` option that will be receive debug informations based on the middleware
+operations:
+
+```ruby
+client = Faraday.new do |builder|
+  builder.use :http_cache, :logger => Rails.logger
+  builder.adapter Faraday.default_adapter
+end
+
+client.get('http://site/api/users')
+# logs "HTTP Cache: [GET users] miss, store"
+```
+
+## See it live
+
+You can clone this repository, install it's dependencies with Bundler (run `bundle install`) and
+execute the `examples/twitter.rb` file to see a sample of the middleware usage - it's issuing
+requests to the Twitter API and caching them, so the rate limit isn't reduced on every request by
+the client object. After sleeping for 5 minutes the cache will expire and the client will hit the
+Twitter API again.
+
+## License
+
+Copyright (c) 2012 Plataformatec. See LICENSE file.

data/lib/faraday/http_cache/cache_control.rb

@@ -0,0 +1,112 @@
+module Faraday
+  class HttpCache < Faraday::Middleware
+    # Internal: a class to represent the 'Cache-Control' header options.
+    # This implementation is based on 'rack-cache' internals by Ryan Tomayko.
+    # It breaks the several directives into keys/values and stores them into
+    # a Hash.
+    class CacheControl
+
+      # Internal: Initialize a new CacheControl.
+      def initialize(string)
+        @directives = {}
+        parse(string)
+      end
+
+      # Internal: Checks if the 'public' directive is present.
+      def public?
+        @directives['public']
+      end
+
+      # Internal: Checks if the 'private' directive is present.
+      def private?
+        @directives['private']
+      end
+
+      # Internal: Checks if the 'no-cache' directive is present.
+      def no_cache?
+        @directives['no-cache']
+      end
+
+      # Internal: Checks if the 'no-store' directive is present.
+      def no_store?
+        @directives['no-store']
+      end
+
+      # Internal: Gets the 'max-age' directive as an Integer.
+      #
+      # Returns nil if the 'max-age' directive isn't present.
+      def max_age
+        @directives['max-age'].to_i if @directives.key?('max-age')
+      end
+
+      # Internal: Gets the 's-maxage' directive as an Integer.
+      #
+      # Returns nil if the 's-maxage' directive isn't present.
+      def shared_max_age
+        @directives['s-maxage'].to_i if @directives.key?('s-maxage')
+      end
+      alias_method :s_maxage, :shared_max_age
+
+      # Internal: Checks if the 'must-revalidate' directive is present.
+      def must_revalidate?
+        @directives['must-revalidate']
+      end
+
+      # Internal: Checks if the 'proxy-revalidate' directive is present.
+      def proxy_revalidate?
+        @directives['proxy-revalidate']
+      end
+
+      # Internal: Gets the String representation for the cache directives.
+      # Directives are joined by a '=' and then combined into a single String
+      # separated by commas. Directives with a 'true' value will omit the '='
+      # sign and their value.
+      #
+      # Returns the Cache Control string.
+      def to_s
+        booleans, values = [], []
+
+        @directives.each do |key, value|
+          if value == true
+            booleans << key
+          elsif value
+            values << "#{key}=#{value}"
+          end
+        end
+
+        (booleans.sort + values.sort).join(', ')
+      end
+
+      private
+
+      # Internal: Parses the Cache Control string into the directives Hash.
+      # Existing whitespaces are removed, and the string is splited on commas.
+      # For each segment, everything before a '=' will be treated as the key
+      # and the excedding will be treated as the value. If only the key is
+      # present the assigned value will defaults to true.
+      #
+      # Examples:
+      #   parse("max-age=600")
+      #   @directives
+      #    # => { "max-age" => "600"}
+      #
+      #   parse("max-age")
+      #   @directives
+      #    # => { "max-age" => true }
+      #
+      # Returns nothing.
+      def parse(string)
+        string = string.to_s
+
+        return if string.empty?
+
+        string.delete(' ').split(',').each do |part|
+          next if part.empty?
+
+          name, value = part.split('=', 2)
+          @directives[name.downcase] = (value || true) unless name.empty?
+        end
+      end
+    end
+  end
+end

data/lib/faraday/http_cache/response.rb

@@ -0,0 +1,170 @@
+require 'time'
+require 'faraday/http_cache/cache_control'
+
+module Faraday
+  class HttpCache < Faraday::Middleware
+    # Internal: a class to represent a response from a Faraday request.
+    # It decorates the response hash into a smarter object that queries
+    # the response headers and status informations about how the caching
+    # middleware should handle this specific response.
+    class Response
+      # Internal: List of status codes that can be cached:
+      # * 200 - 'OK'
+      # * 203 - 'Non-Authoritative Information'
+      # * 300 - 'Multiple Choices'
+      # * 301 - 'Moved Permanently'
+      # * 302 - 'Found'
+      # * 404 - 'Not Found'
+      # * 410 - 'Gone'
+      CACHEABLE_STATUS_CODES = [200, 203, 300, 301, 302, 404, 410]
+
+      # Internal: Gets the actual response Hash (status, headers and body).
+      attr_reader :payload
+
+      # Internal: Gets the 'Last-Modified' header from the headers Hash.
+      attr_reader :last_modified
+
+      # Internal: Gets the 'ETag' header from the headers Hash.
+      attr_reader :etag
+
+      # Internal: Initialize a new Response with the response payload from
+      # a Faraday request.
+      #
+      # payload - the response Hash returned by a Faraday request.
+      #           :status - the status code from the response.
+      #           :response_headers - a 'Hash' like object with the headers.
+      #           :body - the response body.
+      def initialize(payload = {})
+        @now = Time.now
+        @payload = payload
+        wrap_headers!
+        headers['Date'] ||= @now.httpdate
+
+        @last_modified = headers['Last-Modified']
+        @etag = headers['ETag']
+      end
+
+      # Internal: Checks the response freshness based on expiration headers.
+      # The calculated 'ttl' should be present and bigger than 0.
+      #
+      # Returns true if the response is fresh, otherwise false.
+      def fresh?
+        ttl && ttl > 0
+      end
+
+      # Internal: Checks if the Response returned a 'Not Modified' status.
+      #
+      # Returns true if the response status code is 304.
+      def not_modified?
+        @payload[:status] == 304
+      end
+
+      # Internal: Checks if the response can be cached by the client.
+      # This is validated by the 'Cache-Control' directives, the response
+      # status code and it's freshness or validation status.
+      #
+      # Returns false if the 'Cache-Control' says that we can't store the
+      # response, or if isn't fresh or it can't be revalidated with the origin
+      # server. Otherwise, returns true.
+      def cacheable?
+        return false if cache_control.private? || cache_control.no_store?
+
+        cacheable_status_code? && (validateable? || fresh?)
+      end
+
+      # Internal: Gets the response age in seconds.
+      #
+      # Returns the 'Age' header if present, or subtracts the response 'date'
+      # from the current time.
+      def age
+        (headers['Age'] || (@now - date)).to_i
+      end
+
+      # Internal: Calculates the 'Time to live' left on the Response.
+      #
+      # Returns the remaining seconds for the response, or nil the 'max_age'
+      # isn't present.
+      def ttl
+        max_age - age if max_age
+      end
+
+      # Internal: Parses the 'Date' header back into a Time instance.
+      #
+      # Returns the Time object.
+      def date
+        Time.httpdate(headers['Date'])
+      end
+
+      # Internal: Gets the response max age.
+      # The max age is extracted from one of the following:
+      # * The shared max age directive from the 'Cache-Control' header;
+      # * The max age directive from the 'Cache-Control' header;
+      # * The difference between the 'Expires' header and the response
+      #   date.
+      #
+      # Returns the max age value in seconds or nil if all options above fails.
+      def max_age
+        cache_control.shared_max_age ||
+          cache_control.max_age ||
+          (expires && (expires - date))
+      end
+
+      # Internal: Creates a new 'Faraday::Response'.
+      #
+      # Returns a new instance of a 'Faraday::Response' with the payload.
+      def to_response
+        Faraday::Response.new(@payload)
+      end
+
+      private
+
+      # Internal: Checks if this response can be revalidated.
+      #
+      # Returns true if the 'headers' contains a 'Last-Modified' or an 'ETag'
+      # entry.
+      def validateable?
+        headers.key?('Last-Modified') || headers.key?('ETag')
+      end
+
+      # Internal: Validates the response status against the
+      # `CACHEABLE_STATUS_CODES' constant.
+      #
+      # Returns true if the constant includes the response status code.
+      def cacheable_status_code?
+        CACHEABLE_STATUS_CODES.include?(@payload[:status])
+      end
+
+      # Internal: Gets the 'Expires' in a Time object.
+      #
+      # Returns the Time object, or nil if the header isn't present.
+      def expires
+        headers['Expires'] && Time.httpdate(headers['Expires'])
+      end
+
+      # Internal: Gets the 'CacheControl' object.
+      def cache_control
+        @cache_control ||= CacheControl.new(headers['Cache-Control'])
+      end
+
+      # Internal: Converts the headers 'Hash' into 'Faraday::Utils::Headers'.
+      # Faraday actually uses a Hash subclass, `Faraday::Utils::Headers` to
+      # store the headers hash. When retrieving a serialized response,
+      # the headers object is decoded as a 'Hash' instead of the actual
+      # 'Faraday::Utils::Headers' object, so we need to ensure that the
+      # 'response_headers' is always a 'Headers' instead of a plain 'Hash'.
+      #
+      # Returns nothing.
+      def wrap_headers!
+        headers = @payload[:response_headers]
+
+        @payload[:response_headers] = Faraday::Utils::Headers.new
+        @payload[:response_headers].update(headers) if headers
+      end
+
+      # Internal: Gets the headers 'Hash' from the payload.
+      def headers
+        @payload[:response_headers]
+      end
+    end
+  end
+end

data/lib/faraday/http_cache/storage.rb

@@ -0,0 +1,71 @@
+require 'digest/sha1'
+require 'active_support/cache'
+require 'active_support/core_ext/hash/keys'
+
+module Faraday
+  class HttpCache < Faraday::Middleware
+    # Internal: A Wrapper around a ActiveSupport::CacheStore to store responses.
+    #
+    # Examples
+    #   # Creates a new Storage using a MemCached backend from ActiveSupport.
+    #   Faraday::HttpCache::Storage.new(:mem_cache_store)
+    #
+    #   # Reuse some other instance of a ActiveSupport::CacheStore object.
+    #   Faraday::HttpCache::Storage.new(Rails.cache)
+    class Storage
+      attr_reader :cache
+
+      # Internal: Initialize a new Storage object with a cache backend.
+      #
+      # store - An ActiveSupport::CacheStore identifier (default: nil).
+      # options - The Hash options for the CacheStore backend (default: {}).
+      def initialize(store = nil, options = {})
+        @cache = ActiveSupport::Cache.lookup_store(store, options)
+      end
+
+      # Internal: Writes a response with a key based on the given request.
+      #
+      # request - The Hash containing the request information.
+      #           :method          - The HTTP Method used for the request.
+      #           :url             - The requested URL.
+      #           :request_headers - The custom headers for the request.
+      # response - The Faraday::HttpCache::Response instance to be stored.
+      def write(request, response)
+        key = cache_key_for(request)
+        value = MultiJson.dump(response.payload)
+
+        cache.write(key, value)
+      end
+
+      # Internal: Reads a key based on the given request from the underlying cache.
+      #
+      # request - The Hash containing the request information.
+      #           :method          - The HTTP Method used for the request.
+      #           :url             - The requested URL.
+      #           :request_headers - The custom headers for the request.
+      # klass - The Class to be instantiated with the recovered informations.
+      def read(request, klass = Faraday::HttpCache::Response)
+        key = cache_key_for(request)
+        value = cache.read(key)
+
+        if value
+          payload = MultiJson.load(value).symbolize_keys
+          klass.new(payload)
+        end
+      end
+
+      private
+
+      # Internal: Generates a String key for a given request object.
+      # The request object is folded into a sorted Array (since we can't count
+      # on hashes order on Ruby 1.8), encoded as JSON and digested as a `SHA1`
+      # string.
+      #
+      # Returns the encoded String.
+      def cache_key_for(request)
+        array = request.stringify_keys.to_a.sort
+        Digest::SHA1.hexdigest(MultiJson.dump(array))
+      end
+    end
+  end
+end

data/lib/faraday/http_cache.rb

@@ -0,0 +1,228 @@
+require 'faraday'
+require 'multi_json'
+
+require 'active_support/core_ext/hash/slice'
+
+require 'faraday/http_cache/storage'
+require 'faraday/http_cache/response'
+
+module Faraday
+  # Public: The middleware responsible for caching and serving responses.
+  # The middleware use the provided configuration options to establish a
+  # 'Faraday::HttpCache::Storage' to cache responses retrieved by the stack
+  # adapter. If a stored response can be served again for a subsequent
+  # request, the middleware will return the response instead of issuing a new
+  # request to it's server. This middleware should be the last attached handler
+  # to your stack, so it will be closest to the inner app, avoiding issues
+  # with other middlewares on your stack.
+  #
+  # Examples:
+  #
+  #   # Using the middleware with a simple client:
+  #   client = Faraday.new do |builder|
+  #     builder.user :http_cache
+  #     builder.adapter Faraday.default_adapter
+  #   end
+  #
+  #   # Attach a Logger to the middleware.
+  #   client = Faraday.new do |builder|
+  #     builder.use :http_cache, :logger => my_logger_instance
+  #     builder.adapter Faraday.default_adapter
+  #   end
+  #
+  #   # Provide an existing CacheStore (for instance, from a Rails app)
+  #   client = Faraday.new do |builder|
+  #     builder.use :http_cache, Rails.cache
+  #   end
+  class HttpCache < Faraday::Middleware
+
+    # Public: Initializes a new HttpCache middleware.
+    #
+    # app - the next endpoint on the 'Faraday' stack.
+    # arguments - aditional options to setup the logger and the storage.
+    #
+    # Examples:
+    #
+    #   # Initialize the middleware with a logger.
+    #   Faraday::HttpCache.new(app, :logger => my_logger)
+    #
+    #   # Initialize the middleware with a FileStore at the 'tmp' dir.
+    #   Faraday::HttpCache.new(app, :file_store, 'tmp')
+    def initialize(app, *arguments)
+      super(app)
+
+      if arguments.last.is_a? Hash
+        options = arguments.pop
+        @logger = options.delete(:logger)
+      else
+        options = arguments
+      end
+
+      store = arguments.shift
+
+      @storage = Storage.new(store, options)
+    end
+
+    # Public: Process the request into a duplicate of this instance to
+    # ensure that the internal state is preserved.
+    def call(env)
+      dup.call!(env)
+    end
+
+    # Internal: Process the stack request to try to serve a cache response.
+    # On a cacheable request, the middleware will attempt to locate a
+    # valid stored response to serve. On a cache miss, the middleware will
+    # forward the request and try to store the response for future requests.
+    # If the request can't be cached, the request will be delegated directly
+    # to the underlying app and does nothing to the response.
+    # The processed steps will be recorded to be logged once the whole
+    # process is finished.
+    #
+    # Returns a 'Faraday::Response' instance.
+    def call!(env)
+      @trace = []
+      @request = create_request(env)
+
+      response = nil
+
+      if can_cache?(@request[:method])
+        response = process(env)
+      else
+        trace :unacceptable
+        response = @app.call(env)
+      end
+
+      response.on_complete do
+        log_request
+      end
+    end
+
+    private
+    # Internal: Validates if the current request method is valid for caching.
+    #
+    # Returns true if the method is ':get' or ':head'.
+    def can_cache?(method)
+      method == :get || method == :head
+    end
+
+    # Internal: Tries to located a valid response or forwards the call to the stack.
+    # * If no entry is present on the storage, the 'fetch' method will forward
+    # the call to the remaining stack and return the new response.
+    # * If a fresh response is found, the middleware will abort the remaining
+    # stack calls and return the stored response back to the client.
+    # * If a response is found but isn't fresh anymore, the middleware will
+    # revalidate the response back to the server.
+    #
+    # env - the environment 'Hash' provided from the 'Faraday' stack.
+    #
+    # Returns the actual 'Faraday::Response' instance to be served.
+    def process(env)
+      entry = @storage.read(@request)
+
+      return fetch(env) if entry.nil?
+
+      if entry.fresh?
+        response = entry.to_response
+        trace :fresh
+      else
+        response = validate(entry, env)
+      end
+
+      response
+    end
+
+    # Internal: Tries to validated a stored entry back to it's origin server
+    # using the 'If-Modified-Since' and 'If-None-Match' headers with the
+    # existing 'Last-Modified' and 'ETag' headers. If the new response
+    # is marked as 'Not Modified', the previous stored response will be used
+    # and forwarded against the Faraday stack. Otherwise, the freshly new
+    # response will be stored (replacing the old one) and used.
+    #
+    # entry - a stale 'Faraday::HttpCache::Response' retrieved from the cache.
+    # env - the environment 'Hash' to perform the request.
+    #
+    # Returns the 'Faraday::HttpCache::Response' to be forwarded into the stack.
+    def validate(entry, env)
+      headers = env[:request_headers]
+      headers['If-Modified-Since'] = entry.last_modified if entry.last_modified
+      headers['If-None-Match'] = entry.etag if entry.etag
+
+      @app.call(env).on_complete do |env|
+        response = Response.new(env)
+        if response.not_modified?
+          trace :valid
+          env.merge!(entry.payload)
+          response = entry
+        end
+        store(response)
+      end
+    end
+
+    # Internal: Records a traced action to be used by the logger once the
+    # request/response phase is finished.
+    #
+    # operation - the name of the performed action, a String or Symbol.
+    #
+    # Returns nothing.
+    def trace(operation)
+      @trace << operation
+    end
+
+    # Internal: Stores the response into the storage.
+    # If the response isn't cacheable, a trace action 'invalid' will be
+    # recorded for logging purposes.
+    #
+    # response - a 'Faraday::HttpCache::Response' instance to be stored.
+    #
+    # Returns nothing.
+    def store(response)
+      if response.cacheable?
+        trace :store
+        @storage.write(@request, response)
+      else
+        trace :invalid
+      end
+    end
+
+    # Internal: Fetches the response from the Faraday stack and stores it.
+    #
+    # env - the environment 'Hash' from the Faraday stack.
+    #
+    # Returns the fresh 'Faraday::Response' instance.
+    def fetch(env)
+      trace :miss
+      @app.call(env).on_complete do |env|
+        response = Response.new(env)
+        store(response)
+      end
+    end
+
+    # Internal: Creates a new 'Hash' containing the request information.
+    #
+    # env - the environment 'Hash' from the Faraday stack.
+    #
+    # Returns a 'Hash' containing the ':method', ':url' and 'request_headers'
+    # entries.
+    def create_request(env)
+      @request = env.slice(:method, :url)
+      @request[:request_headers] = env[:request_headers].dup
+      @request
+    end
+
+    # Internal: Logs the trace info about the incoming request
+    # and how the middleware handled it.
+    # This method does nothing if theresn't a logger present.
+    #
+    # Returns nothing.
+    def log_request
+      return unless @logger
+
+      method = @request[:method].to_s.upcase
+      path = @request[:url].path
+      line = "HTTP Cache: [#{method} #{path}] #{@trace.join(', ')}"
+      @logger.debug(line)
+    end
+  end
+end
+
+Faraday.register_middleware :http_cache => lambda { Faraday::HttpCache }

data/lib/faraday-http-cache.rb

@@ -0,0 +1 @@
+require 'faraday/http_cache'