faraday-http-cache 2.7.0 → 3.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9178a3cc4f43cad31ef2a21a3cac0ef2ccf1a3ea86e5667df90aee9aa58da4d3
-  data.tar.gz: 28ea9a28a3fee4f78e8da8cf7af3d84f051836475ef8f6aca0e1533f0b0bafa5
+  metadata.gz: 8308a71aed66c20d85c6bc345b40c36f63d6362b562e2ce21ba11c002c25929a
+  data.tar.gz: 707c84e7c6b8d0f54f7f55142649db9623f0031197d0fe08f195ab96d9e2fe49
 SHA512:
-  metadata.gz: 1f7d626be02155cea5f5a4ad8c26070da0a35b3e7e7c0d0af5d4441da3ccd75d46c1e697700510a0abb740e0e0ce3185ca26688f946c907d2fa0a4aab3dec3e0
-  data.tar.gz: f2f881a67a1a7684ef8029932ffb51673c1ce23b49e09178fab248e6bb2648969d99bf1725d5878e9d33b682050577f441520297970cac22db0cc88ceb6e914f
+  metadata.gz: 7cfea8ce8b26348fd53e4295aed88e46f3ac5f628d6b2ee65e0c939a034c789009e9bd403c1037a8c86b4c6f7f39fa3555d4acafc27db4c4a7219abb2c335917
+  data.tar.gz: 037b527d2ba46be6c9f961ba417fcc585f9bda4daf21eb01fd820f4c902b597a2f32df90863dc213ed0916fa1788a142a6b106d46c2bb5afd2314fb75767b6a2

data/README.md

@@ -62,8 +62,10 @@ 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 the stdlib
-[Marshal][marshal] instead. Alternatively you could use another json library like `oj` or `yajl-ruby`.
+For full unicode support, or if you expect to be dealing with images, you can use another json
+library like `oj` or `yajl-ruby`, or the stdlib [Marshal][marshal]. Only pick Marshal when you fully
+trust the cache store: `Marshal.load` will instantiate any object found in the data, while the
+default `JSON` serializer parses entries into plain hashes and never instantiates classes.
 
 ```ruby
 client = Faraday.new do |builder|
@@ -214,9 +216,11 @@ The `max-age`, `must-revalidate`, `proxy-revalidate`, `s-maxage` and
 
 ### Shared vs. non-shared caches
 
-By default, the middleware acts as a "shared cache" per RFC 2616. This means it does not cache
-responses with `Cache-Control: private`. This behavior can be changed by passing in the
-`:shared_cache` configuration option:
+By default, the middleware acts as a "shared cache" per RFC 9111. This means it does not cache
+responses with `Cache-Control: private`, and it only stores and reuses responses to requests that
+carried an `Authorization` header when the response explicitly allows it with `public`,
+`must-revalidate` or `s-maxage` (RFC 9111 section 3.5). This behavior can be changed by passing in
+the `:shared_cache` configuration option:
 
 ```ruby
 client = Faraday.new do |builder|

data/lib/faraday/http_cache/cache_control.rb

@@ -34,9 +34,9 @@ module Faraday
 
       # Internal: Gets the 'max-age' directive as an Integer.
       #
-      # Returns nil if the 'max-age' directive isn't present.
+      # Returns nil if the 'max-age' directive isn't present or has no value.
       def max_age
-        @directives['max-age'].to_i if @directives.key?('max-age')
+        integer_directive('max-age')
       end
 
       # Internal: Gets the 'max-age' directive as an Integer.
@@ -45,16 +45,16 @@ module Faraday
       # if present to account for having to remove static age header when caching responses
       def normalize_max_ages(age)
         if age > 0
-          @directives['max-age'] = @directives['max-age'].to_i - age if @directives.key?('max-age')
-          @directives['s-maxage'] = @directives['s-maxage'].to_i - age if @directives.key?('s-maxage')
+          @directives['max-age'] = max_age - age if max_age
+          @directives['s-maxage'] = shared_max_age - age if shared_max_age
         end
       end
 
       # Internal: Gets the 's-maxage' directive as an Integer.
       #
-      # Returns nil if the 's-maxage' directive isn't present.
+      # Returns nil if the 's-maxage' directive isn't present or has no value.
       def shared_max_age
-        @directives['s-maxage'].to_i if @directives.key?('s-maxage')
+        integer_directive('s-maxage')
       end
       alias s_maxage shared_max_age
 
@@ -70,9 +70,10 @@ module Faraday
 
       # Internal: Gets the 'stale-while-revalidate' directive as an Integer.
       #
-      # Returns nil if the 'stale-while-revalidate' directive isn't present.
+      # Returns nil if the 'stale-while-revalidate' directive isn't present or
+      # has no value.
       def stale_while_revalidate
-        @directives['stale-while-revalidate'].to_i if @directives.key?('stale-while-revalidate')
+        integer_directive('stale-while-revalidate')
       end
 
       # Internal: Gets the String representation for the cache directives.
@@ -98,6 +99,16 @@ module Faraday
 
       private
 
+      # Internal: Reads a directive whose value must be an integer.
+      # A directive given without a value (a bare 'max-age') is parsed as
+      # true; treat it as absent instead of calling to_i on it.
+      #
+      # Returns the Integer value, or nil.
+      def integer_directive(name)
+        value = @directives[name]
+        value.to_i unless value.nil? || value == true
+      end
+
       # Internal: Parses the Cache Control string to a Hash.
       # Existing whitespace will be removed and the string is split on commas.
       # For each part everything before a '=' will be treated as the key

data/lib/faraday/http_cache/response.rb

@@ -98,6 +98,22 @@ module Faraday
         cacheable?(false)
       end
 
+      # Internal: Checks if a shared cache may reuse this response for requests
+      # other than the one that carried an 'Authorization' header.
+      #
+      # RFC 9111 section 3.5: a shared cache must not use a cached response to
+      # a request with an 'Authorization' header to satisfy any subsequent
+      # request unless the response carries a 'Cache-Control' directive that
+      # explicitly allows it. The directives with that effect are
+      # 'must-revalidate', 'public' and 's-maxage'.
+      #
+      # Returns true if one of those directives is present.
+      def shared_cache_authorized?
+        cache_control.public? ||
+          cache_control.must_revalidate? ||
+          !cache_control.shared_max_age.nil?
+      end
+
       # Internal: Gets the response age in seconds.
       #
       # Returns the 'Age' header if present, or subtracts the response 'date'

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

@@ -29,7 +29,9 @@ module Faraday
         # @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'.
+        #   respond to 'dump' and 'load'. 'load' must never instantiate classes
+        #   named by the data, since the cached entries contain response headers
+        #   sent by the origin server.
         # @option options [Logger, nil] :logger - an object to be used to emit warnings.
         def initialize(options = {})
           @cache = options[:store] || Faraday::HttpCache::MemoryStore.new
@@ -80,7 +82,12 @@ module Faraday
         end
 
         def deserialize_object(object)
-          @serializer.load(object).transform_keys(&:to_sym)
+          # JSON.load enables create_additions, so a `json_class` key in the
+          # entry would instantiate that class. Response headers are stored
+          # verbatim, which lets an origin server plant such a key. JSON.parse
+          # only ever builds plain Ruby objects.
+          loaded = @serializer.equal?(::JSON) ? ::JSON.parse(object) : @serializer.load(object)
+          loaded.transform_keys(&:to_sym)
         end
 
         def warn(message)

data/lib/faraday/http_cache/version.rb

@@ -2,6 +2,6 @@
 
 module Faraday
   class HttpCache
-    VERSION = '2.7.0'
+    VERSION = '3.0.0'
   end
 end

data/lib/faraday/http_cache.rb

@@ -196,7 +196,7 @@ module Faraday
     def process(env)
       entry = @strategy.read(@request)
 
-      return fetch(env) if entry.nil?
+      return fetch(env) if entry.nil? || !reusable?(entry)
 
       if entry.fresh? && !@request.no_cache?
         response = entry.to_response(env)
@@ -270,7 +270,7 @@ module Faraday
     #
     # Returns nothing.
     def store(response)
-      if shared_cache? ? response.cacheable_in_shared_cache? : response.cacheable_in_private_cache?
+      if storable?(response)
         trace :store
         @strategy.write(@request, response)
       else
@@ -278,10 +278,47 @@ module Faraday
       end
     end
 
+    # Internal: Checks if the response may be stored by this cache instance.
+    # A shared cache also refuses responses to requests that carried an
+    # 'Authorization' header unless the response explicitly allows it
+    # (RFC 9111 section 3.5), so what is never stored is never served to
+    # another caller.
+    #
+    # response - a 'Faraday::HttpCache::Response' instance.
+    #
+    # Returns true or false.
+    def storable?(response)
+      return response.cacheable_in_private_cache? unless shared_cache?
+      return false if authorization_bearing? && !response.shared_cache_authorized?
+
+      response.cacheable_in_shared_cache?
+    end
+
+    # Internal: Checks if a stored entry may be served for the current request.
+    # Entries written by earlier versions of this middleware may be responses
+    # to authenticated requests that a shared cache must not reuse; such an
+    # entry is treated as a miss and replaced.
+    #
+    # entry - a 'Faraday::HttpCache::Response' read from the strategy.
+    #
+    # Returns true or false.
+    def reusable?(entry)
+      return true unless shared_cache? && authorization_bearing?
+
+      entry.shared_cache_authorized?
+    end
+
+    # Internal: Checks if the current request carries an 'Authorization' header.
+    def authorization_bearing?
+      !@request.headers['Authorization'].nil?
+    end
+
     def delete(request, response)
-      headers = %w[Location Content-Location]
-      headers.each do |header|
-        url = response.headers[header]
+      # A response cut short by a timeout or a reset can arrive without
+      # headers; there is still an entry to invalidate for the request URL.
+      headers = response.headers || {}
+      %w[Location Content-Location].each do |header|
+        url = headers[header]
         @strategy.delete(url) if url
       end
 

data/spec/cache_control_spec.rb

@@ -52,6 +52,23 @@ describe Faraday::HttpCache::CacheControl do
     expect(cache_control.shared_max_age).to eq(600)
   end
 
+  it 'responds to #max_age with nil when the max-age directive has no value' do
+    cache_control = Faraday::HttpCache::CacheControl.new('public, max-age')
+    expect(cache_control.max_age).to be_nil
+  end
+
+  it 'responds to #shared_max_age with nil when the s-maxage directive has no value' do
+    cache_control = Faraday::HttpCache::CacheControl.new('public, s-maxage')
+    expect(cache_control.shared_max_age).to be_nil
+  end
+
+  it 'normalizes max ages without raising when a directive has no value' do
+    cache_control = Faraday::HttpCache::CacheControl.new('max-age, s-maxage=600')
+    cache_control.normalize_max_ages(100)
+    expect(cache_control.max_age).to be_nil
+    expect(cache_control.shared_max_age).to eq(500)
+  end
+
   it 'responds to #shared_max_age with nil when no s-maxage directive present' do
     cache_control = Faraday::HttpCache::CacheControl.new('public')
     expect(cache_control.shared_max_age).to be_nil
@@ -116,4 +133,14 @@ describe Faraday::HttpCache::CacheControl do
     cache_control = Faraday::HttpCache::CacheControl.new('public, max-age=60')
     expect(cache_control.stale_while_revalidate).to be_nil
   end
+
+  it 'responds to #stale_while_revalidate with 0 when directive is invalid true string value' do
+    cache_control = Faraday::HttpCache::CacheControl.new('public, max-age=60, stale-while-revalidate=true')
+    expect(cache_control.stale_while_revalidate).to eq(0)
+  end
+
+  it 'responds to #stale_while_revalidate with nil when directive has no integer assignment' do
+    cache_control = Faraday::HttpCache::CacheControl.new('public, max-age=60, stale-while-revalidate')
+    expect(cache_control.stale_while_revalidate).to be_nil
+  end
 end

data/spec/http_cache_spec.rb

@@ -96,6 +96,33 @@ describe Faraday::HttpCache do
       client.get('broken')
     end
 
+    it 'still expires the request URL when the response has no headers' do
+      store = Faraday::HttpCache::MemoryStore.new
+      cached = Faraday.new(url: ENV['FARADAY_SERVER']) do |stack|
+        stack.use Faraday::HttpCache, store: store
+        stack.adapter ENV['FARADAY_ADAPTER'].to_sym
+      end
+      # Mimics an adapter that gives up mid-response: the env is completed
+      # with no status worth the name and no response headers at all.
+      headerless_adapter = Class.new(Faraday::Adapter) do
+        def call(env)
+          super
+          env.status = 0
+          env.response_headers = nil
+          env.response.finish(env)
+        end
+      end
+      broken = Faraday.new(url: ENV['FARADAY_SERVER']) do |stack|
+        stack.use Faraday::HttpCache, store: store
+        stack.adapter headerless_adapter
+      end
+
+      cached.get('get')
+      broken.post('get')
+
+      expect(cached.get('get').body).to eq('2')
+    end
+
     it 'expires entries for the "Location" header' do
       client.get('get')
       client.post('delete-with-location')
@@ -121,6 +148,48 @@ describe Faraday::HttpCache do
       expect(logger).to receive(:debug) { |&block| expect(block.call).to eq('HTTP Cache: [GET /private] miss, uncacheable') }
       client.get('private')
     end
+
+    describe 'responses to requests with an "Authorization" header' do
+      def get_as(user, path = 'authenticated')
+        client.get(path) { |request| request.headers['Authorization'] = "Bearer #{user}" }
+      end
+
+      it 'does not serve one caller the response cached for another' do
+        alice = get_as('alice')
+        bob = get_as('bob')
+
+        expect(alice.body).to eq('1:Bearer alice')
+        expect(bob.body).to eq('2:Bearer bob')
+      end
+
+      it 'logs that the response is uncacheable' do
+        expect(logger).to receive(:debug) { |&block| expect(block.call).to eq('HTTP Cache: [GET /authenticated] miss, uncacheable') }
+        get_as('alice')
+      end
+
+      it 'caches responses that are explicitly marked as public' do
+        get_as('alice', 'authenticated-public')
+        bob = get_as('bob', 'authenticated-public')
+
+        expect(bob.body).to eq('1:Bearer alice')
+      end
+
+      it 'does not serve entries stored before the authorization check existed' do
+        store = Faraday::HttpCache::MemoryStore.new
+        clients = [false, true].map do |shared|
+          Faraday.new(url: ENV['FARADAY_SERVER']) do |stack|
+            stack.use Faraday::HttpCache, store: store, shared_cache: shared
+            stack.adapter ENV['FARADAY_ADAPTER'].to_sym
+          end
+        end
+        private_client, shared_client = clients
+
+        private_client.get('authenticated') { |request| request.headers['Authorization'] = 'Bearer alice' }
+        bob = shared_client.get('authenticated') { |request| request.headers['Authorization'] = 'Bearer bob' }
+
+        expect(bob.body).to eq('2:Bearer bob')
+      end
+    end
   end
 
   describe 'when acting as a private cache' do
@@ -135,6 +204,13 @@ describe Faraday::HttpCache do
       expect(logger).to receive(:debug) { |&block| expect(block.call).to eq('HTTP Cache: [GET /private] miss, store') }
       client.get('private')
     end
+
+    it 'caches responses to requests with an "Authorization" header' do
+      client.get('authenticated') { |request| request.headers['Authorization'] = 'Bearer alice' }
+      bob = client.get('authenticated') { |request| request.headers['Authorization'] = 'Bearer bob' }
+
+      expect(bob.body).to eq('1:Bearer alice')
+    end
   end
 
   it 'does not cache responses with a explicit no-store directive' do

data/spec/spec_helper.rb

@@ -16,6 +16,7 @@ require 'active_support/cache'
 
 require 'support/test_app'
 require 'support/test_server'
+require 'support/json_gadget'
 
 server = TestServer.new
 

data/spec/strategies/by_url_spec.rb

@@ -16,6 +16,20 @@ describe Faraday::HttpCache::Strategies::ByUrl do
   let(:strategy) { described_class.new(store: cache) }
   subject { strategy }
 
+  describe 'deserializing entries' do
+    let(:response) { double(serializable_hash: { response_headers: { 'json_class' => 'JsonGadget' } }) }
+
+    before { JsonGadget.invocations.clear }
+
+    it 'never instantiates classes named by the cached data' do
+      strategy.write(request, response)
+      cached = strategy.read(request)
+
+      expect(JsonGadget.invocations).to be_empty
+      expect(cached.payload[:response_headers]['json_class']).to eq('JsonGadget')
+    end
+  end
+
   describe 'Cache configuration' do
     it 'uses a MemoryStore by default' do
       expect(Faraday::HttpCache::MemoryStore).to receive(:new).and_call_original

data/spec/strategies/by_vary_spec.rb

@@ -23,6 +23,20 @@ describe Faraday::HttpCache::Strategies::ByVary do
   let(:strategy) { described_class.new(store: cache) }
   subject { strategy }
 
+  describe 'deserializing entries' do
+    let(:response_payload) { { response_headers: { 'Vary' => vary, 'json_class' => 'JsonGadget' } } }
+
+    before { JsonGadget.invocations.clear }
+
+    it 'never instantiates classes named by the cached data' do
+      strategy.write(request, response)
+      cached = strategy.read(request)
+
+      expect(JsonGadget.invocations).to be_empty
+      expect(cached.payload[:response_headers]['json_class']).to eq('JsonGadget')
+    end
+  end
+
   describe 'storing responses' do
     shared_examples 'A strategy with serialization' do
       it 'writes the response object to the underlying cache' do

data/spec/support/json_gadget.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+# A class that records every attempt to build it through JSON.load's
+# create_additions hook, so specs can assert cached entries never do that.
+class JsonGadget
+  def self.invocations
+    @invocations ||= []
+  end
+
+  def self.json_create(attributes)
+    invocations << attributes
+    new
+  end
+end

data/spec/support/test_app.rb

@@ -85,6 +85,14 @@ class TestApp < Sinatra::Base
     halt 405
   end
 
+  get '/authenticated' do
+    [200, { 'Cache-Control' => 'max-age=200' }, "#{increment_counter}:#{env['HTTP_AUTHORIZATION']}"]
+  end
+
+  get '/authenticated-public' do
+    [200, { 'Cache-Control' => 'public, max-age=200' }, "#{increment_counter}:#{env['HTTP_AUTHORIZATION']}"]
+  end
+
   get '/private' do
     [200, { 'Cache-Control' => 'private, max-age=100' }, increment_counter]
   end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: faraday-http-cache
 version: !ruby/object:Gem::Version
-  version: 2.7.0
+  version: 3.0.0
 platform: ruby
 authors:
 - Lucas Mazza
@@ -59,6 +59,7 @@ files:
 - spec/strategies/by_url_spec.rb
 - spec/strategies/by_vary_spec.rb
 - spec/support/empty.png
+- spec/support/json_gadget.rb
 - spec/support/test_app.rb
 - spec/support/test_server.rb
 - spec/validation_spec.rb
@@ -73,14 +74,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 3.2.0
+      version: 3.3.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.3
+rubygems_version: 3.6.9
 specification_version: 4
 summary: A Faraday middleware that stores and validates cache expiration.
 test_files:
@@ -97,6 +98,7 @@ test_files:
 - spec/strategies/by_url_spec.rb
 - spec/strategies/by_vary_spec.rb
 - spec/support/empty.png
+- spec/support/json_gadget.rb
 - spec/support/test_app.rb
 - spec/support/test_server.rb
 - spec/validation_spec.rb