response_bank 1.3.7 → 1.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0a5c7a799e1272fffad4878273bf154c09f809059944dbf47bf6c6c83d1b4acb
-  data.tar.gz: ff7a669443427dcee35c7d2a590258fc0ac0591bd156c1316a42198cacc4bd0e
+  metadata.gz: f9667d810b487f5db154d43ba2e7be769ab999d0d721b881a5c558e97ae55ceb
+  data.tar.gz: 744ec28ba5bdd1e5ae368e215d0ca6e86d0ce0d8910c49cd13b5835fe4283e9b
 SHA512:
-  metadata.gz: 5ddaeeca4364360ce6f2392d5b53d2f34421e44a62f1184d594add38dc45ebf23f72184bc9aa097667404c83d6b64c450b91b1dd25726a307ba41149b8a9509d
-  data.tar.gz: 4bfc7ebc29beab0c67f72e24e635d9fa2a0ca59a06fd92027d00172acc31a1974288adee1a97baf005e2ae64751a49e205a7005c70881f27e44b03a6827bf66a
+  metadata.gz: ec9cb3918c4ff1d9bf6b5d1e18c18eb6bae8f0a49cdc8f15aff494c7d43fc2b3e1bcd38078770d75cfb06f4517f08515b67a8429877d815952576703461eb929
+  data.tar.gz: 9d815e56c3d9986367847c1f2f730c16fa72ab989dcedcf379cd849dd00a436076c7a08b92a94e0123ded75058d628d17b2a6dcab26fc6598a7057140daabfb7

data/README.md

@@ -11,7 +11,7 @@
 
 This gem supports the following versions of Ruby and Rails:
 
-* Ruby 2.7.0+
+* Ruby 3.1.0+
 * Rails 6.0.0+
 
 ## Usage
@@ -123,6 +123,173 @@ 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.
+
+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`:
+
+```ruby
+use ResponseBank::Middleware, ->(env) { HtmlMetadataInjector.new(env) }
+```
+
+Rails applications can configure the same builder through `config.response_bank`:
+
+```ruby
+config.response_bank.brotli_splice_injector =
+  ->(env) { HtmlMetadataInjector.new(env) }
+```
+
+The injector is optional. If it is not configured, ResponseBank uses the normal Brotli compression path. Applications own the concrete injector implementation because they know how to read their request-specific metadata.
+
+Injectors may include `ResponseBank::BrotliSpliceInjector` to document the required methods:
+
+```ruby
+class HtmlMetadataInjector
+  include ResponseBank::BrotliSpliceInjector
+
+  # The per-request value spliced in on cache hits (a 36-byte UUID).
+  TOKEN_PLACEHOLDER = "00000000-0000-0000-0000-000000000000"
+  # BrotliSplice reserves the LAST 2 bytes of a slot as a fixed "\r\n" context
+  # suffix, so a slot must span 2 more bytes than its replaceable region and
+  # `replacement_length` always comes back as `slot length - 2`. We let those
+  # 2 bytes be a real "\r\n" placed after the tag, where a line break is
+  # harmless — the replaceable region is therefore `<uuid>">` (38 bytes).
+  CONTEXT_SUFFIX = "\r\n"
+  PLACEHOLDER_TAG = %(<meta name="shopify-y" content="#{TOKEN_PLACEHOLDER}">#{CONTEXT_SUFFIX})
+  SLOT = %(#{TOKEN_PLACEHOLDER}">#{CONTEXT_SUFFIX}) # 38 replaceable bytes + 2 reserved
+
+  def initialize(env)
+    @env = env
+  end
+
+  def prepare_response_bank_brotli_splice(body, _headers)
+    body_with_placeholder = body.sub("</head>", "#{PLACEHOLDER_TAG}</head>")
+    # Use a byte offset: BrotliSplice.encode addresses the slot by bytes.
+    offset = body_with_placeholder.b.index(TOKEN_PLACEHOLDER)
+    return unless offset
+
+    {
+      body: body_with_placeholder,
+      slots: [
+        {
+          name: "shopify_y",
+          offset: offset,
+          # Include the 2 bytes reserved for the context suffix, or the
+          # replacement below will be 2 bytes too long and silently dropped.
+          length: SLOT.bytesize,
+        },
+      ],
+    }
+  end
+
+  def response_bank_brotli_splice_replacement(slot)
+    # Must return EXACTLY slot["replacement_length"] bytes (== slot length - 2).
+    # If it does not, ResponseBank skips the splice and serves the neutral
+    # placeholder, so guard the length rather than assuming it.
+    replacement = %(#{shopify_y}">)
+    return unless replacement.bytesize == slot.fetch("replacement_length")
+
+    replacement
+  end
+
+  def replace_response_bank_brotli_splice_placeholders(body, slots)
+    slots.reduce(body) do |current, slot|
+      replacement = response_bank_brotli_splice_replacement(slot)
+      next current unless replacement
+
+      offset = slot.fetch("html_placeholder_offset")
+      length = slot.fetch("html_placeholder_length")
+      suffix = slot.fetch("context_suffix", CONTEXT_SUFFIX)
+
+      # replacement + suffix must equal the original slot length (byteslice
+      # replaces `length` bytes), keeping the body byte-for-byte consistent.
+      current.byteslice(0, offset) + replacement + suffix +
+        current.byteslice(offset + length, current.bytesize)
+    end
+  end
+
+  private
+
+  def shopify_y
+    @env.fetch("HTTP_SHOPIFY_Y") # 36-byte UUID
+  end
+end
+```
+
+`prepare_response_bank_brotli_splice` is used on cache writes. It returns HTML
+containing a neutral placeholder and one slot describing that placeholder.
+ResponseBank stores the slot metadata with the cached Brotli body. The slot's
+`offset` and `length` are **byte** offsets/counts — `BrotliSplice.encode`
+addresses the stream by bytes — so locate the placeholder on a binary view
+(`body.b.index(...)`) and size it with `bytesize`. A plain `String#index`/`size`
+silently breaks once any multi-byte UTF-8 precedes the placeholder: a character
+offset is always ≤ the byte length, so the bounds check still passes.
+
+`response_bank_brotli_splice_replacement` is used on Brotli cache hits. It must
+return exactly `slot["replacement_length"]` bytes. Note that `replacement_length`
+is **2 fewer** than the `length` you registered in the slot: `BrotliSplice.encode`
+reserves the last 2 bytes of every slot as a fixed `\r\n` context suffix. So size
+your placeholder to include those 2 bytes (as the example does with the trailing
+`\r\n`), and have the replacement match `replacement_length`. If the byte length
+does not match, ResponseBank **silently skips the splice and serves the neutral
+placeholder** — no exception is raised — so guard the length instead of assuming it.
+
+`replace_response_bank_brotli_splice_placeholders` is used when a cached Brotli response is decompressed for a client that does not accept Brotli.
+
+Advanced integrations can still install the per-request injector directly in the Rack env before ResponseBank reads or writes the cached body:
+
+```ruby
+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_injector.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module ResponseBank
+  module BrotliSpliceInjector
+    def prepare_response_bank_brotli_splice(body, headers)
+      raise NotImplementedError
+    end
+
+    def response_bank_brotli_splice_replacement(slot)
+      raise NotImplementedError
+    end
+
+    def replace_response_bank_brotli_splice_placeholders(body, slots)
+      raise NotImplementedError
+    end
+  end
+end

data/lib/response_bank/brotli_splice_slot.rb

@@ -0,0 +1,184 @@
+# frozen_string_literal: true
+
+module ResponseBank
+  module BrotliSpliceSlot
+    INJECTOR_ENV_KEY = 'response_bank.html_metadata_injector'
+    METADATA_KEY = 'brotli_splice'
+    METADATA_VERSION = 1
+    # BrotliSplice reserves the last 2 bytes of every slot as a fixed "\r\n" context
+    # suffix, so a slot must be longer than that to hold any replaceable content --
+    # BrotliSplice.encode raises unless the slot length exceeds it.
+    CONTEXT_SUFFIX_LENGTH = 2
+
+    EncodedBody = Struct.new(:body, :compressed_body, :metadata, keyword_init: true)
+
+    class << self
+      def encode_body(env, body, headers, compression_level:)
+        injector = env[INJECTOR_ENV_KEY]
+        return unless injector
+        return unless body && body != ''
+
+        prepared = injector.prepare_response_bank_brotli_splice(body, headers)
+        return unless prepared
+
+        prepared_body = hash_fetch(prepared, :body)
+        slots = hash_fetch(prepared, :slots)
+        return unless prepared_body && slots && slots.length == 1
+
+        slot = slots.first
+        slot_name = hash_fetch(slot, :name).to_s
+        html_offset = integer_value(hash_fetch(slot, :offset))
+        html_length = integer_value(hash_fetch(slot, :length))
+        return unless valid_html_slot?(prepared_body, html_offset, html_length)
+
+        # Load the native gem only once we have real splice work to do. Keeping this
+        # outside the begin/rescue below is deliberate: the rescue clause references
+        # BrotliSplice::Error, so if the gem is missing, evaluating that clause would
+        # raise NameError and mask the LoadError we want the caller to see.
+        ensure_brotli_splice_loaded!
+
+        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],
+              },
+            },
+          )
+        rescue BrotliSplice::Error, ArgumentError => error
+          ResponseBank.log("BrotliSplice encode skipped: #{error.class}")
+          nil
+        end
+      end
+
+      def replace_compressed_secret(env, body, metadata)
+        injector = env[INJECTOR_ENV_KEY]
+        slots = metadata_slots(metadata)
+        return body unless injector && slots && body && body != ''
+
+        # See encode_body: load outside the begin/rescue so a missing gem surfaces as
+        # LoadError rather than a masked NameError from the BrotliSplice::Error clause.
+        ensure_brotli_splice_loaded!
+
+        begin
+          slots.reduce(body) do |current_body, slot|
+            replacement = replacement_for_slot(injector, slot)
+
+            unless valid_replacement?(replacement, slot)
+              got = replacement ? replacement.bytesize : 'nil'
+              ResponseBank.log(
+                'BrotliSplice replace skipped: replacement length mismatch ' \
+                "(got #{got}, want #{slot['replacement_length']})",
+              )
+              next current_body
+            end
+
+            offset = integer_value(slot['compressed_offset'])
+            length = integer_value(slot['replacement_length'])
+
+            unless valid_compressed_slot?(current_body, offset, length)
+              ResponseBank.log('BrotliSplice replace skipped: compressed slot out of bounds')
+              next current_body
+            end
+
+            BrotliSplice.replace(current_body, replacement, offset, length)
+          end
+        rescue BrotliSplice::Error, ArgumentError => error
+          ResponseBank.log("BrotliSplice replace skipped: #{error.class}")
+          body
+        end
+      end
+
+      def replace_plain_body(env, body, metadata)
+        injector = env[INJECTOR_ENV_KEY]
+        slots = metadata_slots(metadata)
+        return body unless injector && slots && body && body != ''
+
+        injector.replace_response_bank_brotli_splice_placeholders(body, slots)
+      rescue ArgumentError => error
+        ResponseBank.log("BrotliSplice plain replacement skipped: #{error.class}")
+        body
+      end
+
+      def metadata_slots(metadata)
+        return unless metadata
+
+        brotli_splice = metadata[METADATA_KEY]
+        return unless brotli_splice && brotli_splice['version'] == METADATA_VERSION
+
+        brotli_splice['slots']
+      end
+
+      private
+
+      # Load the native brotli_splice gem on first use. It is an optional dependency:
+      # apps opt into Brotli splice slots by installing an injector, and only those
+      # apps need the gem. If it is missing when we actually need it, fail loudly with
+      # a pointer to the fix rather than limping along.
+      def ensure_brotli_splice_loaded!
+        return if @brotli_splice_loaded
+
+        begin
+          gem('brotli_splice')
+          require('brotli_splice')
+        rescue LoadError => error
+          warn(
+            'The Brotli splice slot feature requires the "brotli_splice" gem. ' \
+            'Add it to your application Gemfile.',
+          )
+          raise error
+        end
+
+        @brotli_splice_loaded = true
+      end
+
+      def replacement_for_slot(injector, slot)
+        injector.response_bank_brotli_splice_replacement(slot)
+      end
+
+      def valid_replacement?(replacement, slot)
+        return false unless replacement
+
+        replacement.bytesize == slot['replacement_length']
+      end
+
+      def valid_compressed_slot?(body, offset, length)
+        return false unless offset && length
+        return false unless offset >= 0 && length > 0
+
+        offset + length <= body.bytesize
+      end
+
+      def valid_html_slot?(body, offset, length)
+        return false unless offset && length
+        return false unless offset >= 0 && length > CONTEXT_SUFFIX_LENGTH
+
+        offset + length <= body.bytesize
+      end
+
+      def integer_value(value)
+        Integer(value)
+      rescue ArgumentError, TypeError
+        nil
+      end
+
+      def hash_fetch(hash, key)
+        hash[key] || hash[key.to_s]
+      end
+    end
+  end
+end

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,117 @@
+# 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
+      )
+        cache_key = env.fetch('cacheable.key')
+        unversioned_key = env.fetch('cacheable.unversioned-key')
+        representation_headers = headers.slice(*ResponseBank::CACHEABLE_HEADERS)
+        representation_headers['ETag'] = %{"#{cache_key}"}
+        stored = prepare_body(env, representation_headers, body, content_encoding)
+        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(cache_key) do
+          payload = MessagePack.dump(data)
+          ResponseBank.write_to_backing_cache_store(
+            env,
+            unversioned_key,
+            payload,
+            expires_in: env['cacheable.versioned-cache-expiry'],
+          )
+        end
+
+        stored
+      end
+
+      private
+
+      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,165 @@
+# 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)
+      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
+        CacheWriter.store(
+          @env,
+          status: status,
+          headers: cached_headers,
+          body: body,
+          timestamp: @timestamp,
+          before_write: -> { 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 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 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,76 +1,78 @@
 # 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"
     USER_AGENT = "HTTP_USER_AGENT"
 
-    def initialize(app)
+    def initialize(app, brotli_splice_injector = nil)
       @app = app
+      @brotli_splice_injector = brotli_splice_injector
     end
 
     def call(env)
       env['cacheable.cache'] = false
+      install_brotli_splice_injector(env)
+
       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
-          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
-              body_compressed = ResponseBank.compress(
-                body_string,
-                content_encoding,
-                compression_level: env["cacheable.compression_level"],
-              )
-            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"]]
-
-          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)
-              body = [body_compressed]
-            else
-              # Remove content-encoding header for response with compressed content
-              headers.delete('Content-Encoding')
+            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
+                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
             end
           end
         end
@@ -87,9 +89,21 @@ module ResponseBank
 
     private
 
+    def install_brotli_splice_injector(env)
+      return unless @brotli_splice_injector
+      return if env.key?(ResponseBank::BrotliSpliceSlot::INJECTOR_ENV_KEY)
+
+      injector = if @brotli_splice_injector.respond_to?(:call)
+        @brotli_splice_injector.call(env)
+      else
+        @brotli_splice_injector
+      end
+
+      env[ResponseBank::BrotliSpliceSlot::INJECTOR_ENV_KEY] = injector if injector
+    end
+
     def timestamp
       Time.now.to_i
     end
-
   end
 end

data/lib/response_bank/railtie.rb

@@ -1,12 +1,20 @@
 # frozen_string_literal: true
 require 'rails'
+require 'active_support/ordered_options'
 require 'response_bank/controller'
 require 'response_bank/model_extensions'
 
 module ResponseBank
   class Railtie < ::Rails::Railtie
-    initializer "cachable.configure_active_record" do |config|
-      config.middleware.insert_after(Rack::Head, ResponseBank::Middleware)
+    config.response_bank = ActiveSupport::OrderedOptions.new
+    config.response_bank.brotli_splice_injector = nil
+
+    initializer "cachable.configure_active_record" do |app|
+      app.config.middleware.insert_after(
+        Rack::Head,
+        ResponseBank::Middleware,
+        app.config.response_bank.brotli_splice_injector,
+      )
 
       ActiveSupport.on_load(:action_controller) do
         include ResponseBank::Controller

data/lib/response_bank/response_cache_handler.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 require 'digest/md5'
+require 'response_bank/brotli_splice_slot'
+require 'response_bank/deferred_store'
 
 module ResponseBank
   class ResponseCacheHandler
@@ -82,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)
@@ -119,7 +128,7 @@ module ResponseBank
         @env['cacheable.miss']  = false
         @env['cacheable.store'] = 'server'
 
-        status, headers, body, timestamp, compression_level = hit
+        status, headers, body, timestamp, compression_level, metadata = hit
 
         @env['cacheable.compression_level'] = compression_level
 
@@ -136,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?
@@ -152,9 +162,14 @@ module ResponseBank
         @headers.merge!(headers)
 
         if @headers['Content-Encoding']
-          if !@env['HTTP_ACCEPT_ENCODING'].to_s.include?(@headers['Content-Encoding'])
+          if @env['HTTP_ACCEPT_ENCODING'].to_s.include?(@headers['Content-Encoding'])
+            if @headers['Content-Encoding'] == 'br'
+              body = ResponseBank::BrotliSpliceSlot.replace_compressed_secret(@env, body, metadata)
+            end
+          else
             ResponseBank.log("uncompressing payload for client as client doesn't require encoding")
             body = ResponseBank.decompress(body, @headers['Content-Encoding'])
+            body = ResponseBank::BrotliSpliceSlot.replace_plain_body(@env, body, metadata)
             @headers.delete('Content-Encoding')
           end
         else
@@ -180,9 +195,9 @@ module ResponseBank
 
       # strictly speaking an unquoted etag is not valid, yet common
       # to avoid unintended greedy matches in we check for naked entity then includes with quoted entity values
-      entity_tag = %{"#{entity_tag}"} unless entity_tag.starts_with?('"')
+      entity_tag = %{"#{entity_tag}"} unless entity_tag.start_with?('"')
 
-      if_none_match = %{"#{if_none_match}"} unless if_none_match.starts_with?('"') || if_none_match.starts_with?('W/"')
+      if_none_match = %{"#{if_none_match}"} unless if_none_match.start_with?('"') || if_none_match.start_with?('W/"')
 
       if_none_match == entity_tag || if_none_match.include?(entity_tag)
     end
@@ -195,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
 
@@ -204,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.7"
+  VERSION = "1.4.0"
 end

data/lib/response_bank.rb

@@ -1,4 +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'
@@ -7,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'
@@ -38,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.7
+  version: 1.4.0
 platform: ruby
 authors:
 - Tobias Lütke
@@ -38,6 +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
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 0.1.1
 - !ruby/object:Gem::Dependency
   name: minitest
   requirement: !ruby/object:Gem::Requirement
@@ -118,7 +146,12 @@ files:
 - LICENSE.txt
 - README.md
 - 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
@@ -136,14 +169,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 2.7.0
+      version: 3.1.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.7.2
+rubygems_version: 4.0.16
 specification_version: 4
 summary: Simple response caching for Ruby applications
 test_files: []