response_bank 1.7.0 → 1.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 54fd4c438eab18c36f842002725ec243f6ca9837f03a2d70dc594a8bf4765d8d
-  data.tar.gz: cc5512b2fa88dd622da3ef9fae6abda48f9c7122eed828dd988a17343607f0cd
+  metadata.gz: bd0398adb597c3f34c02aa07738d644635eb04e349f58182b9c7795880292eba
+  data.tar.gz: 27d93896f30f2d6fff34376b5b93439cb0f1737fb89909734089090dcaf36f66
 SHA512:
-  metadata.gz: 9637541060aab3ac047247fdd13e83d57b99e3921689a7dd354ce684c247f9decb04de2c784e6f04bb57796e71279098a2f1a3db670d67ad25bb8406a7eb30f3
-  data.tar.gz: d3ba8c122b58152cd1e10e8d1fb504b65c2e8c906d3a862be98050f7b252129d392bbc83d0e220a2c79248f0da16bb3f85d8ae441c0c2b03281ee123a872b4bf
+  metadata.gz: ce162be922a3ab92c0ddc5629f27d6d373a6bf4abe01d6b95de9b48035eac46ee5d40aa00eadfa35824b0cd61e39d16546aeec63bd128c83bc79a06253fc75a0
+  data.tar.gz: 30b7df7e16c07e5e3427d042d100904a6ad05456a9e3bda630a01530f188acda3731d447dba6d22c5cbce1c7cdb50082a7fd0dee11d43a7052d64e2a5c3fe17e

data/README.md

@@ -204,6 +204,12 @@ config.response_bank.brotli_splice_injector =
 
 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.
 
+Splicing needs the native `brotli_splice` gem, version 0.3.0 or newer. It is not a runtime dependency of ResponseBank, so add it to your application's Gemfile:
+
+```ruby
+gem 'brotli_splice', '>= 0.3.0'
+```
+
 Injectors may include `ResponseBank::BrotliSpliceInjector` to document the required methods:
 
 ```ruby
@@ -227,7 +233,7 @@ class HtmlMetadataInjector
 
   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.
+    # Use a byte offset: BrotliSplice addresses slots by bytes.
     offset = body_with_placeholder.b.index(TOKEN_PLACEHOLDER)
     return unless offset
 
@@ -280,24 +286,33 @@ 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
+containing neutral placeholders and one slot describing each placeholder, in
+ascending byte order; slots may touch but must not overlap. ResponseBank stores
+one metadata entry per slot with the cached Brotli body. Each slot's
+`offset` and `length` are **byte** offsets/counts — BrotliSplice 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.
+If any slot cannot be encoded (out of bounds, out of order, overlapping, or no
+longer than the 2 reserved bytes), ResponseBank logs it and caches the returned
+HTML without slots, so the response is never cached as rendered. On that
+request, a client that accepts Brotli is served the returned HTML too,
+placeholders included. A Hash without `:body` raises `ArgumentError`, and
+nothing is cached (see [Exception Handling](#exception-handling)). Return `nil`
+to cache the body as rendered.
+
+`response_bank_brotli_splice_replacement` is used on Brotli cache hits, once per
+slot. It must return exactly `slot["replacement_length"]` bytes. Note that
+`replacement_length` is **2 fewer** than the `length` you registered in the slot:
+BrotliSplice 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 that slot,
+which keeps its neutral placeholder** — no exception is raised — so guard the
+length instead of assuming it. The other slots are still filled.
+
+`replace_response_bank_brotli_splice_placeholders` is used when a cached Brotli response is decompressed for a client that does not accept Brotli. It receives every slot.
 
 Advanced integrations can still install the per-request injector directly in the Rack env before ResponseBank reads or writes the cached body:
 

data/lib/response_bank/brotli_splice_slot.rb

@@ -7,12 +7,17 @@ module ResponseBank
     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.
+    # BrotliSplice.encode_slots raises unless every slot length exceeds it.
     CONTEXT_SUFFIX_LENGTH = 2
 
     EncodedBody = Struct.new(:body, :compressed_body, :metadata, keyword_init: true)
 
     class << self
+      # Returns nil when the injector does not prepare the body. Once it does, the
+      # prepared body is the shared copy, so the response is never cached as rendered:
+      # without a prepared body this raises, and nothing is cached; if its slots cannot
+      # be encoded, the result carries that body without a compressed body or metadata,
+      # so the caller compresses it normally.
       def encode_body(env, body, headers, compression_level:)
         injector = env[INJECTOR_ENV_KEY]
         return unless injector
@@ -22,14 +27,13 @@ module ResponseBank
         return unless prepared
 
         prepared_body = hash_fetch(prepared, :body)
-        slots = hash_fetch(prepared, :slots)
-        return unless prepared_body && slots && slots.length == 1
+        raise ArgumentError, 'prepare_response_bank_brotli_splice returned no :body' unless prepared_body
 
-        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)
+        slots = html_slots(prepared_body, hash_fetch(prepared, :slots))
+        unless slots
+          ResponseBank.log('BrotliSplice encode skipped: invalid slot')
+          return EncodedBody.new(body: prepared_body)
+        end
 
         # 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
@@ -38,45 +42,38 @@ module ResponseBank
         ensure_brotli_splice_loaded!
 
         begin
-          result = BrotliSplice.encode(prepared_body, html_offset, html_length, quality: compression_level)
+          result = BrotliSplice.encode_slots(
+            prepared_body,
+            slots.map { |slot| [slot[:offset], slot[:length]] },
+            quality: compression_level,
+          )
+          compressed_slots = slots.zip(result[:slots]).map do |slot, compressed_slot|
+            {
+              name: slot[:name],
+              compressed_offset: compressed_slot[:offset],
+              replacement_length: compressed_slot[:length],
+              html_placeholder_offset: slot[:offset],
+              html_placeholder_length: slot[:length],
+              context_suffix: result[:context_suffix],
+            }
+          end
 
           EncodedBody.new(
             body: prepared_body,
             compressed_body: result[:data],
-            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],
-            ),
+            metadata: metadata_for(compressed_slots),
           )
         rescue BrotliSplice::Error, ArgumentError => error
           ResponseBank.log("BrotliSplice encode skipped: #{error.class}")
-          nil
+          EncodedBody.new(body: prepared_body)
         end
       end
 
-      def metadata_for(
-        name:,
-        compressed_offset:,
-        replacement_length:,
-        html_placeholder_offset:,
-        html_placeholder_length:,
-        context_suffix:
-      )
+      def metadata_for(slots)
         {
           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,
-            }],
+            'slots' => slots.map { |slot| slot_metadata(**slot) },
           },
         }
       end
@@ -91,28 +88,12 @@ module ResponseBank
         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
+          # A slot that cannot be filled keeps its neutral placeholder; the others are
+          # still written, with a single copy of the body.
+          replacements = slots.filter_map { |slot| compressed_replacement(injector, body, slot) }
+          return body if replacements.empty?
+
+          BrotliSplice.replace_slots(body, replacements)
         rescue BrotliSplice::Error, ArgumentError => error
           ResponseBank.log("BrotliSplice replace skipped: #{error.class}")
           body
@@ -149,11 +130,11 @@ module ResponseBank
         return if @brotli_splice_loaded
 
         begin
-          gem('brotli_splice')
+          gem('brotli_splice', '>= 0.3.0')
           require('brotli_splice')
         rescue LoadError => error
           warn(
-            'The Brotli splice slot feature requires the "brotli_splice" gem. ' \
+            'The Brotli splice slot feature requires the "brotli_splice" gem, version 0.3.0 or newer. ' \
             'Add it to your application Gemfile.',
           )
           raise error
@@ -162,6 +143,62 @@ module ResponseBank
         @brotli_splice_loaded = true
       end
 
+      def slot_metadata(
+        name:,
+        compressed_offset:,
+        replacement_length:,
+        html_placeholder_offset:,
+        html_placeholder_length:,
+        context_suffix:
+      )
+        {
+          '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
+
+      # Returns the injector's slots with Integer byte ranges, or nil unless there is
+      # at least one slot and every range fits the body. BrotliSplice.encode_slots
+      # checks that the ranges are ascending and do not overlap.
+      def html_slots(body, slots)
+        return unless slots.is_a?(Array) && !slots.empty?
+
+        slots.map do |slot|
+          offset = integer_value(hash_fetch(slot, :offset))
+          length = integer_value(hash_fetch(slot, :length))
+          return unless valid_html_slot?(body, offset, length)
+
+          { name: hash_fetch(slot, :name).to_s, offset: offset, length: length }
+        end
+      end
+
+      def compressed_replacement(injector, 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']})",
+          )
+          return
+        end
+
+        offset = integer_value(slot['compressed_offset'])
+        length = integer_value(slot['replacement_length'])
+
+        unless valid_compressed_slot?(body, offset, length)
+          ResponseBank.log('BrotliSplice replace skipped: compressed slot out of bounds')
+          return
+        end
+
+        [replacement, offset, length]
+      end
+
       def replacement_for_slot(injector, slot)
         injector.response_bank_brotli_splice_replacement(slot)
       end

data/lib/response_bank/cache_writer.rb

@@ -54,7 +54,7 @@ module ResponseBank
         before_write: nil
       )
         validate_spliced_body!(env, body)
-        metadata = slot && BrotliSpliceSlot.metadata_for(**slot)
+        metadata = slot && BrotliSpliceSlot.metadata_for([slot])
         env['cacheable.compression_level'] = compression_level
         persist(
           env,
@@ -124,13 +124,12 @@ module ResponseBank
             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
+          body_compressed ||= ResponseBank.compress(
+            body,
+            content_encoding,
+            compression_level: compression_level,
+          )
         end
         ResponseBank.log("Compression time: #{time}ms")
         env['cacheable.compression_time'] = time

data/lib/response_bank/version.rb

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

data/lib/response_bank.rb

@@ -114,16 +114,20 @@ module ResponseBank
       when Hash
         return data.inspect unless data.key?(:key)
 
-        key = hash_value_str(data[:key])
+        # Components are joined as bytes, so values in different encodings can't raise.
+        key = String.new(encoding: Encoding::BINARY)
 
-        key = %{#{data[:key_schema_version]}:#{key}} if data[:key_schema_version]
+        key << hash_value_str(data[:key_schema_version]) << ":" if data[:key_schema_version]
 
-        key = %{#{key}:#{hash_value_str(data[:version])}} if data[:version]
+        key << hash_value_str(data[:key])
+
+        key << ":" << hash_value_str(data[:version]) if data[:version]
 
         # add the encoding to only the cache key but don't expose this detail in the entity_tag
-        key = %{#{key}:#{hash_value_str(data[:encoding])}} if data[:encoding]
+        key << ":" << hash_value_str(data[:encoding]) if data[:encoding]
 
-        key
+        key.force_encoding(Encoding::UTF_8)
+        key.valid_encoding? ? key : key.force_encoding(Encoding::BINARY)
       when Array
         data.inspect
       when Time, DateTime
@@ -152,10 +156,32 @@ module ResponseBank
 
     def hash_value_str(data)
       if data.is_a?(Hash)
-        data.values.join(",")
+        append_key_component(String.new(encoding: Encoding::BINARY), data)
+      else
+        data.to_s.b
+      end
+    end
+
+    # Hashes and Arrays are written as a type tag and element count, followed
+    # by their elements; Hash entries are written as name then value, in
+    # insertion order. Every other value is written as the byte length of its
+    # #to_s followed by those bytes, so no value can be read as part of another.
+    def append_key_component(buffer, data)
+      case data
+      when Hash
+        buffer << "h" << data.size.to_s << ":"
+        data.each do |name, value|
+          append_key_component(buffer, name)
+          append_key_component(buffer, value)
+        end
+      when Array
+        buffer << "a" << data.size.to_s << ":"
+        data.each { |value| append_key_component(buffer, value) }
       else
-        data.to_s
+        value = data.to_s.b
+        buffer << value.bytesize.to_s << ":" << value
       end
+      buffer
     end
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: response_bank
 version: !ruby/object:Gem::Version
-  version: 1.7.0
+  version: 1.9.0
 platform: ruby
 authors:
 - Tobias Lütke
@@ -58,14 +58,14 @@ dependencies:
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 0.2.0
+        version: 0.3.0
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 0.2.0
+        version: 0.3.0
 - !ruby/object:Gem::Dependency
   name: minitest
   requirement: !ruby/object:Gem::Requirement
@@ -176,7 +176,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.21
+rubygems_version: 4.0.23
 specification_version: 4
 summary: Simple response caching for Ruby applications
 test_files: []