Class: Faraday::HttpCache
- Inherits:
-
Middleware
- Object
- Middleware
- Faraday::HttpCache
- Defined in:
- lib/faraday/http_cache.rb,
lib/faraday/http_cache/request.rb,
lib/faraday/http_cache/storage.rb,
lib/faraday/http_cache/response.rb,
lib/faraday/http_cache/cache_control.rb
Overview
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 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 to your stack, so it will be closest to the inner app, avoiding issues with other middlewares on your stack.
Examples:
# Using the middleware with a simple client:
client = Faraday.new do |builder|
builder.user :http_cache, store: my_store_backend
builder.adapter Faraday.default_adapter
end
# Attach a Logger to the middleware.
client = Faraday.new do |builder|
builder.use :http_cache, logger: my_logger_instance, store: my_store_backend
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, store: Rails.cache
end
# Use Marshal for serialization
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
Defined Under Namespace
Classes: CacheControl, MemoryStore, Request, Response, Storage
Constant Summary collapse
- VALID_OPTIONS =
Internal: valid options for the ‘initialize’ configuration Hash.
[:store, :serializer, :logger, :shared_cache, :instrumenter]
- UNSAFE_METHODS =
[:post, :put, :delete, :patch]
- ERROR_STATUSES =
400..499
- EVENT_NAME =
The name of the instrumentation event.
'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 ]
Instance Method Summary collapse
-
#call(env) ⇒ Object
Public: Process the request into a duplicate of this instance to ensure that the internal state is preserved.
-
#call!(env) ⇒ Object
Internal: Process the stack request to try to serve a cache response.
-
#initialize(app, options = {}) ⇒ HttpCache
constructor
Public: Initializes a new HttpCache middleware.
Constructor Details
#initialize(app, options = {}) ⇒ HttpCache
Public: Initializes a new HttpCache middleware.
app - the next endpoint on the ‘Faraday’ stack. args - aditional options to setup the logger and the storage.
:logger - A logger object.
: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:
# Initialize the middleware with a 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.
store = ActiveSupport::Cache.lookup_store(:file_store, ['tmp'])
Faraday::HttpCache.new(app, store: store)
# Initialize the middleware with a MemoryStore and logger
store = ActiveSupport::Cache.lookup_store
Faraday::HttpCache.new(app, store: store, logger: my_logger)
98 99 100 101 102 103 104 105 106 |
# File 'lib/faraday/http_cache.rb', line 98 def initialize(app, = {}) super(app) () @logger = [:logger] @shared_cache = .fetch(:shared_cache, true) @instrumenter = [:instrumenter] @storage = create_storage() end |
Instance Method Details
#call(env) ⇒ Object
Public: Process the request into a duplicate of this instance to ensure that the internal state is preserved.
110 111 112 |
# File 'lib/faraday/http_cache.rb', line 110 def call(env) dup.call!(env) end |
#call!(env) ⇒ Object
Internal: Process the stack request to try to serve a cache response. On a cacheable request, the middleware will attempt to locate a valid stored response to serve. On a cache miss, the middleware will forward the request and try to store the response for future requests. If the request can’t be cached, the request will be delegated directly to the underlying app and does nothing to the response. The processed steps will be recorded to be logged once the whole process is finished.
Returns a ‘Faraday::Response’ instance.
124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 |
# File 'lib/faraday/http_cache.rb', line 124 def call!(env) @trace = [] @request = create_request(env) response = nil if @request.cacheable? response = if @request.no_cache? trace :bypass @app.call(env).on_complete do |fresh_env| response = Response.new(create_response(fresh_env)) store(response) end else process(env) end else trace :unacceptable response = @app.call(env) end 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 |