response_bank 1.5.0 → 1.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c3db28140576d28fa3faf6af84b571085208f7f40b977e615b102f038d60632a
-  data.tar.gz: ff991b1105a3c3b7827e5d7872ca55a648b692c6a67a67c144f5c458291adbe5
+  metadata.gz: 4049027dc5a512bb6f1225b179ac82989b995e8e77f0b384fce0154c58cd76c0
+  data.tar.gz: 0351324db2bb6a5d00d2585d7e2fb52d5f1f17860f19ec56e23bc848d411ce0f
 SHA512:
-  metadata.gz: face725382f16dc7ae054efd68de804eb303ff566bbf6758aa88d09922a2d8747e78fc9b9b2a9d109d508a0af9bcea28dc919d7f2b70954661c349f5feaaad2a
-  data.tar.gz: b9101b86d39ddc5ea9a427326cfd58834bd5d3015509d0411007f286ad34cd00f1113c43f6d20d1d01a2cc317340d905dc9bfb1b24bb2e2df8c6509ca897b00e
+  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
@@ -169,6 +169,24 @@ The headers passed to `complete` describe the cached representation. They can di
 
 `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/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

@@ -157,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/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.5.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.5.0
+  version: 1.6.0
 platform: ruby
 authors:
 - Tobias Lütke
@@ -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.19
+rubygems_version: 4.0.21
 specification_version: 4
 summary: Simple response caching for Ruby applications
 test_files: []