response_bank 1.3.8 → 1.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f9c672021efe766d0fc33677c57dd7b1b1c4dc83c1a88824f40919722111b99a
-  data.tar.gz: f1215de9f225b7ea78d71cc7c815d7cff0811a737e3e9df4f686261e07339db7
+  metadata.gz: c3db28140576d28fa3faf6af84b571085208f7f40b977e615b102f038d60632a
+  data.tar.gz: ff991b1105a3c3b7827e5d7872ca55a648b692c6a67a67c144f5c458291adbe5
 SHA512:
-  metadata.gz: 563abba82ed5b7e1308edcc406dfc842b4f7bfa1c7ae489d886f73a67737261690a8faeec48d0ff7e2458f57ec3142620da88777625362e4b2c874f8bd93873d
-  data.tar.gz: bb6450674d14ba9aa4b9e9b35c54ebc740c55903ae0f3b19ead162c6764948c37bb69029e903ad75886dc7de40f1628e81c0af5ba411a7a015ff600d91bdaf7a
+  metadata.gz: face725382f16dc7ae054efd68de804eb303ff566bbf6758aa88d09922a2d8747e78fc9b9b2a9d109d508a0af9bcea28dc919d7f2b70954661c349f5feaaad2a
+  data.tar.gz: b9101b86d39ddc5ea9a427326cfd58834bd5d3015509d0411007f286ad34cd00f1113c43f6d20d1d01a2cc317340d905dc9bfb1b24bb2e2df8c6509ca897b00e

data/README.md

@@ -123,6 +123,52 @@ This gem supports the following versions of Ruby and Rails:
     end
     ```
 
+## Completing a deferred cache miss
+
+`ResponseBank::Middleware` can cache a body only when it is complete before the Rack tuple returns. An application that finishes a response later, such as through Rack partial hijack, can defer the cache write during a real ResponseBank miss:
+
+```ruby
+deferred_store = ResponseBank.defer_store(env)
+
+# Return the Rack response. Later, after the body was generated and written in full:
+cache_headers = headers.dup
+cache_headers.delete('Cache-Control') if cache_headers['Cache-Control'] == 'no-cache, no-store'
+deferred_store.complete(headers: cache_headers, body: completed_body)
+
+# Run this from the response-finished path. It is a no-op after completion.
+deferred_store.abort
+```
+
+`defer_store` is a cache-fill lifecycle API. Call it only from a ResponseBank cache-miss path after `ResponseCacheHandler` initialized the request and recorded logical fill-lock ownership. It raises if the request is not a GET cache miss, if required cache context is absent, or if another deferred store is already registered.
+
+The middleware arms the handle after the application returns the Rack tuple. It does not add an ETag to the live deferred response. `complete` copies and filters the final cache headers, adds the cached ETag and `Content-Encoding`, compresses the complete body, and writes the existing MessagePack cache format. It returns `true` when it stores and `false` when the request no longer owns an eligible fill.
+
+Call `complete` only after the intended response was generated and written successfully. Never call it from a rescue or ensure path. Do not complete failed, timed-out, disconnected, or truncated responses. The body must be the shared cache representation and must not contain client-specific data added for the live response.
+
+A caller that has already produced a Brotli representation can complete the fill without a second compression pass:
+
+```ruby
+deferred_store.complete_spliced(
+  headers: cache_headers,
+  body: compressed_body,
+  compression_level: 5,
+  slot: {
+    name: 'shopify_y',
+    compressed_offset: slot_offset,
+    replacement_length: replacement_length,
+    html_placeholder_offset: html_placeholder_offset,
+    html_placeholder_length: html_placeholder_length,
+    context_suffix: "\r\n",
+  },
+)
+```
+
+The body must be a complete, non-empty Brotli stream in the server cache encoding. It must already be safe for shared caching: if the live response contained client-specific slot bytes, replace them with the neutral placeholder before calling `complete_spliced`. ResponseBank builds versioned cache metadata from the slot descriptor. Omit `slot` when the Brotli stream has no replaceable content.
+
+The headers passed to `complete` describe the cached representation. They can differ from headers already sent to the client. ResponseBank rejects final cache headers that contain `private` or `no-store`, and it does not mutate the supplied hash. It captures the cache timestamp when `defer_store` is called, before deferred rendering and compression.
+
+`abort` is idempotent and releases an owned fill lock through `ResponseBank.release_lock`. Its default implementation is a no-op. The existing `write_to_cache` hook remains responsible for cleanup after a write attempt. An integration that releases those fills from `write_to_cache` should also implement `release_lock` for abandoned fills and failures that happen before the write hook. A key-only lock cannot prevent an old fill from releasing a replacement lock after its lease expires; integrations that need that guarantee must use owner tokens in their lock implementation.
+
 ## Brotli Splice Slots
 
 Applications that need per-request replacement inside cached Brotli HTML responses can pass an injector builder to `ResponseBank::Middleware`:
@@ -241,6 +287,29 @@ Advanced integrations can still install the per-request injector directly in the
 env[ResponseBank::BrotliSpliceSlot::INJECTOR_ENV_KEY] = injector
 ```
 
+## Exception Handling
+
+ResponseBank handles all exceptions gracefully during cache operations. If an exception occurs while reading from cache, deserializing cached data, or writing to cache, the middleware will:
+
+1. **On cache read failures**: Fall back to rendering the page normally (as if it was a cache miss).
+2. **On cache write failures**: Still serve the successfully rendered page to the user, but log the cache write failure.
+
+This ensures that issues with cache stores (Redis/Memcached down), serialization errors, or compression/decompression failures don't cause 500 errors for your users.
+
+### Custom Exception Handlers
+
+You can set a custom exception handler in the Rack environment to be notified when cache operations fail (e.g., to report to Bugsnag, Sentry, etc.):
+
+```ruby
+# In an initializer or middleware
+class MyMiddleware
+  def call(env)
+    env['response_bank.on_exception'] = ->(e) { Bugsnag.notify(e) }
+    @app.call(env)
+  end
+end
+```
+
 ## License
 
 ResponseBank is released under the [MIT License](LICENSE.txt).

data/lib/response_bank/brotli_splice_slot.rb

@@ -40,24 +40,17 @@ module ResponseBank
         begin
           result = BrotliSplice.encode(prepared_body, html_offset, html_length, quality: compression_level)
 
-          metadata_slot = {
-            'name' => slot_name,
-            'compressed_offset' => result[:secret_offset],
-            'replacement_length' => result[:secret_length],
-            'html_placeholder_offset' => html_offset,
-            'html_placeholder_length' => html_length,
-          }
-          metadata_slot['context_suffix'] = result[:context_suffix] if result[:context_suffix]
-
           EncodedBody.new(
             body: prepared_body,
             compressed_body: result[:data],
-            metadata: {
-              METADATA_KEY => {
-                'version' => METADATA_VERSION,
-                'slots' => [metadata_slot],
-              },
-            },
+            metadata: metadata_for(
+              name: slot_name,
+              compressed_offset: result[:secret_offset],
+              replacement_length: result[:secret_length],
+              html_placeholder_offset: html_offset,
+              html_placeholder_length: html_length,
+              context_suffix: result[:context_suffix],
+            ),
           )
         rescue BrotliSplice::Error, ArgumentError => error
           ResponseBank.log("BrotliSplice encode skipped: #{error.class}")
@@ -65,6 +58,29 @@ module ResponseBank
         end
       end
 
+      def metadata_for(
+        name:,
+        compressed_offset:,
+        replacement_length:,
+        html_placeholder_offset:,
+        html_placeholder_length:,
+        context_suffix:
+      )
+        {
+          METADATA_KEY => {
+            'version' => METADATA_VERSION,
+            'slots' => [{
+              'name' => name.to_s,
+              'compressed_offset' => compressed_offset,
+              'replacement_length' => replacement_length,
+              'html_placeholder_offset' => html_placeholder_offset,
+              'html_placeholder_length' => html_placeholder_length,
+              'context_suffix' => context_suffix,
+            }],
+          },
+        }
+      end
+
       def replace_compressed_secret(env, body, metadata)
         injector = env[INJECTOR_ENV_KEY]
         slots = metadata_slots(metadata)

data/lib/response_bank/cache_policy.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+module ResponseBank
+  CACHEABLE_HEADERS = ["Location", "Content-Type", "ETag", "Content-Encoding", "Last-Modified", "Cache-Control", "Expires", "Link", "Surrogate-Keys", "Cache-Tags", "Speculation-Rules"].freeze
+  CACHEABLE_STATUSES = [200, 404, 301].freeze
+end

data/lib/response_bank/cache_writer.rb

@@ -0,0 +1,165 @@
+# frozen_string_literal: true
+
+require 'response_bank/brotli_splice_slot'
+require 'response_bank/cache_policy'
+require 'msgpack'
+
+module ResponseBank
+  class CacheWriter
+    Stored = Struct.new(:body, :compressed_body, :metadata, keyword_init: true)
+
+    class << self
+      def flatten(body)
+        if body.is_a?(String)
+          body
+        elsif body.instance_of?(Array) && body.size == 1 && body[0].is_a?(String)
+          body[0]
+        else
+          result = +''
+          body.each { |part| result << part }
+          result
+        end
+      end
+
+      def store(
+        env,
+        status:,
+        headers:,
+        body:,
+        timestamp:,
+        content_encoding: env.fetch('response_bank.server_cache_encoding'),
+        before_write: nil
+      )
+        representation_headers = representation_headers(env, headers)
+        stored = prepare_body(env, representation_headers, body, content_encoding)
+        persist(
+          env,
+          status: status,
+          representation_headers: representation_headers,
+          stored: stored,
+          timestamp: timestamp,
+          content_encoding: content_encoding,
+          before_write: before_write,
+        )
+      end
+
+      def store_spliced(
+        env,
+        status:,
+        headers:,
+        body:,
+        compression_level:,
+        slot: nil,
+        timestamp:,
+        before_write: nil
+      )
+        validate_spliced_body!(env, body)
+        metadata = slot && BrotliSpliceSlot.metadata_for(**slot)
+        env['cacheable.compression_level'] = compression_level
+        persist(
+          env,
+          status: status,
+          representation_headers: representation_headers(env, headers),
+          stored: Stored.new(body: nil, compressed_body: body, metadata: metadata),
+          timestamp: timestamp,
+          content_encoding: 'br',
+          before_write: before_write,
+        )
+      end
+
+      private
+
+      def representation_headers(env, headers)
+        headers.slice(*ResponseBank::CACHEABLE_HEADERS).tap do |cached_headers|
+          cached_headers['ETag'] = %{"#{env.fetch('cacheable.key')}"}
+        end
+      end
+
+      def persist(env, status:, representation_headers:, stored:, timestamp:, content_encoding:, before_write:)
+        generated_at = timestamp.respond_to?(:call) ? timestamp.call : timestamp
+        data = cache_data(status, representation_headers, stored, env, generated_at, content_encoding)
+
+        before_write&.call
+        ResponseBank.write_to_cache(env.fetch('cacheable.key')) do
+          payload = MessagePack.dump(data)
+          ResponseBank.write_to_backing_cache_store(
+            env,
+            env.fetch('cacheable.unversioned-key'),
+            payload,
+            expires_in: env['cacheable.versioned-cache-expiry'],
+          )
+        end
+
+        stored
+      end
+
+      def validate_spliced_body!(env, body)
+        unless body.is_a?(String) && !body.empty?
+          raise ArgumentError, 'spliced body must be a non-empty String'
+        end
+        return if env.fetch('response_bank.server_cache_encoding') == 'br'
+
+        raise ArgumentError, 'spliced bodies require br server cache encoding'
+      end
+
+      def prepare_body(env, headers, body, content_encoding)
+        body = flatten(body)
+        return Stored.new(body: body) if body.empty?
+
+        representation_headers = headers.merge('Content-Encoding' => content_encoding)
+        compression_level = ResponseBank.compression_level_for_request(env, representation_headers)
+        env['cacheable.compression_level'] = compression_level
+        body_compressed = nil
+        metadata = nil
+        time = ResponseBank.measure do
+          encoded_body = encode_spliced_body(
+            env,
+            body,
+            representation_headers,
+            content_encoding,
+            compression_level,
+          )
+
+          if encoded_body
+            body = encoded_body.body
+            body_compressed = encoded_body.compressed_body
+            metadata = encoded_body.metadata
+          else
+            body_compressed = ResponseBank.compress(
+              body,
+              content_encoding,
+              compression_level: compression_level,
+            )
+          end
+        end
+        ResponseBank.log("Compression time: #{time}ms")
+        env['cacheable.compression_time'] = time
+
+        Stored.new(body: body, compressed_body: body_compressed, metadata: metadata)
+      end
+
+      def encode_spliced_body(env, body, headers, content_encoding, compression_level)
+        return unless content_encoding == 'br'
+
+        ResponseBank::BrotliSpliceSlot.encode_body(
+          env,
+          body,
+          headers,
+          compression_level: compression_level,
+        )
+      end
+
+      def cache_data(status, representation_headers, stored, env, timestamp, content_encoding)
+        if stored.compressed_body
+          representation_headers['Content-Encoding'] = content_encoding
+        else
+          representation_headers.delete('Content-Encoding')
+        end
+        cached_headers = representation_headers.slice(*ResponseBank::CACHEABLE_HEADERS)
+        data = [status, cached_headers, stored.compressed_body, timestamp, env['cacheable.compression_level']]
+        data << stored.metadata if stored.metadata
+        data
+      end
+    end
+  end
+end

data/lib/response_bank/deferred_store.rb

@@ -0,0 +1,188 @@
+# frozen_string_literal: true
+
+require 'response_bank/cache_policy'
+require 'response_bank/cache_writer'
+
+module ResponseBank
+  class DeferredStore
+    ENV_KEY = 'response_bank.deferred_store'
+    LOCK_OWNED_ENV_KEY = 'response_bank.fill_lock_owned'
+    TERMINAL_STATES = %i[aborted completing consumed].freeze
+    PRIVATE_CACHE_DIRECTIVES = %w[private no-store].freeze
+
+    class InvalidContextError < ArgumentError; end
+    class StateError < StandardError; end
+
+    class << self
+      def create(env, timestamp:)
+        validate_context!(env)
+        raise InvalidContextError, 'a deferred store is already registered for this request' if env.key?(ENV_KEY)
+
+        new(env, timestamp: timestamp).tap { |store| env[ENV_KEY] = store }
+      end
+
+      def from_env(env)
+        env[ENV_KEY]
+      end
+
+      def arm_from_middleware(env, status:, headers:)
+        from_env(env)&.__send__(:arm, status: status, headers: headers)
+      end
+
+      private
+
+      def validate_context!(env)
+        raise InvalidContextError, 'deferred storage requires a cache miss' unless cache_miss?(env)
+        raise InvalidContextError, 'deferred storage requires a GET request' unless env['REQUEST_METHOD'] == 'GET'
+
+        ['cacheable.key', 'cacheable.unversioned-key', 'response_bank.server_cache_encoding'].each do |key|
+          raise InvalidContextError, "deferred storage requires #{key}" unless env[key]
+        end
+        unless env.key?(LOCK_OWNED_ENV_KEY)
+          raise InvalidContextError, "deferred storage requires #{LOCK_OWNED_ENV_KEY}"
+        end
+      end
+
+      def cache_miss?(env)
+        env['cacheable.cache'] && env['cacheable.miss']
+      end
+    end
+
+    def initialize(env, timestamp:)
+      @env = env
+      @timestamp = timestamp
+      @cache_key = env.fetch('cacheable.key')
+      @owns_lock = env.fetch(LOCK_OWNED_ENV_KEY) == true
+      @mutex = Mutex.new
+      @state = :requested
+    end
+
+    # `body` and `headers` must describe the complete shared cache representation,
+    # not a partial response or bytes personalized for the live client.
+    def complete(body:, headers: nil)
+      complete_with(headers) do |status, cached_headers, before_write|
+        CacheWriter.store(
+          @env,
+          status: status,
+          headers: cached_headers,
+          body: body,
+          timestamp: @timestamp,
+          before_write: before_write,
+        )
+      end
+    end
+
+    # `body` must be a complete Brotli stream that is already safe for shared
+    # caching. If present, `slot` describes its neutral replacement slot.
+    def complete_spliced(body:, compression_level:, slot: nil, headers: nil)
+      complete_with(headers) do |status, cached_headers, before_write|
+        CacheWriter.store_spliced(
+          @env,
+          status: status,
+          headers: cached_headers,
+          body: body,
+          compression_level: compression_level,
+          slot: slot,
+          timestamp: @timestamp,
+          before_write: before_write,
+        )
+      end
+    end
+
+    def abort
+      transitioned, release_lock = @mutex.synchronize do
+        if TERMINAL_STATES.include?(@state)
+          [false, false]
+        else
+          @state = :aborted
+          [true, @owns_lock]
+        end
+      end
+
+      release_owned_lock if release_lock
+      transitioned
+    end
+
+    private
+
+    def complete_with(headers)
+      status, cached_headers, release_lock = prepare_completion(headers)
+
+      if release_lock
+        release_owned_lock
+        return false
+      end
+      return false unless status
+
+      write_started = false
+      completed = false
+      begin
+        yield(status, cached_headers, -> { write_started = true })
+        completed = true
+      ensure
+        @mutex.synchronize { @state = :consumed }
+        @env['cacheable.locked'] = false if @owns_lock
+        release_owned_lock if @owns_lock && !completed && !write_started
+      end
+      true
+    end
+
+    def arm(status:, headers:)
+      @mutex.synchronize do
+        if @state != :aborted
+          raise StateError, "cannot arm a deferred store in the #{@state} state" unless @state == :requested
+
+          @status = status
+          @headers = headers.slice(*ResponseBank::CACHEABLE_HEADERS)
+          @eligible = @owns_lock && cache_miss? && status_cacheable?(status)
+          @state = :armed
+        end
+      end
+
+      self
+    end
+
+    def prepare_completion(headers)
+      @mutex.synchronize do
+        raise StateError, 'the deferred store has not been armed by the middleware' if @state == :requested
+        return [nil, nil, false] if @state == :aborted
+        raise StateError, "cannot complete a deferred store in the #{@state} state" unless @state == :armed
+
+        cached_headers = (headers || @headers).slice(*ResponseBank::CACHEABLE_HEADERS)
+        if completion_eligible?(cached_headers)
+          @state = :completing
+          [@status, cached_headers, false]
+        else
+          @state = :aborted
+          [nil, nil, @owns_lock]
+        end
+      end
+    end
+
+    def completion_eligible?(headers)
+      @eligible && cache_miss? && cache_control_allows_storage?(headers)
+    end
+
+    def cache_miss?
+      @env['cacheable.cache'] && @env['cacheable.miss']
+    end
+
+    def status_cacheable?(status)
+      ResponseBank::CACHEABLE_STATUSES.include?(status)
+    end
+
+    def cache_control_allows_storage?(headers)
+      value = headers['Cache-Control']
+      return true unless value
+
+      directives = value.split(',').map { |directive| directive.strip.downcase.split('=', 2).first }
+      (directives & PRIVATE_CACHE_DIRECTIVES).empty?
+    end
+
+    def release_owned_lock
+      ResponseBank.release_lock(@cache_key)
+    ensure
+      @env['cacheable.locked'] = false
+    end
+  end
+end

data/lib/response_bank/middleware.rb

@@ -1,11 +1,13 @@
 # frozen_string_literal: true
 require 'response_bank/brotli_splice_slot'
+require 'response_bank/cache_policy'
+require 'response_bank/cache_writer'
+require 'response_bank/deferred_store'
 
 module ResponseBank
   class Middleware
-    # Limit the cached headers
-    # TODO: Make this lowercase/case-insentitive as per rfc2616 §4.2
-    CACHEABLE_HEADERS = ["Location", "Content-Type", "ETag", "Content-Encoding", "Last-Modified", "Cache-Control", "Expires", "Link", "Surrogate-Keys", "Cache-Tags", "Speculation-Rules"].freeze
+    CACHEABLE_HEADERS = ResponseBank::CACHEABLE_HEADERS
+    CACHEABLE_STATUSES = ResponseBank::CACHEABLE_STATUSES
 
     REQUESTED_WITH = "HTTP_X_REQUESTED_WITH"
     ACCEPT = "HTTP_ACCEPT"
@@ -22,81 +24,55 @@ module ResponseBank
 
       content_encoding = env['response_bank.server_cache_encoding'] = ResponseBank.check_encoding(env)
 
-      status, headers, body = @app.call(env)
+      status, headers, body = begin
+        @app.call(env)
+      rescue StandardError
+        ResponseBank::DeferredStore.from_env(env)&.abort
+        raise
+      end
+      deferred_store = ResponseBank::DeferredStore.from_env(env)
+      ResponseBank::DeferredStore.arm_from_middleware(env, status: status, headers: headers)
 
       if env['cacheable.cache']
-        if [200, 404, 301, 304].include?(status)
+        if [200, 404, 301, 304].include?(status) && !deferred_store
           headers['ETag'] = %{"#{env['cacheable.key']}"}
         end
 
-        if [200, 404, 301].include?(status) && env['cacheable.miss']
-          # Flatten down the result so that it can be stored to memcached.
-          if body.is_a?(String)
-            body_string = body
-          else
-            body_string = +""
-            body.each { |part| body_string << part }
-          end
-
-          body_compressed = nil
-          metadata = nil
-          if body_string && body_string != ""
-            headers['Content-Encoding'] = content_encoding
-            env["cacheable.compression_level"] = ResponseBank.compression_level_for_request(env, headers)
-            time = ResponseBank.measure do
-              encoded_body = if content_encoding == 'br'
-                ResponseBank::BrotliSpliceSlot.encode_body(
-                  env,
-                  body_string,
-                  headers,
-                  compression_level: env["cacheable.compression_level"],
-                )
-              end
-
-              if encoded_body
-                body_string = encoded_body.body
-                body_compressed = encoded_body.compressed_body
-                metadata = encoded_body.metadata
-              else
-                body_compressed = ResponseBank.compress(
-                  body_string,
-                  content_encoding,
-                  compression_level: env["cacheable.compression_level"],
-                )
-              end
-            end
-            ResponseBank.log("Compression time: #{time}ms")
-            env["cacheable.compression_time"] = time
-          end
-
-          cached_headers = headers.slice(*CACHEABLE_HEADERS)
-          # Store result
-          cache_data = [status, cached_headers, body_compressed, timestamp, env["cacheable.compression_level"]]
-          cache_data << metadata if metadata
-
-          ResponseBank.write_to_cache(env['cacheable.key']) do
-            payload = MessagePack.dump(cache_data)
-            ResponseBank.write_to_backing_cache_store(
+        if CACHEABLE_STATUSES.include?(status) && env['cacheable.miss'] && !deferred_store
+          body_string = CacheWriter.flatten(body)
+          stored = nil
+          begin
+            stored = CacheWriter.store(
               env,
-              env['cacheable.unversioned-key'],
-              payload,
-              expires_in: env['cacheable.versioned-cache-expiry'],
+              status: status,
+              headers: headers,
+              body: body_string,
+              timestamp: -> { timestamp },
+              content_encoding: content_encoding,
             )
-          end
 
-          # since we had to generate the compressed version already we may
-          # as well serve it if the client wants it
-          if body_compressed
-            if env['HTTP_ACCEPT_ENCODING'].to_s.include?(content_encoding)
-              if content_encoding == 'br'
-                body = [ResponseBank::BrotliSpliceSlot.replace_compressed_secret(env, body_compressed, metadata)]
+            if stored.compressed_body
+              if env['HTTP_ACCEPT_ENCODING'].to_s.include?(content_encoding)
+                headers['Content-Encoding'] = content_encoding
+                if content_encoding == 'br'
+                  body = [ResponseBank::BrotliSpliceSlot.replace_compressed_secret(env, stored.compressed_body, stored.metadata)]
+                else
+                  body = [stored.compressed_body]
+                end
               else
-                body = [body_compressed]
+                headers.delete('Content-Encoding')
+                body = [ResponseBank::BrotliSpliceSlot.replace_plain_body(env, stored.body, stored.metadata)] if stored.metadata
+              end
+            end
+          rescue => exception
+            headers.delete('Content-Encoding') if stored&.compressed_body
+            ResponseBank.log("Failed to write to cache: #{exception.class} - #{exception.message}")
+            if env['response_bank.on_exception']
+              begin
+                env['response_bank.on_exception'].call(exception)
+              rescue => handler_exception
+                ResponseBank.log("Exception handler failed: #{handler_exception.class} - #{handler_exception.message}")
               end
-            else
-              # Remove content-encoding header for response with compressed content
-              headers.delete('Content-Encoding')
-              body = [ResponseBank::BrotliSpliceSlot.replace_plain_body(env, body_string, metadata)] if metadata
             end
           end
         end
@@ -129,6 +105,5 @@ module ResponseBank
     def timestamp
       Time.now.to_i
     end
-
   end
 end

data/lib/response_bank/response_cache_handler.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 require 'digest/md5'
 require 'response_bank/brotli_splice_slot'
+require 'response_bank/deferred_store'
 
 module ResponseBank
   class ResponseCacheHandler
@@ -83,18 +84,25 @@ module ResponseBank
     end
 
     def try_to_serve_from_cache
+      response = read_from_cache
+      return response if response
+
+      # No cache hit; this request cannot be handled from cache.
+      # Yield to the controller and mark for writing into cache.
+      refill_cache
+    end
+
+    def read_from_cache
       # Etag
       unless @skip_browser_cache
         response = serve_from_browser_cache(entity_tag_hash, @env['HTTP_IF_NONE_MATCH'])
         return response if response
       end
 
-      response = serve_from_cache(cache_key_hash, @serve_unversioned ? "*" : entity_tag_hash, @cache_age_tolerance)
-      return response if response
-
-      # No cache hit; this request cannot be handled from cache.
-      # Yield to the controller and mark for writing into cache.
-      refill_cache
+      serve_from_cache(cache_key_hash, @serve_unversioned ? "*" : entity_tag_hash, @cache_age_tolerance)
+    rescue => exception
+      handle_cache_exception(exception)
+      nil
     end
 
     def serve_from_browser_cache(entity_tag, if_none_match)
@@ -137,6 +145,7 @@ module ResponseBank
           if ResponseBank.acquire_lock(match_entity_tag)
             # execute if we can get the lock
             @env['cacheable.locked'] = true
+            @env[ResponseBank::DeferredStore::LOCK_OWNED_ENV_KEY] = true
             return
           elsif stale_while_revalidate?(timestamp, cache_age_tolerance)
             # cache is being regenerated, can we avoid piling on and use a stale version in the interim?
@@ -201,8 +210,10 @@ module ResponseBank
     end
 
     def refill_cache
-      # non cache hits do not yet have the lock
-      ResponseBank.acquire_lock(entity_tag_hash) unless @env['cacheable.locked']
+      unless @env['cacheable.locked']
+        acquired = ResponseBank.acquire_lock(entity_tag_hash)
+        @env[ResponseBank::DeferredStore::LOCK_OWNED_ENV_KEY] = !!acquired
+      end
       @env['cacheable.locked'] = true
       @env['cacheable.miss'] = true
 
@@ -210,5 +221,17 @@ module ResponseBank
 
       @cache_miss_block.call
     end
+
+    def handle_cache_exception(exception)
+      ResponseBank.log("Cache operation failed: #{exception.class} - #{exception.message}")
+
+      if @env['response_bank.on_exception']
+        begin
+          @env['response_bank.on_exception'].call(exception)
+        rescue => handler_exception
+          ResponseBank.log("Exception handler failed: #{handler_exception.class} - #{handler_exception.message}")
+        end
+      end
+    end
   end
 end

data/lib/response_bank/version.rb

@@ -1,4 +1,4 @@
 # frozen_string_literal: true
 module ResponseBank
-  VERSION = "1.3.8"
+  VERSION = "1.5.0"
 end

data/lib/response_bank.rb

@@ -1,6 +1,9 @@
 # frozen_string_literal: true
 require 'response_bank/brotli_splice_injector'
 require 'response_bank/brotli_splice_slot'
+require 'response_bank/cache_policy'
+require 'response_bank/cache_writer'
+require 'response_bank/deferred_store'
 require 'response_bank/middleware'
 require 'response_bank/railtie' if defined?(Rails)
 require 'response_bank/response_cache_handler'
@@ -9,14 +12,16 @@ require 'brotli'
 require 'benchmark'
 
 module ResponseBank
+  private_constant :CacheWriter
+
   class << self
     attr_accessor :cache_store
     attr_writer :logger, :compression_level
 
     DEFAULT_BROTLI_COMPRESSION_LEVEL = 7
 
-    DEFAULT_COMPRESSION_LEVEL = -> (_env, headers) {
-      case headers['Content-Encoding']
+    DEFAULT_COMPRESSION_LEVEL = -> (env, _headers) {
+      case env['response_bank.server_cache_encoding']
       when 'br'
         DEFAULT_BROTLI_COMPRESSION_LEVEL
       when 'gzip'
@@ -40,6 +45,17 @@ module ResponseBank
       raise NotImplementedError, "Override ResponseBank.acquire_lock in an initializer."
     end
 
+    # Starts a one-shot deferred cache fill for the current ResponseBank miss.
+    # Complete it only after the intended shared response was generated and
+    # written successfully. Abort failed, disconnected or truncated responses.
+    def defer_store(env, timestamp: Time.now.to_i)
+      DeferredStore.create(env, timestamp: timestamp)
+    end
+
+    # Override when deferred fills must release an application-managed lock.
+    def release_lock(_cache_key)
+    end
+
     def write_to_cache(_key)
       yield
     end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: response_bank
 version: !ruby/object:Gem::Version
-  version: 1.3.8
+  version: 1.5.0
 platform: ruby
 authors:
 - Tobias Lütke
@@ -38,20 +38,34 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: benchmark
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: brotli_splice
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 0.1.1
+        version: 0.2.0
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 0.1.1
+        version: 0.2.0
 - !ruby/object:Gem::Dependency
   name: minitest
   requirement: !ruby/object:Gem::Requirement
@@ -134,7 +148,10 @@ files:
 - lib/response_bank.rb
 - lib/response_bank/brotli_splice_injector.rb
 - lib/response_bank/brotli_splice_slot.rb
+- lib/response_bank/cache_policy.rb
+- lib/response_bank/cache_writer.rb
 - lib/response_bank/controller.rb
+- lib/response_bank/deferred_store.rb
 - lib/response_bank/middleware.rb
 - lib/response_bank/model_extensions.rb
 - lib/response_bank/railtie.rb
@@ -159,7 +176,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.14
+rubygems_version: 4.0.19
 specification_version: 4
 summary: Simple response caching for Ruby applications
 test_files: []