legion-cache 1.3.22 → 1.4.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b9beae1671201b0badb0e624397d49fc7bd87ad72b7b934da511de49cb73b4ca
-  data.tar.gz: 774613e524ac32ebf1f418162972d4adcef79520117516034c7e034ad2dc9ffa
+  metadata.gz: 0fe912c13fe0c2a7f697df703795eaadde5865c91aa96f112b89720fa4f6d4ee
+  data.tar.gz: 81053355f02e0763186aa3bf4c66f8bbc3fe5fd5592a4349164709e567055d28
 SHA512:
-  metadata.gz: 20adce165ec6becfb16dde7b68f2c597f045e61834ee6251bc175c6219da630d72a5d8a09ed74eeee62680eb309db526b992193f8fdaf1f613369914df8061ea
-  data.tar.gz: 2e54304b1ebb1ccb2bba53f465e314825ddee6fd1099248590b0664ca09e3727a655ce5d1f320095fd612c37d26ba9de5bb14a79d7c98848c3fe1f98cb97b231
+  metadata.gz: 58018a8630317f2f20ad6487e44dc072965e5d5c4125a003227f1bc54d5e97a6a8eeb71c7ab12f0a014646b2ba662492019960b25e6b66d52049215f9eade7c0
+  data.tar.gz: e1cfa791e292d2448ac3ad4026c847150dc62437a1bcb3d7bf25000138b65f7e33ae82d76b5f539fe19f7ee645ef40e4ea05f2933e8ead15dc18154de1cf0967

data/CHANGELOG.md

@@ -2,6 +2,61 @@
 
 ## [Unreleased]
 
+## [1.4.1] - 2026-04-06
+
+### Fixed
+- AsyncWriter TOCTOU race condition in enqueue (capture local executor reference)
+- Reconnector deadlock on stop (release mutex before thread.join)
+- Reconnector NoMethodError on successful reconnect (AtomicFixnum reset)
+- Missing `require 'concurrent'` in reconnector.rb
+- Redis cluster flush now passes auth/TLS credentials to per-node connections
+- Async writer drains before pool close on shutdown
+- Serialization applied to mget/mset_sync (was only on set_sync/get)
+- Binary encoding forced before serialization prefix checks
+
+### Added
+- Automatic failback to Local tier when shared cache is disabled or disconnected (configurable via `failback_to_local: true`)
+- `mget`/`mset` methods on Memory adapter for interface consistency
+- Public `pool` accessor on `Legion::Cache` (replaces direct `@client` access)
+- `failed_count` counter in AsyncWriter stats (`async_failed` in stats hash)
+- `reconnect_shared!` raising method for reconnector connect_block
+- End-to-end lifecycle integration test (shared fail -> local failback -> reconnect)
+
+### Changed
+- Helper and Cacheable use `async: false` for read-after-write consistency
+- AsyncWriter and Reconnector are tier-aware (`settings_key:` parameter, `:cache_local` for local tier)
+- Redis driver `pool_size` resolved from settings (was hardcoded to 20)
+- Pool checkout timeout separated from operation timeout (new `pool_checkout_timeout` setting)
+- Reconnector starts on any shared failure (even when local fallback succeeds)
+- `setup` guarded by `enabled?` check
+- State flags (`@connected`, `@using_local`, `@using_memory`) refactored to `Concurrent::AtomicBoolean`
+- Reconnector `@stop_signal` refactored to `Concurrent::AtomicBoolean`
+- `RedisHash` uses public `pool` accessor instead of `instance_variable_get(:@client)`
+
+## [1.4.0] - 2026-04-06
+
+### Added
+- Async write support via `Legion::Cache::AsyncWriter` backed by `concurrent-ruby` ThreadPoolExecutor
+- `set`, `delete`, and `mset` now accept `async:` keyword (default `true`) for non-blocking writes
+- `Legion::Cache::Reconnector` with exponential backoff (1s to 60s) for background reconnection
+- Reconnector auto-starts when both shared and local cache are unavailable at setup
+- `enabled?` guard on both shared and local tiers
+- `stats` method returning frozen Hash with driver, connection, pool, async, and reconnect metrics
+- `set_sync`, `delete_sync`, `mset_sync` explicit synchronous write methods on all tiers
+- Async and reconnect default settings in `Legion::Cache::Settings`
+- Transparent JSON serialization for Redis driver (prefix-byte protocol, backward-compatible with legacy data)
+
+### Changed
+- All cache drivers now use keyword TTL (`ttl:`) instead of positional arguments
+- `flush` takes no arguments across all drivers (was `flush(delay = 0)`)
+- `Helper` module updated: `FALLBACK_TTL` changed from 60 to 3600, all delegations use keyword signatures, `cache_set`/`cache_delete`/`cache_mset` accept `async:` keyword
+- `Cacheable` module updated: `cache_write` and `local_cache_write` use keyword TTL
+- Default TTL changed from 60 to 3600 (shared) and 21600 (local)
+- Version bump from 1.3.22 to 1.4.0
+
+### Fixed
+- Unified exception handling model: reads return nil (handled), sync writes re-raise, lifecycle handles internally
+
 ## [1.3.22] - 2026-04-03
 
 ### Fixed

data/legion-cache.gemspec

@@ -26,6 +26,7 @@ Gem::Specification.new do |spec|
     'rubygems_mfa_required' => 'true'
   }
 
+  spec.add_dependency 'concurrent-ruby', '>= 1.2'
   spec.add_dependency 'connection_pool', '>= 2.4'
   spec.add_dependency 'dalli', '>= 3.0'
   spec.add_dependency 'legion-logging', '>= 1.5.0'

data/lib/legion/cache/async_writer.rb

@@ -0,0 +1,126 @@
+# frozen_string_literal: true
+
+require 'concurrent-ruby'
+require 'legion/logging/helper'
+
+module Legion
+  module Cache
+    class AsyncWriter
+      include Legion::Logging::Helper
+
+      DEFAULT_POOL_SIZE = 4
+      DEFAULT_QUEUE_SIZE = 1000
+      DEFAULT_SHUTDOWN_TIMEOUT = 5
+
+      def initialize(pool_size: nil, queue_size: nil, shutdown_timeout: nil, settings_key: :cache)
+        @settings_key = settings_key
+        @config_pool_size = pool_size
+        @config_queue_size = queue_size
+        @config_shutdown_timeout = shutdown_timeout
+        @processed = Concurrent::AtomicFixnum.new(0)
+        @failed = Concurrent::AtomicFixnum.new(0)
+        @executor = nil
+        @mutex = Mutex.new
+      end
+
+      def start(pool_size: nil, queue_size: nil, **)
+        @mutex.synchronize do
+          return if running?
+
+          ps = pool_size || @config_pool_size || configured_pool_size
+          qs = queue_size || @config_queue_size || configured_queue_size
+
+          @executor = Concurrent::ThreadPoolExecutor.new(
+            min_threads:     1,
+            max_threads:     ps,
+            max_queue:       qs,
+            fallback_policy: :caller_runs
+          )
+          log.info "Legion::Cache::AsyncWriter started pool_size=#{ps} queue_size=#{qs}"
+        end
+      end
+
+      def stop(timeout: nil)
+        @mutex.synchronize do
+          return unless @executor
+
+          to = timeout || @config_shutdown_timeout || configured_shutdown_timeout
+          @executor.shutdown
+          unless @executor.wait_for_termination(to)
+            @executor.kill
+            log.warn "Legion::Cache::AsyncWriter force-killed after #{to}s timeout"
+          end
+          log.info "Legion::Cache::AsyncWriter stopped processed=#{@processed.value}"
+          @executor = nil
+        end
+      end
+
+      def enqueue(&block)
+        executor = @executor
+        if executor&.running?
+          executor.post do
+            block.call
+            @processed.increment
+          rescue StandardError => e
+            handle_exception(e, level: :warn, handled: true, operation: :async_writer_job)
+            @failed.increment
+          end
+        else
+          begin
+            block.call
+            @processed.increment
+          rescue StandardError => e
+            handle_exception(e, level: :warn, handled: true, operation: :async_writer_sync_fallback)
+            @failed.increment
+          end
+        end
+      end
+
+      def running?
+        @executor&.running? == true
+      end
+
+      def pool_size
+        @executor&.max_length || 0
+      end
+
+      def queue_depth
+        @executor&.queue_length || 0
+      end
+
+      def processed_count
+        @processed.value
+      end
+
+      def failed_count
+        @failed.value
+      end
+
+      private
+
+      def configured_pool_size
+        return DEFAULT_POOL_SIZE unless defined?(Legion::Settings)
+
+        Legion::Settings.dig(@settings_key, :async, :pool_size) || DEFAULT_POOL_SIZE
+      rescue StandardError
+        DEFAULT_POOL_SIZE
+      end
+
+      def configured_queue_size
+        return DEFAULT_QUEUE_SIZE unless defined?(Legion::Settings)
+
+        Legion::Settings.dig(@settings_key, :async, :queue_size) || DEFAULT_QUEUE_SIZE
+      rescue StandardError
+        DEFAULT_QUEUE_SIZE
+      end
+
+      def configured_shutdown_timeout
+        return DEFAULT_SHUTDOWN_TIMEOUT unless defined?(Legion::Settings)
+
+        Legion::Settings.dig(@settings_key, :async, :shutdown_timeout) || DEFAULT_SHUTDOWN_TIMEOUT
+      rescue StandardError
+        DEFAULT_SHUTDOWN_TIMEOUT
+      end
+    end
+  end
+end

data/lib/legion/cache/cacheable.rb

@@ -72,13 +72,13 @@ module Legion
         case scope
         when :global
           if global_cache_available?
-            Legion::Cache.set(key, value, ttl)
+            Legion::Cache.set(key, value, ttl: ttl, async: false)
           else
             memory_write(key, value, ttl)
           end
         else
           if local_cache_available?
-            result = local_cache_write(key, value, ttl)
+            result = local_cache_write(key, value, ttl: ttl)
             memory_write(key, value, ttl) unless result
           else
             memory_write(key, value, ttl)
@@ -104,10 +104,10 @@ module Legion
         LOCAL_CACHE_MISS
       end
 
-      def self.local_cache_write(key, value, ttl)
+      def self.local_cache_write(key, value, ttl:)
         return unless local_cache_available?
 
-        Legion::Cache::Local.set(key, value, ttl)
+        Legion::Cache::Local.set(key, value, ttl: ttl, async: false)
       rescue StandardError => e
         handle_exception(e, level: :warn, operation: :local_cache_write, key: key, ttl: ttl)
         nil

data/lib/legion/cache/helper.rb

@@ -7,7 +7,7 @@ module Legion
     module Helper
       include Legion::Logging::Helper
 
-      FALLBACK_TTL = 60
+      FALLBACK_TTL = 3600
 
       # --- TTL Resolution ---
       # Override in your LEX to set a custom default TTL for the extension.
@@ -40,7 +40,7 @@ module Legion
 
       def cache_set(key, value, ttl: nil, phi: false)
         effective_ttl = ttl || cache_default_ttl
-        Legion::Cache.set(cache_namespace + key, value, effective_ttl, phi: phi)
+        Legion::Cache.set(cache_namespace + key, value, ttl: effective_ttl, async: false, phi: phi)
       end
 
       def cache_get(key)
@@ -48,12 +48,12 @@ module Legion
       end
 
       def cache_delete(key)
-        Legion::Cache.delete(cache_namespace + key)
+        Legion::Cache.delete(cache_namespace + key, async: false)
       end
 
       def cache_fetch(key, ttl: nil, &)
         effective_ttl = ttl || cache_default_ttl
-        Legion::Cache.fetch(cache_namespace + key, effective_ttl, &)
+        Legion::Cache.fetch(cache_namespace + key, ttl: effective_ttl, &)
       end
 
       def cache_exist?(key)
@@ -90,7 +90,7 @@ module Legion
 
         effective_ttl = ttl || cache_default_ttl
 
-        hash.each { |k, v| Legion::Cache.set(cache_namespace + k, v, effective_ttl) }
+        hash.each { |k, v| Legion::Cache.set(cache_namespace + k, v, ttl: effective_ttl, async: false) }
         true
       rescue StandardError => e
         log_cache_error('cache_mset', e)
@@ -114,7 +114,7 @@ module Legion
 
         effective_ttl = ttl || local_cache_default_ttl
 
-        hash.each { |k, v| Legion::Cache::Local.set(cache_namespace + k, v, effective_ttl) }
+        hash.each { |k, v| Legion::Cache::Local.set(cache_namespace + k, v, ttl: effective_ttl, async: false) }
         true
       rescue StandardError => e
         log_cache_error('local_cache_mset', e)
@@ -205,7 +205,7 @@ module Legion
       def local_cache_set(key, value, ttl: nil, phi: false)
         effective_ttl = ttl || local_cache_default_ttl
         effective_ttl = Legion::Cache.enforce_phi_ttl(effective_ttl, phi: phi)
-        Legion::Cache::Local.set(cache_namespace + key, value, effective_ttl)
+        Legion::Cache::Local.set(cache_namespace + key, value, ttl: effective_ttl, async: false)
       end
 
       def local_cache_get(key)
@@ -213,12 +213,12 @@ module Legion
       end
 
       def local_cache_delete(key)
-        Legion::Cache::Local.delete(cache_namespace + key)
+        Legion::Cache::Local.delete(cache_namespace + key, async: false)
       end
 
       def local_cache_fetch(key, ttl: nil, &)
         effective_ttl = ttl || local_cache_default_ttl
-        Legion::Cache::Local.fetch(cache_namespace + key, effective_ttl, &)
+        Legion::Cache::Local.fetch(cache_namespace + key, ttl: effective_ttl, &)
       end
 
       def local_cache_exist?(key)
@@ -312,7 +312,7 @@ module Legion
       def memcached_hash_merge(full_key, new_fields)
         current = memcached_hash_load(full_key) || {}
         merged = current.merge(new_fields.transform_keys(&:to_s))
-        Legion::Cache.set(full_key, Legion::JSON.dump(merged), cache_default_ttl)
+        Legion::Cache.set(full_key, Legion::JSON.dump(merged), ttl: cache_default_ttl, async: false)
         true
       end
 
@@ -335,7 +335,7 @@ module Legion
         str_fields = fields.map(&:to_s)
         removed = str_fields.count { |f| current.key?(f) }
         str_fields.each { |f| current.delete(f) }
-        Legion::Cache.set(full_key, Legion::JSON.dump(current), cache_default_ttl)
+        Legion::Cache.set(full_key, Legion::JSON.dump(current), ttl: cache_default_ttl, async: false)
         removed
       end
 

data/lib/legion/cache/local.rb

@@ -1,16 +1,20 @@
 # frozen_string_literal: true
 
+require 'concurrent'
 require 'legion/logging/helper'
 require 'legion/cache/settings'
 
 module Legion
   module Cache
     module Local
+      @connected = Concurrent::AtomicBoolean.new(false)
+
       class << self
         include Legion::Logging::Helper
 
         def setup(**)
-          return if @connected
+          return unless enabled?
+          return if connected?
 
           settings = local_settings
           return unless settings[:enabled]
@@ -19,12 +23,12 @@ module Legion
           @driver_name = Legion::Cache::Settings.normalize_driver(driver_name)
           @driver = build_driver(driver_name)
           @driver.client(**settings, logger: log, **)
-          @connected = true
+          @connected.make_true
           servers = Array(settings[:servers]).join(', ')
           log.info "Legion::Cache::Local connected (#{driver_name}) to #{servers}"
         rescue StandardError => e
           handle_exception(e, level: :warn, handled: true, operation: :cache_local_setup, driver: driver_name)
-          @connected = false
+          @connected.make_false
         end
 
         def shutdown
@@ -34,11 +38,20 @@ module Legion
           @driver&.close
           @driver = nil
           @driver_name = nil
-          @connected = false
+          @connected.make_false
+        end
+
+        def enabled?
+          return true unless defined?(Legion::Settings)
+
+          Legion::Settings.dig(:cache_local, :enabled) != false
+        rescue StandardError => e
+          handle_exception(e, level: :warn, handled: true, operation: :cache_local_enabled)
+          true
         end
 
         def connected?
-          @connected == true
+          @connected&.true? || false
         end
 
         def driver_name
@@ -47,47 +60,82 @@ module Legion
 
         def get(key)
           result = @driver.get(key)
-          log.debug "[cache:local] GET #{key} hit=#{!result.nil?}"
+          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
+          handle_exception(e, level: :warn, handled: true, operation: :cache_local_get, key: key)
+          nil
         end
 
-        def set(key, value, ttl = 180)
-          result = @driver.set(key, value, ttl)
-          log.debug "[cache:local] SET #{key} ttl=#{ttl} success=#{result}"
+        def set(key, value, ttl: nil, **)
+          set_sync(key, value, ttl: ttl, **)
+        end
+
+        def set_sync(key, value, ttl: nil, **)
+          effective_ttl = ttl || local_default_ttl
+          result = @driver.set_sync(key, value, ttl: effective_ttl)
+          log.debug { "[cache:local] SET #{key} ttl=#{effective_ttl} success=#{result}" }
           result
         rescue StandardError => e
-          handle_exception(e, level: :warn, handled: false, operation: :cache_local_set, key: key, ttl: ttl)
+          handle_exception(e, level: :error, handled: false, operation: :cache_local_set_sync, key: key, ttl: effective_ttl)
           raise
         end
 
-        def fetch(key, ttl = nil, &)
-          result = @driver.fetch(key, ttl, &)
-          log.debug "[cache:local] FETCH #{key} hit=#{!result.nil?}"
+        def fetch(key, ttl: nil, &)
+          result = @driver.fetch(key, ttl: 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
+          handle_exception(e, level: :warn, handled: true, operation: :cache_local_fetch, key: key, ttl: ttl)
+          nil
+        end
+
+        def delete(key, **)
+          delete_sync(key)
         end
 
-        def delete(key)
-          result = @driver.delete(key)
-          log.debug "[cache:local] DELETE #{key} success=#{result}"
+        def delete_sync(key)
+          result = @driver.delete_sync(key)
+          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)
+          handle_exception(e, level: :error, handled: false, operation: :cache_local_delete_sync, key: key)
           raise
         end
 
-        def flush(delay = 0)
-          result = @driver.flush(delay)
-          log.debug '[cache:local] FLUSH completed'
+        def flush
+          result = @driver.flush
+          log.debug { '[cache:local] FLUSH completed' }
           result
         rescue StandardError => e
-          handle_exception(e, level: :warn, handled: false, operation: :cache_local_flush, delay: delay)
-          raise
+          handle_exception(e, level: :warn, handled: true, operation: :cache_local_flush)
+          nil
+        end
+
+        def mget(*keys)
+          keys = keys.flatten
+          return {} if keys.empty?
+
+          keys.to_h { |key| [key, get(key)] }
+        end
+
+        def mset(hash, ttl: nil, **)
+          return true if hash.empty?
+
+          hash.each { |key, value| set(key, value, ttl: ttl) }
+          true
+        end
+
+        def stats
+          {
+            driver:    driver_name,
+            servers:   local_servers,
+            enabled:   enabled?,
+            connected: connected?
+          }.freeze
+        rescue StandardError => e
+          handle_exception(e, level: :warn, handled: true, operation: :cache_local_stats)
+          { error: e.message }.freeze
         end
 
         def client
@@ -98,7 +146,7 @@ module Legion
           @driver&.close
           @driver = nil
           @driver_name = nil
-          @connected = false
+          @connected.make_false
           log.info 'Legion::Cache::Local pool closed'
           @connected
         end
@@ -106,7 +154,7 @@ module Legion
         def restart(**opts)
           settings = local_settings
           @driver&.restart(**settings.merge(opts, logger: log))
-          @connected = true
+          @connected.make_true
           log.info 'Legion::Cache::Local pool restarted'
           @connected
         end
@@ -130,13 +178,27 @@ module Legion
         def reset!
           @driver = nil
           @driver_name = nil
-          @connected = false
+          @connected.make_false
           log.debug 'Legion::Cache::Local state reset'
           @connected
         end
 
         private
 
+        def local_servers
+          Array(local_settings[:servers])
+        rescue StandardError
+          []
+        end
+
+        def local_default_ttl
+          return 21_600 unless defined?(Legion::Settings)
+
+          Legion::Settings.dig(:cache_local, :default_ttl) || 21_600
+        rescue StandardError
+          21_600
+        end
+
         def build_driver(driver_name)
           case Legion::Cache::Settings.normalize_driver(driver_name)
           when 'redis'