faraday-http-cache 2.3.0 → 2.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 962b23db73b9799330e7229f9a6d6e252705a55f3c3ad316f810132160a30522
-  data.tar.gz: 51a43a544f924e75c00ffffd777368cf995000a3855e1ea7b9b86fb54b5f6b2a
+  metadata.gz: 6603be3bbf6a2840ba11f947f7e42f030ab52600912e9a62d16aaf27ee5e6446
+  data.tar.gz: 95b8b2f4b08525406027d47e14341f5f301409a2518332b243dc08d2bde4e693
 SHA512:
-  metadata.gz: 57de8b27682d5aa8367fd7612ec3814c300a0856ba7e1ee61354646117a2370f216981b60f5224662236444a44669a70840fb07118602a82b66a0c886ae1540d
-  data.tar.gz: d8e1644ed674c3c7a6c8f44adfe83eda6f9268590235330eaf0ed62ec41795a97a35f28f52bddf7c3103a8cef6c849330167b1b708a6c8124da642e371bf434b
+  metadata.gz: 4675c865c18641322c71b77881a74d3ca4edbf4fb1d628ac0fe7a6388d6a3c973946f1d7fa7b09d654f1eff61484a8c2d8524c966e4377c1e12854bf8114e13a
+  data.tar.gz: 832d7579eb75d3631e539ca7af996b9d062dbe43582468f98c349b3dbc963dde17cecf57a0202af1916297013143becba1a0fc1f32ddf92ab98490876e3efc84

data/README.md

@@ -1,8 +1,9 @@
 # Faraday Http Cache
 
-[![Build Status](https://secure.travis-ci.org/sourcelevel/faraday-http-cache.svg?branch=master)](https://travis-ci.org/sourcelevel/faraday-http-cache)
+[![Gem Version](https://badge.fury.io/rb/faraday-http-cache.svg)](https://rubygems.org/gems/faraday-http-cache)
+[![Build](https://github.com/sourcelevel/faraday-http-cache/actions/workflows/main.yml/badge.svg)](https://github.com/sourcelevel/faraday-http-cache/actions)
 
-a [Faraday](https://github.com/lostisland/faraday) middleware that respects HTTP cache,
+A [Faraday](https://github.com/lostisland/faraday) middleware that respects HTTP cache,
 by checking expiration and validation of the stored responses.
 
 ## Installation
@@ -53,15 +54,15 @@ This type of store **might not be persisted across multiple processes or connect
 so it is probably not suitable for most production environments.
 Make sure that you configure a store that is suitable for you.
 
-The stdlib `JSON` module is used for serialization by default, which can struggle with unicode 
-characters in responses. For example, if your JSON returns `"name": "Raül"` then you might see 
-errors like:
+The stdlib `JSON` module is used for serialization by default, which can struggle with unicode
+characters in responses in Ruby < 3.1. For example, if your JSON returns `"name": "Raül"` then
+you might see errors like:
 
 ```
 Response could not be serialized: "\xC3" from ASCII-8BIT to UTF-8. Try using Marshal to serialize.
 ```
 
-For full unicode support, or if you expect to be dealing with images, you can use 
+For full unicode support, or if you expect to be dealing with images, you can use the stdlib
 [Marshal][marshal] instead. Alternatively you could use another json library like `oj` or `yajl-ruby`.
 
 ```ruby
@@ -71,9 +72,47 @@ client = Faraday.new do |builder|
 end
 ```
 
+### Strategies
+
+You can provide a `:strategy` option to the middleware to specify the strategy to use.
+
+```ruby
+client = Faraday.new do |builder|
+  builder.use :http_cache, store: Rails.cache, strategy: Faraday::HttpCache::Strategies::ByVary
+  builder.adapter Faraday.default_adapter
+end
+```
+
+Available strategies are:
+
+#### `Faraday::HttpCache::Strategies::ByUrl`
+
+The default strategy.
+It Uses URL + HTTP method to generate cache keys and stores an array of request + response for each key.
+
+#### `Faraday::HttpCache::Strategies::ByVary`
+
+This strategy uses headers from `Vary` header to generate cache keys.
+It also uses cache to store `Vary` headers mapped to the request URL.
+This strategy is more suitable for caching private responses with the same URLs but different results for different users, like `https://api.github.com/user`.
+
+*Note:* To automatically remove stale cache keys, you might want to use the `:expires_in` option.
+
+```ruby
+store = ActiveSupport::Cache.lookup_store(:redis_cache_store, expires_in: 1.day, url: 'redis://localhost:6379/0')
+client = Faraday.new do |builder|
+  builder.use :http_cache, store: store, strategy: Faraday::HttpCache::Strategies::ByVary
+  builder.adapter Faraday.default_adapter
+end
+```
+
+#### Custom strategies
+
+You can write your own strategy by subclassing `Faraday::HttpCache::Strategies::BaseStrategy` and implementing `#write`, `#read` and `#delete` methods.
+
 ### Logging
 
-You can provide a `:logger` option that will be receive debug informations based on the middleware
+You can provide a `:logger` option that will receive debug information based on the middleware
 operations:
 
 ```ruby
@@ -82,7 +121,7 @@ client = Faraday.new do |builder|
   builder.adapter Faraday.default_adapter
 end
 
-client.get('http://site/api/users')
+client.get('https://site/api/users')
 # logs "HTTP Cache: [GET users] miss, store"
 ```
 
@@ -133,6 +172,7 @@ execute the files under the `examples` directory to see a sample of the middlewa
 ## What gets cached?
 
 The middleware will use the following headers to make caching decisions:
+- Vary
 - Cache-Control
 - Age
 - Last-Modified
@@ -155,7 +195,7 @@ client = Faraday.new do |builder|
   builder.adapter Faraday.default_adapter
 end
 
-client.get('http://site/api/some-private-resource') # => will be cached
+client.get('https://site/api/some-private-resource') # => will be cached
 ```
 
 ## License
@@ -163,4 +203,4 @@ client.get('http://site/api/some-private-resource') # => will be cached
 Copyright (c) 2012-2018 Plataformatec.
 Copyright (c) 2019 SourceLevel and contributors.
 
-  [marshal]: http://www.ruby-doc.org/core-2.0/Marshal.html
+  [marshal]: https://www.ruby-doc.org/core-3.0/Marshal.html

data/lib/faraday/http_cache/memory_store.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Faraday
+  class HttpCache < Faraday::Middleware
+    # @private
+    # A Hash based store to be used by strategies
+    # when a `store` is not provided for the middleware setup.
+    class MemoryStore
+      def initialize
+        @cache = {}
+      end
+
+      def read(key)
+        @cache[key]
+      end
+
+      def delete(key)
+        @cache.delete(key)
+      end
+
+      def write(key, value)
+        @cache[key] = value
+      end
+    end
+  end
+end

data/lib/faraday/http_cache/storage.rb

@@ -1,194 +1,15 @@
 # frozen_string_literal: true
 
-require 'json'
-require 'digest/sha1'
+require 'faraday/http_cache/strategies/by_url'
 
 module Faraday
   class HttpCache < Faraday::Middleware
-    # Internal: A wrapper around an ActiveSupport::CacheStore to store responses.
-    #
-    # Examples
-    #
-    #   # Creates a new Storage using a MemCached backend from ActiveSupport.
-    #   mem_cache_store = ActiveSupport::Cache.lookup_store(:mem_cache_store, ['localhost:11211'])
-    #   Faraday::HttpCache::Storage.new(store: mem_cache_store)
-    #
-    #   # Reuse some other instance of an ActiveSupport::Cache::Store object.
-    #   Faraday::HttpCache::Storage.new(store: Rails.cache)
-    #
-    #   # Creates a new Storage using Marshal for serialization.
-    #   Faraday::HttpCache::Storage.new(store: Rails.cache, serializer: Marshal)
-    class Storage
-      # Public: Gets the underlying cache store object.
-      attr_reader :cache
-
-      # Internal: Initialize a new Storage object with a cache backend.
-      #
-      # :logger     - A Logger object to be used to emit warnings.
-      # :store      - An cache store object that should respond to 'read',
-      #              'write', and 'delete'.
-      # :serializer - A serializer object that should respond to 'dump'
-      #               and 'load'.
-      def initialize(store: nil, serializer: nil, logger: nil)
-        @cache = store || MemoryStore.new
-        @serializer = serializer || JSON
-        @logger = logger
-        assert_valid_store!
-      end
-
-      # Internal: Store a response inside the cache.
-      #
-      # request  - A Faraday::HttpCache::::Request instance of the executed HTTP
-      #            request.
-      # response - The Faraday::HttpCache::Response instance to be stored.
-      #
-      # Returns nothing.
-      def write(request, response)
-        key = cache_key_for(request.url)
-        entry = serialize_entry(request.serializable_hash, response.serializable_hash)
-
-        entries = cache.read(key) || []
-        entries = entries.dup if entries.frozen?
-
-        entries.reject! do |(cached_request, cached_response)|
-          response_matches?(request, deserialize_object(cached_request), deserialize_object(cached_response))
-        end
-
-        entries << entry
-
-        cache.write(key, entries)
-      rescue ::Encoding::UndefinedConversionError => e
-        warn "Response could not be serialized: #{e.message}. Try using Marshal to serialize."
-        raise e
-      end
-
-      # Internal: Attempt to retrieve an stored response that suits the incoming
-      # HTTP request.
-      #
-      # request  - A Faraday::HttpCache::::Request instance of the incoming HTTP
-      #            request.
-      # klass    - The Class to be instantiated with the stored response.
-      #
-      # Returns an instance of 'klass'.
-      def read(request, klass: Faraday::HttpCache::Response)
-        cache_key = cache_key_for(request.url)
-        entries = cache.read(cache_key)
-        response = lookup_response(request, entries)
-
-        if response
-          klass.new(response)
-        end
-      end
-
-      def delete(url)
-        cache_key = cache_key_for(url)
-        cache.delete(cache_key)
-      end
-
-      private
-
-      # Internal: Retrieve a response Hash from the list of entries that match
-      # the given request.
-      #
-      # request  - A Faraday::HttpCache::::Request instance of the incoming HTTP
-      #            request.
-      # entries  - An Array of pairs of Hashes (request, response).
-      #
-      # Returns a Hash or nil.
-      def lookup_response(request, entries)
-        if entries
-          entries = entries.map { |entry| deserialize_entry(*entry) }
-          _, response = entries.find { |req, res| response_matches?(request, req, res) }
-          response
-        end
-      end
-
-      # Internal: Check if a cached response and request matches the given
-      # request.
-      #
-      # request         - A Faraday::HttpCache::::Request instance of the
-      #                   current HTTP request.
-      # cached_request  - The Hash of the request that was cached.
-      # cached_response - The Hash of the response that was cached.
-      #
-      # Returns true or false.
-      def response_matches?(request, cached_request, cached_response)
-        request.method.to_s == cached_request[:method].to_s &&
-          vary_matches?(cached_response, request, cached_request)
-      end
-
-      def vary_matches?(cached_response, request, cached_request)
-        headers = Faraday::Utils::Headers.new(cached_response[:response_headers])
-        vary = headers['Vary'].to_s
-
-        vary.empty? || (vary != '*' && vary.split(/[\s,]+/).all? do |header|
-          request.headers[header] == cached_request[:headers][header]
-        end)
-      end
-
-      def serialize_entry(*objects)
-        objects.map { |object| serialize_object(object) }
-      end
-
-      def serialize_object(object)
-        @serializer.dump(object)
-      end
-
-      def deserialize_entry(*objects)
-        objects.map { |object| deserialize_object(object) }
-      end
-
-      def deserialize_object(object)
-        @serializer.load(object).each_with_object({}) do |(key, value), hash|
-          hash[key.to_sym] = value
-        end
-      end
-
-      # Internal: Computes the cache key for a specific request, taking in
-      # account the current serializer to avoid cross serialization issues.
-      #
-      # url - The request URL.
-      #
-      # Returns a String.
-      def cache_key_for(url)
-        prefix = (@serializer.is_a?(Module) ? @serializer : @serializer.class).name
-        Digest::SHA1.hexdigest("#{prefix}#{url}")
-      end
-
-      # Internal: Checks if the given cache object supports the
-      # expect API ('read' and 'write').
-      #
-      # Raises an 'ArgumentError'.
-      #
-      # Returns nothing.
-      def assert_valid_store!
-        unless cache.respond_to?(:read) && cache.respond_to?(:write) && cache.respond_to?(:delete)
-          raise ArgumentError.new("#{cache.inspect} is not a valid cache store as it does not responds to 'read', 'write' or 'delete'.")
-        end
-      end
-
-      def warn(message)
-        @logger&.warn(message)
-      end
-    end
-
-    # Internal: A Hash based store to be used by the 'Storage' class
-    # when a 'store' is not provided for the middleware setup.
-    class MemoryStore
-      def initialize
-        @cache = {}
-      end
-
-      def read(key)
-        @cache[key]
-      end
-
-      def delete(key)
-        @cache.delete(key)
-      end
-
-      def write(key, value)
-        @cache[key] = value
+    # @deprecated Use Faraday::HttpCache::Strategies::ByUrl instead.
+    class Storage < Faraday::HttpCache::Strategies::ByUrl
+      def initialize(*)
+        Kernel.warn("Deprecated: #{self.class} is deprecated and will be removed in " \
+             'the next major release. Use Faraday::HttpCache::Strategies::ByUrl instead.')
+        super
       end
     end
   end

data/lib/faraday/http_cache/strategies/base_strategy.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'faraday/http_cache/memory_store'
+
+module Faraday
+  class HttpCache < Faraday::Middleware
+    module Strategies
+      # Base class for all strategies.
+      # @abstract
+      #
+      # @example
+      #
+      #   # Creates a new strategy using a MemCached backend from ActiveSupport.
+      #   mem_cache_store = ActiveSupport::Cache.lookup_store(:mem_cache_store, ['localhost:11211'])
+      #   Faraday::HttpCache::Strategies::ByVary.new(store: mem_cache_store)
+      #
+      #   # Reuse some other instance of an ActiveSupport::Cache::Store object.
+      #   Faraday::HttpCache::Strategies::ByVary.new(store: Rails.cache)
+      #
+      #   # Creates a new strategy using Marshal for serialization.
+      #   Faraday::HttpCache::Strategies::ByVary.new(store: Rails.cache, serializer: Marshal)
+      class BaseStrategy
+        # Returns the underlying cache store object.
+        attr_reader :cache
+
+        # @param [Hash] options the options to create a message with.
+        # @option options [Faraday::HttpCache::MemoryStore, nil] :store - a cache
+        #   store object that should respond to 'read', 'write', and 'delete'.
+        # @option options [#dump#load] :serializer - an object that should
+        #   respond to 'dump' and 'load'.
+        # @option options [Logger, nil] :logger - an object to be used to emit warnings.
+        def initialize(options = {})
+          @cache = options[:store] || Faraday::HttpCache::MemoryStore.new
+          @serializer = options[:serializer] || JSON
+          @logger = options[:logger] || Logger.new(IO::NULL)
+          @cache_salt = (@serializer.is_a?(Module) ? @serializer : @serializer.class).name
+          assert_valid_store!
+        end
+
+        # Store a response inside the cache.
+        # @abstract
+        def write(_request, _response)
+          raise NotImplementedError, 'Implement this method in your strategy'
+        end
+
+        # Read a response from the cache.
+        # @abstract
+        def read(_request)
+          raise NotImplementedError, 'Implement this method in your strategy'
+        end
+
+        # Delete responses from the cache by the url.
+        # @abstract
+        def delete(_url)
+          raise NotImplementedError, 'Implement this method in your strategy'
+        end
+
+        private
+
+        # @private
+        # @raise [ArgumentError] if the cache object doesn't support the expect API.
+        def assert_valid_store!
+          unless cache.respond_to?(:read) && cache.respond_to?(:write) && cache.respond_to?(:delete)
+            raise ArgumentError.new("#{cache.inspect} is not a valid cache store as it does not responds to 'read', 'write' or 'delete'.")
+          end
+        end
+
+        def serialize_entry(*objects)
+          objects.map { |object| serialize_object(object) }
+        end
+
+        def serialize_object(object)
+          @serializer.dump(object)
+        end
+
+        def deserialize_entry(*objects)
+          objects.map { |object| deserialize_object(object) }
+        end
+
+        def deserialize_object(object)
+          @serializer.load(object).each_with_object({}) do |(key, value), hash|
+            hash[key.to_sym] = value
+          end
+        end
+
+        def warn(message)
+          @logger.warn(message)
+        end
+      end
+    end
+  end
+end

data/lib/faraday/http_cache/strategies/by_url.rb

@@ -0,0 +1,118 @@
+# frozen_string_literal: true
+
+require 'digest/sha1'
+
+require 'faraday/http_cache/strategies/base_strategy'
+
+module Faraday
+  class HttpCache < Faraday::Middleware
+    module Strategies
+      # The original strategy by Faraday::HttpCache.
+      # Uses URL + HTTP method to generate cache keys.
+      class ByUrl < BaseStrategy
+        # Store a response inside the cache.
+        #
+        # @param [Faraday::HttpCache::Request] request - instance of the executed HTTP request.
+        # @param [Faraday::HttpCache::Response] response - instance to be stored.
+        #
+        # @return [void]
+        def write(request, response)
+          key = cache_key_for(request.url)
+          entry = serialize_entry(request.serializable_hash, response.serializable_hash)
+          entries = cache.read(key) || []
+          entries = entries.dup if entries.frozen?
+          entries.reject! do |(cached_request, cached_response)|
+            response_matches?(request, deserialize_object(cached_request), deserialize_object(cached_response))
+          end
+
+          entries << entry
+
+          cache.write(key, entries)
+        rescue ::Encoding::UndefinedConversionError => e
+          warn "Response could not be serialized: #{e.message}. Try using Marshal to serialize."
+          raise e
+        end
+
+        # Fetch a stored response that suits the incoming HTTP request or return nil.
+        #
+        # @param [Faraday::HttpCache::Request] request - an instance of the incoming HTTP request.
+        #
+        # @return [Faraday::HttpCache::Response, nil]
+        def read(request)
+          cache_key = cache_key_for(request.url)
+          entries = cache.read(cache_key)
+          response = lookup_response(request, entries)
+          return nil unless response
+
+          Faraday::HttpCache::Response.new(response)
+        end
+
+        # @param [String] url – the url of a changed resource, will be used to invalidate the cache.
+        #
+        # @return [void]
+        def delete(url)
+          cache_key = cache_key_for(url)
+          cache.delete(cache_key)
+        end
+
+        private
+
+        # Retrieve a response Hash from the list of entries that match the given request.
+        #
+        # @param [Faraday::HttpCache::Request] request - an instance of the incoming HTTP request.
+        # @param [Array<Array(Hash, Hash)>] entries - pairs of Hashes (request, response).
+        #
+        # @return [Hash, nil]
+        def lookup_response(request, entries)
+          if entries
+            entries = entries.map { |entry| deserialize_entry(*entry) }
+            _, response = entries.find { |req, res| response_matches?(request, req, res) }
+            response
+          end
+        end
+
+        # Check if a cached response and request matches the given request.
+        #
+        # @param [Faraday::HttpCache::Request] request - an instance of the incoming HTTP request.
+        # @param [Hash] cached_request - a Hash of the request that was cached.
+        # @param [Hash] cached_response - a Hash of the response that was cached.
+        #
+        # @return [true, false]
+        def response_matches?(request, cached_request, cached_response)
+          request.method.to_s == cached_request[:method].to_s &&
+            vary_matches?(cached_response, request, cached_request)
+        end
+
+        # Check if the cached request matches the incoming
+        # request based on the Vary header of cached response.
+        #
+        # If Vary header is not present, the request is considered to match.
+        # If Vary header is '*', the request is considered to not match.
+        #
+        # @param [Faraday::HttpCache::Request] request - an instance of the incoming HTTP request.
+        # @param [Hash] cached_request - a Hash of the request that was cached.
+        # @param [Hash] cached_response - a Hash of the response that was cached.
+        #
+        # @return [true, false]
+        def vary_matches?(cached_response, request, cached_request)
+          headers = Faraday::Utils::Headers.new(cached_response[:response_headers])
+          vary = headers['Vary'].to_s
+
+          vary.empty? || (vary != '*' && vary.split(/[\s,]+/).all? do |header|
+            request.headers[header] == cached_request[:headers][header]
+          end)
+        end
+
+        # Computes the cache key for a specific request, taking
+        # in account the current serializer to avoid cross serialization issues.
+        #
+        # @param [String] url - the request URL.
+        #
+        # @return [String]
+        def cache_key_for(url)
+          Digest::SHA1.hexdigest("#{@cache_salt}#{url}")
+        end
+      end
+    end
+  end
+end

data/lib/faraday/http_cache/strategies/by_vary.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+require 'digest/sha1'
+
+require 'faraday/http_cache/strategies/base_strategy'
+
+module Faraday
+  class HttpCache < Faraday::Middleware
+    module Strategies
+      # This strategy uses headers from the Vary response header to generate cache keys.
+      # It also uses the index with Vary headers mapped to the request url.
+      # This strategy is more suitable for caching private responses with the same urls,
+      # like https://api.github.com/user.
+      #
+      # This strategy does not support #delete method to clear cache on unsafe methods.
+      class ByVary < BaseStrategy
+        # Store a response inside the cache.
+        #
+        # @param [Faraday::HttpCache::Request] request - instance of the executed HTTP request.
+        # @param [Faraday::HttpCache::Response] response - instance to be stored.
+        #
+        # @return [void]
+        def write(request, response)
+          vary_cache_key = vary_cache_key_for(request)
+          headers = Faraday::Utils::Headers.new(response.payload[:response_headers])
+          vary = headers['Vary'].to_s
+          cache.write(vary_cache_key, vary)
+
+          response_cache_key = response_cache_key_for(request, vary)
+          entry = serialize_object(response.serializable_hash)
+          cache.write(response_cache_key, entry)
+        rescue ::Encoding::UndefinedConversionError => e
+          warn "Response could not be serialized: #{e.message}. Try using Marshal to serialize."
+          raise e
+        end
+
+        # Fetch a stored response that suits the incoming HTTP request or return nil.
+        #
+        # @param [Faraday::HttpCache::Request] request - an instance of the incoming HTTP request.
+        #
+        # @return [Faraday::HttpCache::Response, nil]
+        def read(request)
+          vary_cache_key = vary_cache_key_for(request)
+          vary = cache.read(vary_cache_key)
+          return nil if vary.nil? || vary == '*'
+
+          cache_key = response_cache_key_for(request, vary)
+          response = cache.read(cache_key)
+          return nil if response.nil?
+
+          Faraday::HttpCache::Response.new(deserialize_object(response))
+        end
+
+        # This strategy does not support #delete method to clear cache on unsafe methods.
+        # @return [void]
+        def delete(_url)
+          # do nothing since we can't find the key by url
+        end
+
+        private
+
+        # Computes the cache key for the index with Vary headers.
+        #
+        # @param [Faraday::HttpCache::Request] request - instance of the executed HTTP request.
+        #
+        # @return [String]
+        def vary_cache_key_for(request)
+          method = request.method.to_s
+          Digest::SHA1.hexdigest("by_vary_index#{@cache_salt}#{method}#{request.url}")
+        end
+
+        # Computes the cache key for the response.
+        #
+        # @param [Faraday::HttpCache::Request] request - instance of the executed HTTP request.
+        # @param [String] vary - the Vary header value.
+        #
+        # @return [String]
+        def response_cache_key_for(request, vary)
+          method = request.method.to_s
+          headers = vary.split(/[\s,]+/).map { |header| request.headers[header] }
+          Digest::SHA1.hexdigest("by_vary#{@cache_salt}#{method}#{request.url}#{headers.join}")
+        end
+      end
+    end
+  end
+end

data/lib/faraday/http_cache/strategies.rb

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+
+require 'faraday/http_cache/strategies/by_url'
+require 'faraday/http_cache/strategies/by_vary'

data/lib/faraday/http_cache.rb

@@ -5,11 +5,12 @@ require 'faraday'
 require 'faraday/http_cache/storage'
 require 'faraday/http_cache/request'
 require 'faraday/http_cache/response'
+require 'faraday/http_cache/strategies'
 
 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
+  # The middleware use the provided configuration options to establish on of
+  # 'Faraday::HttpCache::Strategies' 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
@@ -91,7 +92,7 @@ module Faraday
     #   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)
+    #   Faraday::HttpCache.new(app, logger: my_logger, serializer: Marshal)
     #
     #   # Initialize the middleware with a FileStore at the 'tmp' dir.
     #   store = ActiveSupport::Cache.lookup_store(:file_store, ['tmp'])
@@ -104,17 +105,14 @@ module Faraday
       super(app)
 
       options = options.dup
-      @logger = options.delete(:logger)
+      @logger = options[:logger]
       @shared_cache = options.delete(:shared_cache) { true }
       @instrumenter = options.delete(:instrumenter)
       @instrument_name = options.delete(:instrument_name) { EVENT_NAME }
 
-      store = options.delete(:store)
-      serializer = options.delete(:serializer)
+      strategy = options.delete(:strategy) { Strategies::ByUrl }
 
-      raise ArgumentError, "Unknown options: #{options.inspect}" unless options.empty?
-
-      @storage = Storage.new(store: store, serializer: serializer, logger: @logger)
+      @strategy = strategy.new(**options)
     end
 
     # Public: Process the request into a duplicate of this instance to
@@ -159,9 +157,6 @@ module Faraday
     # Internal: Gets the request object created from the Faraday env Hash.
     attr_reader :request
 
-    # Internal: Gets the storage instance associated with the middleware.
-    attr_reader :storage
-
     private
 
     # Internal: Should this cache instance act like a "shared cache" according
@@ -190,7 +185,7 @@ module Faraday
     #
     # Returns the 'Faraday::Response' instance to be served.
     def process(env)
-      entry = @storage.read(@request)
+      entry = @strategy.read(@request)
 
       return fetch(env) if entry.nil?
 
@@ -264,7 +259,7 @@ module Faraday
     def store(response)
       if shared_cache? ? response.cacheable_in_shared_cache? : response.cacheable_in_private_cache?
         trace :store
-        @storage.write(@request, response)
+        @strategy.write(@request, response)
       else
         trace :uncacheable
       end
@@ -274,10 +269,10 @@ module Faraday
       headers = %w[Location Content-Location]
       headers.each do |header|
         url = response.headers[header]
-        @storage.delete(url) if url
+        @strategy.delete(url) if url
       end
 
-      @storage.delete(request.url)
+      @strategy.delete(request.url)
       trace :delete
     end
 

data/spec/http_cache_spec.rb

@@ -283,23 +283,13 @@ describe Faraday::HttpCache do
     expect(client.get('must-revalidate').body).to eq('1')
   end
 
-  it 'raises an error when misconfigured' do
-    expect {
-      client = Faraday.new(url: ENV['FARADAY_SERVER']) do |stack|
-        stack.use Faraday::HttpCache, i_have_no_idea: true
-      end
-
-      client.get('get')
-    }.to raise_error(ArgumentError)
-  end
-
   describe 'Configuration options' do
     let(:app) { double('it is an app!') }
 
     it 'uses the options to create a Cache Store' do
       store = double(read: nil, write: nil)
 
-      expect(Faraday::HttpCache::Storage).to receive(:new).with(hash_including(store: store))
+      expect(Faraday::HttpCache::Strategies::ByUrl).to receive(:new).with(hash_including(store: store))
       Faraday::HttpCache.new(app, store: store)
     end
   end

data/spec/storage_spec.rb

@@ -16,6 +16,21 @@ describe Faraday::HttpCache::Storage do
   let(:storage) { Faraday::HttpCache::Storage.new(store: cache) }
   subject { storage }
 
+  before do
+    allow(Kernel).to receive(:warn).with(
+      'Deprecated: Faraday::HttpCache::Storage is deprecated and will be removed '\
+      'in the next major release. Use Faraday::HttpCache::Strategies::ByUrl instead.'
+    )
+  end
+
+  it 'creates strategy and warns about deprecation' do
+    expect(Kernel).to receive(:warn).with(
+      'Deprecated: Faraday::HttpCache::Storage is deprecated and will be removed '\
+      'in the next major release. Use Faraday::HttpCache::Strategies::ByUrl instead.'
+    )
+    is_expected.to be_a_kind_of(Faraday::HttpCache::Strategies::ByUrl)
+  end
+
   describe 'Cache configuration' do
     it 'uses a MemoryStore by default' do
       expect(Faraday::HttpCache::MemoryStore).to receive(:new).and_call_original
@@ -128,9 +143,10 @@ describe Faraday::HttpCache::Storage do
     end
 
     it 'is fresh until cached and that 1 second elapses then the response is no longer fresh' do
+      current_time = Time.now
       headers = {
-        'Date' => (Time.now - 39).httpdate,
-        'Expires' => (Time.now + 40).httpdate
+        'Date' => (current_time - 39).httpdate,
+        'Expires' => (current_time + 40).httpdate
       }
 
       response = Faraday::HttpCache::Response.new(response_headers: headers)

data/spec/strategies/base_strategy_spec.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+
+describe Faraday::HttpCache::Strategies::BaseStrategy do
+  subject(:strategy) { described_class.new }
+
+  it 'uses a MemoryStore as a default store' do
+    expect(Faraday::HttpCache::MemoryStore).to receive(:new).and_call_original
+    strategy
+  end
+
+  context 'when the given store is not valid' do
+    let(:store) { double(:wrong_store) }
+    subject(:strategy) { described_class.new(store: store) }
+
+    it 'raises an error' do
+      expect { strategy }.to raise_error(ArgumentError)
+    end
+  end
+
+  it 'raises an error when abstract methods are called' do
+    expect { strategy.write(nil, nil) }.to raise_error(NotImplementedError)
+    expect { strategy.read(nil) }.to raise_error(NotImplementedError)
+    expect { strategy.delete(nil) }.to raise_error(NotImplementedError)
+  end
+end

data/spec/strategies/by_url_spec.rb

@@ -0,0 +1,145 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+
+describe Faraday::HttpCache::Strategies::ByUrl do
+  let(:cache_key) { '6e3b941d0f7572291c777b3e48c04b74124a55d0' }
+  let(:request) do
+    env = { method: :get, url: 'http://test/index' }
+    double(env.merge(serializable_hash: env))
+  end
+
+  let(:response) { double(serializable_hash: { response_headers: {} }) }
+
+  let(:cache) { Faraday::HttpCache::MemoryStore.new }
+
+  let(:strategy) { described_class.new(store: cache) }
+  subject { strategy }
+
+  describe 'Cache configuration' do
+    it 'uses a MemoryStore by default' do
+      expect(Faraday::HttpCache::MemoryStore).to receive(:new).and_call_original
+      described_class.new
+    end
+
+    it 'raises an error when the given store is not valid' do
+      wrong = double
+
+      expect {
+        described_class.new(store: wrong)
+      }.to raise_error(ArgumentError)
+    end
+  end
+
+  describe 'storing responses' do
+    shared_examples 'A strategy with serialization' do
+      it 'writes the response object to the underlying cache' do
+        entry = [serializer.dump(request.serializable_hash), serializer.dump(response.serializable_hash)]
+        expect(cache).to receive(:write).with(cache_key, [entry])
+        subject.write(request, response)
+      end
+    end
+
+    context 'with the JSON serializer' do
+      let(:serializer) { JSON }
+      it_behaves_like 'A strategy with serialization'
+
+      context 'when ASCII characters in response cannot be converted to UTF-8', if: Gem::Version.new(RUBY_VERSION) < Gem::Version.new('3.1') do
+        let(:response) do
+          body = String.new("\u2665").force_encoding('ASCII-8BIT')
+          double(:response, serializable_hash: { 'body' => body })
+        end
+
+        it 'raises and logs a warning' do
+          logger = double(:logger, warn: nil)
+          strategy = described_class.new(logger: logger)
+
+          expect {
+            strategy.write(request, response)
+          }.to raise_error(::Encoding::UndefinedConversionError)
+          expect(logger).to have_received(:warn).with(
+            'Response could not be serialized: "\xE2" from ASCII-8BIT to UTF-8. Try using Marshal to serialize.'
+          )
+        end
+      end
+    end
+
+    context 'with the Marshal serializer' do
+      let(:cache_key) { '337d1e9c6c92423dd1c48a23054139058f97be40' }
+      let(:serializer) { Marshal }
+      let(:strategy) { described_class.new(store: cache, serializer: Marshal) }
+
+      it_behaves_like 'A strategy with serialization'
+    end
+  end
+
+  describe 'reading responses' do
+    let(:strategy) { described_class.new(store: cache, serializer: serializer) }
+
+    shared_examples 'A strategy with serialization' do
+      it 'returns nil if the response is not cached' do
+        expect(subject.read(request)).to be_nil
+      end
+
+      it 'decodes a stored response' do
+        subject.write(request, response)
+
+        expect(subject.read(request)).to be_a(Faraday::HttpCache::Response)
+      end
+    end
+
+    context 'with the JSON serializer' do
+      let(:serializer) { JSON }
+
+      it_behaves_like 'A strategy with serialization'
+    end
+
+    context 'with the Marshal serializer' do
+      let(:serializer) { Marshal }
+
+      it_behaves_like 'A strategy with serialization'
+    end
+  end
+
+  describe 'deleting responses' do
+    it 'removes the entries from the cache of the given URL' do
+      subject.write(request, response)
+      subject.delete(request.url)
+      expect(subject.read(request)).to be_nil
+    end
+  end
+
+  describe 'remove age before caching and normalize max-age if non-zero age present' do
+    it 'is fresh if the response still has some time to live' do
+      headers = {
+        'Age' => 6,
+        'Cache-Control' => 'public, max-age=40',
+        'Date' => (Time.now - 38).httpdate,
+        'Expires' => (Time.now - 37).httpdate,
+        'Last-Modified' => (Time.now - 300).httpdate
+      }
+      response = Faraday::HttpCache::Response.new(response_headers: headers)
+      expect(response).to be_fresh
+      subject.write(request, response)
+
+      cached_response = subject.read(request)
+      expect(cached_response.max_age).to eq(34)
+      expect(cached_response).not_to be_fresh
+    end
+
+    it 'is fresh until cached and that 1 second elapses then the response is no longer fresh' do
+      headers = {
+        'Date' => (Time.now - 39).httpdate,
+        'Expires' => (Time.now + 40).httpdate
+      }
+
+      response = Faraday::HttpCache::Response.new(response_headers: headers)
+      expect(response).to be_fresh
+      subject.write(request, response)
+
+      sleep(1)
+      cached_response = subject.read(request)
+      expect(cached_response).not_to be_fresh
+    end
+  end
+end

data/spec/strategies/by_vary_spec.rb

@@ -0,0 +1,138 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+
+describe Faraday::HttpCache::Strategies::ByVary do
+  let(:vary_index_cache_key) { '64896419583e8022efeb21d0ece6e266c0e58b59' }
+  let(:cache_key) { '25230d75622fffc4f4de8a6af69e6e3764f7eb6f' }
+  let(:vary) { '' }
+  let(:request) do
+    env = {method: :get, url: 'http://test/index'}
+    double(env.merge(serializable_hash: env))
+  end
+
+  let(:response_payload) { {response_headers: {'Vary' => vary}} }
+
+  let(:response) do
+    instance_double(Faraday::HttpCache::Response, payload: response_payload, serializable_hash: response_payload)
+  end
+
+  let(:cache) { Faraday::HttpCache::MemoryStore.new }
+
+  let(:strategy) { described_class.new(store: cache) }
+  subject { strategy }
+
+  describe 'storing responses' do
+    shared_examples 'A strategy with serialization' do
+      it 'writes the response object to the underlying cache' do
+        entry = serializer.dump(response.serializable_hash)
+        expect(cache).to receive(:write).with(vary_index_cache_key, vary)
+        expect(cache).to receive(:write).with(cache_key, entry)
+        subject.write(request, response)
+      end
+    end
+
+    context 'with the JSON serializer' do
+      let(:serializer) { JSON }
+      it_behaves_like 'A strategy with serialization'
+
+      context 'when ASCII characters in response cannot be converted to UTF-8', if: Gem::Version.new(RUBY_VERSION) < Gem::Version.new('3.1') do
+        let(:response_payload) do
+          body = String.new("\u2665").force_encoding('ASCII-8BIT')
+          super().merge('body' => body)
+        end
+
+        it 'raises and logs a warning' do
+          logger = double(:logger, warn: nil)
+          strategy = described_class.new(logger: logger)
+
+          expect {
+            strategy.write(request, response)
+          }.to raise_error(::Encoding::UndefinedConversionError)
+          expect(logger).to have_received(:warn).with(
+            'Response could not be serialized: "\xE2" from ASCII-8BIT to UTF-8. Try using Marshal to serialize.'
+          )
+        end
+      end
+    end
+
+    context 'with the Marshal serializer' do
+      let(:vary_index_cache_key) { '6a7cb42440c10ef6edeb1826086a4d90b04103f0' }
+      let(:cache_key) { '45e0efd1a60d29ed69d6c6018dfcb96f58db89e0' }
+      let(:serializer) { Marshal }
+      let(:strategy) { described_class.new(store: cache, serializer: Marshal) }
+
+      it_behaves_like 'A strategy with serialization'
+    end
+  end
+
+  describe 'reading responses' do
+    let(:strategy) { described_class.new(store: cache, serializer: serializer) }
+
+    shared_examples 'A strategy with serialization' do
+      it 'returns nil if the response is not cached' do
+        expect(subject.read(request)).to be_nil
+      end
+
+      it 'decodes a stored response' do
+        subject.write(request, response)
+
+        expect(subject.read(request)).to be_a(Faraday::HttpCache::Response)
+      end
+    end
+
+    context 'with the JSON serializer' do
+      let(:serializer) { JSON }
+
+      it_behaves_like 'A strategy with serialization'
+    end
+
+    context 'with the Marshal serializer' do
+      let(:serializer) { Marshal }
+
+      it_behaves_like 'A strategy with serialization'
+    end
+  end
+
+  describe 'deleting responses' do
+    it 'ignores delete method' do
+      subject.write(request, response)
+      subject.delete(request.url)
+      expect(subject.read(request)).not_to be_nil
+    end
+  end
+
+  describe 'remove age before caching and normalize max-age if non-zero age present' do
+    it 'is fresh if the response still has some time to live' do
+      headers = {
+        'Age' => 6,
+        'Cache-Control' => 'public, max-age=40',
+        'Date' => (Time.now - 38).httpdate,
+        'Expires' => (Time.now - 37).httpdate,
+        'Last-Modified' => (Time.now - 300).httpdate
+      }
+      response = Faraday::HttpCache::Response.new(response_headers: headers)
+      expect(response).to be_fresh
+      subject.write(request, response)
+
+      cached_response = subject.read(request)
+      expect(cached_response.max_age).to eq(34)
+      expect(cached_response).not_to be_fresh
+    end
+
+    it 'is fresh until cached and that 1 second elapses then the response is no longer fresh' do
+      headers = {
+        'Date' => (Time.now - 39).httpdate,
+        'Expires' => (Time.now + 40).httpdate
+      }
+
+      response = Faraday::HttpCache::Response.new(response_headers: headers)
+      expect(response).to be_fresh
+      subject.write(request, response)
+
+      sleep(1)
+      cached_response = subject.read(request)
+      expect(cached_response).not_to be_fresh
+    end
+  end
+end

metadata

@@ -1,15 +1,16 @@
 --- !ruby/object:Gem::Specification
 name: faraday-http-cache
 version: !ruby/object:Gem::Version
-  version: 2.3.0
+  version: 2.4.0
 platform: ruby
 authors:
+- Lucas Mazza
 - George Guimarães
 - Gustavo Araujo
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2022-05-25 00:00:00.000000000 Z
+date: 2022-06-08 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: faraday
@@ -37,9 +38,14 @@ files:
 - lib/faraday-http-cache.rb
 - lib/faraday/http_cache.rb
 - lib/faraday/http_cache/cache_control.rb
+- lib/faraday/http_cache/memory_store.rb
 - lib/faraday/http_cache/request.rb
 - lib/faraday/http_cache/response.rb
 - lib/faraday/http_cache/storage.rb
+- lib/faraday/http_cache/strategies.rb
+- lib/faraday/http_cache/strategies/base_strategy.rb
+- lib/faraday/http_cache/strategies/by_url.rb
+- lib/faraday/http_cache/strategies/by_vary.rb
 - spec/binary_spec.rb
 - spec/cache_control_spec.rb
 - spec/http_cache_spec.rb
@@ -49,6 +55,9 @@ files:
 - spec/response_spec.rb
 - spec/spec_helper.rb
 - spec/storage_spec.rb
+- spec/strategies/base_strategy_spec.rb
+- spec/strategies/by_url_spec.rb
+- spec/strategies/by_vary_spec.rb
 - spec/support/empty.png
 - spec/support/test_app.rb
 - spec/support/test_server.rb
@@ -72,21 +81,24 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.0.3
+rubygems_version: 3.2.3
 signing_key:
 specification_version: 4
 summary: A Faraday middleware that stores and validates cache expiration.
 test_files:
-- spec/spec_helper.rb
-- spec/validation_spec.rb
-- spec/json_spec.rb
+- spec/binary_spec.rb
+- spec/cache_control_spec.rb
+- spec/http_cache_spec.rb
 - spec/instrumentation_spec.rb
+- spec/json_spec.rb
+- spec/request_spec.rb
+- spec/response_spec.rb
+- spec/spec_helper.rb
 - spec/storage_spec.rb
-- spec/http_cache_spec.rb
-- spec/binary_spec.rb
-- spec/support/test_app.rb
+- spec/strategies/base_strategy_spec.rb
+- spec/strategies/by_url_spec.rb
+- spec/strategies/by_vary_spec.rb
 - spec/support/empty.png
+- spec/support/test_app.rb
 - spec/support/test_server.rb
-- spec/request_spec.rb
-- spec/cache_control_spec.rb
-- spec/response_spec.rb
+- spec/validation_spec.rb