familia 1.0.0.pre.rc3 → 1.0.0.pre.rc5

data/lib/familia/logging.rb

@@ -126,26 +126,48 @@ module Familia
     #
     # @param label [Symbol] A label for the trace message (e.g., :EXPAND,
     #   :FROMREDIS, :LOAD, :EXISTS).
-    # @param redis_instance [Object] The Redis instance being used.
+    # @param redis_instance [Redis, Redis::Future, nil] The Redis instance or
+    #   Future being used.
     # @param ident [String] An identifier or key related to the operation being
     #   traced.
     # @param context [Array<String>, String, nil] The calling context, typically
     #   obtained from `caller` or `caller.first`. Default is nil.
     #
     # @example
-    #   Familia.trace :LOAD, Familia.redis(uri), objkey, caller if Familia.debug?
-    #
+    #   Familia.trace :LOAD, Familia.redis(uri), objkey, caller(1..1) if
+    #   Familia.debug?
     #
     # @return [nil]
     #
+    # @note This method only executes if LoggerTraceRefinement::ENABLED is true.
+    # @note The redis_instance can be a Redis object, Redis::Future (used in
+    #   pipelined and multi blocks), or nil (when the redis connection isn't
+    #   relevant).
+    #
     def trace(label, redis_instance, ident, context = nil)
       return unless LoggerTraceRefinement::ENABLED
-      instance_id = redis_instance&.id
+
+      # Usually redis_instance is a Redis object, but it could be
+      # a Redis::Future which is what is used inside of pipelined
+      # and multi blocks. In some contexts it's nil where the
+      # redis connection isn't relevant.
+      instance_id = if redis_instance
+        case redis_instance
+        when Redis
+          redis_instance.id.respond_to?(:to_s) ? redis_instance.id.to_s : redis_instance.class.name
+        when Redis::Future
+          "Redis::Future"
+        else
+          redis_instance.class.name
+        end
+      end
+
       codeline = if context
                    context = [context].flatten
                    context.reject! { |line| line =~ %r{lib/familia} }
                    context.first
                  end
+
       @logger.trace format('[%s] %s -> %s <- at %s', label, instance_id, ident, codeline)
     end
 

data/lib/familia/redistype/serialization.rb

@@ -4,63 +4,80 @@ class Familia::RedisType
 
   module Serialization
 
-    # Serializes an individual value for storage in Redis.
-    #
-    # This method prepares a value for storage in Redis by converting it to a string representation.
-    # If a class option is specified, it uses that class's serialization method.
-    # Otherwise, it relies on the value's own `to_s` method for serialization.
+    # Serializes a value for storage in Redis.
     #
     # @param val [Object] The value to be serialized.
-    # @param strict_values [Boolean] Whether to enforce strict value serialization (default: true). Only applies when no class option is specified because the class option is assumed to handle its own serialization.
-    # @return [String] The serialized representation of the value.
+    # @param strict_values [Boolean] Whether to enforce strict value
+    #   serialization (default: true).
+    # @return [String, nil] The serialized representation of the value, or nil
+    #   if serialization fails.
     #
-    # @note When no class option is specified, this method attempts to serialize the value directly.
-    #       If the serialization fails, it falls back to the value's own string representation.
+    # @note When a class option is specified, it uses that class's
+    #   serialization method. Otherwise, it relies on Familia.distinguisher for
+    #   serialization.
     #
     # @example With a class option
-    #   to_redis(User.new(name: "John"), strict_values: false) #=> '{"name":"John"}'
-    #   to_redis(nil, strict_values: false) #=> "" (empty string)
-    #   to_redis(true, strict_values: false) #=> "true"
+    #   to_redis(User.new(name: "Cloe"), strict_values: false) #=> '{"name":"Cloe"}'
     #
-    # @example Without a class option and strict values
-    #   to_redis(123) #=> "123" (which becomes "123" in Redis)
+    # @example Without a class option
+    #   to_redis(123) #=> "123"
     #   to_redis("hello") #=> "hello"
-    #   to_redis(nil) # raises an exception
-    #   to_redis(true) # raises an exception
     #
-    # @raise [Familia::HighRiskFactor]
+    # @raise [Familia::HighRiskFactor] If serialization fails under strict
+    #   mode.
     #
     def to_redis(val, strict_values = true)
-      ret = nil
+      prepared = nil
 
       Familia.trace :TOREDIS, redis, "#{val}<#{val.class}|#{opts[:class]}>", caller(1..1) if Familia.debug?
 
       if opts[:class]
-        ret = Familia.distinguisher(opts[:class], strict_values)
-        Familia.ld "  from opts[class] <#{opts[:class]}>: #{ret||'<nil>'}"
+        prepared = Familia.distinguisher(opts[:class], strict_values)
+        Familia.ld "  from opts[class] <#{opts[:class]}>: #{prepared||'<nil>'}"
       end
 
-      if ret.nil?
+      if prepared.nil?
         # Enforce strict values when no class option is specified
-        ret = Familia.distinguisher(val, true)
-        Familia.ld "  from value #{val}<#{val.class}>: #{ret}<#{ret.class}>"
+        prepared = Familia.distinguisher(val, true)
+        Familia.ld "  from <#{val.class}> => <#{prepared.class}>"
       end
 
-      Familia.trace :TOREDIS, redis, "#{val}<#{val.class}|#{opts[:class]}> => #{ret}<#{ret.class}>", caller(1..1) if Familia.debug?
+      Familia.trace :TOREDIS, redis, "#{val}<#{val.class}|#{opts[:class]}> => #{prepared}<#{prepared.class}>", caller(1..1) if Familia.debug?
 
-      Familia.warn "[#{self.class}\#to_redis] nil returned for #{opts[:class]}\##{name}" if ret.nil?
-      ret
+      Familia.warn "[#{self.class}\#to_redis] nil returned for #{opts[:class]}\##{name}" if prepared.nil?
+      prepared
     end
 
+    # Deserializes multiple values from Redis, removing nil values.
+    #
+    # @param values [Array<String>] The values to deserialize.
+    # @return [Array<Object>] Deserialized objects, with nil values removed.
+    #
+    # @see #multi_from_redis_with_nil
+    #
     def multi_from_redis(*values)
-      # Avoid using compact! here. Using compact! as the last expression in the method
-      # can unintentionally return nil if no changes are made, which is not desirable.
-      # Instead, use compact to ensure the method returns the expected value.
+      # Avoid using compact! here. Using compact! as the last expression in the
+      # method can unintentionally return nil if no changes are made, which is
+      # not desirable. Instead, use compact to ensure the method returns the
+      # expected value.
       multi_from_redis_with_nil(*values).compact
     end
 
+    # Deserializes multiple values from Redis, preserving nil values.
+    #
+    # @param values [Array<String>] The values to deserialize.
+    # @return [Array<Object, nil>] Deserialized objects, including nil values.
+    #
+    # @raise [Familia::Problem] If the specified class doesn't respond to the
+    #   load method.
+    #
+    # @note This method attempts to deserialize each value using the specified
+    #   class's load method. If deserialization fails for a value, it's
+    #   replaced with nil.
+    #
     # NOTE: `multi` in this method name refers to multiple values from
     # redis and not the Redis server MULTI command.
+    #
     def multi_from_redis_with_nil(*values)
       Familia.ld "multi_from_redis: (#{@opts}) #{values}"
       return [] if values.empty?
@@ -89,6 +106,20 @@ class Familia::RedisType
       values
     end
 
+    # Deserializes a single value from Redis.
+    #
+    # @param val [String, nil] The value to deserialize.
+    # @return [Object, nil] The deserialized object, the default value if
+    #   val is nil, or nil if deserialization fails.
+    #
+    # @note If no class option is specified, the original value is
+    #   returned unchanged.
+    #
+    # NOTE: Currently only the RedisType class uses this method. Horreum
+    # fields are a newer addition and don't support the full range of
+    # deserialization options that RedisType supports. It uses to_redis
+    # for serialization since everything becomes a string in Redis.
+    #
     def from_redis(val)
       return @opts[:default] if val.nil?
       return val unless @opts[:class]
@@ -96,15 +127,6 @@ class Familia::RedisType
       ret = multi_from_redis val
       ret&.first # return the object or nil
     end
-
-    def update_expiration(ttl = nil)
-      ttl ||= opts[:ttl]
-      return if ttl.to_i.zero? # nil will be zero
-
-      Familia.ld "#{rediskey} to #{ttl}"
-      expire ttl.to_i
-    end
-
   end
 
 end

data/lib/familia/redistype.rb

@@ -13,31 +13,29 @@ module Familia
   # @abstract Subclass and implement Redis data type specific methods
   class RedisType
     include Familia::Base
+    extend Familia::Features
 
     @registered_types = {}
     @valid_options = %i[class parent ttl default db key redis]
     @db = nil
-    @ttl = nil
+
+    feature :expiration
+    feature :quantization
 
     class << self
       attr_reader :registered_types, :valid_options
       attr_accessor :parent
-      attr_writer :ttl, :db, :uri
+      attr_writer :db, :uri
 
       # To be called inside every class that inherits RedisType
       # +methname+ is the term used for the class and instance methods
       # that are created for the given +klass+ (e.g. set, list, etc)
       def register(klass, methname)
-        Familia.ld "[#{self}] Registering #{klass} as #{methname}"
+        Familia.ld "[#{self}] Registering #{klass} as #{methname.inspect}"
 
         @registered_types[methname] = klass
       end
 
-      def ttl(val = nil)
-        @ttl = val unless val.nil?
-        @ttl || parent&.ttl
-      end
-
       def db(val = nil)
         @db = val unless val.nil?
         @db || parent&.db
@@ -49,8 +47,9 @@ module Familia
       end
 
       def inherited(obj)
+        Familia.trace :REDISTYPE, nil, "#{obj} is my kinda type", caller(1..1) if Familia.debug?
         obj.db = db
-        obj.ttl = ttl
+        obj.ttl = ttl # method added via Features::Expiration
         obj.uri = uri
         obj.parent = self
         super(obj)
@@ -101,6 +100,17 @@ module Familia
       @opts = opts || {}
       @opts = RedisType.valid_keys_only(@opts)
 
+      # Apply the options to instance method setters of the same name
+      @opts.each do |k, v|
+        # Bewarde logging :parent instance here implicitly calls #to_s which for
+        # some classes could include the identifier which could still be nil at
+        # this point. This would result in a Familia::Problem being raised. So
+        # to be on the safe-side here until we have a better understanding of
+        # the issue, we'll just log the class name for each key-value pair.
+        Familia.ld " [setting] #{k} #{v.class}"
+        send(:"#{k}=", v) if respond_to? :"#{k}="
+      end
+
       init if respond_to? :init
     end
 
@@ -110,10 +120,37 @@ module Familia
       parent? ? parent.redis : Familia.redis(opts[:db])
     end
 
-    # Produces the full redis key for this object.
+    # Produces the full Redis key for this object.
+    #
+    # @return [String] The full Redis key.
+    #
+    # This method determines the appropriate Redis key based on the context of the RedisType object:
+    #
+    # 1. If a hardcoded key is set in the options, it returns that key.
+    # 2. For instance-level RedisType objects, it uses the parent instance's rediskey method.
+    # 3. For class-level RedisType objects, it uses the parent class's rediskey method.
+    # 4. For standalone RedisType objects, it uses the keystring as the full Redis key.
+    #
+    # For class-level RedisType objects (parent_class? == true):
+    # - The suffix is optional and used to differentiate between different types of objects.
+    # - If no suffix is provided, the class's default suffix is used (via the self.suffix method).
+    # - If a nil suffix is explicitly passed, it won't appear in the resulting Redis key.
+    # - Passing nil as the suffix is how class-level RedisType objects are created without
+    #   the global default 'object' suffix.
+    #
+    # @example Instance-level RedisType
+    #   user_instance.some_redistype.rediskey  # => "user:123:some_redistype"
+    #
+    # @example Class-level RedisType
+    #   User.some_redistype.rediskey  # => "user:some_redistype"
+    #
+    # @example Standalone RedisType
+    #   RedisType.new("mykey").rediskey  # => "mykey"
+    #
+    # @example Class-level RedisType with explicit nil suffix
+    #   User.rediskey("123", nil)  # => "user:123"
+    #
     def rediskey
-      Familia.ld "[rediskey] #{keystring} for #{self.class} (#{opts})"
-
       # Return the hardcoded key if it's set. This is useful for
       # support legacy keys that aren't derived in the same way.
       return opts[:key] if opts[:key]
@@ -128,7 +165,7 @@ module Familia
         parent.rediskey(keystring, nil)
       else
         # This is a standalone RedisType object where it's keystring
-        # is the full key.
+        # is the full redis key.
         keystring
       end
     end
@@ -153,10 +190,6 @@ module Familia
       @opts[:parent]
     end
 
-    def ttl
-      @opts[:ttl] || self.class.ttl
-    end
-
     def db
       @opts[:db] || self.class.db
     end

data/lib/familia/settings.rb

@@ -5,7 +5,7 @@ module Familia
   @delim = ':'
   @prefix = nil
   @suffix = :object
-  @ttl = nil
+  @ttl = 0 # see update_expiration. Zero is skip. nil is an exception.
   @db = nil
 
   module Settings
@@ -27,6 +27,16 @@ module Familia
       @suffix
     end
 
+    def ttl(v = nil)
+      @ttl = v unless v.nil?
+      @ttl
+    end
+
+    def db(v = nil)
+      @db = v unless v.nil?
+      @db
+    end
+
     # We define this do-nothing method because it reads better
     # than simply Familia.suffix in some contexts.
     def default_suffix

data/lib/familia/tools.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+module Familia
+  module Tools
+    extend self
+    def move_keys(filter, source_uri, target_uri, &each_key)
+      raise "Source and target are the same (#{target_uri})" if target_uri == source_uri
+
+      Familia.connect target_uri
+      source_keys = Familia.redis(source_uri).keys(filter)
+      puts "Moving #{source_keys.size} keys from #{source_uri} to #{target_uri} (filter: #{filter})"
+      source_keys.each_with_index do |key, idx|
+        type = Familia.redis(source_uri).type key
+        ttl = Familia.redis(source_uri).ttl key
+        if source_uri.host == target_uri.host && source_uri.port == target_uri.port
+          Familia.redis(source_uri).move key, target_uri.db
+        else
+          case type
+          when 'string'
+            Familia.redis(source_uri).get key
+          when 'list'
+            Familia.redis(source_uri).lrange key, 0, -1
+          when 'set'
+            Familia.redis(source_uri).smembers key
+          else
+            raise Familia::Problem, "unknown key type: #{type}"
+          end
+          raise 'Not implemented'
+        end
+        yield(idx, type, key, ttl) unless each_key.nil?
+      end
+    end
+
+    # Use the return value from each_key as the new key name
+    def rename(filter, source_uri, target_uri = nil, &each_key)
+      target_uri ||= source_uri
+      move_keys filter, source_uri, target_uri if source_uri != target_uri
+      source_keys = Familia.redis(source_uri).keys(filter)
+      puts "Renaming #{source_keys.size} keys from #{source_uri} (filter: #{filter})"
+      source_keys.each_with_index do |key, idx|
+        Familia.trace :RENAME1, Familia.redis(source_uri), "#{key}", ''
+        type = Familia.redis(source_uri).type key
+        ttl = Familia.redis(source_uri).ttl key
+        newkey = yield(idx, type, key, ttl) unless each_key.nil?
+        Familia.trace :RENAME2, Familia.redis(source_uri), "#{key} -> #{newkey}", caller(1..1).first
+        Familia.redis(source_uri).renamenx key, newkey
+      end
+    end
+
+    def get_any(keyname, uri = nil)
+      type = Familia.redis(uri).type keyname
+      case type
+      when 'string'
+        Familia.redis(uri).get keyname
+      when 'list'
+        Familia.redis(uri).lrange(keyname, 0, -1) || []
+      when 'set'
+        Familia.redis(uri).smembers(keyname) || []
+      when 'zset'
+        Familia.redis(uri).zrange(keyname, 0, -1) || []
+      when 'hash'
+        Familia.redis(uri).hgetall(keyname) || {}
+      else
+        nil
+      end
+    end
+  end
+end

data/lib/familia/types/hashkey.rb

@@ -49,12 +49,12 @@ module Familia
     end
 
     def values
-      el = redis.hvals(rediskey)
-      multi_from_redis(*el)
+      elements = redis.hvals(rediskey)
+      multi_from_redis(*elements)
     end
 
     def hgetall
-      # TODO: Use from_redis. Also name `all` is confusing with
+      # TODO: Use from_redis. Also alias `all` is confusing with
       # Onetime::Customer.all which returns all customers.
       redis.hgetall rediskey
     end
@@ -98,8 +98,8 @@ module Familia
     alias merge! update
 
     def values_at *fields
-      el = redis.hmget(rediskey, *fields.flatten.compact)
-      multi_from_redis(*el)
+      elements = redis.hmget(rediskey, *fields.flatten.compact)
+      multi_from_redis(*elements)
     end
 
     Familia::RedisType.register self, :hash # legacy, deprecated

data/lib/familia/types/list.rb

@@ -65,8 +65,8 @@ module Familia
     alias del delete
 
     def range(sidx = 0, eidx = -1)
-      el = rangeraw sidx, eidx
-      multi_from_redis(*el)
+      elements = rangeraw sidx, eidx
+      multi_from_redis(*elements)
     end
 
     def rangeraw(sidx = 0, eidx = -1)

data/lib/familia/types/sorted_set.rb

@@ -75,8 +75,8 @@ module Familia
 
     def members(count = -1, opts = {})
       count -= 1 if count.positive?
-      el = membersraw count, opts
-      multi_from_redis(*el)
+      elements = membersraw count, opts
+      multi_from_redis(*elements)
     end
     alias to_a members
     alias all members
@@ -88,8 +88,8 @@ module Familia
 
     def revmembers(count = -1, opts = {})
       count -= 1 if count.positive?
-      el = revmembersraw count, opts
-      multi_from_redis(*el)
+      elements = revmembersraw count, opts
+      multi_from_redis(*elements)
     end
 
     def revmembersraw(count = -1, opts = {})
@@ -131,8 +131,8 @@ module Familia
 
     def range(sidx, eidx, opts = {})
       echo :range, caller(1..1).first if Familia.debug
-      el = rangeraw(sidx, eidx, opts)
-      multi_from_redis(*el)
+      elements = rangeraw(sidx, eidx, opts)
+      multi_from_redis(*elements)
     end
 
     def rangeraw(sidx, eidx, opts = {})
@@ -148,8 +148,8 @@ module Familia
 
     def revrange(sidx, eidx, opts = {})
       echo :revrange, caller(1..1).first if Familia.debug
-      el = revrangeraw(sidx, eidx, opts)
-      multi_from_redis(*el)
+      elements = revrangeraw(sidx, eidx, opts)
+      multi_from_redis(*elements)
     end
 
     def revrangeraw(sidx, eidx, opts = {})
@@ -159,8 +159,8 @@ module Familia
     # e.g. obj.metrics.rangebyscore (now-12.hours), now, :limit => [0, 10]
     def rangebyscore(sscore, escore, opts = {})
       echo :rangebyscore, caller(1..1).first if Familia.debug
-      el = rangebyscoreraw(sscore, escore, opts)
-      multi_from_redis(*el)
+      elements = rangebyscoreraw(sscore, escore, opts)
+      multi_from_redis(*elements)
     end
 
     def rangebyscoreraw(sscore, escore, opts = {})
@@ -171,8 +171,8 @@ module Familia
     # e.g. obj.metrics.revrangebyscore (now-12.hours), now, :limit => [0, 10]
     def revrangebyscore(sscore, escore, opts = {})
       echo :revrangebyscore, caller(1..1).first if Familia.debug
-      el = revrangebyscoreraw(sscore, escore, opts)
-      multi_from_redis(*el)
+      elements = revrangebyscoreraw(sscore, escore, opts)
+      multi_from_redis(*elements)
     end
 
     def revrangebyscoreraw(sscore, escore, opts = {})

data/lib/familia/types/string.rb

@@ -14,7 +14,7 @@ module Familia
     end
 
     def value
-      echo :value, caller[0..0] if Familia.debug
+      echo :value, caller(0..0) if Familia.debug
       redis.setnx rediskey, @opts[:default] if @opts[:default]
       from_redis redis.get(rediskey)
     end

data/lib/familia/types/unsorted_set.rb

@@ -23,8 +23,8 @@ module Familia
 
     def members
       echo :members, caller(1..1).first if Familia.debug
-      el = membersraw
-      multi_from_redis(*el)
+      elements = membersraw
+      multi_from_redis(*elements)
     end
     alias all members
     alias to_a members