Faraday Http Cache

You can specify a :strategy to change how cache keys are generated.

• Faraday::HttpCache::Strategies::ByUrl (Default): Uses URL + HTTP method. Stores an array of request + response for each key.
• Faraday::HttpCache::Strategies::ByVary: Uses headers from the Vary header to generate keys. This is ideal for caching private responses with the same URL but different results for different users (e.g., /user).

To implement a custom strategy, subclass Faraday::HttpCache::Strategies::BaseStrategy and implement #write, #read, and #delete.

client = Faraday.new do |builder|
  builder.use :http_cache, store: Rails.cache, strategy: Faraday::HttpCache::Strategies::ByVary
  builder.adapter Faraday.default_adapter
end

The middleware supports stale-while-revalidate directives. When a response is stale but within the window, the middleware serves the stale response immediately. You can use the :on_stale callback to trigger asynchronous background refreshes.

client = Faraday.new do |builder|
  builder.use :http_cache,
    store: Rails.cache,
    on_stale: lambda { |request:, env:, cached_response:|
      RefreshApiCacheJob.perform_later(request.url.to_s)
    }
  builder.adapter Faraday.default_adapter
end

To use the middleware, add it to your Faraday builder. You can use the symbol :http_cache or the class Faraday::HttpCache. You must provide a store that responds to write, read, and delete (following the ActiveSupport::Cache API).

client = Faraday.new do |builder|
  builder.use :http_cache, store: Rails.cache
  # or
  builder.use Faraday::HttpCache, store: Rails.cache

  builder.adapter Faraday.default_adapter
end

Add faraday-http-cache to your Gemfile to use the middleware in your Faraday connection.

gem 'faraday-http-cache'

By default, the middleware acts as a 'shared cache' (RFC 9111), meaning it does not cache Cache-Control: private responses. To allow caching of private resources, set :shared_cache to false.

client = Faraday.new do |builder|
  builder.use :http_cache, shared_cache: false
  builder.adapter Faraday.default_adapter
end

The middleware requires a store for recording API responses. While a default in-memory store is provided, it is not suitable for production as it is not persisted across processes. For full Unicode support or handling binary data like images, you should specify a serializer such as Marshal or a library like oj or yajl-ruby.

# Using a specific Memcache store
store = ActiveSupport::Cache.lookup_store(:mem_cache_store, ['localhost:11211'])

client = Faraday.new do |builder|
  builder.use :http_cache, store: store
  builder.adapter Faraday.default_adapter
end

# Using Marshal for full unicode/binary support
client = Faraday.new do |builder|
  builder.use :http_cache, store: Rails.cache, serializer: Marshal
  builder.adapter Faraday.default_adapter
end

The ByVary strategy generates cache keys based on the Vary response header. It is specifically designed for caching private responses that share the same URL but differ based on request headers (e.g., https://api.github.com/user).

Key Characteristics:

• Header-based indexing: It uses an index that maps the request URL and Vary headers to specific cache entries.
• Limitation on Cache Invalidation: This strategy does not support the #delete method for clearing the cache via unsafe HTTP methods (like DELETE), because it cannot reliably find the specific cache keys using only the URL.
• Serialization: If you encounter Encoding::UndefinedConversionError during serialization, you may need to use Marshal for your serialization logic.

Pass a :logger option to receive debug information about cache hits, misses, and stores.

client = Faraday.new do |builder|
  builder.use :http_cache, store: Rails.cache, logger: Rails.logger
  builder.adapter Faraday.default_adapter
end

# Example log output:
# HTTP Cache: [GET users] miss, store

To enable HTTP caching in your Faraday connection, add the :http_cache middleware to your builder stack.

Important: This middleware should be the last handler attached to your stack (closest to the inner adapter) to avoid interference from other middlewares.

client = Faraday.new do |builder|
  builder.use :http_cache, store: my_store_backend
  builder.adapter Faraday.default_adapter
end

Pass an :instrumenter (e.g., ActiveSupport::Notifications) to subscribe to the http_cache.faraday event. The event payload contains :env and :cache_status.

ActiveSupport::Notifications.subscribe "http_cache.faraday" do |*args|
  event = ActiveSupport::Notifications::Event.new(*args)
  cache_status = event.payload[:cache_status]

  case cache_status
  when :fresh, :valid, :stale
    # Handle cache hit
  when :invalid, :miss
    # Handle cache miss
  when :unacceptable
    # Handle cache bypass
  end
end