Add a fault_tolerant flag to fail-over to stale cache.

Gemfile

@@ -1,2 +1,3 @@
 source :rubygems
+gem 'rake', '~> 10.0'
 gemspec

README

@@ -24,6 +24,10 @@ caching solution for small to medium sized deployments. More sophisticated /
 high-performance caching systems (e.g., Varnish, Squid, httpd/mod-cache) may be
 more appropriate for large deployments with significant throughput requirements.
 
+Rack::Cache includes an option to enable fault tolerant caching, so that stale
+cached results can be returned if the downstream service is unavailable.  Just
+set `:fault_tolerant => true` in the options hash.
+
 Installation
 ------------
 

lib/rack/cache/context.rb

@@ -6,6 +6,15 @@
 module Rack::Cache
   # Implements Rack's middleware interface and provides the context for all
   # cache logic, including the core logic engine.
+
+  # The list of exceptions indicating a network failure.
+  def self.network_failure_exceptions
+    # TODO: Make these configurable, to work in a non-faraday environment.
+    @network_failure_exceptions ||= Set.new(
+      %w(Timeout::Error Faraday::Error::ConnectionFailed Faraday::Error::TimeoutError)
+    )
+  end
+
   class Context
     include Rack::Cache::Options
 
@@ -159,7 +168,9 @@ def invalidate
     # found and is fresh, use it as the response without forwarding any
     # request to the backend. When a matching cache entry is found but is
     # stale, attempt to #validate the entry with the backend using conditional
-    # GET. When no matching cache entry is found, trigger #miss processing.
+    # GET. If validation fails due to a timeout or connection error, serve the
+    # stale cache entry anyway. When no matching cache entry is found, trigger
+    # miss processing.
     def lookup
       if @request.no_cache? && allow_reload?
         record :reload
@@ -178,14 +189,45 @@ def lookup
             entry
           else
             record :stale
-            validate(entry)
+            validate_with_retries_and_stale_cache_failover(entry)
           end
         else
           record :miss
-          fetch
+          fetch_with_retries
         end
       end
     end
+
+    # Returns stale cache on timeout or connection error.
+    def validate_with_retries_and_stale_cache_failover(entry)
+      begin
+        send_with_retries(:validate, entry)
+      rescue lambda { |error| fault_tolerant_condition? && network_failure_exception?(error) } => e
+        record :connnection_failed
+        age = entry.age.to_s
+        entry.headers['Age'] = age
+        record "Fail-over to stale cache data with age #{age} due to #{e.class.name}: #{e.to_s}"
+        entry
+      end
+    end
+
+    # Calls fetch wrapped with retries.
+    def fetch_with_retries
+      send_with_retries(:fetch)
+    end
+
+    #This method is used in the lambda of lookup (a few lines up) to test if in an error case the fallback to stale
+    #data should be performed.
+    #If the per-request parameter :fallback_to_cache is in the middleware options then it will be used to decide.
+    #If it is not present, then the global setting will be honored.
+    #Setting the per-request option to false overrides the global settings!
+    def fault_tolerant_condition?
+      if @request.env.include?(:middleware_options) && @request.env[:middleware_options].include?(:fallback_to_cache)
+        @request.env[:middleware_options][:fallback_to_cache]
+      else
+        fault_tolerant?
+      end
+    end
 
     # Validate that the cache entry is fresh. The original request is used
     # as a template for a conditional GET request with the backend.
@@ -194,16 +236,15 @@ def validate(entry)
       @env['REQUEST_METHOD'] = 'GET'
 
       # add our cached last-modified validator to the environment
-      @env['HTTP_IF_MODIFIED_SINCE'] = entry.last_modified
+      @env['HTTP_IF_MODIFIED_SINCE'] = entry.last_modified if entry.last_modified
 
       # Add our cached etag validator to the environment.
       # We keep the etags from the client to handle the case when the client
       # has a different private valid entry which is not cached here.
       cached_etags = entry.etag.to_s.split(/\s*,\s*/)
       request_etags = @request.env['HTTP_IF_NONE_MATCH'].to_s.split(/\s*,\s*/)
       etags = (cached_etags + request_etags).uniq
-      @env['HTTP_IF_NONE_MATCH'] = etags.empty? ? nil : etags.join(', ')
-
+      @env['HTTP_IF_NONE_MATCH'] = etags.join(', ') unless etags.empty?
       response = forward
 
       if response.status == 304
@@ -295,5 +336,41 @@ def log(level, message)
         @env['rack.errors'].write(message)
       end
     end
+
+    private
+
+    # How many times has the consumer requested retries.
+    def requested_retries
+      retries_defined? ? @request.env[:middleware_options][:retries].to_i : 0
+    end
+
+    # Whether the consumer asked us to retry.
+    def retries_defined?
+      @request.env[:middleware_options] && @request.env[:middleware_options][:retries]
+    end
+
+    # Whether the error is a known network failure exception or not.
+    def network_failure_exception?(error)
+      Rack::Cache.network_failure_exceptions.include?(error.class.name)
+    end
+
+    # Sends a method and wraps it with a retry loop if retries are requested
+    def send_with_retries(method, *args)
+      retries = requested_retries
+      retry_counter = 0
+
+      begin
+        send(method, *args)
+      rescue lambda { |error| (retries > 0) && network_failure_exception?(error) } => e
+        if retry_counter < retries
+          retry_counter += 1
+          record "Retrying #{retry_counter} of #{retries} times due to #{e.class.name}: #{e.to_s}"
+          retry
+        else
+          record "Failed retry after #{retries} retries due to #{e.class.name}: #{e.to_s}"
+          raise
+        end
+      end
+    end
   end
 end

lib/rack/cache/options.rb

@@ -107,6 +107,11 @@ def option_name(key)
     # be used.
     option_accessor :use_native_ttl
 
+    # Specifies whether to serve a request from a stale cache entry if
+    # the attempt to revalidate that entry returns a connection
+    # failure or times out.
+    option_accessor :fault_tolerant
+
     # The underlying options Hash. During initialization (or outside of a
     # request), this is a default values Hash. During a request, this is the
     # Rack environment Hash. The default values Hash is merged in underneath
@@ -149,6 +154,7 @@ def initialize_options(options={})
         'rack-cache.allow_reload'     => false,
         'rack-cache.allow_revalidate' => false,
         'rack-cache.use_native_ttl'   => false,
+        'rack-cache.fault_tolerant'   => false,
       }
       self.options = options
     end

lib/rack/cache/response.rb

@@ -146,7 +146,7 @@ def date
 
     # The age of the response.
     def age
-      (headers['Age'] ||  [(now - date).to_i, 0].max).to_i
+      [headers['Age'].to_i, (now - date).to_i].max
     end
 
     # The number of seconds after the time specified in the response's Date

rack-cache.gemspec

@@ -3,8 +3,8 @@ Gem::Specification.new do |s|
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
 
   s.name = 'rack-cache'
-  s.version = '1.2'
-  s.date = '2012-03-05'
+  s.version = '1.3'
+  s.date = '2013-06-18'
 
   s.summary     = "HTTP Caching for Rack"
   s.description = "Rack::Cache is suitable as a quick drop-in component to enable HTTP caching for Rack-based applications that produce freshness (Expires, Cache-Control) and/or validation (Last-Modified, ETag) information."
@@ -66,6 +66,7 @@ Gem::Specification.new do |s|
   s.add_development_dependency 'bacon'
   s.add_development_dependency 'memcached'
   s.add_development_dependency 'dalli'
+  s.add_development_dependency 'pry'
 
   s.has_rdoc = true
   s.homepage = "http://rtomayko.github.com/rack-cache/"