response_bank 1.4.0 → 1.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f9667d810b487f5db154d43ba2e7be769ab999d0d721b881a5c558e97ae55ceb
-  data.tar.gz: 744ec28ba5bdd1e5ae368e215d0ca6e86d0ce0d8910c49cd13b5835fe4283e9b
+  metadata.gz: c3db28140576d28fa3faf6af84b571085208f7f40b977e615b102f038d60632a
+  data.tar.gz: ff991b1105a3c3b7827e5d7872ca55a648b692c6a67a67c144f5c458291adbe5
 SHA512:
-  metadata.gz: ec9cb3918c4ff1d9bf6b5d1e18c18eb6bae8f0a49cdc8f15aff494c7d43fc2b3e1bcd38078770d75cfb06f4517f08515b67a8429877d815952576703461eb929
-  data.tar.gz: 9d815e56c3d9986367847c1f2f730c16fa72ab989dcedcf379cd849dd00a436076c7a08b92a94e0123ded75058d628d17b2a6dcab26fc6598a7057140daabfb7
+  metadata.gz: face725382f16dc7ae054efd68de804eb303ff566bbf6758aa88d09922a2d8747e78fc9b9b2a9d109d508a0af9bcea28dc919d7f2b70954661c349f5feaaad2a
+  data.tar.gz: b9101b86d39ddc5ea9a427326cfd58834bd5d3015509d0411007f286ad34cd00f1113c43f6d20d1d01a2cc317340d905dc9bfb1b24bb2e2df8c6509ca897b00e

data/README.md

@@ -145,6 +145,26 @@ 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.

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_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)

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/version.rb

@@ -1,4 +1,4 @@
 # frozen_string_literal: true
 module ResponseBank
-  VERSION = "1.4.0"
+  VERSION = "1.5.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.5.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
@@ -176,7 +176,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.16
+rubygems_version: 4.0.19
 specification_version: 4
 summary: Simple response caching for Ruby applications
 test_files: []