response_bank 1.3.7 → 1.3.8

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0a5c7a799e1272fffad4878273bf154c09f809059944dbf47bf6c6c83d1b4acb
-  data.tar.gz: ff7a669443427dcee35c7d2a590258fc0ac0591bd156c1316a42198cacc4bd0e
+  metadata.gz: f9c672021efe766d0fc33677c57dd7b1b1c4dc83c1a88824f40919722111b99a
+  data.tar.gz: f1215de9f225b7ea78d71cc7c815d7cff0811a737e3e9df4f686261e07339db7
 SHA512:
-  metadata.gz: 5ddaeeca4364360ce6f2392d5b53d2f34421e44a62f1184d594add38dc45ebf23f72184bc9aa097667404c83d6b64c450b91b1dd25726a307ba41149b8a9509d
-  data.tar.gz: 4bfc7ebc29beab0c67f72e24e635d9fa2a0ca59a06fd92027d00172acc31a1974288adee1a97baf005e2ae64751a49e205a7005c70881f27e44b03a6827bf66a
+  metadata.gz: 563abba82ed5b7e1308edcc406dfc842b4f7bfa1c7ae489d886f73a67737261690a8faeec48d0ff7e2458f57ec3142620da88777625362e4b2c874f8bd93873d
+  data.tar.gz: bb6450674d14ba9aa4b9e9b35c54ebc740c55903ae0f3b19ead162c6764948c37bb69029e903ad75886dc7de40f1628e81c0af5ba411a7a015ff600d91bdaf7a

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,124 @@ This gem supports the following versions of Ruby and Rails:
     end
     ```
 
+## 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
+```
+
 ## 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/middleware.rb

@@ -1,4 +1,5 @@
 # frozen_string_literal: true
+require 'response_bank/brotli_splice_slot'
 
 module ResponseBank
   class Middleware
@@ -10,12 +11,15 @@ module ResponseBank
     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)
@@ -35,15 +39,31 @@ module ResponseBank
           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
-              body_compressed = ResponseBank.compress(
-                body_string,
-                content_encoding,
-                compression_level: env["cacheable.compression_level"],
-              )
+              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
@@ -52,6 +72,7 @@ module ResponseBank
           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)
@@ -67,10 +88,15 @@ module ResponseBank
           # 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]
+              if content_encoding == 'br'
+                body = [ResponseBank::BrotliSpliceSlot.replace_compressed_secret(env, body_compressed, metadata)]
+              else
+                body = [body_compressed]
+              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
@@ -87,6 +113,19 @@ 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

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,6 @@
 # frozen_string_literal: true
 require 'digest/md5'
+require 'response_bank/brotli_splice_slot'
 
 module ResponseBank
   class ResponseCacheHandler
@@ -119,7 +120,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
 
@@ -152,9 +153,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 +186,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

data/lib/response_bank/version.rb

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

data/lib/response_bank.rb

@@ -1,4 +1,6 @@
 # frozen_string_literal: true
+require 'response_bank/brotli_splice_injector'
+require 'response_bank/brotli_splice_slot'
 require 'response_bank/middleware'
 require 'response_bank/railtie' if defined?(Rails)
 require 'response_bank/response_cache_handler'

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: response_bank
 version: !ruby/object:Gem::Version
-  version: 1.3.7
+  version: 1.3.8
 platform: ruby
 authors:
 - Tobias Lütke
@@ -38,6 +38,20 @@ dependencies:
     - - ">="
       - !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,6 +132,8 @@ 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/controller.rb
 - lib/response_bank/middleware.rb
 - lib/response_bank/model_extensions.rb
@@ -136,14 +152,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.14
 specification_version: 4
 summary: Simple response caching for Ruby applications
 test_files: []