response_bank 1.5.0 → 1.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c3db28140576d28fa3faf6af84b571085208f7f40b977e615b102f038d60632a
-  data.tar.gz: ff991b1105a3c3b7827e5d7872ca55a648b692c6a67a67c144f5c458291adbe5
+  metadata.gz: 54fd4c438eab18c36f842002725ec243f6ca9837f03a2d70dc594a8bf4765d8d
+  data.tar.gz: cc5512b2fa88dd622da3ef9fae6abda48f9c7122eed828dd988a17343607f0cd
 SHA512:
-  metadata.gz: face725382f16dc7ae054efd68de804eb303ff566bbf6758aa88d09922a2d8747e78fc9b9b2a9d109d508a0af9bcea28dc919d7f2b70954661c349f5feaaad2a
-  data.tar.gz: b9101b86d39ddc5ea9a427326cfd58834bd5d3015509d0411007f286ad34cd00f1113c43f6d20d1d01a2cc317340d905dc9bfb1b24bb2e2df8c6509ca897b00e
+  metadata.gz: 9637541060aab3ac047247fdd13e83d57b99e3921689a7dd354ce684c247f9decb04de2c784e6f04bb57796e71279098a2f1a3db670d67ad25bb8406a7eb30f3
+  data.tar.gz: d3ba8c122b58152cd1e10e8d1fb504b65c2e8c906d3a862be98050f7b252129d392bbc83d0e220a2c79248f0da16bb3f85d8ae441c0c2b03281ee123a872b4bf

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`:
@@ -287,6 +305,19 @@ Advanced integrations can still install the per-request injector directly in the
 env[ResponseBank::BrotliSpliceSlot::INJECTOR_ENV_KEY] = injector
 ```
 
+## Observing server cache hits
+
+After successfully serving an entry from the server cache, ResponseBank exposes its generation time and stale-while-revalidate status in the Rack environment:
+
+```ruby
+timestamp = env['cacheable.timestamp']
+stale = env['cacheable.stale']
+```
+
+`cacheable.timestamp` is only set after successfully serving a server-cache entry.
+`cacheable.stale` is initialized to `false` when a server-cache entry is evaluated
+and set to `true` only when ResponseBank serves it through stale-while-revalidate.
+
 ## Exception Handling
 
 ResponseBank handles all exceptions gracefully during cache operations. If an exception occurs while reading from cache, deserializing cached data, or writing to cache, the middleware will:

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

@@ -133,6 +133,7 @@ module ResponseBank
         @env['cacheable.compression_level'] = compression_level
 
         @env['cacheable.locked'] ||= false
+        @env['cacheable.stale'] = false
 
         # to preserve the unversioned/versioned logging messages from past releases we split the match_entity_tag test
         if match_entity_tag == "*"
@@ -149,6 +150,7 @@ module ResponseBank
             return
           elsif stale_while_revalidate?(timestamp, cache_age_tolerance)
             # cache is being regenerated, can we avoid piling on and use a stale version in the interim?
+            @env['cacheable.stale'] = true
             ResponseBank.log("Cache hit: server (recent)")
           else
             ResponseBank.log("Found an unversioned cache entry, but it was too old (#{timestamp})")
@@ -176,6 +178,15 @@ 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
+
+        @env['cacheable.timestamp'] = timestamp
         [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.7.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.7.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: []