faraday-http-cache 0.2.1 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 75eed5459ea58ad83130acdab34d7acf40967eaa
-  data.tar.gz: f5847df239db40584db36489818143e31d821222
+  metadata.gz: 80c7adcab041a8cfdcc1bfa6ac4a8ddd30661d9b
+  data.tar.gz: 688398ca6e4d77ac6769f66925c3108d5257ecdd
 SHA512:
-  metadata.gz: f95af2c373abe3e7b3055c10fcd92b2208b01c3725da597e9b07d9e56c0ee477e7028852f883b6a7870f02ba8a65bcbd8c338e05a0b2535cd9093a63cfdc7682
-  data.tar.gz: 8abb220a303052b25b83c4e16f40c77c4dbc6e4bd87ee33e18be28d108fde5ef2600e2baf5f5802a37e30650a89f1e8f35c7d63ffc67799ce49b5b0dc961b89f
+  metadata.gz: 789666e8549d1cb08978ae0870d97333e333541f0a774ec7bc10563dce42d3b4f9cf4ec425d16d03d13ae81d5420f5f5ecb8e71962525370b0aa9b39edae0f7b
+  data.tar.gz: 936fd149b8b358248bdb868fd347c7a53bc5115dae097a9ef6137680afc8d2584bf2f6066f328664132cc0191a9e199a813d31ee803ee1b5bdd8af02f9f8c514

data/README.md

@@ -1,6 +1,6 @@
 # Faraday Http Cache
 
-[![Build Status](https://secure.travis-ci.org/plataformatec/faraday-http-cache.png)](https://travis-ci.org/plataformatec/faraday-http-cache)
+[![Build Status](https://secure.travis-ci.org/plataformatec/faraday-http-cache.png?branch=master)](https://travis-ci.org/plataformatec/faraday-http-cache)
 
 a [Faraday](https://github.com/lostisland/faraday) middleware that respects HTTP cache,
 by checking expiration and validation of the stored responses.
@@ -34,13 +34,13 @@ endpoints, and any extra configuration option will be used to setup the cache st
 ```ruby
 # Connect the middleware to a Memcache instance.
 client = Faraday.new do |builder|
-  builder.use :http_cache, :mem_cache_store, "localhost:11211"
+  builder.use :http_cache, store: :mem_cache_store, store_options: ['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.use :http_cache, store: Rails.cache
   builder.adapter Faraday.default_adapter
 end
 ```
@@ -48,6 +48,16 @@ end
 The default store provided by ActiveSupport is the `MemoryStore` one, so it's important to
 configure a proper one for your production environment.
 
+MultiJson is used for serialization by default. If you expect to be dealing
+with images, you can use [Marshal][marshal] instead.
+
+```ruby
+client = Faraday.new do |builder|
+  builder.use :http_cache, serializer: Marshal
+  builder.adapter Faraday.default_adapter
+end
+```
+
 ### Logging
 
 You can provide a `:logger` option that will be receive debug informations based on the middleware
@@ -55,7 +65,7 @@ operations:
 
 ```ruby
 client = Faraday.new do |builder|
-  builder.use :http_cache, :logger => Rails.logger
+  builder.use :http_cache, logger: Rails.logger
   builder.adapter Faraday.default_adapter
 end
 
@@ -66,11 +76,25 @@ client.get('http://site/api/users')
 ## 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.
+execute the files under the `examples` directory to see a sample of the middleware usage.
+
+## What get's cached?
+
+The middleware will use the following headers to make caching decisions:
+- Cache-Control
+- Age
+- Last-Modified
+- ETag
+- Expires
+
+### Cache-Control
+
+The `max-age`, `must-revalidate`, `proxy-revalidate` and `s-maxage` directives are checked.
+
+Note: private caches are ignored.
 
 ## License
 
 Copyright (c) 2012-2013 Plataformatec. See LICENSE file.
+
+  [marshal]: http://www.ruby-doc.org/core-2.0/Marshal.html

data/lib/faraday/http_cache.rb

@@ -2,6 +2,7 @@ require 'faraday'
 require 'multi_json'
 
 require 'active_support/core_ext/hash/slice'
+require 'active_support/deprecation'
 
 require 'faraday/http_cache/storage'
 require 'faraday/http_cache/response'
@@ -26,13 +27,18 @@ module Faraday
   #
   #   # Attach a Logger to the middleware.
   #   client = Faraday.new do |builder|
-  #     builder.use :http_cache, :logger => my_logger_instance
+  #     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
+  #     builder.use :http_cache, store: Rails.cache
+  #   end
+  #
+  #   # Use Marshal for serialization
+  #   client = Faraday.new do |builder|
+  #     builder.use :http_cache, serializer: Marshal
   #   end
   class HttpCache < Faraday::Middleware
 
@@ -44,23 +50,27 @@ module Faraday
     # Examples:
     #
     #   # Initialize the middleware with a logger.
-    #   Faraday::HttpCache.new(app, :logger => my_logger)
+    #   Faraday::HttpCache.new(app, logger: my_logger)
+    #
+    #   # Initialize the middleware with a logger and Marshal as a serializer
+    #   Faraday:HttpCache.new(app, logger: my_logger, serializer: Marshal)
     #
     #   # Initialize the middleware with a FileStore at the 'tmp' dir.
-    #   Faraday::HttpCache.new(app, :file_store, 'tmp')
-    def initialize(app, *arguments)
+    #   Faraday::HttpCache.new(app, store: :file_store, store_options: ['tmp'])
+    #
+    #   # Initialize the middleware with a MemoryStore and logger
+    #   Faraday::HttpCache.new(app, store: :memory_store, logger: my_logger, store_options: [size: 1024])
+    def initialize(app, *args)
       super(app)
-
-      if arguments.last.is_a? Hash
-        options = arguments.pop
-        @logger = options.delete(:logger)
+      @logger = nil
+      if args.first.is_a? Hash
+        options = args.first
+        @logger = options[:logger]
       else
-        options = arguments
+        options = parse_deprecated_options(*args)
       end
 
-      store = arguments.shift
-
-      @storage = Storage.new(store, options)
+      @storage = Storage.new(options)
     end
 
     # Public: Process the request into a duplicate of this instance to
@@ -98,6 +108,61 @@ module Faraday
     end
 
     private
+    # Internal: Receive the deprecated arguments to initialize the old API
+    # and returns a Hash compatible with the new API
+    #
+    # Examples:
+    #
+    #   parse_deprecated_options(Rails.cache)
+    #   # => { store: Rails.cache }
+    #
+    #   parse_deprecated_options(:mem_cache_store)
+    #   # => { store: :mem_cache_store }
+    #
+    #   parse_deprecated_options(:mem_cache_store, logger: Rails.logger)
+    #   # => { store: :mem_cache_store, logger: Rails.logger }
+    #
+    #   parse_deprecated_options(:mem_cache_store, 'localhost:11211')
+    #   # => { store: :mem_cache_store, store_options: ['localhost:11211] }
+    #
+    #   parse_deprecated_options(:mem_cache_store, logger: Rails.logger, serializer: Marshal)
+    #   # => { store: :mem_cache_store, logger: Rails.logger, serializer: Marshal }
+    #
+    #   parse_deprecated_options(serializer: Marshal)
+    #   # => { serializer: Marshal }
+    #
+    #   parse_deprecated_options(:file_store, { serializer: Marshal }, 'tmp')
+    #   # => { store: :file_store, serializer: Marshal, store_options: ['tmp'] }
+    #
+    #   parse_deprecated_options(:memory_store, size: 1024)
+    #   # => { store: :memory_store, store_options: [size: 1024] }
+    #
+    # Returns a hash with the following keys:
+    #   - store
+    #   - serializer
+    #   - logger
+    #   - store_options
+    #
+    # In order to check what each key means, check `Storage#initialize` description.
+    def parse_deprecated_options(*args)
+      options = {}
+      if args.length > 0
+        ActiveSupport::Deprecation.warn('This api is deprecated, refer to the documentation for the new one', caller)
+      end
+
+      options[:store] = args.shift
+
+      if args.first.is_a? Hash
+        hash_params = args.first
+        options[:serializer] = hash_params.delete(:serializer)
+
+        @logger = hash_params.delete(:logger)
+      end
+
+      options[:store_options] = args
+      options
+    end
+
     # Internal: Validates if the current request method is valid for caching.
     #
     # Returns true if the method is ':get' or ':head'.
@@ -147,13 +212,13 @@ module Faraday
       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)
+      @app.call(env).on_complete do |requested_env|
+        response = Response.new(requested_env)
         if response.not_modified?
           trace :valid
           updated_payload = entry.payload
           updated_payload[:response_headers].update(response.payload[:response_headers])
-          env.update(updated_payload)
+          requested_env.update(updated_payload)
           response = Response.new(updated_payload)
         end
         store(response)
@@ -193,8 +258,8 @@ module Faraday
     # Returns the fresh 'Faraday::Response' instance.
     def fetch(env)
       trace :miss
-      @app.call(env).on_complete do |env|
-        response = Response.new(create_response(env))
+      @app.call(env).on_complete do |fresh_env|
+        response = Response.new(create_response(fresh_env))
         store(response)
       end
     end
@@ -238,7 +303,7 @@ module Faraday
 end
 
 if Faraday.respond_to?(:register_middleware)
-  Faraday.register_middleware :http_cache => Faraday::HttpCache
+  Faraday.register_middleware http_cache: Faraday::HttpCache
 elsif Faraday::Middleware.respond_to?(:register_middleware)
-  Faraday::Middleware.register_middleware :http_cache => Faraday::HttpCache
+  Faraday::Middleware.register_middleware http_cache: Faraday::HttpCache
 end

data/lib/faraday/http_cache/response.rb

@@ -177,10 +177,12 @@ module Faraday
         @payload[:response_headers]
       end
 
-      # Internal: prepares the response headers ready to be cached
+      # Internal: Prepares the response headers ready to be cached.
       #
-      # removes the age header if present to allow cached responses to continue aging while cached
-      # also normalizes the max age headers if age header provided to ensure accuracy once age header removed
+      # It removes the age header if present to allow cached responses
+      # to continue aging while cached. It also normalizes the 'max-age'
+      # related headers if the 'Age' header is provided to ensure accuracy
+      # once the 'Age' header is removed.
       def prepare_to_cache
         if headers.key? 'Age'
           cache_control.normalize_max_ages(headers['Age'].to_i)
@@ -188,7 +190,6 @@ module Faraday
           headers['Cache-Control'] = cache_control.to_s
         end
       end
-
     end
   end
 end

data/lib/faraday/http_cache/storage.rb

@@ -12,15 +12,24 @@ module Faraday
     #
     #   # Reuse some other instance of a ActiveSupport::CacheStore object.
     #   Faraday::HttpCache::Storage.new(Rails.cache)
+    #
+    #   # Creates a new Storage using Marshal for serialization.
+    #   Faraday::HttpCache::Storage.new(:memory_store, serializer: Marshal)
     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)
+      # options      - Storage options (default: {}).
+      #                :store         - An ActiveSupport::CacheStore identifier.
+      #                :serializer    - A serializer class for the body.
+      #                                 Should respond to #dump and #load.
+      #                :store_options - An array containg the options for
+      #                                 the cache store
+      def initialize(options = {})
+        store = options[:store]
+        @serializer = options[:serializer] || MultiJson
+        @cache = ActiveSupport::Cache.lookup_store(store, options[:store_options])
       end
 
       # Internal: Writes a response with a key based on the given request.
@@ -32,7 +41,7 @@ module Faraday
       # response - The Faraday::HttpCache::Response instance to be stored.
       def write(request, response)
         key = cache_key_for(request)
-        value = MultiJson.dump(response.serializable_hash)
+        value = @serializer.dump(response.serializable_hash)
         cache.write(key, value)
       end
 
@@ -48,7 +57,7 @@ module Faraday
         value = cache.read(key)
 
         if value
-          payload = MultiJson.load(value).symbolize_keys
+          payload = @serializer.load(value).symbolize_keys
           klass.new(payload)
         end
       end
@@ -63,7 +72,7 @@ module Faraday
       # Returns the encoded String.
       def cache_key_for(request)
         array = request.stringify_keys.to_a.sort
-        Digest::SHA1.hexdigest(MultiJson.dump(array))
+        Digest::SHA1.hexdigest(@serializer.dump(array))
       end
     end
   end

data/spec/binary_spec.rb

@@ -0,0 +1,18 @@
+require 'spec_helper'
+
+describe Faraday::HttpCache do
+  let(:client) do
+    Faraday.new(url: ENV['FARADAY_SERVER']) do |stack|
+      stack.use :http_cache, serializer: Marshal
+      adapter = ENV['FARADAY_ADAPTER']
+      stack.headers['X-Faraday-Adapter'] = adapter
+      stack.adapter adapter.to_sym
+    end
+  end
+  let(:data) { IO.binread File.expand_path('../support/empty.png', __FILE__) }
+
+  it 'works fine with binary data' do
+    expect(client.get('image').body).to eq data
+    expect(client.get('image').body).to eq data
+  end
+end

data/spec/cache_control_spec.rb

@@ -2,106 +2,106 @@ require 'spec_helper'
 
 describe Faraday::HttpCache::CacheControl do
   it 'takes a String with multiple name=value pairs' do
-    instance = Faraday::HttpCache::CacheControl.new('max-age=600, max-stale=300, min-fresh=570')
-    instance.max_age.should == 600
+    cache_control = Faraday::HttpCache::CacheControl.new('max-age=600, max-stale=300, min-fresh=570')
+    expect(cache_control.max_age).to eq(600)
   end
 
   it 'takes a String with a single flag value' do
-    instance = Faraday::HttpCache::CacheControl.new('no-cache')
-    instance.should be_no_cache
+    cache_control = Faraday::HttpCache::CacheControl.new('no-cache')
+    expect(cache_control).to be_no_cache
   end
 
   it 'takes a String with a bunch of all kinds of stuff' do
-    instance =
+    cache_control =
       Faraday::HttpCache::CacheControl.new('max-age=600,must-revalidate,min-fresh=3000,foo=bar,baz')
-    instance.max_age.should == 600
-    instance.should be_must_revalidate
+    expect(cache_control.max_age).to eq(600)
+    expect(cache_control).to be_must_revalidate
   end
 
   it 'strips leading and trailing spaces' do
-    instance = Faraday::HttpCache::CacheControl.new('   public,   max-age =   600  ')
-    instance.should be_public
-    instance.max_age.should == 600
+    cache_control = Faraday::HttpCache::CacheControl.new('   public,   max-age =   600  ')
+    expect(cache_control).to be_public
+    expect(cache_control.max_age).to eq(600)
   end
 
   it 'ignores blank segments' do
-    instance = Faraday::HttpCache::CacheControl.new('max-age=600,,s-maxage=300')
-    instance.max_age.should == 600
-    instance.shared_max_age.should == 300
+    cache_control = Faraday::HttpCache::CacheControl.new('max-age=600,,s-maxage=300')
+    expect(cache_control.max_age).to eq(600)
+    expect(cache_control.shared_max_age).to eq(300)
   end
 
   it 'sorts alphabetically with boolean directives before value directives' do
-    instance = Faraday::HttpCache::CacheControl.new('foo=bar, z, x, y, bling=baz, zoom=zib, b, a')
-    instance.to_s.should == 'a, b, x, y, z, bling=baz, foo=bar, zoom=zib'
+    cache_control = Faraday::HttpCache::CacheControl.new('foo=bar, z, x, y, bling=baz, zoom=zib, b, a')
+    expect(cache_control.to_s).to eq('a, b, x, y, z, bling=baz, foo=bar, zoom=zib')
   end
 
   it 'responds to #max_age with an integer when max-age directive present' do
-    instance = Faraday::HttpCache::CacheControl.new('public, max-age=600')
-    instance.max_age.should == 600
+    cache_control = Faraday::HttpCache::CacheControl.new('public, max-age=600')
+    expect(cache_control.max_age).to eq(600)
   end
 
   it 'responds to #max_age with nil when no max-age directive present' do
-    instance = Faraday::HttpCache::CacheControl.new('public')
-    instance.max_age.should be_nil
+    cache_control = Faraday::HttpCache::CacheControl.new('public')
+    expect(cache_control.max_age).to be_nil
   end
 
   it 'responds to #shared_max_age with an integer when s-maxage directive present' do
-    instance = Faraday::HttpCache::CacheControl.new('public, s-maxage=600')
-    instance.shared_max_age.should == 600
+    cache_control = Faraday::HttpCache::CacheControl.new('public, s-maxage=600')
+    expect(cache_control.shared_max_age).to eq(600)
   end
 
   it 'responds to #shared_max_age with nil when no s-maxage directive present' do
-    instance = Faraday::HttpCache::CacheControl.new('public')
-    instance.shared_max_age.should be_nil
+    cache_control = Faraday::HttpCache::CacheControl.new('public')
+    expect(cache_control.shared_max_age).to be_nil
   end
 
   it 'responds to #public? truthfully when public directive present' do
-    instance = Faraday::HttpCache::CacheControl.new('public')
-    instance.should be_public
+    cache_control = Faraday::HttpCache::CacheControl.new('public')
+    expect(cache_control).to be_public
   end
 
   it 'responds to #public? non-truthfully when no public directive present' do
-    instance = Faraday::HttpCache::CacheControl.new('private')
-    instance.should_not be_public
+    cache_control = Faraday::HttpCache::CacheControl.new('private')
+    expect(cache_control).not_to be_public
   end
 
   it 'responds to #private? truthfully when private directive present' do
-    instance = Faraday::HttpCache::CacheControl.new('private')
-    instance.should be_private
+    cache_control = Faraday::HttpCache::CacheControl.new('private')
+    expect(cache_control).to be_private
   end
 
   it 'responds to #private? non-truthfully when no private directive present' do
-    instance = Faraday::HttpCache::CacheControl.new('public')
-    instance.should_not be_private
+    cache_control = Faraday::HttpCache::CacheControl.new('public')
+    expect(cache_control).not_to be_private
   end
 
   it 'responds to #no_cache? truthfully when no-cache directive present' do
-    instance = Faraday::HttpCache::CacheControl.new('no-cache')
-    instance.should be_no_cache
+    cache_control = Faraday::HttpCache::CacheControl.new('no-cache')
+    expect(cache_control).to be_no_cache
   end
 
   it 'responds to #no_cache? non-truthfully when no no-cache directive present' do
-    instance = Faraday::HttpCache::CacheControl.new('max-age=600')
-    instance.should_not be_no_cache
+    cache_control = Faraday::HttpCache::CacheControl.new('max-age=600')
+    expect(cache_control).not_to be_no_cache
   end
 
   it 'responds to #must_revalidate? truthfully when must-revalidate directive present' do
-    instance = Faraday::HttpCache::CacheControl.new('must-revalidate')
-    instance.should be_must_revalidate
+    cache_control = Faraday::HttpCache::CacheControl.new('must-revalidate')
+    expect(cache_control).to be_must_revalidate
   end
 
   it 'responds to #must_revalidate? non-truthfully when no must-revalidate directive present' do
-    instance = Faraday::HttpCache::CacheControl.new('max-age=600')
-    instance.should_not be_no_cache
+    cache_control = Faraday::HttpCache::CacheControl.new('max-age=600')
+    expect(cache_control).not_to be_must_revalidate
   end
 
   it 'responds to #proxy_revalidate? truthfully when proxy-revalidate directive present' do
-    instance = Faraday::HttpCache::CacheControl.new('proxy-revalidate')
-    instance.should be_proxy_revalidate
+    cache_control = Faraday::HttpCache::CacheControl.new('proxy-revalidate')
+    expect(cache_control).to be_proxy_revalidate
   end
 
   it 'responds to #proxy_revalidate? non-truthfully when no proxy-revalidate directive present' do
-    instance = Faraday::HttpCache::CacheControl.new('max-age=600')
-    instance.should_not be_no_cache
+    cache_control = Faraday::HttpCache::CacheControl.new('max-age=600')
+    expect(cache_control).not_to be_no_cache
   end
 end