faraday-http-cache 1.0.1 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: d851a7d541055e460f971cf80a0e06ac22e532e5
-  data.tar.gz: 519218770fbff5e98c7fbb9ba6561b6f8af3a75e
+  metadata.gz: fbe28eb1ed1ea0c338b45aad4f4c85002031a3d7
+  data.tar.gz: a98f5ecdd009cabb2a535ebc9b505c168fdac1f7
 SHA512:
-  metadata.gz: b13880d63d13760de6e4759b1315311412ca445f706b80e9dcb4a4fc7a23bdb22f976f5fbd77e6782ed62b0fa2e5c9e48c0806cbf4e5e137ab038ad0ea2739d2
-  data.tar.gz: 8945bb6f2bf29e4f9e6578eb40c4fcaa2d1c0502ad1c22963ae0bfab6c7f848d0fdac4df1f9010225c67e9461d23bedecfeaf4f61782fab28c6bfc3063ac7866
+  metadata.gz: d92bdd0d0ccc0e30da2aa4288c7b33be98c82ef2c8e200f8bdd65bb79433dfc64ba1314c0174dd4e5add8992499816b3e0385b38c7e8d50b3ac665612f25d77d
+  data.tar.gz: d9f5c220e6179f176640c7d97c5c6ff7235e5d774882dbbff9352dcbecf73ce788b6d303655a6cafba2ae53332fddd499fdc06caf41432611aaf4af6a3b4d3c2

data/README.md

@@ -79,6 +79,45 @@ client.get('http://site/api/users')
 # logs "HTTP Cache: [GET users] miss, store"
 ```
 
+### Instrumentation
+
+In addition to logging you can instrument the middleware by passing in an `:instrumenter` option
+such as ActiveSupport::Notifications (compatible objects are also allowed).
+
+The event `process_request.http_cache.faraday` will be published every time the middleware
+processes a request. In the event payload, `:env` contains the response Faraday env and
+`:cache_status` contains a Symbol indicating the status of the cache processing for that request:
+
+- `:unacceptable` means that the request did not go through the cache at all.
+- `:miss` means that no cached response could be found.
+- `:invalid` means that the cached response could not be validated against the server.
+- `:valid` means that the cached response *could* be validated against the server.
+- `:fresh` means that the cached response was still fresh and could be returned without even
+  calling the server.
+
+```ruby
+client = Faraday.new do |builder|
+  builder.use :http_cache, store: Rails.cache, instrumenter: ActiveSupport::Notifications
+  builder.adapter Faraday.default_adapter
+end
+
+# Subscribes to all events from Faraday::HttpCache.
+ActiveSupport::Notifications.subscribe "process_request.http_cache.faraday" do |*args|
+  event = ActiveSupport::Notifications::Event.new(*args)
+  cache_status = event.payload.fetch(:cache_status)
+  statsd = Statsd.new
+
+  case cache_status
+  when :fresh, :valid
+    statsd.increment("api-calls.cache_hits")
+  when :invalid, :miss
+    statsd.increment("api-calls.cache_misses")
+  when :unacceptable
+    statsd.increment("api-calls.cache_bypass")
+  end
+end
+```
+
 ## See it live
 
 You can clone this repository, install it's dependencies with Bundler (run `bundle install`) and

data/lib/faraday/http_cache.rb

@@ -37,14 +37,39 @@ module Faraday
   #   client = Faraday.new do |builder|
   #     builder.use :http_cache, store: Rails.cache, serializer: Marshal
   #   end
+  #
+  #   # Instrument events using ActiveSupport::Notifications
+  #   client = Faraday.new do |builder|
+  #     builder.use :http_cache, store: Rails.cache, instrumenter: ActiveSupport::Notifications
+  #   end
   class HttpCache < Faraday::Middleware
     # Internal: valid options for the 'initialize' configuration Hash.
-    VALID_OPTIONS = [:store, :serializer, :logger, :shared_cache]
+    VALID_OPTIONS = [:store, :serializer, :logger, :shared_cache, :instrumenter]
 
     UNSAFE_METHODS = [:post, :put, :delete, :patch]
 
     ERROR_STATUSES = 400..499
 
+    # The name of the instrumentation event.
+    EVENT_NAME = 'process_request.http_cache.faraday'
+
+    CACHE_STATUSES = [
+      # The request was not cacheable:
+      :unacceptable,
+
+      # The response was cached and can still be used:
+      :fresh,
+
+      # The response was cached and the server has validated it with a 304 response:
+      :valid,
+
+      # The response was cached but the server could not validate it.
+      :invalid,
+
+      # No response was found in the cache:
+      :miss
+    ]
+
     # Public: Initializes a new HttpCache middleware.
     #
     # app  - the next endpoint on the 'Faraday' stack.
@@ -53,6 +78,7 @@ module Faraday
     #             :serializer    - A serializer that should respond to 'dump' and 'load'.
     #             :shared_cache  - A flag to mark the middleware as a shared cache or not.
     #             :store         - A cache store that should respond to 'read' and 'write'.
+    #             :instrumenter  - An instrumentation object that should respond to 'instrument'.
     #
     # Examples:
     #
@@ -75,6 +101,7 @@ module Faraday
 
       @logger = options[:logger]
       @shared_cache = options.fetch(:shared_cache, true)
+      @instrumenter = options[:instrumenter]
       @storage = create_storage(options)
     end
 
@@ -118,6 +145,8 @@ module Faraday
       response.on_complete do
         delete(@request, response) if should_delete?(response.status, @request.method)
         log_request
+        response.env[:http_cache_trace] = @trace
+        instrument(response.env)
       end
     end
 
@@ -200,8 +229,16 @@ module Faraday
         response = Response.new(requested_env)
         if response.not_modified?
           trace :valid
+          updated_response_headers = response.payload[:response_headers]
+
+          # These headers are not allowed in 304 responses, yet some proxy
+          # servers add them in. Don't override the values from the original
+          # response.
+          updated_response_headers.delete('Content-Type')
+          updated_response_headers.delete('Content-Length')
+
           updated_payload = entry.payload
-          updated_payload[:response_headers].update(response.payload[:response_headers])
+          updated_payload[:response_headers].update(updated_response_headers)
           requested_env.update(updated_payload)
           response = Response.new(updated_payload)
         end
@@ -293,6 +330,27 @@ module Faraday
       @logger.debug(line)
     end
 
+    # Internal: instruments the request processing.
+    #
+    # Returns nothing.
+    def instrument(env)
+      return unless @instrumenter
+
+      payload = {
+        env: env,
+        cache_status: extract_status(env[:http_cache_trace])
+      }
+
+      @instrumenter.instrument(EVENT_NAME, payload)
+    end
+
+    # Internal: Extracts the cache status from a trace.
+    #
+    # Returns the Symbol status or nil if none was available.
+    def extract_status(trace)
+      CACHE_STATUSES.detect {|status| trace.include?(status) }
+    end
+
     # Internal: Checks if the given 'options' Hash contains only
     # valid keys. Please see the 'VALID_OPTIONS' constant for the
     # acceptable keys.

data/spec/http_cache_spec.rb

@@ -32,6 +32,11 @@ describe Faraday::HttpCache do
     expect(client.get('broken').body).to eq('2')
   end
 
+  it 'adds a trace of the actions performed to the env' do
+    response = client.post('post')
+    expect(response.env[:http_cache_trace]).to eq([:unacceptable, :delete])
+  end
+
   describe 'cache invalidation' do
     it 'expires POST requests' do
       client.get('counter')

data/spec/instrumentation_spec.rb

@@ -0,0 +1,78 @@
+require 'spec_helper'
+
+describe 'Instrumentation' do
+  let(:backend) { Faraday::Adapter::Test::Stubs.new }
+
+  let(:client) do
+    Faraday.new do |stack|
+      stack.use Faraday::HttpCache, instrumenter: ActiveSupport::Notifications
+      stack.adapter :test, backend
+    end
+  end
+
+  let(:events) { [] }
+  let(:subscriber) { lambda {|*args| events << ActiveSupport::Notifications::Event.new(*args) } }
+
+  around do |example|
+    ActiveSupport::Notifications.subscribed(subscriber, 'process_request.http_cache.faraday') do
+      example.run
+    end
+  end
+
+  describe 'the :cache_status payload entry' do
+    it 'is :miss if there is no cache entry for the URL' do
+      backend.get('/hello') do
+        [200, { 'Cache-Control' => 'public, max-age=999' }, '']
+      end
+
+      client.get('/hello')
+      expect(events.last.payload.fetch(:cache_status)).to eq(:miss)
+    end
+
+    it 'is :fresh if the cache entry has not expired' do
+      backend.get('/hello') do
+        [200, { 'Cache-Control' => 'public, max-age=999' }, '']
+      end
+
+      client.get('/hello') # miss
+      client.get('/hello') # fresh!
+      expect(events.last.payload.fetch(:cache_status)).to eq(:fresh)
+    end
+
+    it 'is :valid if the cache entry can be validated against the upstream' do
+      backend.get('/hello') do
+        headers = {
+          'Cache-Control' => 'public, must-revalidate, max-age=0',
+          'Etag' => '123ABCD'
+        }
+
+        [200, headers, '']
+      end
+
+      client.get('/hello') # miss
+
+      backend.get('/hello') { [304, {}, ''] }
+
+      client.get('/hello') # valid!
+      expect(events.last.payload.fetch(:cache_status)).to eq(:valid)
+    end
+
+    it 'is :invalid if the cache entry could not be validated against the upstream' do
+      backend.get('/hello') do
+        headers = {
+          'Cache-Control' => 'public, must-revalidate, max-age=0',
+          'Etag' => '123ABCD'
+        }
+
+        [200, headers, '']
+      end
+
+      client.get('/hello') # miss
+
+      backend.get('/hello') { [200, {}, ''] }
+
+      client.get('/hello') # invalid!
+      expect(events.last.payload.fetch(:cache_status)).to eq(:invalid)
+    end
+  end
+end

data/spec/validation_spec.rb

@@ -0,0 +1,36 @@
+require 'spec_helper'
+
+describe Faraday::HttpCache do
+  let(:backend) { Faraday::Adapter::Test::Stubs.new }
+
+  let(:client) do
+    Faraday.new(url: ENV['FARADAY_SERVER']) do |stack|
+      stack.use Faraday::HttpCache
+      stack.adapter :test, backend
+    end
+  end
+
+  it 'maintains the "Content-Type" header for cached responses' do
+    backend.get('/test') { [200, { 'ETag' => '123ABC', 'Content-Type' => 'x' }, ""] }
+    first_content_type = client.get('/test').headers['Content-Type']
+
+    # The Content-Type header of the validation response should be ignored.
+    backend.get('/test') { [304, { 'Content-Type' => 'y' }, ""] }
+    second_content_type = client.get('/test').headers['Content-Type']
+
+    expect(first_content_type).to eq('x')
+    expect(second_content_type).to eq('x')
+  end
+
+  it 'maintains the "Content-Length" header for cached responses' do
+    backend.get('/test') { [200, { 'ETag' => '123ABC', 'Content-Length' => 1 }, ""] }
+    first_content_length = client.get('/test').headers['Content-Length']
+
+    # The Content-Length header of the validation response should be ignored.
+    backend.get('/test') { [304, { 'Content-Length' => 2 }, ""] }
+    second_content_length = client.get('/test').headers['Content-Length']
+
+    expect(first_content_length).to eq(1)
+    expect(second_content_length).to eq(1)
+  end
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: faraday-http-cache
 version: !ruby/object:Gem::Version
-  version: 1.0.1
+  version: 1.1.0
 platform: ruby
 authors:
 - Lucas Mazza
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2015-01-30 00:00:00.000000000 Z
+date: 2015-04-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: faraday
@@ -42,6 +42,7 @@ files:
 - 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
@@ -50,6 +51,7 @@ files:
 - spec/support/empty.png
 - spec/support/test_app.rb
 - spec/support/test_server.rb
+- spec/validation_spec.rb
 homepage: https://github.com/plataformatec/faraday-http-cache
 licenses:
 - Apache 2.0
@@ -78,6 +80,7 @@ test_files:
 - 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
@@ -86,3 +89,4 @@ test_files:
 - spec/support/empty.png
 - spec/support/test_app.rb
 - spec/support/test_server.rb
+- spec/validation_spec.rb