legion-cache 1.3.21 → 1.4.1

data/lib/legion/cache.rb

@@ -10,33 +10,77 @@ require 'legion/cache/redis'
 require 'legion/cache/redis_hash'
 require 'legion/cache/memory'
 require 'legion/cache/local'
+require 'legion/cache/async_writer'
+require 'legion/cache/reconnector'
+require 'concurrent'
 require 'legion/cache/helper'
 
 module Legion
   module Cache
     extend Legion::Logging::Helper
 
+    @async_writer = Legion::Cache::AsyncWriter.new(settings_key: :cache)
+    @connected = Concurrent::AtomicBoolean.new(false)
+    @using_local = Concurrent::AtomicBoolean.new(false)
+    @using_memory = Concurrent::AtomicBoolean.new(false)
+
     class << self
       include Legion::Logging::Helper
 
+      def enabled?
+        return true unless defined?(Legion::Settings)
+
+        Legion::Settings.dig(:cache, :enabled) != false
+      rescue StandardError => e
+        handle_exception(e, level: :warn, handled: true, operation: :cache_enabled)
+        true
+      end
+
       def connected?
-        @connected == true
+        @connected&.true? || false
       end
 
       def driver_name
-        return 'memory' if @using_memory
-        return 'local' if @using_local
+        return 'memory' if using_memory?
+        return 'local' if using_local?
 
         @active_shared_driver || configured_shared_driver
       end
 
+      def stats
+        {
+          driver:             driver_name,
+          servers:            resolved_servers,
+          enabled:            enabled?,
+          connected:          connected?,
+          using_local:        using_local?,
+          using_memory:       using_memory?,
+          pool_size:          safe_pool_size,
+          pool_available:     safe_pool_available,
+          async_pool_size:    async_writer_pool_size,
+          async_queue_depth:  async_writer_queue_depth,
+          async_processed:    async_writer_processed_count,
+          async_failed:       async_writer_failed_count,
+          reconnect_attempts: reconnector_attempts,
+          uptime:             uptime_seconds
+        }.freeze
+      rescue StandardError => e
+        handle_exception(e, level: :warn, handled: true, operation: :cache_stats)
+        { error: e.message }.freeze
+      end
+
       def setup(**)
+        return unless enabled?
         return Legion::Settings[:cache][:connected] = true if connected?
 
+        @setup_at = Time.now
+
+        async_writer.start
+
         if ENV['LEGION_MODE'] == 'lite'
           Legion::Cache::Memory.setup
-          @using_memory = true
-          @connected = true
+          @using_memory.make_true
+          @connected.make_true
           Legion::Settings[:cache][:connected] = true
           log.info 'Legion::Cache using in-memory adapter (lite mode)'
           return
@@ -49,15 +93,20 @@ module Legion
 
       def shutdown
         log.info 'Shutting down Legion::Cache'
-        if @using_memory
+        # 1. Drain async writer FIRST (while pool is still alive)
+        async_writer.stop(timeout: configured_shutdown_timeout)
+        # 2. Stop reconnector
+        stop_reconnector
+        # 3. Now close pools
+        if using_memory?
           Legion::Cache::Memory.shutdown
         else
-          close unless @using_local
+          close unless using_local?
           Legion::Cache::Local.shutdown if Legion::Cache::Local.connected?
         end
-        @using_local = false
-        @using_memory = false
-        @connected = false
+        @using_local.make_false
+        @using_memory.make_false
+        @connected.make_false
         Legion::Settings[:cache][:connected] = false
       end
 
@@ -65,44 +114,53 @@ module Legion
         Legion::Cache::Local
       end
 
+      def pool
+        @client
+      end
+
       def using_local?
-        @using_local == true
+        @using_local&.true? || false
       end
 
       def using_memory?
-        @using_memory == true
+        @using_memory&.true? || false
       end
 
       def client(**opts)
         if ENV['LEGION_MODE'] == 'lite'
           Legion::Cache::Memory.setup unless Legion::Cache::Memory.connected?
-          @using_memory = true
-          @using_local = false
-          @connected = true
+          @using_memory.make_true
+          @using_local.make_false
+          @connected.make_true
           @active_shared_driver = nil
           Legion::Settings[:cache][:connected] = true if defined?(Legion::Settings)
           return Legion::Cache::Memory.client
         end
 
         configure_shared_adapter!(opts[:driver])
-        @using_memory = false
-        @using_local = false
+        @using_memory.make_false
+        @using_local.make_false
         result = super
-        @connected = true
+        # super (Pool) sets @connected to a plain boolean; restore AtomicBoolean
+        @connected = Concurrent::AtomicBoolean.new(true)
         Legion::Settings[:cache][:connected] = true if defined?(Legion::Settings)
         result
       rescue StandardError
-        @connected = false
+        @connected = Concurrent::AtomicBoolean.new(false)
         Legion::Settings[:cache][:connected] = false if defined?(Legion::Settings)
         raise
       end
 
       def get(key)
-        return Legion::Cache::Memory.get(key) if @using_memory
-        return Legion::Cache::Local.get(key) if @using_local
+        return Legion::Cache::Memory.get(key) if using_memory?
+        return Legion::Cache::Local.get(key) if using_local?
+        return Legion::Cache::Local.get(key) if failback_to_local?
 
         configure_shared_adapter!
         super
+      rescue StandardError => e
+        handle_exception(e, level: :warn, handled: true, operation: :cache_get, key: key)
+        nil
       end
 
       def phi_max_ttl
@@ -121,35 +179,57 @@ module Legion
         [ttl, max].min
       end
 
-      def set(key, value, ttl = nil, **opts)
-        ttl = opts.delete(:ttl) || ttl || 180
-        effective_ttl = enforce_phi_ttl(ttl, **opts)
-        return Legion::Cache::Memory.set(key, value, effective_ttl) if @using_memory
-        return Legion::Cache::Local.set(key, value, effective_ttl) if @using_local
+      def set(key, value, ttl: nil, async: true, phi: false)
+        effective_ttl = resolve_ttl(ttl, phi: phi)
+
+        if async && async_writer.running?
+          async_writer.enqueue { set_internal(key, value, ttl: effective_ttl) }
+          true
+        else
+          set_internal(key, value, ttl: effective_ttl)
+        end
+      end
+
+      def set_sync(key, value, ttl: nil, **)
+        return Legion::Cache::Memory.set_sync(key, value, ttl: ttl) if using_memory?
+        return Legion::Cache::Local.set_sync(key, value, ttl: ttl) if using_local?
+        return Legion::Cache::Local.set_sync(key, value, ttl: ttl) if failback_to_local?
 
         configure_shared_adapter!
-        super(key, value, effective_ttl)
+        super
       end
 
-      def fetch(key, ttl = nil, &)
-        return Legion::Cache::Memory.fetch(key, ttl, &) if @using_memory
-        return Legion::Cache::Local.fetch(key, ttl, &) if @using_local
+      def fetch(key, ttl: nil, &)
+        return Legion::Cache::Memory.fetch(key, ttl: ttl, &) if using_memory?
+        return Legion::Cache::Local.fetch(key, ttl: ttl, &) if using_local?
+        return Legion::Cache::Local.fetch(key, ttl: ttl, &) if failback_to_local?
 
         configure_shared_adapter!
         super
       end
 
-      def delete(key)
-        return Legion::Cache::Memory.delete(key) if @using_memory
-        return Legion::Cache::Local.delete(key) if @using_local
+      def delete(key, async: true)
+        if async && async_writer.running?
+          async_writer.enqueue { delete_internal(key) }
+          true
+        else
+          delete_internal(key)
+        end
+      end
+
+      def delete_sync(key)
+        return Legion::Cache::Memory.delete_sync(key) if using_memory?
+        return Legion::Cache::Local.delete_sync(key) if using_local?
+        return Legion::Cache::Local.delete_sync(key) if failback_to_local?
 
         configure_shared_adapter!
         super
       end
 
-      def flush(delay = 0)
-        return Legion::Cache::Memory.flush(delay) if @using_memory
-        return Legion::Cache::Local.flush(delay) if @using_local
+      def flush
+        return Legion::Cache::Memory.flush if using_memory?
+        return Legion::Cache::Local.flush if using_local?
+        return Legion::Cache::Local.flush if failback_to_local?
 
         configure_shared_adapter!
         super
@@ -158,35 +238,48 @@ module Legion
       def mget(*keys)
         keys = keys.flatten
         return {} if keys.empty?
-        return keys.to_h { |key| [key, Legion::Cache::Memory.get(key)] } if @using_memory
-        return local_mget(*keys) if @using_local
+        return keys.to_h { |key| [key, Legion::Cache::Memory.get(key)] } if using_memory?
+        return Legion::Cache::Local.mget(*keys) if using_local?
+        return Legion::Cache::Local.mget(*keys) if failback_to_local?
 
         configure_shared_adapter!
         super
       end
 
-      def mset(hash)
+      def mset(hash, ttl: nil, async: true)
         return true if hash.empty?
-        return hash.each { |key, value| Legion::Cache::Memory.set(key, value) } && true if @using_memory
-        return local_mset(hash) if @using_local
+
+        if async && async_writer.running?
+          async_writer.enqueue { mset_internal(hash, ttl: ttl) }
+          true
+        else
+          mset_internal(hash, ttl: ttl)
+        end
+      end
+
+      def mset_sync(hash, ttl: nil, **)
+        return true if hash.empty?
+        return hash.each { |key, value| Legion::Cache::Memory.set_sync(key, value, ttl: ttl) } && true if using_memory?
+        return Legion::Cache::Local.mset(hash, ttl: ttl) if using_local?
+        return Legion::Cache::Local.mset(hash, ttl: ttl) if failback_to_local?
 
         configure_shared_adapter!
         super
       end
 
       def close
-        if @using_memory
+        if using_memory?
           Legion::Cache::Memory.shutdown
-          @using_memory = false
-          @connected = false
+          @using_memory.make_false
+          @connected.make_false
           Legion::Settings[:cache][:connected] = false if defined?(Legion::Settings)
           return false
         end
 
-        if @using_local
+        if using_local?
           Legion::Cache::Local.close
-          @using_local = false
-          @connected = false
+          @using_local.make_false
+          @connected.make_false
           Legion::Settings[:cache][:connected] = false if defined?(Legion::Settings)
           return false
         end
@@ -195,48 +288,48 @@ module Legion
 
         configure_shared_adapter!
         result = super
-        @connected = false
+        @connected = Concurrent::AtomicBoolean.new(false)
         Legion::Settings[:cache][:connected] = false if defined?(Legion::Settings)
         result
       end
 
       def restart(**opts)
         configure_shared_adapter!(opts[:driver])
-        @using_memory = false
-        @using_local = false
+        @using_memory.make_false
+        @using_local.make_false
         result = super
-        @connected = true
+        @connected = Concurrent::AtomicBoolean.new(true)
         Legion::Settings[:cache][:connected] = true if defined?(Legion::Settings)
         result
       end
 
       def size
-        return Legion::Cache::Memory.size if @using_memory
-        return Legion::Cache::Local.size if @using_local
+        return Legion::Cache::Memory.size if using_memory?
+        return Legion::Cache::Local.size if using_local?
 
         configure_shared_adapter!
         super
       end
 
       def available
-        return Legion::Cache::Memory.available if @using_memory
-        return Legion::Cache::Local.available if @using_local
+        return Legion::Cache::Memory.available if using_memory?
+        return Legion::Cache::Local.available if using_local?
 
         configure_shared_adapter!
         super
       end
 
       def pool_size
-        return Legion::Cache::Memory.size if @using_memory
-        return Legion::Cache::Local.pool_size if @using_local
+        return Legion::Cache::Memory.size if using_memory?
+        return Legion::Cache::Local.pool_size if using_local?
 
         configure_shared_adapter!
         super
       end
 
       def timeout
-        return 0 if @using_memory
-        return Legion::Cache::Local.timeout if @using_local
+        return 0 if using_memory?
+        return Legion::Cache::Local.timeout if using_local?
 
         configure_shared_adapter!
         super
@@ -244,6 +337,64 @@ module Legion
 
       private
 
+      def async_writer
+        Legion::Cache.instance_variable_get(:@async_writer)
+      end
+
+      def set_internal(key, value, ttl: nil)
+        return Legion::Cache::Memory.set(key, value, ttl: ttl) if using_memory?
+        return Legion::Cache::Local.set(key, value, ttl: ttl) if using_local?
+        return Legion::Cache::Local.set(key, value, ttl: ttl) if failback_to_local?
+
+        configure_shared_adapter!
+        set_sync(key, value, ttl: ttl)
+      end
+
+      def delete_internal(key)
+        return Legion::Cache::Memory.delete(key) if using_memory?
+        return Legion::Cache::Local.delete(key) if using_local?
+        return Legion::Cache::Local.delete(key) if failback_to_local?
+
+        configure_shared_adapter!
+        delete_sync(key)
+      end
+
+      def mset_internal(hash, ttl: nil)
+        return hash.each { |key, value| Legion::Cache::Memory.set(key, value, ttl: ttl) } && true if using_memory?
+        return Legion::Cache::Local.mset(hash, ttl: ttl) if using_local?
+        return Legion::Cache::Local.mset(hash, ttl: ttl) if failback_to_local?
+
+        configure_shared_adapter!
+        mset_sync(hash, ttl: ttl)
+      end
+
+      def failback_to_local?
+        return false unless Legion::Cache::Local.connected?
+
+        setting = if defined?(Legion::Settings)
+                    Legion::Settings.dig(:cache, :failback_to_local) != false
+                  else
+                    true
+                  end
+        setting && (!enabled? || !connected?)
+      rescue StandardError => e
+        handle_exception(e, level: :warn, handled: true, operation: :cache_failback_check)
+        false
+      end
+
+      def resolve_ttl(ttl, phi: false)
+        effective = ttl || default_ttl
+        enforce_phi_ttl(effective, phi: phi)
+      end
+
+      def default_ttl
+        return 3600 unless defined?(Legion::Settings)
+
+        Legion::Settings.dig(:cache, :default_ttl) || 3600
+      rescue StandardError
+        3600
+      end
+
       def setup_local
         return if Legion::Cache::Local.connected?
 
@@ -254,8 +405,8 @@ module Legion
 
       def setup_shared(**)
         client(**Legion::Settings[:cache], logger: log, **)
-        @connected = true
-        @using_local = false
+        @connected.make_true
+        @using_local.make_false
         Legion::Settings[:cache][:connected] = true
         driver = Legion::Settings[:cache][:driver] || 'dalli'
         servers = Array(Legion::Settings[:cache][:servers]).join(', ')
@@ -263,15 +414,24 @@ module Legion
       rescue StandardError => e
         report_exception(e, level: :warn, handled: true, operation: :setup_shared, fallback: :local)
         if Legion::Cache::Local.connected?
-          @using_local = true
-          @connected = true
+          @using_local.make_true
+          @connected.make_true
           Legion::Settings[:cache][:connected] = true
           log.info 'Legion::Cache fell back to Local cache'
         else
-          @connected = false
+          @connected.make_false
           Legion::Settings[:cache][:connected] = false
           log.error 'Legion::Cache shared and local adapters are unavailable'
         end
+        start_reconnector if enabled?
+      end
+
+      def reconnect_shared!
+        client(**Legion::Settings[:cache], logger: log)
+        @connected.make_true
+        @using_local.make_false
+        Legion::Settings[:cache][:connected] = true
+        log.info 'Legion::Cache shared reconnected'
       end
 
       def report_exception(exception, level:, handled:, **)
@@ -317,16 +477,96 @@ module Legion
         handle_exception(e, level: :warn, handled: true, operation: :cache_close_existing_shared_client)
       ensure
         @client = nil
-        @connected = false
+        @connected = Concurrent::AtomicBoolean.new(false)
+      end
+
+      def resolved_servers
+        return [] if using_memory?
+
+        Array(Legion::Settings.dig(:cache, :servers))
+      rescue StandardError
+        []
       end
 
-      def local_mget(*keys)
-        keys.to_h { |key| [key, Legion::Cache::Local.get(key)] }
+      def safe_pool_size
+        return 1 if using_memory?
+        return 0 unless connected?
+
+        pool_size
+      rescue StandardError
+        0
       end
 
-      def local_mset(hash)
-        hash.each { |key, value| Legion::Cache::Local.set(key, value) }
-        true
+      def safe_pool_available
+        return 1 if using_memory?
+        return 0 unless connected?
+
+        available
+      rescue StandardError
+        0
+      end
+
+      def async_writer_pool_size
+        async_writer.pool_size
+      rescue StandardError
+        0
+      end
+
+      def async_writer_queue_depth
+        async_writer.queue_depth
+      rescue StandardError
+        0
+      end
+
+      def async_writer_processed_count
+        async_writer.processed_count
+      rescue StandardError
+        0
+      end
+
+      def configured_shutdown_timeout
+        return 5 unless defined?(Legion::Settings)
+
+        Legion::Settings.dig(:cache, :async, :shutdown_timeout) || 5
+      rescue StandardError
+        5
+      end
+
+      def async_writer_failed_count
+        async_writer.failed_count
+      rescue StandardError
+        0
+      end
+
+      def reconnector_attempts
+        @reconnector&.attempts || 0
+      end
+
+      def start_reconnector
+        return unless enabled?
+
+        stop_reconnector
+        @reconnector = Legion::Cache::Reconnector.new(
+          tier:          :shared,
+          connect_block: -> { reconnect_shared! },
+          enabled_block: -> { enabled? },
+          settings_key:  :cache
+        )
+        @reconnector.start
+        log.info 'Legion::Cache started background reconnector for shared tier'
+      end
+
+      def stop_reconnector
+        @reconnector&.stop
+        @reconnector = nil
+      end
+
+      def uptime_seconds
+        return 0 unless @setup_at
+
+        (Time.now - @setup_at).to_i
+      rescue StandardError
+        0
       end
     end
   end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: legion-cache
 version: !ruby/object:Gem::Version
-  version: 1.3.21
+  version: 1.4.1
 platform: ruby
 authors:
 - Esity
@@ -9,6 +9,20 @@ bindir: bin
 cert_chain: []
 date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
+- !ruby/object:Gem::Dependency
+  name: concurrent-ruby
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.2'
 - !ruby/object:Gem::Dependency
   name: connection_pool
   requirement: !ruby/object:Gem::Requirement
@@ -102,12 +116,14 @@ files:
 - README.md
 - legion-cache.gemspec
 - lib/legion/cache.rb
+- lib/legion/cache/async_writer.rb
 - lib/legion/cache/cacheable.rb
 - lib/legion/cache/helper.rb
 - lib/legion/cache/local.rb
 - lib/legion/cache/memcached.rb
 - lib/legion/cache/memory.rb
 - lib/legion/cache/pool.rb
+- lib/legion/cache/reconnector.rb
 - lib/legion/cache/redis.rb
 - lib/legion/cache/redis_hash.rb
 - lib/legion/cache/settings.rb