legion-cache 1.4.2 → 1.4.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 151b591709ad7af3c6012b1e701bef89a7516ee606bf8bd91385ed3da986f590
-  data.tar.gz: '0593b44cbefdfa99cf2f30fc4e1601ac9d758ed404896ca90eb639ddcc2a7fbd'
+  metadata.gz: 468452176251521d3ab40135e1801f7081f738a2e5d6fd60af7710292a066ba7
+  data.tar.gz: 79361a0d3b3f4e5c0baf65deaaec789a4a1750079c298eef92cbc72d3f73bd0e
 SHA512:
-  metadata.gz: 95d1f2d1b482514062f7711727571b7a168f830454d0faf516d527f86eb3d047b892ac77b8c4709c163161414e1f099f5d751bd57c3b9b29f8e20de3c4282740
-  data.tar.gz: 8e7b5eb4667e70e23a91c75a65589210611d66865647ce9d0bb32edaff8fc323073c742a340594ea7dc395b9bd993d5c9493f38611eb211dcc39d8ee90f705b7
+  metadata.gz: 2e07439fc6f681b7664561eb1b60a4e592c9633a4b26c8c5445062193f8fd883d3118e09f85317051ee93dba81e8d80c584704688d6564ff48c32f7c550a1527
+  data.tar.gz: 7e61e51d9302b24aef31e86fc3ce39ef19c0ff13171968393c2ce0a8bc25931b7fbc1a80686f04ec34cc1f950ec447732fced3a8ae8c97f67e76fb4a581cc4eb

data/.gitignore

@@ -17,3 +17,4 @@ legionio.key
 legion.log
 .DS_Store
 .worktrees/
+*.gem

data/CHANGELOG.md

@@ -2,6 +2,32 @@
 
 ## [Unreleased]
 
+## [1.4.3] - 2026-10-29
+
+### Fixed
+- Local cache `set`, `delete`, and `mset` now honor `async: true` using a dedicated, locally configured AsyncWriter.
+- Drain Local async mutations before closing, restarting, or resetting the local pool; preserve synchronous facade fallback writes without double-enqueueing.
+- Reject saturated/stopped async writes without running backend work on the caller; preserve admission order for each key while allowing independent keys to proceed.
+- Interrupt reconnect backoff and stop/join in-flight workers before returning from shutdown; honor `reconnect.enabled`.
+- Preserve atomic connection-state flags across setup, restart, backend failure, fallback, and recovery.
+- Health-check Memcached and Redis before reporting connected; retry failed shared operations against healthy Local and reconnect shared in the background.
+- Rebuild Local after close/reset, honor disabled-cache guards, and preserve explicit endpoint/auth/database configuration on lazy connections and restart.
+- Release Memcached pool checkouts before executing fetch blocks; propagate application exceptions across every fetch path.
+- Preserve computed method results when global-cache writes fail; isolate authenticated caller keys and anonymous method-cache owners.
+- Normalize Memcached insert-if-absent results, preserve batch TTLs, and acknowledge each batch write.
+- Use atomic, bounded CAS for emulated hash updates/deletes to prevent concurrent field loss.
+- Enforce finite positive PHI retention across synchronous/asynchronous writes, batches, insert-if-absent, and CAS.
+- Bound Memory and method-cache fallback storage and reclaim inactive expired entries with managed cleanup workers.
+- Construct Redis Cluster with the supported clustering client; forward TLS and hostname verification to discovered nodes.
+- Apply Redis namespaces to scalar, batch, hash, and sorted-set operations; namespace-only flush reports partial failures without global fallback.
+- Correct README keyword-TTL examples and document admission, ordering, fallback, expiry, and namespace-upgrade behavior.
+- Restore the intentional shared → Local → in-process fallback order for global misses, rejected writes, disabled shared cache, and missing batch entries.
+
+### Changed
+- Require Redis/redis-clustering versions >= 5.4.1 and < 7.0; keep Dalli below 5.0 to retain binary-protocol SASL authentication.
+- Redis namespace enforcement intentionally produces a cold cache for old unprefixed entries; no legacy-key fallback is used.
+- Memory and method-cache fallback default to 10,000 entries with oldest-entry eviction; ordinary zero TTL means no expiration until eviction or clear.
+
 ## [1.4.1] - 2026-04-06
 
 ### Fixed

data/README.md

@@ -2,7 +2,7 @@
 
 Caching wrapper for the [LegionIO](https://github.com/LegionIO/LegionIO) framework. Provides a consistent interface for Memcached (via `dalli`) and Redis (via `redis` gem) with connection pooling. Driver selection is config-driven.
 
-**Version**: 1.3.17
+**Version**: 1.4.3
 
 ## Installation
 
@@ -24,22 +24,38 @@ require 'legion/cache'
 Legion::Cache.setup
 Legion::Cache.connected? # => true
 
-# Memcached driver (default) — TTL is a positional argument, default 180s
-Legion::Cache.set('foobar', 'testing', 10)
-Legion::Cache.get('foobar')    # => 'testing'
-Legion::Cache.fetch('foobar')  # => 'testing' (get with block support)
-Legion::Cache.delete('foobar') # => true
-Legion::Cache.flush            # flush all keys
+# Both drivers use keyword TTLs. Use synchronous writes for read-after-write.
+Legion::Cache.set('foobar', 'testing', ttl: 10, async: false)
+Legion::Cache.get('foobar')                         # => 'testing'
+Legion::Cache.fetch('computed', ttl: 60) { 'value' } # computes only on a miss
+Legion::Cache.set_nx('once', 'first', ttl: 60)       # atomic insert-if-absent
+Legion::Cache.mset({ 'one' => 1, 'two' => 2 }, ttl: 60, async: false)
+Legion::Cache.mget('one', 'two')
+Legion::Cache.delete('foobar', async: false)
 
-# Redis driver — TTL is the third positional argument
-Legion::Cache.set('foobar', 'testing', 10)
-Legion::Cache.get('foobar')    # => 'testing'
-Legion::Cache.delete('foobar') # => true
-Legion::Cache.flush            # flushdb
+# Redis: deletes only this namespace. Memcached: flushes the entire server.
+Legion::Cache.flush
 
 Legion::Cache.shutdown
 ```
 
+### Asynchronous Writes
+
+`set`, `delete`, and `mset` default to `async: true`. A `true` return means the
+mutation was admitted, not that the backend has committed it. A stopped or full
+writer returns `false`; it never executes overflow work on the caller's thread.
+For `mset`, a `false` result can mean partial admission.
+
+Each tier has its own bounded writer. Accepted asynchronous mutations for the
+same key execute in admission order; other keys can execute concurrently.
+Capacity is `async.pool_size + async.queue_size` outstanding operations.
+Synchronous writes bypass the queue and do not act as barriers for earlier
+asynchronous work. Use one mode consistently when ordering matters.
+
+Use `async: false`, `set_sync`, `delete_sync`, or `mset_sync` when the following
+read must observe the write. Shutdown drains accepted work up to the configured
+deadline, then terminates remaining workers before closing the backend.
+
 ## Lite Mode (No Infrastructure)
 
 When `LEGION_MODE=lite` is set, `Legion::Cache` activates the pure in-memory `Memory` adapter, bypassing Redis and Memcached entirely:
@@ -48,15 +64,30 @@ When `LEGION_MODE=lite` is set, `Legion::Cache` activates the pure in-memory `Me
 ENV['LEGION_MODE'] = 'lite'
 Legion::Cache.setup
 Legion::Cache.using_memory?   # => true
-Legion::Cache.set('key', 'value', 60)
+Legion::Cache.set('key', 'value', ttl: 60, async: false)
 Legion::Cache.get('key')      # => 'value'
 ```
 
-The Memory adapter is thread-safe (Mutex), supports TTL expiry, and exposes the same `get`/`set`/`fetch`/`delete`/`flush` interface. Shutdown cleanly tears it down.
+Memory and the method-cache fallback use bounded, mutex-protected storage:
+10,000 entries by default, with oldest-entry eviction. Expired entries are
+reclaimed in the background even when never read again. Cleanup workers stop
+when no expiring entries remain; clearing or closing storage wakes and joins
+them. `Legion::Cache::Memory.setup(max_entries: 1000)` changes Memory's capacity.
 
 ## Two-Tier Cache
 
-Legion::Cache supports a two-tier architecture: a shared remote cluster and a local per-machine cache. If the shared cluster is unreachable at setup, all operations transparently fall back to local.
+Legion::Cache supports a shared remote cache and an independent Local cache.
+Setup performs a backend health check. Every shared miss checks healthy Local
+before reporting a miss; `mget` checks Local only for missing keys. If shared
+setup or a later operation fails with a connection error, the operation is
+retried against Local when `failback_to_local` is enabled. Background
+reconnection returns traffic to shared only after a successful health check.
+Setting `reconnect.enabled` to `false` disables that worker.
+
+Setting `cache.enabled` to `false` disables shared connectivity but leaves a
+healthy, enabled Local cache available through the facade. Set
+`cache_local.enabled` to `false`, or `failback_to_local` to `false`, to prevent
+that fallback.
 
 ```ruby
 # Shared cache connects to remote cluster; Local connects to localhost
@@ -66,12 +97,25 @@ Legion::Cache.local          # => Legion::Cache::Local
 
 # Use Local directly if needed
 Legion::Cache::Local.setup
-Legion::Cache::Local.set('key', 'value', 60)
+Legion::Cache::Local.set('key', 'value', ttl: 60, async: false)
 Legion::Cache::Local.get('key')  # => 'value'
 Legion::Cache::Local.shutdown
 ```
 
-Local uses a separate namespace (`legion_local`) and independent connection pool (pool_size: 5, timeout: 3) so it never collides with the shared tier.
+Local uses its own configuration, namespace (`legion_local`), connection pool
+(size 5, timeout 3 seconds), and default TTL (21,600 seconds). Redis scalar,
+batch, hash, and sorted-set keys all include the selected tier's namespace.
+
+Local `set`, `delete`, and `mset` accept `async:` (default `true`). After setup,
+asynchronous mutations use a dedicated Local writer; pass `async: false` when a
+following read must see the mutation immediately. `set_sync`, `delete_sync`, and
+`mset_sync` are always synchronous. Shared-cache fallback does not enqueue the
+same mutation a second time.
+
+Local shutdown, close, restart, and reset drain pending mutations before
+releasing the driver, up to the configured shutdown timeout. Restart rebuilds
+the driver even after close or reset. Local uses the same overload rejection
+and per-key ordering rules as the shared writer.
 
 ## Configuration
 
@@ -88,11 +132,27 @@ Local uses a separate namespace (`legion_local`) and independent connection pool
   "cache_nils": false,
   "pool_size": 10,
   "timeout": 5,
-  "expires_in": 0
+  "pool_checkout_timeout": 5,
+  "default_ttl": 3600,
+  "expires_in": 0,
+  "failback_to_local": true,
+  "async": {
+    "pool_size": 4,
+    "queue_size": 1000,
+    "shutdown_timeout": 5
+  },
+  "reconnect": {
+    "enabled": true,
+    "initial_delay": 1,
+    "max_delay": 60
+  }
 }
 ```
 
-The driver is auto-detected at load time: prefers `dalli` (Memcached) if available, falls back to `redis`. Override with `"driver": "redis"` and update `servers` to point at your Redis instance.
+These are the `Legion::Settings[:cache]` settings. Driver selection prefers
+`dalli` when installed and otherwise uses `redis`; an explicit `driver` wins.
+Shared pool size defaults to 10 for both drivers. TTLs are seconds; ordinary
+`ttl: 0` disables expiration. Batch writes apply the same TTL as single writes.
 
 ### Driver Names
 
@@ -100,7 +160,15 @@ Supported driver names: `memcached` (or `dalli`), `redis`. All names are normali
 
 ### Server Resolution
 
-Both `server` (singular string) and `servers` (array) are accepted and merged. Default ports are injected per driver when omitted: 11211 for memcached, 6379 for redis. Duplicates are removed.
+Both `server` (a string) and `servers` (an array) are accepted. Missing ports
+default to 11211 for Memcached and 6379 for Redis; duplicates are removed.
+Memcached uses the resolved server list. Standalone Redis uses its first
+endpoint; use `cluster` for Redis Cluster. Redis URLs preserve credentials and
+database selection.
+
+An explicit `server:` or `servers:` passed to setup/restart replaces inherited
+endpoints and clears an inherited cluster unless `cluster:` is also explicit.
+Local settings do not inherit shared credentials, database, cluster, or TLS.
 
 ```json
 {
@@ -115,7 +183,46 @@ Both `server` (singular string) and `servers` (array) are accepted and merged. D
 ### Memcached notes
 
 - `value_max_bytes` defaults to **8MB**. Dalli enforces a 1MB client-side limit by default, which silently rejects large values. This default overrides that. Your Memcached server should also be started with `-I 8m` to match.
-- Redis default pool size is 20; Memcached default pool size is 10.
+- Dalli 3.x and 4.x are supported. Dalli 5 is excluded because it removes the binary protocol and SASL authentication; configure `username` and `password` for SASL-capable servers.
+- `fetch` releases its pooled connection before running application code. Application exceptions propagate unchanged.
+- Hash helpers use bounded CAS retries instead of read/modify/write overwrites, preserving concurrent field updates.
+- Memcached `flush` is server-wide, not namespace-scoped. Do not use it on a server whose other namespaces must be preserved.
+
+### Redis Cluster and TLS
+
+Redis and `redis-clustering` support the 5.4.x and 6.x client families.
+Cluster configuration uses the dedicated `Redis::Cluster` client:
+
+```ruby
+Legion::Settings[:cache].merge!(
+  driver: 'redis',
+  cluster: ['redis://cache-1.example:6380', 'redis://cache-2.example:6380'],
+  namespace: 'legion',
+  tls: { enabled: true, verify: 'peer', ca: '/etc/ssl/cache-ca.pem' }
+)
+Legion::Cache.setup
+```
+
+Configured TLS requires `Legion::Crypt::TLS` to be loaded. CA verification,
+client certificates/keys, and optional `fixed_hostname` settings are forwarded
+to cluster-discovered connections as well as startup nodes. Redis Cluster
+supports database 0 only.
+
+Redis `flush` scans and deletes only the configured namespace, including across
+cluster nodes. Partial scan/deletion failures return failure rather than
+reporting success or falling back to a global flush.
+
+**Upgrade note:** Redis keys now consistently include the namespace. Previously
+unprefixed entries are not migrated or read; expect a cold cache after upgrade.
+
+### PHI Retention
+
+Pass `phi: true` to facade or Memory writes to enforce
+`cache.compliance.phi_max_ttl` (default 3600 seconds). Zero or negative PHI TTL
+requests use the cap; larger TTLs are clamped. Facades apply their tier's
+default when TTL is omitted, bounded by the same cap. The cap itself must be
+finite and positive. This applies to synchronous/asynchronous writes, batches,
+`set_nx`, and `cas`, including Local writes.
 
 ### Local Cache Settings
 
@@ -125,7 +232,12 @@ Both `server` (singular string) and `servers` (array) are accepted and merged. D
   "servers": ["127.0.0.1:11211"],
   "namespace": "legion_local",
   "pool_size": 5,
-  "timeout": 3
+  "timeout": 3,
+  "async": {
+    "pool_size": 4,
+    "queue_size": 1000,
+    "shutdown_timeout": 5
+  }
 }
 ```
 
@@ -139,24 +251,33 @@ Runner modules can use `cache_method` to transparently cache method results with
 module Runners::Presence
   extend Legion::Cache::Cacheable
 
-  cache_method :get_presence, ttl: 300, exclude_from_key: [:token]
+  cache_method :get_presence, ttl: 300
 
-  def get_presence(user_id: 'me', **)
-    conn = graph_connection(**)
+  def get_presence(token:, user_id: 'me', **)
+    conn = graph_connection(token: token, **)
     response = conn.get("#{user_path(user_id)}/presence")
     { availability: response.body['availability'], activity: response.body['activity'] }
   end
 end
 ```
 
-Every caller of `get_presence` gets cached results for 5 minutes. Use `bypass_local_method_cache: true` to force-refresh:
+Results are cached for five minutes per caller identity and arguments. Use `bypass_local_method_cache: true` to force-refresh:
 
 ```ruby
-runner.get_presence(user_id: 'me')                                    # cached
-runner.get_presence(user_id: 'me', bypass_local_method_cache: true)   # fresh
+runner.get_presence(token: token, user_id: 'me')                                  # cached
+runner.get_presence(token: token, user_id: 'me', bypass_local_method_cache: true) # fresh
 ```
 
-Options: `ttl:` (seconds), `scope:` (`:local` or `:global`), `exclude_from_key:` (args to ignore in cache key). Falls back to in-memory store when no cache backend is available.
+Options: `ttl:` (seconds), `scope:` (`:local` or `:global`), and
+`exclude_from_key:` (arguments to ignore). Authentication `token` values always
+contribute to the SHA-256 key digest, even if listed for exclusion; plaintext
+tokens never appear in cache keys. Anonymous modules have distinct identities.
+
+Global method-cache reads and writes use the same order: shared cache, then
+healthy Local, then bounded in-process storage. Cache failures do not replace a
+successfully computed method result with an exception; application exceptions
+still propagate. Ordinary zero TTL means no expiration, subject to capacity
+eviction.
 
 ## Pool API
 
@@ -171,7 +292,8 @@ Legion::Cache.shutdown    # close pool and mark disconnected
 ## Requirements
 
 - Ruby >= 3.4
-- Memcached or Redis server
+- Memcached or Redis server, unless using lite mode
+- Dalli >= 3.0 and < 5.0; Redis and redis-clustering >= 5.4.1 and < 7.0
 
 ## License
 

data/legion-cache.gemspec

@@ -28,8 +28,9 @@ Gem::Specification.new do |spec|
 
   spec.add_dependency 'concurrent-ruby', '>= 1.2'
   spec.add_dependency 'connection_pool', '>= 2.4'
-  spec.add_dependency 'dalli', '>= 3.0'
+  spec.add_dependency 'dalli', '>= 3.0', '< 5.0'
   spec.add_dependency 'legion-logging', '>= 1.5.0'
   spec.add_dependency 'legion-settings', '>= 1.3.12'
-  spec.add_dependency 'redis', '>= 5.0'
+  spec.add_dependency 'redis', '>= 5.4.1', '< 7.0'
+  spec.add_dependency 'redis-clustering', '>= 5.4.1', '< 7.0'
 end

data/lib/legion/cache/async_writer.rb

@@ -19,73 +19,91 @@ module Legion
         @config_shutdown_timeout = shutdown_timeout
         @processed = Concurrent::AtomicFixnum.new(0)
         @failed = Concurrent::AtomicFixnum.new(0)
-        @executor = nil
         @mutex = Mutex.new
+        @lifecycle_mutex = Mutex.new
+        @ready = ConditionVariable.new
+        @workers = []
+        @queue = []
+        @active_keys = {}
+        @outstanding = 0
+        @capacity = 0
+        @running = false
       end
 
       def start(pool_size: nil, queue_size: nil, **)
-        @mutex.synchronize do
+        @lifecycle_mutex.synchronize do
           return if running?
 
           ps = pool_size || @config_pool_size || configured_pool_size
           qs = queue_size || @config_queue_size || configured_queue_size
+          raise ArgumentError, 'pool_size must be a positive integer' unless ps.is_a?(Integer) && ps.positive?
+          raise ArgumentError, 'queue_size must be a nonnegative integer' unless qs.is_a?(Integer) && qs >= 0
 
-          @executor = Concurrent::ThreadPoolExecutor.new(
-            min_threads:     1,
-            max_threads:     ps,
-            max_queue:       qs,
-            fallback_policy: :caller_runs
-          )
+          @mutex.synchronize do
+            @capacity = ps + qs
+            @running = true
+            @workers = Array.new(ps) { Thread.new { work } }
+          end
           log.info "Legion::Cache::AsyncWriter started pool_size=#{ps} queue_size=#{qs}"
         end
       end
 
       def stop(timeout: nil)
-        @mutex.synchronize do
-          return unless @executor
+        @lifecycle_mutex.synchronize do
+          workers = @mutex.synchronize do
+            return if @workers.empty?
 
+            @running = false
+            @ready.broadcast
+            @workers.dup
+          end
           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"
+          deadline = ::Process.clock_gettime(::Process::CLOCK_MONOTONIC) + to
+          workers.each do |worker|
+            remaining = deadline - ::Process.clock_gettime(::Process::CLOCK_MONOTONIC)
+            worker.join(remaining) if remaining.positive?
+          end
+          unfinished = workers.select(&:alive?)
+          unfinished.each(&:kill)
+          workers.each(&:join)
+          @mutex.synchronize do
+            @workers.clear
+            @queue.clear
+            @active_keys.clear
+            @outstanding = 0
+            @capacity = 0
           end
+          log.warn "Legion::Cache::AsyncWriter force-killed after #{to}s timeout" unless unfinished.empty?
           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
+      # Admission includes running and waiting jobs, bounded by pool_size + queue_size.
+      # A nil key is independent work; equal non-nil keys execute in submission order.
+      def enqueue(key: nil, &block)
+        raise ArgumentError, 'a job block is required' unless block
+
+        @mutex.synchronize do
+          return false unless @running && @outstanding < @capacity
+
+          key = key.dup.freeze if key.is_a?(String)
+          @queue << [key, block]
+          @outstanding += 1
+          @ready.signal
+          true
         end
       end
 
       def running?
-        @executor&.running? == true
+        @mutex.synchronize { @running }
       end
 
       def pool_size
-        @executor&.max_length || 0
+        @mutex.synchronize { @workers.size }
       end
 
       def queue_depth
-        @executor&.queue_length || 0
+        @mutex.synchronize { @queue.size }
       end
 
       def processed_count
@@ -98,6 +116,40 @@ module Legion
 
       private
 
+      def work
+        loop do
+          job = @mutex.synchronize do
+            loop do
+              index = @queue.index { |key, _block| key.nil? || !@active_keys.key?(key) }
+              if index
+                next_job = @queue.delete_at(index)
+                @active_keys[next_job.first] = true unless next_job.first.nil?
+                break next_job
+              end
+              return unless @running || !@queue.empty?
+
+              @ready.wait(@mutex)
+            end
+          end
+          perform_job(job)
+        end
+      end
+
+      def perform_job(job)
+        key, block = job
+        block.call
+        @processed.increment
+      rescue StandardError => e
+        @failed.increment
+        handle_exception(e, level: :warn, handled: true, operation: :async_writer_job)
+      ensure
+        @mutex.synchronize do
+          @active_keys.delete(key) unless key.nil?
+          @outstanding -= 1
+          @ready.broadcast
+        end
+      end
+
       def configured_pool_size
         return DEFAULT_POOL_SIZE unless defined?(Legion::Settings)
 

data/lib/legion/cache/cacheable.rb

@@ -1,7 +1,9 @@
 # frozen_string_literal: true
 
 require 'digest'
+require 'securerandom'
 require 'legion/logging/helper'
+require 'legion/cache/memory'
 
 module Legion
   module Cache
@@ -10,8 +12,11 @@ module Legion
 
       LOCAL_CACHE_MISS = Object.new
 
+      @memory_store = Legion::Cache::ExpiringStore.new
+
       def self.extended(base)
         base.instance_variable_set(:@cached_methods, {})
+        base.instance_variable_set(:@cache_identity, "Anonymous:#{SecureRandom.uuid}")
       end
 
       def cached_methods
@@ -19,10 +24,10 @@ module Legion
       end
 
       def cache_method(method_name, ttl:, scope: :local, exclude_from_key: [])
-        exclude_from_key |= %i[token bypass_local_method_cache]
+        exclude_from_key = (exclude_from_key - [:token, 'token']) | [:bypass_local_method_cache]
         cached_methods[method_name] = { ttl: ttl, scope: scope, exclude_from_key: exclude_from_key }
 
-        mod_name = name || 'Anonymous'
+        mod_name = name || @cache_identity
         config = cached_methods[method_name]
 
         wrapper = Module.new do
@@ -51,39 +56,20 @@ module Legion
       end
 
       def self.build_cache_key(mod_name, method_name, exclude:, **kwargs)
-        filtered = kwargs.except(*exclude)
-        args_hash = Digest::MD5.hexdigest(filtered.sort.to_s)
+        filtered = kwargs.except(*(exclude - [:token, 'token']))
+        args_hash = Digest::SHA256.hexdigest(filtered.sort.to_s)
         "#{mod_name}.#{method_name}.#{args_hash}"
       end
 
       def self.cache_read(key, scope:)
-        case scope
-        when :global
-          return Legion::Cache.get(key) if global_cache_available?
-
-          memory_read(key)
-        else
-          result = local_cache_read(key)
-          result.equal?(LOCAL_CACHE_MISS) ? memory_read(key) : result
-        end
+        result = scope == :global ? global_cache_read(key) : local_cache_read(key)
+        result.equal?(LOCAL_CACHE_MISS) ? memory_read(key) : result
       end
 
       def self.cache_write(key, value, ttl:, scope:)
-        case scope
-        when :global
-          if global_cache_available?
-            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: ttl)
-            memory_write(key, value, ttl) unless result
-          else
-            memory_write(key, value, ttl)
-          end
-        end
+        result = scope == :global ? global_cache_write(key, value, ttl: ttl) : local_cache_write(key, value, ttl: ttl)
+        result ||= local_cache_write(key, value, ttl: ttl) if scope == :global
+        memory_write(key, value, ttl) unless result
       end
 
       def self.global_cache_available?
@@ -94,6 +80,25 @@ module Legion
         defined?(Legion::Cache::Local) && Legion::Cache::Local.respond_to?(:connected?) && Legion::Cache::Local.connected?
       end
 
+      def self.global_cache_read(key)
+        result = Legion::Cache.get(key) if global_cache_available?
+        return result unless result.nil?
+
+        local_cache_read(key)
+      rescue StandardError => e
+        handle_exception(e, level: :warn, operation: :global_cache_read, key: key)
+        local_cache_read(key)
+      end
+
+      def self.global_cache_write(key, value, ttl:)
+        return unless global_cache_available?
+
+        Legion::Cache.set(key, value, ttl: ttl, async: false)
+      rescue StandardError => e
+        handle_exception(e, level: :warn, operation: :global_cache_write, key: key, ttl: ttl)
+        nil
+      end
+
       def self.local_cache_read(key)
         return LOCAL_CACHE_MISS unless local_cache_available?
 
@@ -115,23 +120,19 @@ module Legion
 
       # In-memory fallback store (class-level, process-wide)
       def self.memory_store
-        @memory_store ||= {}
+        @memory_store
       end
 
       def self.memory_read(key)
-        entry = memory_store[key]
-        return nil unless entry
-        return nil if Time.now.utc > entry[:expires_at]
-
-        entry[:value]
+        memory_store.get(key)
       end
 
       def self.memory_write(key, value, ttl)
-        memory_store[key] = { value: value, expires_at: Time.now.utc + ttl }
+        memory_store.set(key, value, ttl: ttl)
       end
 
       def self.memory_clear!
-        @memory_store = {}
+        memory_store.clear
       end
     end
   end