legion-cache 1.3.20 → 1.3.21

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9f7b5b5352d50ed073af5771dd82ce824db96f0cc508beb942250dfc447428df
-  data.tar.gz: 42f6988a094eaaf4ba63c0b91ac35dd614c91bba256f574e2b97a93df4d63686
+  metadata.gz: 02b45cdf2162b9906e9e51c9ba9dbc205b38b65813844100223b0985945352da
+  data.tar.gz: 2a590f3f1e8d615165955c8ded6ed35c3057abb308bcef04b5d97fd025351800
 SHA512:
-  metadata.gz: 155a80836657e0f8e0d1260ad02d2082fa82f80fed10f7f861d794fc47e7538dbe70305c2561d99e457fe5e8ee2c40d09985bd1a5c8351cb9a2cc26913f43804
-  data.tar.gz: c17d8a5c0a71f85488713ccbff577d5b7beb4f7a88126a393c1978d7f6a89c20e71f3ede41ce8e7d1f214664a24c72eb7dba3f2d2d8dd5a09363c0b7cda66ce2
+  metadata.gz: 5938e92b24a66f18169f00544aa96c3c88d80ca820807cd2ee8f08d6308fc4cd939f01e5e47d8b5ad0537c0a1ea450515641f21ad582c8726c92be0516511cec
+  data.tar.gz: 04de2781334fb61676f5943a39c85a34ddf29db2f5cbec83b9afa9b9b08b0b9e2bd532667ceef3e2e759fb821a063d4a12cf27b592860da098bdf6290dd55483

data/CHANGELOG.md

@@ -2,6 +2,19 @@
 
 ## [Unreleased]
 
+## [1.3.21] - 2026-04-02
+
+### Fixed
+- Preserve `fetch` block behavior across shared, local, memory, and Redis cache paths; local-cache failures now fall back to the in-process cache and cached `false` values are retained correctly
+- Move shared adapter selection to runtime setup/client calls, register cache defaults through `Legion::Cache::Settings`, and normalize IPv4/hostname/IPv6 server addresses consistently
+- Restrict Redis hash/sorted-set helpers to the actual Redis backend and enforce documented TTL behavior for helper batch writes
+- Make the default `bundle exec rspec` suite hermetic by excluding service-backed integration specs unless `RUN_INTEGRATION_SPECS=1`
+
+### Changed
+- Uplift cache logging internals to `Legion::Logging::Helper`, replacing direct logger calls with helper-provided `log` usage across cache runtime modules
+- Route rescued cache adapter/helper/setup failures through `handle_exception` and expand runtime `info`/`debug`/`error` coverage for shared, local, memory, pool, and RedisHash flows
+- Require `legion-logging >= 1.5.0` at runtime so helper exception handling is always available
+
 ## [1.3.20] - 2026-03-31
 
 ### Fixed

data/legion-cache.gemspec

@@ -28,7 +28,7 @@ Gem::Specification.new do |spec|
 
   spec.add_dependency 'connection_pool', '>= 2.4'
   spec.add_dependency 'dalli', '>= 3.0'
-  spec.add_dependency 'legion-logging', '>= 1.2.8'
+  spec.add_dependency 'legion-logging', '>= 1.5.0'
   spec.add_dependency 'legion-settings', '>= 1.3.12'
   spec.add_dependency 'redis', '>= 5.0'
 end

data/lib/legion/cache/cacheable.rb

@@ -1,10 +1,15 @@
 # frozen_string_literal: true
 
 require 'digest'
+require 'legion/logging/helper'
 
 module Legion
   module Cache
     module Cacheable
+      extend Legion::Logging::Helper
+
+      LOCAL_CACHE_MISS = Object.new
+
       def self.extended(base)
         base.instance_variable_set(:@cached_methods, {})
       end
@@ -29,9 +34,9 @@ module Legion
             unless bypass_local_method_cache
               cached = Legion::Cache::Cacheable.cache_read(key, scope: config[:scope])
               if cached.nil?
-                Legion::Logging.debug "[cacheable] miss key=#{key}" if defined?(Legion::Logging)
+                Legion::Cache::Cacheable.log.debug { "[cacheable] miss key=#{key}" }
               else
-                Legion::Logging.debug "[cacheable] hit key=#{key}" if defined?(Legion::Logging)
+                Legion::Cache::Cacheable.log.debug { "[cacheable] hit key=#{key}" }
                 return cached
               end
             end
@@ -58,7 +63,8 @@ module Legion
 
           memory_read(key)
         else
-          local_cache_read(key) || memory_read(key)
+          result = local_cache_read(key)
+          result.equal?(LOCAL_CACHE_MISS) ? memory_read(key) : result
         end
       end
 
@@ -72,7 +78,8 @@ module Legion
           end
         else
           if local_cache_available?
-            local_cache_write(key, value, ttl)
+            result = local_cache_write(key, value, ttl)
+            memory_write(key, value, ttl) unless result
           else
             memory_write(key, value, ttl)
           end
@@ -88,12 +95,13 @@ module Legion
       end
 
       def self.local_cache_read(key)
-        return nil unless local_cache_available?
+        return LOCAL_CACHE_MISS unless local_cache_available?
 
-        Legion::Cache::Local.get(key)
+        result = Legion::Cache::Local.get(key)
+        result.nil? ? LOCAL_CACHE_MISS : result
       rescue StandardError => e
-        Legion::Logging.warn "[cacheable] local_cache_read failed key=#{key} error=#{e.message}" if defined?(Legion::Logging)
-        nil
+        handle_exception(e, level: :warn, operation: :local_cache_read, key: key)
+        LOCAL_CACHE_MISS
       end
 
       def self.local_cache_write(key, value, ttl)
@@ -101,7 +109,7 @@ module Legion
 
         Legion::Cache::Local.set(key, value, ttl)
       rescue StandardError => e
-        Legion::Logging.warn "[cacheable] local_cache_write failed key=#{key} error=#{e.message}" if defined?(Legion::Logging)
+        handle_exception(e, level: :warn, operation: :local_cache_write, key: key, ttl: ttl)
         nil
       end
 

data/lib/legion/cache/helper.rb

@@ -1,8 +1,12 @@
 # frozen_string_literal: true
 
+require 'legion/logging/helper'
+
 module Legion
   module Cache
     module Helper
+      include Legion::Logging::Helper
+
       FALLBACK_TTL = 60
 
       # --- TTL Resolution ---
@@ -12,7 +16,8 @@ module Legion
         return FALLBACK_TTL unless defined?(Legion::Settings)
 
         Legion::Settings.dig(:cache, :default_ttl) || FALLBACK_TTL
-      rescue StandardError
+      rescue StandardError => e
+        handle_exception(e, level: :warn, handled: true, operation: :cache_default_ttl)
         FALLBACK_TTL
       end
 
@@ -20,7 +25,8 @@ module Legion
         return cache_default_ttl unless defined?(Legion::Settings)
 
         Legion::Settings.dig(:cache_local, :default_ttl) || cache_default_ttl
-      rescue StandardError
+      rescue StandardError => e
+        handle_exception(e, level: :warn, handled: true, operation: :local_cache_default_ttl)
         cache_default_ttl
       end
 
@@ -84,13 +90,8 @@ module Legion
 
         effective_ttl = ttl || cache_default_ttl
 
-        if cache_redis?
-          namespaced = hash.transform_keys { |k| cache_namespace + k }
-          Legion::Cache.mset(namespaced)
-        else
-          hash.each { |k, v| Legion::Cache.set(cache_namespace + k, v, effective_ttl) }
-          true
-        end
+        hash.each { |k, v| Legion::Cache.set(cache_namespace + k, v, effective_ttl) }
+        true
       rescue StandardError => e
         log_cache_error('cache_mset', e)
         false
@@ -102,13 +103,7 @@ module Legion
         keys = keys.flatten
         return {} if keys.empty?
 
-        if local_cache_redis?
-          namespaced = keys.map { |k| cache_namespace + k }
-          raw = Legion::Cache::Local.mget(*namespaced)
-          keys.to_h { |k| [k, raw[cache_namespace + k]] }
-        else
-          keys.to_h { |k| [k, Legion::Cache::Local.get(cache_namespace + k)] }
-        end
+        keys.to_h { |k| [k, Legion::Cache::Local.get(cache_namespace + k)] }
       rescue StandardError => e
         log_cache_error('local_cache_mget', e)
         {}
@@ -119,13 +114,8 @@ module Legion
 
         effective_ttl = ttl || local_cache_default_ttl
 
-        if local_cache_redis?
-          namespaced = hash.transform_keys { |k| cache_namespace + k }
-          Legion::Cache::Local.mset(namespaced)
-        else
-          hash.each { |k, v| Legion::Cache::Local.set(cache_namespace + k, v, effective_ttl) }
-          true
-        end
+        hash.each { |k, v| Legion::Cache::Local.set(cache_namespace + k, v, effective_ttl) }
+        true
       rescue StandardError => e
         log_cache_error('local_cache_mset', e)
         false
@@ -251,7 +241,8 @@ module Legion
         return 0 unless cache_connected?
 
         Legion::Cache.pool_size
-      rescue StandardError
+      rescue StandardError => e
+        handle_exception(e, level: :warn, handled: true, operation: :cache_pool_size)
         0
       end
 
@@ -259,7 +250,8 @@ module Legion
         return 0 unless cache_connected?
 
         Legion::Cache.available
-      rescue StandardError
+      rescue StandardError => e
+        handle_exception(e, level: :warn, handled: true, operation: :cache_pool_available)
         0
       end
 
@@ -267,7 +259,8 @@ module Legion
         return 0 unless local_cache_connected?
 
         Legion::Cache::Local.pool_size
-      rescue StandardError
+      rescue StandardError => e
+        handle_exception(e, level: :warn, handled: true, operation: :local_cache_pool_size)
         0
       end
 
@@ -275,7 +268,8 @@ module Legion
         return 0 unless local_cache_connected?
 
         Legion::Cache::Local.available
-      rescue StandardError
+      rescue StandardError => e
+        handle_exception(e, level: :warn, handled: true, operation: :local_cache_pool_available)
         0
       end
 
@@ -310,8 +304,9 @@ module Legion
 
       def local_cache_redis?
         defined?(Legion::Cache::Local) &&
-          Legion::Cache::Local.respond_to?(:mget) &&
-          Legion::Cache::Local.connected?
+          Legion::Cache::Local.connected? &&
+          Legion::Cache::Local.respond_to?(:driver_name) &&
+          Legion::Cache::Local.driver_name == 'redis'
       end
 
       def memcached_hash_merge(full_key, new_fields)
@@ -328,7 +323,8 @@ module Legion
         parsed = Legion::JSON.load(raw)
         # Legion::JSON.load returns symbol keys; convert to string keys to mirror Redis hgetall
         parsed.transform_keys(&:to_s)
-      rescue StandardError
+      rescue StandardError => e
+        handle_exception(e, level: :warn, handled: true, operation: :memcached_hash_load, key: full_key)
         nil
       end
 
@@ -349,9 +345,7 @@ module Legion
       end
 
       def log_cache_error(method, error)
-        return unless defined?(Legion::Logging)
-
-        Legion::Logging.warn "[cache:helper] #{method} failed: #{error.class} — #{error.message}"
+        handle_exception(error, level: :warn, operation: method)
       end
     end
   end

data/lib/legion/cache/local.rb

@@ -1,11 +1,14 @@
 # frozen_string_literal: true
 
+require 'legion/logging/helper'
 require 'legion/cache/settings'
 
 module Legion
   module Cache
     module Local
       class << self
+        include Legion::Logging::Helper
+
         def setup(**)
           return if @connected
 
@@ -13,22 +16,24 @@ module Legion
           return unless settings[:enabled]
 
           driver_name = settings[:driver] || Legion::Cache::Settings.driver
+          @driver_name = Legion::Cache::Settings.normalize_driver(driver_name)
           @driver = build_driver(driver_name)
-          @driver.client(**settings, **)
+          @driver.client(**settings, logger: log, **)
           @connected = true
           servers = Array(settings[:servers]).join(', ')
-          Legion::Logging.info "Legion::Cache::Local connected (#{driver_name}) to #{servers}" if defined?(Legion::Logging)
+          log.info "Legion::Cache::Local connected (#{driver_name}) to #{servers}"
         rescue StandardError => e
-          Legion::Logging.warn "Legion::Cache::Local setup failed: #{e.message}" if defined?(Legion::Logging)
+          handle_exception(e, level: :warn, handled: true, operation: :cache_local_setup, driver: driver_name)
           @connected = false
         end
 
         def shutdown
           return unless @connected
 
-          Legion::Logging.info 'Shutting down Legion::Cache::Local' if defined?(Legion::Logging)
+          log.info 'Shutting down Legion::Cache::Local'
           @driver&.close
           @driver = nil
+          @driver_name = nil
           @connected = false
         end
 
@@ -36,34 +41,53 @@ module Legion
           @connected == true
         end
 
+        def driver_name
+          @driver_name || Legion::Cache::Settings.normalize_driver(local_settings[:driver] || Legion::Cache::Settings.driver)
+        end
+
         def get(key)
           result = @driver.get(key)
-          Legion::Logging.debug "[cache:local] GET #{key} hit=#{!result.nil?}" if defined?(Legion::Logging)
+          log.debug "[cache:local] GET #{key} hit=#{!result.nil?}"
           result
+        rescue StandardError => e
+          handle_exception(e, level: :warn, handled: false, operation: :cache_local_get, key: key)
+          raise
         end
 
         def set(key, value, ttl = 180)
           result = @driver.set(key, value, ttl)
-          Legion::Logging.debug "[cache:local] SET #{key} ttl=#{ttl} success=#{result}" if defined?(Legion::Logging)
+          log.debug "[cache:local] SET #{key} ttl=#{ttl} success=#{result}"
           result
+        rescue StandardError => e
+          handle_exception(e, level: :warn, handled: false, operation: :cache_local_set, key: key, ttl: ttl)
+          raise
         end
 
-        def fetch(key, ttl = nil)
-          result = @driver.fetch(key, ttl)
-          Legion::Logging.debug "[cache:local] FETCH #{key} hit=#{!result.nil?}" if defined?(Legion::Logging)
+        def fetch(key, ttl = nil, &)
+          result = @driver.fetch(key, ttl, &)
+          log.debug "[cache:local] FETCH #{key} hit=#{!result.nil?}"
           result
+        rescue StandardError => e
+          handle_exception(e, level: :warn, handled: false, operation: :cache_local_fetch, key: key, ttl: ttl)
+          raise
         end
 
         def delete(key)
           result = @driver.delete(key)
-          Legion::Logging.debug "[cache:local] DELETE #{key} success=#{result}" if defined?(Legion::Logging)
+          log.debug "[cache:local] DELETE #{key} success=#{result}"
           result
+        rescue StandardError => e
+          handle_exception(e, level: :warn, handled: false, operation: :cache_local_delete, key: key)
+          raise
         end
 
         def flush(delay = 0)
           result = @driver.flush(delay)
-          Legion::Logging.debug '[cache:local] FLUSH completed' if defined?(Legion::Logging)
+          log.debug '[cache:local] FLUSH completed'
           result
+        rescue StandardError => e
+          handle_exception(e, level: :warn, handled: false, operation: :cache_local_flush, delay: delay)
+          raise
         end
 
         def client
@@ -72,13 +96,19 @@ module Legion
 
         def close
           @driver&.close
+          @driver = nil
+          @driver_name = nil
           @connected = false
+          log.info 'Legion::Cache::Local pool closed'
+          @connected
         end
 
         def restart(**opts)
           settings = local_settings
-          @driver&.restart(**settings.merge(opts))
+          @driver&.restart(**settings.merge(opts, logger: log))
           @connected = true
+          log.info 'Legion::Cache::Local pool restarted'
+          @connected
         end
 
         def size
@@ -99,7 +129,10 @@ module Legion
 
         def reset!
           @driver = nil
+          @driver_name = nil
           @connected = false
+          log.debug 'Legion::Cache::Local state reset'
+          @connected
         end
 
         private

data/lib/legion/cache/memcached.rb

@@ -2,6 +2,7 @@
 
 require 'openssl'
 require 'dalli'
+require 'legion/logging/helper'
 require 'legion/cache/pool'
 
 module Legion
@@ -9,12 +10,14 @@ module Legion
     module Memcached
       include Legion::Cache::Pool
       extend self
+      extend Legion::Logging::Helper
 
-      def client(server: nil, servers: nil, **opts)
+      def client(server: nil, servers: nil, logger: nil, **opts)
         return @client unless @client.nil?
 
         settings = defined?(Legion::Settings) ? Legion::Settings[:cache] : {}
         servers ||= settings[:servers] || []
+        @component_logger = logger || log
 
         @pool_size = opts.key?(:pool_size) ? opts[:pool_size] : settings[:pool_size] || 10
         @timeout = opts.key?(:timeout) ? opts[:timeout] : settings[:timeout] || 5
@@ -23,7 +26,7 @@ module Legion
           driver: 'memcached', server: server, servers: Array(servers)
         )
 
-        Dalli.logger = Legion::Logging
+        Dalli.logger = shared_dalli_logger
         cache_opts = settings.merge(opts)
         cache_opts[:value_max_bytes] ||= 8 * 1024 * 1024
         cache_opts[:serializer] ||= Legion::JSON
@@ -36,40 +39,103 @@ module Legion
         end
 
         @connected = true
-        Legion::Logging.info "Memcached connected to #{resolved.join(', ')}" if defined?(Legion::Logging)
+        cache_logger.info "Memcached connected to #{resolved.join(', ')}"
         @client
+      rescue StandardError => e
+        handle_exception(e, level: :error, handled: false, operation: :memcached_client,
+                            server: server, servers: Array(servers))
+        @connected = false
+        raise
       end
 
       def get(key)
         result = client.with { |conn| conn.get(key) }
-        Legion::Logging.debug "[cache] GET #{key} hit=#{!result.nil?}"
+        cache_logger.debug "[cache] GET #{key} hit=#{!result.nil?}"
         result
+      rescue StandardError => e
+        handle_exception(e, level: :warn, handled: false, operation: :memcached_get, key: key)
+        raise
       end
 
-      def fetch(key, ttl = nil)
-        result = client.with { |conn| conn.fetch(key, ttl) }
-        Legion::Logging.debug "[cache] FETCH #{key} hit=#{!result.nil?}"
+      def fetch(key, ttl = nil, &)
+        result = client.with do |conn|
+          if block_given?
+            conn.fetch(key, ttl, &)
+          else
+            conn.fetch(key, ttl)
+          end
+        end
+        cache_logger.debug "[cache] FETCH #{key} hit=#{!result.nil?}"
         result
+      rescue StandardError => e
+        handle_exception(e, level: :warn, handled: false, operation: :memcached_fetch, key: key, ttl: ttl)
+        raise
       end
 
       def set(key, value, ttl = 180)
         result = client.with { |conn| conn.set(key, value, ttl).positive? }
-        Legion::Logging.debug "[cache] SET #{key} ttl=#{ttl} success=#{result} value_class=#{value.class}"
+        cache_logger.debug "[cache] SET #{key} ttl=#{ttl} success=#{result} value_class=#{value.class}"
         result
+      rescue StandardError => e
+        handle_exception(e, level: :warn, handled: false, operation: :memcached_set, key: key, ttl: ttl)
+        raise
       end
 
       def delete(key)
         result = client.with { |conn| conn.delete(key) == true }
-        Legion::Logging.debug "[cache] DELETE #{key} success=#{result}"
+        cache_logger.debug "[cache] DELETE #{key} success=#{result}"
         result
+      rescue StandardError => e
+        handle_exception(e, level: :warn, handled: false, operation: :memcached_delete, key: key)
+        raise
       end
 
       def flush(delay = 0)
-        client.with { |conn| conn.flush(delay).first }
+        result = client.with { |conn| conn.flush(delay).first }
+        cache_logger.debug '[cache] FLUSH completed'
+        result
+      rescue StandardError => e
+        handle_exception(e, level: :warn, handled: false, operation: :memcached_flush, delay: delay)
+        raise
+      end
+
+      def mget(*keys)
+        keys = keys.flatten
+        return {} if keys.empty?
+
+        result = client.with { |conn| conn.get_multi(*keys) }
+        cache_logger.debug "[cache] MGET keys=#{keys.size} hits=#{result.size}"
+        result
+      rescue StandardError => e
+        handle_exception(e, level: :warn, handled: false, operation: :memcached_mget, key_count: keys.size)
+        raise
+      end
+
+      def mset(hash)
+        return true if hash.empty?
+
+        client.with { |conn| conn.set_multi(hash) }
+        cache_logger.debug "[cache] MSET keys=#{hash.size}"
+        true
+      rescue StandardError => e
+        handle_exception(e, level: :warn, handled: false, operation: :memcached_mset, key_count: hash.size)
+        raise
       end
 
       private
 
+      def cache_logger
+        @component_logger || log
+      end
+
+      def shared_dalli_logger
+        if defined?(Legion::Cache) && Legion::Cache.respond_to?(:log)
+          Legion::Cache.log
+        else
+          cache_logger
+        end
+      end
+
       def memcached_tls_context(port:)
         return nil unless defined?(Legion::Crypt::TLS)
 
@@ -87,7 +153,7 @@ module Legion
 
         Legion::Settings[:cache][:tls] || {}
       rescue StandardError => e
-        Legion::Logging.debug("Memcached#memcached_tls_settings failed: #{e.message}") if defined?(Legion::Logging)
+        handle_exception(e, level: :warn, handled: true, operation: :memcached_tls_settings)
         {}
       end
     end

data/lib/legion/cache/memory.rb

@@ -1,9 +1,12 @@
 # frozen_string_literal: true
 
+require 'legion/logging/helper'
+
 module Legion
   module Cache
     module Memory
       extend self
+      extend Legion::Logging::Helper
 
       @store = {}
       @expiry = {}
@@ -12,6 +15,8 @@ module Legion
 
       def setup(**)
         @connected = true
+        log.info 'Legion::Cache::Memory connected'
+        @connected
       end
 
       def client(**) = self
@@ -23,14 +28,21 @@ module Legion
       def get(key)
         @mutex.synchronize do
           expire_if_needed(key)
-          @store[key]
+          result = @store[key]
+          log.debug { "[cache:memory] GET #{key} hit=#{!result.nil?}" }
+          result
         end
       end
 
       def set(key, value, ttl = nil)
         @mutex.synchronize do
           @store[key] = value
-          @expiry[key] = Time.now + ttl if ttl&.positive?
+          if ttl&.positive?
+            @expiry[key] = Time.now + ttl
+          else
+            @expiry.delete(key)
+          end
+          log.debug { "[cache:memory] SET #{key} ttl=#{ttl.inspect}" }
           value
         end
       end
@@ -39,6 +51,7 @@ module Legion
         val = get(key)
         return val unless val.nil?
 
+        log.debug { "[cache:memory] FETCH #{key} miss=true" }
         val = yield if block_given?
         set(key, val, ttl)
         val
@@ -46,16 +59,20 @@ module Legion
 
       def delete(key)
         @mutex.synchronize do
-          @store.delete(key)
+          removed = @store.delete(key)
           @expiry.delete(key)
+          log.debug { "[cache:memory] DELETE #{key} success=#{!removed.nil?}" }
+          removed
         end
       end
 
       def flush(_delay = 0)
-        @mutex.synchronize do
+        result = @mutex.synchronize do
           @store.clear
           @expiry.clear
         end
+        log.info 'Legion::Cache::Memory flushed'
+        result
       end
 
       def close = nil
@@ -63,14 +80,18 @@ module Legion
       def shutdown
         flush
         @connected = false
+        log.info 'Legion::Cache::Memory shut down'
+        @connected
       end
 
       def reset!
-        @mutex.synchronize do
+        result = @mutex.synchronize do
           @store.clear
           @expiry.clear
           @connected = false
         end
+        log.info 'Legion::Cache::Memory state reset'
+        result
       end
 
       def size = 1
@@ -83,6 +104,7 @@ module Legion
 
         @store.delete(key)
         @expiry.delete(key)
+        log.debug { "[cache:memory] EXPIRE #{key}" }
       end
     end
   end