Address current-head review findings on PR #3964

- Require cache/tag_index from cache.rb so direct requires of the cache
  file keep working (Codex)
- Blank tags in revalidate_tags are a no-op returning 0, mirroring
  register_tags (CodeRabbit)
- Validate cache_tag_index_expires_in / cache_tag_index_max_keys with
  dedicated setters per the neighboring renderer-setting pattern
  (CodeRabbit)
- Expose revalidates_react_cache and the private callback in the
  Revalidates RBS surface (CodeRabbit + Claude review)
- Guard the private Store key-normalization API with a respond_to? check,
  one-time warning, and raw-key fallback for custom stores (Claude review)
- Blank-tag error message now shows both the original entry and the
  resolved value so Proc-derived blanks are debuggable (Claude review)
- Specs: legacy bare-array index payload, blank revalidate no-op,
  private-API fallback warning, config setter validation

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: justin808

react_on_rails_pro/lib/react_on_rails_pro/cache.rb

@@ -14,6 +14,7 @@
 # https://github.com/shakacode/react_on_rails/blob/main/REACT-ON-RAILS-PRO-LICENSE.md
 
 require "react_on_rails/utils"
+require "react_on_rails_pro/cache/tag_index"
 
 module ReactOnRailsPro
   class Cache
@@ -55,10 +56,14 @@ def register_tags(tags, cache_key, cache_options)
 
       # Deletes every cached component entry registered under the given tags
       # and clears the tag index entries. Tags accept the same forms as the
-      # `cache_tags:` helper option. Missing/evicted index entries are a no-op.
-      # Returns the number of cache entries deleted.
+      # `cache_tags:` helper option. Blank tags (nil/empty/whitespace) are
+      # ignored, mirroring register_tags; missing/evicted index entries are a
+      # no-op. Returns the number of cache entries deleted.
       def revalidate_tags(*tags)
-        TagIndex.revalidate(*tags)
+        meaningful_tags = tags.flatten.reject(&:blank?)
+        return 0 if meaningful_tags.empty?
+
+        TagIndex.revalidate(*meaningful_tags)
       end
 
       def use_cache?(options)

react_on_rails_pro/lib/react_on_rails_pro/cache/tag_index.rb

@@ -76,7 +76,11 @@ def normalize_tag(tag)
           return normalize_tags(resolved) if resolved.is_a?(Array)
 
           value = tag_value(resolved)
-          raise ReactOnRailsPro::Error, "cache_tags value #{tag.inspect} normalized to a blank tag" if value.blank?
+          if value.blank?
+            raise ReactOnRailsPro::Error,
+                  "cache_tags entry resolved to a blank tag " \
+                  "(original: #{tag.inspect}, resolved: #{resolved.inspect})"
+          end
 
           [value]
         end
@@ -212,6 +216,11 @@ def delete_entries(keys)
           end
         end
 
+        # The private Store methods normalized_entry_key reproduces. Custom or
+        # future stores missing any of these fall back to the raw cache key
+        # (with a one-time warning) instead of failing registration silently.
+        PRIVATE_KEY_METHODS = %i[expanded_key namespace_key merged_options].freeze
+
         def normalized_entry_key(cache_key, cache_options)
           # Record the store's *logical* cache name: the expanded key plus any
           # :namespace from the entry's cache_options or the store default —
@@ -226,8 +235,26 @@ def normalized_entry_key(cache_key, cache_options)
           # these private Store methods is the only way to reproduce the
           # store's naming; all three have been stable across ActiveSupport
           # versions for years.
-          expanded = Rails.cache.send(:expanded_key, cache_key)
-          Rails.cache.send(:namespace_key, expanded, Rails.cache.send(:merged_options, cache_options))
+          store = Rails.cache
+          unless PRIVATE_KEY_METHODS.all? { |method_name| store.respond_to?(method_name, true) }
+            warn_missing_private_key_api(store)
+            return cache_key.to_s
+          end
+
+          expanded = store.send(:expanded_key, cache_key)
+          store.send(:namespace_key, expanded, store.send(:merged_options, cache_options))
+        end
+
+        def warn_missing_private_key_api(store)
+          @warned_private_key_api ||= {}
+          return if @warned_private_key_api[store.class]
+
+          @warned_private_key_api[store.class] = true
+          Rails.logger.warn do
+            "[ReactOnRailsPro] #{store.class} does not implement the private key-normalization API " \
+              "(#{PRIVATE_KEY_METHODS.join(', ')}); the cache tag index falls back to raw cache keys, " \
+              "so tag revalidation may miss entries written with a :namespace or expanded key forms."
+          end
         end
       end
     end

react_on_rails_pro/lib/react_on_rails_pro/configuration.rb

@@ -115,10 +115,34 @@ class Configuration # rubocop:disable Metrics/ClassLength
                   :renderer_request_retry_limit, :throw_js_errors, :ssr_timeout,
                   :profile_server_rendering_js_code, :raise_non_shell_server_rendering_errors, :enable_rsc_support,
                   :rsc_payload_generation_url_path, :rsc_bundle_js_file, :react_client_manifest_file,
-                  :react_server_client_manifest_file, :cache_tag_index_expires_in, :cache_tag_index_max_keys
+                  :react_server_client_manifest_file
 
     attr_reader :concurrent_component_streaming_buffer_size, :renderer_http_keep_alive_timeout,
-                :renderer_http_pool_size
+                :renderer_http_pool_size, :cache_tag_index_expires_in, :cache_tag_index_max_keys
+
+    # Sets how long tag->key index entries live (see Cache::TagIndex).
+    #
+    # @param value [Numeric] A positive number of seconds (e.g. 7.days)
+    # @raise [ReactOnRailsPro::Error] if value is not a positive, finite number
+    def cache_tag_index_expires_in=(value)
+      unless value.is_a?(Numeric) && value.positive? && value.to_f.finite?
+        raise ReactOnRailsPro::Error,
+              "config.cache_tag_index_expires_in must be a positive number of seconds"
+      end
+      @cache_tag_index_expires_in = value
+    end
+
+    # Sets the maximum cache-entry keys recorded per tag (see Cache::TagIndex).
+    #
+    # @param value [Integer] A positive integer
+    # @raise [ReactOnRailsPro::Error] if value is not a positive integer
+    def cache_tag_index_max_keys=(value)
+      unless value.is_a?(Integer) && value.positive?
+        raise ReactOnRailsPro::Error,
+              "config.cache_tag_index_max_keys must be a positive integer"
+      end
+      @cache_tag_index_max_keys = value
+    end
 
     # Sets the buffer size for concurrent component streaming.
     #

react_on_rails_pro/sig/react_on_rails_pro/cache.rbs

@@ -42,6 +42,14 @@ module ReactOnRailsPro
 
     module Revalidates
       def self.included: (Module base) -> void
+
+      module ClassMethods
+        def revalidates_react_cache: () ?{ (untyped record) -> untyped } -> void
+      end
+
+      private
+
+      def revalidate_react_on_rails_cache_tags: () -> void
     end
   end
 end

react_on_rails_pro/spec/react_on_rails_pro/cache/tag_index_spec.rb

@@ -290,5 +290,30 @@ def index_payload(tag)
       expect { ReactOnRailsPro::Cache.register_tags(nil, "entry/one", nil) }.not_to raise_error
       expect { ReactOnRailsPro::Cache.register_tags([], "entry/one", nil) }.not_to raise_error
     end
+
+    it "treats blank tags in revalidate_tags as a no-op returning 0" do
+      expect(ReactOnRailsPro.revalidate_tag(nil)).to eq(0)
+      expect(ReactOnRailsPro.revalidate_tags(nil, "", "   ", [])).to eq(0)
+    end
+
+    it "tolerates a legacy bare-array index payload (no expires_at)" do
+      Rails.cache.write(described_class.index_key("legacy-tag"), %w[entry/one entry/two])
+      Rails.cache.write("entry/one", "one")
+
+      expect(described_class.revalidate("legacy-tag")).to eq(1)
+      expect(Rails.cache.read("entry/one")).to be_nil
+    end
+
+    it "falls back to the raw cache key with a warning when the store lacks the private key API" do
+      bare_store = ActiveSupport::Cache::MemoryStore.new
+      allow(bare_store).to receive(:respond_to?).and_call_original
+      allow(bare_store).to receive(:respond_to?).with(:expanded_key, true).and_return(false)
+      allow(Rails).to receive(:cache).and_return(bare_store)
+      allow(Rails.logger).to receive(:warn)
+      described_class.instance_variable_set(:@warned_private_key_api, nil)
+
+      expect(described_class.send(:normalized_entry_key, "entry/raw", {})).to eq("entry/raw")
+      expect(Rails.logger).to have_received(:warn)
+    end
   end
 end

react_on_rails_pro/spec/react_on_rails_pro/configuration_spec.rb

@@ -989,6 +989,32 @@ def self.upload(_hash, _options = {}, **nil); end
       end
     end
 
+    describe ".cache_tag_index_expires_in / .cache_tag_index_max_keys" do
+      it "accepts valid values" do
+        ReactOnRailsPro.configure do |config|
+          config.cache_tag_index_expires_in = 3600
+          config.cache_tag_index_max_keys = 100
+        end
+
+        expect(ReactOnRailsPro.configuration.cache_tag_index_expires_in).to eq(3600)
+        expect(ReactOnRailsPro.configuration.cache_tag_index_max_keys).to eq(100)
+      end
+
+      it "raises on a non-positive or non-numeric expires_in" do
+        expect { ReactOnRailsPro.configure { |config| config.cache_tag_index_expires_in = 0 } }
+          .to raise_error(ReactOnRailsPro::Error, /cache_tag_index_expires_in/)
+        expect { ReactOnRailsPro.configure { |config| config.cache_tag_index_expires_in = "1 day" } }
+          .to raise_error(ReactOnRailsPro::Error, /cache_tag_index_expires_in/)
+      end
+
+      it "raises on a non-positive or non-integer max_keys" do
+        expect { ReactOnRailsPro.configure { |config| config.cache_tag_index_max_keys = -1 } }
+          .to raise_error(ReactOnRailsPro::Error, /cache_tag_index_max_keys/)
+        expect { ReactOnRailsPro.configure { |config| config.cache_tag_index_max_keys = 5.5 } }
+          .to raise_error(ReactOnRailsPro::Error, /cache_tag_index_max_keys/)
+      end
+    end
+
     describe ".concurrent_component_streaming_buffer_size" do
       it "accepts positive integers" do
         ReactOnRailsPro.configure do |config|