response_bank 1.4.0 → 1.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f9667d810b487f5db154d43ba2e7be769ab999d0d721b881a5c558e97ae55ceb
-  data.tar.gz: 744ec28ba5bdd1e5ae368e215d0ca6e86d0ce0d8910c49cd13b5835fe4283e9b
+  metadata.gz: 4049027dc5a512bb6f1225b179ac82989b995e8e77f0b384fce0154c58cd76c0
+  data.tar.gz: 0351324db2bb6a5d00d2585d7e2fb52d5f1f17860f19ec56e23bc848d411ce0f
 SHA512:
-  metadata.gz: ec9cb3918c4ff1d9bf6b5d1e18c18eb6bae8f0a49cdc8f15aff494c7d43fc2b3e1bcd38078770d75cfb06f4517f08515b67a8429877d815952576703461eb929
-  data.tar.gz: 9d815e56c3d9986367847c1f2f730c16fa72ab989dcedcf379cd849dd00a436076c7a08b92a94e0123ded75058d628d17b2a6dcab26fc6598a7057140daabfb7
+  metadata.gz: 278e15de6e89c0a006c13da52ff42a326be704050ef905d8ad7c0541a8444359253923a9331747440f72fe2855ac7addf3af3b917c75c5a2775c052618aa62fb
+  data.tar.gz: 9ec95ddb14b3a4d6763dd7ddd0e40b9f5367a3943baad464890b64723747b849627cbb513e1d3b982640563f3c73e1f18d8a437470e6303853369c07bf9b8154

data/README.md

@@ -11,7 +11,7 @@
 
 This gem supports the following versions of Ruby and Rails:
 
-* Ruby 3.1.0+
+* Ruby 3.3.0+
 * Rails 6.0.0+
 
 ## Usage
@@ -145,10 +145,48 @@ The middleware arms the handle after the application returns the Rack tuple. It
 
 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.
 
+## Cache Entry Metadata
+
+Applications can store a Hash inside a cache entry by setting
+`env['cacheable.metadata']` before the response is stored:
+
+```ruby
+env['cacheable.metadata'] = { 'variant' => 'b' }
+```
+
+On a server cache hit, `env['cacheable.metadata']` holds the Hash stored with the
+served entry, stale or fresh; the key is removed when the entry has none. The Hash
+is stored once and shared by every request served from the entry, so it must not
+contain anything visitor-specific. It is serialized with MessagePack (String keys on
+read) and nested under `ResponseBank::APP_METADATA_KEY`, so it cannot collide with
+ResponseBank's own slots. Keep it to plain MessagePack types: a Hash that does not
+survive a MessagePack round-trip, because a value cannot be serialized or the nesting
+is too deep for the unpacker, is logged and dropped, and the response is cached without it.
+
 ## Brotli Splice Slots
 
 Applications that need per-request replacement inside cached Brotli HTML responses can pass an injector builder to `ResponseBank::Middleware`:

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

@@ -3,4 +3,11 @@
 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
+
+  # Application metadata stored inside the cache entry: set `env[METADATA_ENV_KEY]`
+  # (a Hash) before the response is stored; on a server cache hit it holds the Hash
+  # stored with the served entry.
+  METADATA_ENV_KEY = 'cacheable.metadata'
+  # Keeps application metadata apart from ResponseBank's own slots.
+  APP_METADATA_KEY = 'app'
 end

data/lib/response_bank/cache_writer.rb

@@ -30,20 +30,61 @@ module ResponseBank
         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}"}
+        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(cache_key) do
+        ResponseBank.write_to_cache(env.fetch('cacheable.key')) do
           payload = MessagePack.dump(data)
           ResponseBank.write_to_backing_cache_store(
             env,
-            unversioned_key,
+            env.fetch('cacheable.unversioned-key'),
             payload,
             expires_in: env['cacheable.versioned-cache-expiry'],
           )
@@ -52,7 +93,14 @@ module ResponseBank
         stored
       end
 
-      private
+      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)
@@ -109,9 +157,34 @@ module ResponseBank
         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
+        metadata = entry_metadata(env, stored.metadata)
+        data << metadata if metadata
         data
       end
+
+      # Application metadata never fails the write, nor the reads that follow: anything
+      # that is not a Hash, or that does not round-trip through MessagePack, is logged
+      # and left out of the entry.
+      def entry_metadata(env, metadata)
+        app_metadata = env[ResponseBank::METADATA_ENV_KEY]
+        return metadata if app_metadata.nil?
+        unless app_metadata.is_a?(Hash)
+          ResponseBank.log("Ignoring #{ResponseBank::METADATA_ENV_KEY}: expected a Hash, got #{app_metadata.class}")
+          return metadata
+        end
+
+        merged = (metadata || {}).merge(ResponseBank::APP_METADATA_KEY => app_metadata)
+        begin
+          # Loading catches what dumping accepts but the reader rejects, such as nesting
+          # past the unpacker's stack; the array puts the Hash at its depth in the entry.
+          MessagePack.load(MessagePack.dump([merged]))
+        rescue StandardError => error
+          ResponseBank.log("Ignoring #{ResponseBank::METADATA_ENV_KEY}: #{error.class} - #{error.message}")
+          return metadata
+        end
+
+        merged
+      end
     end
   end
 end

data/lib/response_bank/deferred_store.rb

@@ -60,32 +60,33 @@ module ResponseBank
     # `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
+      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
-      return false unless status
+    end
 
-      write_started = false
-      completed = false
-      begin
-        CacheWriter.store(
+    # `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: -> { write_started = true },
+          before_write: before_write,
         )
-        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
@@ -104,6 +105,28 @@ module ResponseBank
 
     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

data/lib/response_bank/response_cache_handler.rb

@@ -176,6 +176,14 @@ module ResponseBank
           ResponseBank.log("Cache hit, but missing content-encoding in the cache value headers, maybe because of 301 or 404 response or empty body string")
         end
 
+        # After decompression and splicing, so a refill never inherits the rejected
+        # entry's metadata; cleared when the served entry has none.
+        if metadata&.key?(ResponseBank::APP_METADATA_KEY)
+          @env[ResponseBank::METADATA_ENV_KEY] = metadata[ResponseBank::APP_METADATA_KEY]
+        else
+          @env.delete(ResponseBank::METADATA_ENV_KEY)
+        end
+
         [status, @headers, [body]]
 
       end

data/lib/response_bank/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: response_bank
 version: !ruby/object:Gem::Version
-  version: 1.4.0
+  version: 1.6.0
 platform: ruby
 authors:
 - Tobias Lütke
@@ -58,14 +58,14 @@ dependencies:
     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
@@ -169,14 +169,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 3.1.0
+      version: 3.3.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.16
+rubygems_version: 4.0.21
 specification_version: 4
 summary: Simple response caching for Ruby applications
 test_files: []