legion-cache 1.3.20 → 1.3.21

data/lib/legion/cache/pool.rb

@@ -1,11 +1,13 @@
 # frozen_string_literal: true
 
 require 'connection_pool'
+require 'legion/logging/helper'
 
 module Legion
   module Cache
     module Pool
-      extend self # rubocop:disable Style/ModuleFunction
+      extend self
+      extend Legion::Logging::Helper
 
       def connected?
         @connected ||= false
@@ -28,10 +30,12 @@ module Legion
       end
 
       def close
-        client.shutdown(&:close)
+        return unless @client
+
+        @client.shutdown(&:close)
         @client = nil
         @connected = false
-        Legion::Logging.info "#{name} pool closed" if defined?(Legion::Logging)
+        log.info "#{pool_log_name} pool closed"
       end
 
       def restart(**opts)
@@ -42,7 +46,26 @@ module Legion
         client_hash[:timeout] = opts[:timeout] if opts.key? :timeout
         client(**client_hash)
         @connected = true
-        Legion::Logging.info "#{name} pool restarted" if defined?(Legion::Logging)
+        log.info "#{pool_log_name} pool restarted"
+      end
+
+      private
+
+      def pool_log_name
+        if respond_to?(:name)
+          label = name.to_s
+          return label unless label.empty? || label.start_with?('#<')
+        end
+
+        segments = if instance_variable_defined?(:@component_logger) && @component_logger.respond_to?(:segments)
+                     Array(@component_logger.segments)
+                   elsif log.respond_to?(:segments)
+                     Array(log.segments)
+                   else
+                     []
+                   end
+
+        segments.empty? ? 'cache.pool' : segments.join('.')
       end
     end
   end

data/lib/legion/cache/redis.rb

@@ -2,6 +2,7 @@
 
 require 'openssl'
 require 'redis'
+require 'legion/logging/helper'
 require 'legion/cache/pool'
 require 'legion/cache/settings'
 
@@ -10,14 +11,17 @@ module Legion
     module Redis
       include Legion::Cache::Pool
       extend self
+      extend Legion::Logging::Helper
 
       def client(pool_size: 20, timeout: 5, server: nil, servers: [], cluster: nil, replica: false, # rubocop:disable Metrics/ParameterLists
+                 logger: nil,
                  fixed_hostname: nil, username: nil, password: nil, db: nil, reconnect_attempts: [0, 0.5, 1], **)
         return @client unless @client.nil?
 
         @pool_size = pool_size
         @timeout   = timeout
         @cluster_mode = Array(cluster).compact.any?
+        @component_logger = logger || log
 
         @client = ConnectionPool.new(size: pool_size, timeout: timeout) do
           build_redis_client(server: server, servers: servers, cluster: cluster,
@@ -26,8 +30,13 @@ module Legion
                              reconnect_attempts: reconnect_attempts)
         end
         @connected = true
-        Legion::Logging.info "Redis connected to #{resolved_redis_address(server: server, servers: servers, cluster: cluster)}" if defined?(Legion::Logging)
+        cache_logger.info "Redis connected to #{resolved_redis_address(server: server, servers: servers, cluster: cluster)}"
         @client
+      rescue StandardError => e
+        handle_exception(e, level: :error, handled: false, operation: :redis_client,
+                            server: server, servers: Array(servers), cluster_nodes: Array(cluster))
+        @connected = false
+        raise
       end
 
       def build_redis_client(server: nil, servers: [], cluster: nil, replica: false, fixed_hostname: nil, # rubocop:disable Metrics/ParameterLists
@@ -44,7 +53,7 @@ module Legion
           resolved = Legion::Cache::Settings.resolve_servers(
             driver: 'redis', server: server, servers: servers
           )
-          host, port = resolved.first.split(':')
+          host, port = Legion::Cache::Settings.parse_server_address(resolved.first, default_port: 6379)
           redis_opts = { host: host, port: port.to_i, reconnect_attempts: reconnect_attempts,
                          timeout: @timeout }
           redis_opts[:username] = username unless username.nil?
@@ -61,31 +70,39 @@ module Legion
 
       def get(key)
         result = client.with { |conn| conn.get(key) }
-        Legion::Logging.debug "[cache] GET #{key} hit=#{!result.nil?}" if defined?(Legion::Logging)
+        cache_logger.debug "[cache] GET #{key} hit=#{!result.nil?}"
         result
       rescue ::Redis::BaseError => e
-        log_cluster_error(e)
+        log_cluster_error('redis_get', e, key: key)
         raise
       end
-      alias fetch get
+
+      def fetch(key, ttl = nil)
+        result = get(key)
+        return result unless result.nil? && block_given?
+
+        result = yield
+        set(key, result, ttl)
+        result
+      end
 
       def set(key, value, ttl = nil)
         args = {}
         args[:ex] = ttl unless ttl.nil?
         result = client.with { |conn| conn.set(key, value, **args) == 'OK' }
-        Legion::Logging.debug "[cache] SET #{key} ttl=#{ttl.inspect} success=#{result}" if defined?(Legion::Logging)
+        cache_logger.debug "[cache] SET #{key} ttl=#{ttl.inspect} success=#{result}"
         result
       rescue ::Redis::BaseError => e
-        log_cluster_error(e)
+        log_cluster_error('redis_set', e, key: key, ttl: ttl)
         raise
       end
 
       def delete(key)
         result = client.with { |conn| conn.del(key) == 1 }
-        Legion::Logging.debug "[cache] DELETE #{key} success=#{result}" if defined?(Legion::Logging)
+        cache_logger.debug "[cache] DELETE #{key} success=#{result}"
         result
       rescue ::Redis::BaseError => e
-        log_cluster_error(e)
+        log_cluster_error('redis_delete', e, key: key)
         raise
       end
 
@@ -97,10 +114,10 @@ module Legion
             conn.flushdb == 'OK'
           end
         end
-        Legion::Logging.debug '[cache] FLUSH completed' if defined?(Legion::Logging)
+        cache_logger.debug '[cache] FLUSH completed'
         result
       rescue ::Redis::BaseError => e
-        log_cluster_error(e)
+        log_cluster_error('redis_flush', e)
         raise
       end
 
@@ -116,10 +133,10 @@ module Legion
             keys.zip(values).to_h
           end
         end
-        Legion::Logging.debug "[cache] MGET keys=#{keys.size}" if defined?(Legion::Logging)
+        cache_logger.debug "[cache] MGET keys=#{keys.size}"
         result
       rescue ::Redis::BaseError => e
-        log_cluster_error(e)
+        log_cluster_error('redis_mget', e, key_count: keys.size)
         raise
       end
 
@@ -133,15 +150,19 @@ module Legion
             conn.mset(*hash.flatten) == 'OK'
           end
         end
-        Legion::Logging.debug "[cache] MSET keys=#{hash.size}" if defined?(Legion::Logging)
+        cache_logger.debug "[cache] MSET keys=#{hash.size}"
         result
       rescue ::Redis::BaseError => e
-        log_cluster_error(e)
+        log_cluster_error('redis_mset', e, key_count: hash.size)
         raise
       end
 
       private
 
+      def cache_logger
+        @component_logger || log
+      end
+
       def cluster_mget(conn, keys)
         groups = group_keys_by_slot(keys)
         result = {}
@@ -165,14 +186,14 @@ module Legion
         node_info = conn.cluster('nodes')
         primaries = node_info.lines.select { |l| l.include?('master') }.map { |l| l.split[1].split('@').first }
         primaries.each do |addr|
-          host, port = addr.split(':')
+          host, port = Legion::Cache::Settings.parse_server_address(addr, default_port: 6379)
           node = ::Redis.new(host: host, port: port.to_i)
           node.flushdb
           node.close
         end
         true
       rescue StandardError => e
-        Legion::Logging.warn("Redis#cluster_flush cluster node flush failed, falling back to single flushdb: #{e.message}") if defined?(Legion::Logging)
+        handle_exception(e, level: :warn, handled: true, operation: :cluster_flush, fallback: :single_flushdb)
         conn.flushdb == 'OK'
       end
 
@@ -190,14 +211,12 @@ module Legion
 
         Legion::Cache::Settings.resolve_servers(driver: 'redis', server: server, servers: Array(servers)).first
       rescue StandardError => e
-        Legion::Logging.debug("Redis#resolved_redis_address failed: #{e.message}") if defined?(Legion::Logging)
+        handle_exception(e, level: :warn, handled: true, operation: :resolved_redis_address)
         'unknown'
       end
 
-      def log_cluster_error(error)
-        return unless defined?(Legion::Logging)
-
-        Legion::Logging.warn "Redis cluster error: #{error.class} — #{error.message}"
+      def log_cluster_error(operation, error, **)
+        handle_exception(error, level: :warn, handled: false, operation: operation, **)
       end
 
       def redis_tls_options(port:)
@@ -219,7 +238,7 @@ module Legion
 
         Legion::Settings[:cache][:tls] || {}
       rescue StandardError => e
-        Legion::Logging.debug("Redis#cache_tls_settings failed: #{e.message}") if defined?(Legion::Logging)
+        handle_exception(e, level: :warn, handled: true, operation: :cache_tls_settings)
         {}
       end
     end

data/lib/legion/cache/redis_hash.rb

@@ -1,17 +1,23 @@
 # frozen_string_literal: true
 
+require 'legion/logging/helper'
+
 module Legion
   module Cache
     module RedisHash
+      extend Legion::Logging::Helper
+
       module_function
 
       # Returns true when the Redis driver is loaded and the connection pool is live.
       def redis_available?
         pool = Legion::Cache.instance_variable_get(:@client)
         return false if pool.nil?
+        return false unless Legion::Cache.respond_to?(:driver_name) && Legion::Cache.driver_name == 'redis'
 
         Legion::Cache.connected?
-      rescue StandardError
+      rescue StandardError => e
+        handle_exception(e, level: :warn, handled: true, operation: :redis_hash_available)
         false
       end
 
@@ -24,6 +30,7 @@ module Legion
           flat = hash.flat_map { |k, v| [k.to_s, v.to_s] }
           conn.hset(key, *flat)
         end
+        log.debug "[cache:redis_hash] HSET #{key} fields=#{hash.size}"
         true
       rescue StandardError => e
         log_redis_error('hset', e)
@@ -34,9 +41,11 @@ module Legion
       def hgetall(key)
         return nil unless redis_available?
 
-        Legion::Cache.instance_variable_get(:@client).with do |conn|
+        result = Legion::Cache.instance_variable_get(:@client).with do |conn|
           conn.hgetall(key)
         end
+        log.debug "[cache:redis_hash] HGETALL #{key} fields=#{result.size}"
+        result
       rescue StandardError => e
         log_redis_error('hgetall', e)
         nil
@@ -46,9 +55,11 @@ module Legion
       def hdel(key, *fields)
         return 0 unless redis_available?
 
-        Legion::Cache.instance_variable_get(:@client).with do |conn|
+        result = Legion::Cache.instance_variable_get(:@client).with do |conn|
           conn.hdel(key, *fields)
         end
+        log.debug "[cache:redis_hash] HDEL #{key} fields=#{fields.size} removed=#{result}"
+        result
       rescue StandardError => e
         log_redis_error('hdel', e)
         0
@@ -61,6 +72,7 @@ module Legion
         Legion::Cache.instance_variable_get(:@client).with do |conn|
           conn.zadd(key, score.to_f, member.to_s)
         end
+        log.debug "[cache:redis_hash] ZADD #{key} member=#{member}"
         true
       rescue StandardError => e
         log_redis_error('zadd', e)
@@ -75,9 +87,11 @@ module Legion
         opts = {}
         opts[:limit] = limit if limit
 
-        Legion::Cache.instance_variable_get(:@client).with do |conn|
+        result = Legion::Cache.instance_variable_get(:@client).with do |conn|
           conn.zrangebyscore(key, min, max, **opts)
         end
+        log.debug "[cache:redis_hash] ZRANGEBYSCORE #{key} results=#{result.size}"
+        result
       rescue StandardError => e
         log_redis_error('zrangebyscore', e)
         []
@@ -90,6 +104,7 @@ module Legion
         Legion::Cache.instance_variable_get(:@client).with do |conn|
           conn.zrem(key, member.to_s)
         end
+        log.debug "[cache:redis_hash] ZREM #{key} member=#{member}"
         true
       rescue StandardError => e
         log_redis_error('zrem', e)
@@ -100,18 +115,18 @@ module Legion
       def expire(key, seconds)
         return false unless redis_available?
 
-        Legion::Cache.instance_variable_get(:@client).with do |conn|
+        result = Legion::Cache.instance_variable_get(:@client).with do |conn|
           conn.expire(key, seconds.to_i) == 1
         end
+        log.debug "[cache:redis_hash] EXPIRE #{key} seconds=#{seconds} success=#{result}"
+        result
       rescue StandardError => e
         log_redis_error('expire', e)
         false
       end
 
       def log_redis_error(method, error)
-        return unless defined?(Legion::Logging)
-
-        Legion::Logging.warn "[cache:redis_hash] #{method} failed: #{error.class} — #{error.message}"
+        handle_exception(error, level: :warn, handled: true, operation: method)
       end
     end
   end

data/lib/legion/cache/settings.rb

@@ -1,16 +1,22 @@
 # frozen_string_literal: true
 
-begin
-  require 'legion/settings'
-rescue StandardError => e
-  warn "legion-cache: failed to require legion/settings: #{e.message}"
-end
+require 'ipaddr'
+require 'legion/logging/helper'
 
 module Legion
   module Cache
     module Settings
-      Legion::Settings.merge_settings(:cache, default) if Legion::Settings.method_defined? :merge_settings
-      Legion::Settings.merge_settings(:cache_local, local) if Legion::Settings.method_defined? :merge_settings
+      extend Legion::Logging::Helper
+
+      begin
+        require 'legion/settings'
+      rescue StandardError => e
+        handle_exception(e,
+                         level:     :error,
+                         handled:   true,
+                         operation: :cache_settings_require_legion_settings)
+      end
+
       def self.default
         {
           driver:             driver,
@@ -69,8 +75,34 @@ module Legion
         all = Array(servers) + Array(server)
         all = ["127.0.0.1:#{port}"] if all.empty?
 
-        all.map! { |s| s.include?(':') ? s : "#{s}:#{port}" }
-        all.uniq
+        all.map! { |s| normalize_server(s, port: port) }
+        resolved = all.uniq
+        log.debug "Legion::Cache::Settings resolved driver=#{gem_driver} servers=#{resolved.join(', ')}"
+        resolved
+      end
+
+      def self.parse_server_address(server, default_port:)
+        raw = server.to_s.strip
+        return ['127.0.0.1', default_port] if raw.empty?
+
+        bracketed = raw.match(/\A\[(?<host>[^\]]+)\](?::(?<port>\d+))?\z/)
+        return [bracketed[:host], (bracketed[:port] || default_port).to_i] if bracketed
+
+        return [raw, default_port] if ipv6_literal?(raw)
+
+        host, explicit_port = raw.split(':', 2)
+        if explicit_port&.match?(/\A\d+\z/)
+          [host, explicit_port.to_i]
+        else
+          [raw, default_port]
+        end
+      end
+
+      def self.register_defaults!
+        return unless defined?(Legion::Settings) && Legion::Settings.respond_to?(:merge_settings)
+
+        Legion::Settings.merge_settings(:cache, default)
+        Legion::Settings.merge_settings(:cache_local, local)
       end
 
       def self.normalize_driver(name)
@@ -84,13 +116,36 @@ module Legion
       def self.driver(prefer = 'dalli')
         secondary = prefer == 'dalli' ? 'redis' : 'dalli'
         if Gem::Specification.find_all_by_name(prefer).any?
+          log.debug "Legion::Cache::Settings selected driver=#{prefer}"
           prefer
         elsif Gem::Specification.find_all_by_name(secondary).any?
+          log.info "Legion::Cache::Settings falling back driver=#{secondary} preferred=#{prefer}"
           secondary
         else
-          raise NameError('Legion::Cache.driver is nil')
+          error = NameError.new('Legion::Cache.driver is nil')
+          handle_exception(error, level: :error, handled: false, operation: :cache_settings_driver, preferred: prefer)
+          raise error
         end
       end
+
+      def self.normalize_server(server, port:)
+        host, resolved_port = parse_server_address(server, default_port: port)
+        format_server(host, resolved_port)
+      end
+
+      def self.format_server(host, port)
+        return "[#{host}]:#{port}" if ipv6_literal?(host)
+
+        "#{host}:#{port}"
+      end
+
+      def self.ipv6_literal?(value)
+        IPAddr.new(value).ipv6?
+      rescue IPAddr::InvalidAddressError
+        false
+      end
+
+      register_defaults!
     end
   end
 end

data/lib/legion/cache/version.rb

@@ -2,6 +2,6 @@
 
 module Legion
   module Cache
-    VERSION = '1.3.20'
+    VERSION = '1.3.21'
   end
 end