familia 1.2.1 → 2.0.0.pre2

data/lib/familia/{redistype → datatype}/types/list.rb

@@ -1,12 +1,12 @@
-# frozen_string_literal: true
+# lib/familia/datatype/types/list.rb
 
 module Familia
-  class List < RedisType
+  class List < DataType
 
     # Returns the number of elements in the list
     # @return [Integer] number of elements
     def element_count
-      redis.llen rediskey
+      dbclient.llen dbkey
     end
     alias size element_count
 
@@ -16,8 +16,8 @@ module Familia
 
     def push *values
       echo :push, caller(1..1).first if Familia.debug
-      values.flatten.compact.each { |v| redis.rpush rediskey, serialize_value(v) }
-      redis.ltrim rediskey, -@opts[:maxlength], -1 if @opts[:maxlength]
+      values.flatten.compact.each { |v| dbclient.rpush dbkey, serialize_value(v) }
+      dbclient.ltrim dbkey, -@opts[:maxlength], -1 if @opts[:maxlength]
       update_expiration
       self
     end
@@ -29,20 +29,20 @@ module Familia
     alias add <<
 
     def unshift *values
-      values.flatten.compact.each { |v| redis.lpush rediskey, serialize_value(v) }
+      values.flatten.compact.each { |v| dbclient.lpush dbkey, serialize_value(v) }
       # TODO: test maxlength
-      redis.ltrim rediskey, 0, @opts[:maxlength] - 1 if @opts[:maxlength]
+      dbclient.ltrim dbkey, 0, @opts[:maxlength] - 1 if @opts[:maxlength]
       update_expiration
       self
     end
     alias prepend unshift
 
     def pop
-      deserialize_value redis.rpop(rediskey)
+      deserialize_value dbclient.rpop(dbkey)
     end
 
     def shift
-      deserialize_value redis.lpop(rediskey)
+      deserialize_value dbclient.lpop(dbkey)
     end
 
     def [](idx, count = nil)
@@ -65,7 +65,7 @@ module Familia
     # @param count [Integer] Number of elements to remove (0 means all)
     # @return [Integer] The number of removed elements
     def remove_element(value, count = 0)
-      redis.lrem rediskey, count, serialize_value(value)
+      dbclient.lrem dbkey, count, serialize_value(value)
     end
     alias remove remove_element
 
@@ -75,7 +75,7 @@ module Familia
     end
 
     def rangeraw(sidx = 0, eidx = -1)
-      redis.lrange(rediskey, sidx, eidx)
+      dbclient.lrange(dbkey, sidx, eidx)
     end
 
     def members(count = -1)
@@ -124,7 +124,7 @@ module Familia
     end
 
     def at(idx)
-      deserialize_value redis.lindex(rediskey, idx)
+      deserialize_value dbclient.lindex(dbkey, idx)
     end
 
     def first
@@ -157,6 +157,6 @@ module Familia
     #  end
     # end
 
-    Familia::RedisType.register self, :list
+    Familia::DataType.register self, :list
   end
 end

data/lib/familia/{redistype → datatype}/types/sorted_set.rb

@@ -1,11 +1,11 @@
-# frozen_string_literal: true
+# lib/familia/datatype/types/sorted_set.rb
 
 module Familia
-  class SortedSet < RedisType
+  class SortedSet < DataType
     # Returns the number of elements in the sorted set
     # @return [Integer] number of elements
     def element_count
-      redis.zcard rediskey
+      dbclient.zcard dbkey
     end
     alias size element_count
 
@@ -46,32 +46,32 @@ module Familia
     end
 
     def add(score, val)
-      ret = redis.zadd rediskey, score, serialize_value(val)
+      ret = dbclient.zadd dbkey, score, serialize_value(val)
       update_expiration
       ret
     end
 
     def score(val)
-      ret = redis.zscore rediskey, serialize_value(val, strict_values: false)
+      ret = dbclient.zscore dbkey, serialize_value(val, strict_values: false)
       ret&.to_f
     end
     alias [] score
 
     def member?(val)
-      Familia.trace :MEMBER, redis, "#{val}<#{val.class}>", caller(1..1) if Familia.debug?
+      Familia.trace :MEMBER, dbclient, "#{val}<#{val.class}>", caller(1..1) if Familia.debug?
       !rank(val).nil?
     end
     alias include? member?
 
     # rank of member +v+ when ordered lowest to highest (starts at 0)
     def rank(v)
-      ret = redis.zrank rediskey, serialize_value(v, strict_values: false)
+      ret = dbclient.zrank dbkey, serialize_value(v, strict_values: false)
       ret&.to_i
     end
 
     # rank of member +v+ when ordered highest to lowest (starts at 0)
     def revrank(v)
-      ret = redis.zrevrank rediskey, serialize_value(v, strict_values: false)
+      ret = dbclient.zrevrank dbkey, serialize_value(v, strict_values: false)
       ret&.to_i
     end
 
@@ -140,12 +140,12 @@ module Familia
     def rangeraw(sidx, eidx, opts = {})
       # NOTE: :withscores (no underscore) is the correct naming for the
       # redis-4.x gem. We pass :withscores through explicitly b/c
-      # redis.zrange et al only accept that one optional argument.
+      # dbclient.zrange et al only accept that one optional argument.
       # Passing `opts`` through leads to an ArgumentError:
       #
       #   sorted_sets.rb:374:in `zrevrange': wrong number of arguments (given 4, expected 3) (ArgumentError)
       #
-      redis.zrange(rediskey, sidx, eidx, **opts)
+      dbclient.zrange(dbkey, sidx, eidx, **opts)
     end
 
     def revrange(sidx, eidx, opts = {})
@@ -155,7 +155,7 @@ module Familia
     end
 
     def revrangeraw(sidx, eidx, opts = {})
-      redis.zrevrange(rediskey, sidx, eidx, **opts)
+      dbclient.zrevrange(dbkey, sidx, eidx, **opts)
     end
 
     # e.g. obj.metrics.rangebyscore (now-12.hours), now, :limit => [0, 10]
@@ -167,7 +167,7 @@ module Familia
 
     def rangebyscoreraw(sscore, escore, opts = {})
       echo :rangebyscoreraw, caller(1..1).first if Familia.debug
-      redis.zrangebyscore(rediskey, sscore, escore, **opts)
+      dbclient.zrangebyscore(dbkey, sscore, escore, **opts)
     end
 
     # e.g. obj.metrics.revrangebyscore (now-12.hours), now, :limit => [0, 10]
@@ -180,19 +180,19 @@ module Familia
     def revrangebyscoreraw(sscore, escore, opts = {})
       echo :revrangebyscoreraw, caller(1..1).first if Familia.debug
       opts[:with_scores] = true if opts[:withscores]
-      redis.zrevrangebyscore(rediskey, sscore, escore, opts)
+      dbclient.zrevrangebyscore(dbkey, sscore, escore, opts)
     end
 
     def remrangebyrank(srank, erank)
-      redis.zremrangebyrank rediskey, srank, erank
+      dbclient.zremrangebyrank dbkey, srank, erank
     end
 
     def remrangebyscore(sscore, escore)
-      redis.zremrangebyscore rediskey, sscore, escore
+      dbclient.zremrangebyscore dbkey, sscore, escore
     end
 
     def increment(val, by = 1)
-      redis.zincrby(rediskey, by, val).to_i
+      dbclient.zincrby(dbkey, by, val).to_i
     end
     alias incr increment
     alias incrby increment
@@ -207,13 +207,13 @@ module Familia
     # @param value The value to remove from the sorted set
     # @return [Integer] The number of members that were removed (0 or 1)
     def remove_element(value)
-      Familia.trace :REMOVE_ELEMENT, redis, "#{value}<#{value.class}>", caller(1..1) if Familia.debug?
+      Familia.trace :REMOVE_ELEMENT, dbclient, "#{value}<#{value.class}>", caller(1..1) if Familia.debug?
       # We use `strict_values: false` here to allow for the deletion of values
       # that are in the sorted set. If it's a horreum object, the value is
       # the identifier and not a serialized version of the object. So either
       # the value exists in the sorted set or it doesn't -- we don't need to
       # raise an error if it's not found.
-      redis.zrem rediskey, serialize_value(value, strict_values: false)
+      dbclient.zrem dbkey, serialize_value(value, strict_values: false)
     end
     alias remove remove_element # deprecated
 
@@ -231,7 +231,7 @@ module Familia
       at(-1)
     end
 
-    Familia::RedisType.register self, :sorted_set
-    Familia::RedisType.register self, :zset
+    Familia::DataType.register self, :sorted_set
+    Familia::DataType.register self, :zset
   end
 end

data/lib/familia/{redistype → datatype}/types/string.rb

@@ -1,7 +1,7 @@
-# frozen_string_literal: true
+# lib/familia/datatype/types/string.rb
 
 module Familia
-  class String < RedisType
+  class String < DataType
     def init; end
 
     # Returns the number of elements in the list
@@ -17,22 +17,23 @@ module Familia
 
     def value
       echo :value, caller(0..0) if Familia.debug
-      redis.setnx rediskey, @opts[:default] if @opts[:default]
-      deserialize_value redis.get(rediskey)
+      dbclient.setnx dbkey, @opts[:default] if @opts[:default]
+      deserialize_value dbclient.get(dbkey)
     end
     alias content value
     alias get value
 
     def to_s
-      value.to_s # value can return nil which to_s should not
+      return super if value.to_s.empty?
+      value.to_s
     end
 
     def to_i
-      value.to_i
+      value&.to_i || 0
     end
 
     def value=(val)
-      ret = redis.set(rediskey, serialize_value(val))
+      ret = dbclient.set(dbkey, serialize_value(val))
       update_expiration
       ret
     end
@@ -40,68 +41,68 @@ module Familia
     alias set value=
 
     def setnx(val)
-      ret = redis.setnx(rediskey, serialize_value(val))
+      ret = dbclient.setnx(dbkey, serialize_value(val))
       update_expiration
       ret
     end
 
     def increment
-      ret = redis.incr(rediskey)
+      ret = dbclient.incr(dbkey)
       update_expiration
       ret
     end
     alias incr increment
 
     def incrementby(val)
-      ret = redis.incrby(rediskey, val.to_i)
+      ret = dbclient.incrby(dbkey, val.to_i)
       update_expiration
       ret
     end
     alias incrby incrementby
 
     def decrement
-      ret = redis.decr rediskey
+      ret = dbclient.decr dbkey
       update_expiration
       ret
     end
     alias decr decrement
 
     def decrementby(val)
-      ret = redis.decrby rediskey, val.to_i
+      ret = dbclient.decrby dbkey, val.to_i
       update_expiration
       ret
     end
     alias decrby decrementby
 
     def append(val)
-      ret = redis.append rediskey, val
+      ret = dbclient.append dbkey, val
       update_expiration
       ret
     end
     alias << append
 
     def getbit(offset)
-      redis.getbit rediskey, offset
+      dbclient.getbit dbkey, offset
     end
 
     def setbit(offset, val)
-      ret = redis.setbit rediskey, offset, val
+      ret = dbclient.setbit dbkey, offset, val
       update_expiration
       ret
     end
 
     def getrange(spoint, epoint)
-      redis.getrange rediskey, spoint, epoint
+      dbclient.getrange dbkey, spoint, epoint
     end
 
     def setrange(offset, val)
-      ret = redis.setrange rediskey, offset, val
+      ret = dbclient.setrange dbkey, offset, val
       update_expiration
       ret
     end
 
     def getset(val)
-      ret = redis.getset rediskey, val
+      ret = dbclient.getset dbkey, val
       update_expiration
       ret
     end
@@ -110,8 +111,8 @@ module Familia
       value.nil?
     end
 
-    Familia::RedisType.register self, :string
-    Familia::RedisType.register self, :counter
-    Familia::RedisType.register self, :lock
+    Familia::DataType.register self, :string
+    Familia::DataType.register self, :counter
+    Familia::DataType.register self, :lock
   end
 end

data/lib/familia/{redistype → datatype}/types/unsorted_set.rb

@@ -1,12 +1,12 @@
-# frozen_string_literal: true
+# lib/familia/datatype/types/unsorted_set.rb
 
 module Familia
-  class Set < RedisType
+  class Set < DataType
 
     # Returns the number of elements in the unsorted set
     # @return [Integer] number of elements
     def element_count
-      redis.scard rediskey
+      dbclient.scard dbkey
     end
     alias size element_count
 
@@ -15,7 +15,7 @@ module Familia
     end
 
     def add *values
-      values.flatten.compact.each { |v| redis.sadd? rediskey, serialize_value(v) }
+      values.flatten.compact.each { |v| dbclient.sadd? dbkey, serialize_value(v) }
       update_expiration
       self
     end
@@ -33,7 +33,7 @@ module Familia
     alias to_a members
 
     def membersraw
-      redis.smembers(rediskey)
+      dbclient.smembers(dbkey)
     end
 
     def each(&blk)
@@ -69,7 +69,7 @@ module Familia
     end
 
     def member?(val)
-      redis.sismember rediskey, serialize_value(val)
+      dbclient.sismember dbkey, serialize_value(val)
     end
     alias include? member?
 
@@ -77,7 +77,7 @@ module Familia
     # @param value The value to remove from the set
     # @return [Integer] The number of members that were removed (0 or 1)
     def remove_element(value)
-      redis.srem rediskey, serialize_value(value)
+      dbclient.srem dbkey, serialize_value(value)
     end
     alias remove remove_element # deprecated
 
@@ -86,11 +86,11 @@ module Familia
     end
 
     def pop
-      redis.spop rediskey
+      dbclient.spop dbkey
     end
 
     def move(dstkey, val)
-      redis.smove rediskey, dstkey, val
+      dbclient.smove dbkey, dstkey, val
     end
 
     def random
@@ -98,7 +98,7 @@ module Familia
     end
 
     def randomraw
-      redis.srandmember(rediskey)
+      dbclient.srandmember(dbkey)
     end
 
     ## Make the value stored at KEY identical to the given list
@@ -122,6 +122,6 @@ module Familia
     #  end
     # end
 
-    Familia::RedisType.register self, :set
+    Familia::DataType.register self, :set
   end
 end

data/lib/familia/datatype.rb

@@ -0,0 +1,243 @@
+# lib/familia/datatype.rb
+
+require_relative 'datatype/commands'
+require_relative 'datatype/serialization'
+
+module Familia
+
+  # DataType - Base class for Database data type wrappers
+  #
+  # This class provides common functionality for various Database data types
+  # such as String, List, Set, SortedSet, and HashKey.
+  #
+  # @abstract Subclass and implement Database data type specific methods
+  class DataType
+    include Familia::Base
+    extend Familia::Features
+
+    @registered_types = {}
+    @valid_options = %i[class parent default_expiration default logical_database dbkey dbclient suffix prefix]
+    @logical_database = nil
+
+    feature :expiration
+    feature :quantization
+
+    class << self
+      attr_reader :registered_types, :valid_options, :has_relations
+      attr_accessor :parent
+      attr_writer :logical_database, :uri
+    end
+
+    module ClassMethods
+      # To be called inside every class that inherits DataType
+      # +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.inspect}"
+
+        @registered_types[methname] = klass
+      end
+
+      def logical_database(val = nil)
+        @logical_database = val unless val.nil?
+        @logical_database || parent&.logical_database
+      end
+
+      def uri(val = nil)
+        @uri = val unless val.nil?
+        @uri || (parent ? parent.uri : Familia.uri)
+      end
+
+      def inherited(obj)
+        Familia.trace :DATATYPE, nil, "#{obj} is my kinda type", caller(1..1) if Familia.debug?
+        obj.logical_database = logical_database
+        obj.default_expiration = default_expiration # method added via Features::Expiration
+        obj.uri = uri
+        obj.parent = self
+        super(obj)
+      end
+
+      def valid_keys_only(opts)
+        opts.select { |k, _| DataType.valid_options.include? k }
+      end
+
+      def has_relations?
+        @has_relations ||= false
+      end
+    end
+    extend ClassMethods
+
+    attr_reader :keystring, :parent, :opts
+    attr_writer :dump_method, :load_method
+
+    # +keystring+: If parent is set, this will be used as the suffix
+    # for dbkey. Otherwise this becomes the value of the key.
+    # If this is an Array, the elements will be joined.
+    #
+    # Options:
+    #
+    # :class => A class that responds to Familia.load_method and
+    # Familia.dump_method. These will be used when loading and
+    # saving data from/to the database to unmarshal/marshal the class.
+    #
+    # :parent => The Familia object that this datatype object belongs
+    # to. This can be a class that includes Familia or an instance.
+    #
+    # :default_expiration => the time to live in seconds. When not nil, this will
+    # set the default expiration for this dbkey whenever #save is called.
+    # You can also call it explicitly via #update_expiration.
+    #
+    # :default => the default value (String-only)
+    #
+    # :logical_database => the logical database index to use (ignored if :dbclient is used).
+    #
+    # :dbclient => an instance of database client.
+    #
+    # :dbkey => a hardcoded key to use instead of the deriving the from
+    # the name and parent (e.g. a derived key: customer:custid:secret_counter).
+    #
+    # :suffix => the suffix to use for the key (e.g. 'scores' in customer:custid:scores).
+    # :prefix => the prefix to use for the key (e.g. 'customer' in customer:custid:scores).
+    #
+    # Connection precendence: uses the database connection of the parent or the
+    # value of opts[:dbclient] or Familia.dbclient (in that order).
+    def initialize(keystring, opts = {})
+      #Familia.ld " [initializing] #{self.class} #{opts}"
+      @keystring = keystring
+      @keystring = @keystring.join(Familia.delim) if @keystring.is_a?(Array)
+
+      # Remove all keys from the opts that are not in the allowed list
+      @opts = opts || {}
+      @opts = DataType.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
+
+    def dbclient
+      return Fiber[:familia_transaction] if Fiber[:familia_transaction]
+      return @dbclient if @dbclient
+
+      parent? ? parent.dbclient : Familia.dbclient(opts[:logical_database])
+    end
+
+    # Produces the full dbkey for this object.
+    #
+    # @return [String] The full dbkey.
+    #
+    # This method determines the appropriate dbkey based on the context of the DataType object:
+    #
+    # 1. If a hardcoded key is set in the options, it returns that key.
+    # 2. For instance-level DataType objects, it uses the parent instance's dbkey method.
+    # 3. For class-level DataType objects, it uses the parent class's dbkey method.
+    # 4. For standalone DataType objects, it uses the keystring as the full dbkey.
+    #
+    # For class-level DataType 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 dbkey.
+    # - Passing nil as the suffix is how class-level DataType objects are created without
+    #   the global default 'object' suffix.
+    #
+    # @example Instance-level DataType
+    #   user_instance.some_datatype.dbkey  # => "user:123:some_datatype"
+    #
+    # @example Class-level DataType
+    #   User.some_datatype.dbkey  # => "user:some_datatype"
+    #
+    # @example Standalone DataType
+    #   DataType.new("mykey").dbkey  # => "mykey"
+    #
+    # @example Class-level DataType with explicit nil suffix
+    #   User.dbkey("123", nil)  # => "user:123"
+    #
+    def dbkey
+      # 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[:dbkey] if opts[:dbkey]
+
+      if parent_instance?
+        # This is an instance-level datatype object so the parent instance's
+        # dbkey method is defined in Familia::Horreum::InstanceMethods.
+        parent.dbkey(keystring)
+      elsif parent_class?
+        # This is a class-level datatype object so the parent class' dbkey
+        # method is defined in Familia::Horreum::ClassMethods.
+        parent.dbkey(keystring, nil)
+      else
+        # This is a standalone DataType object where it's keystring
+        # is the full database key (dbkey).
+        keystring
+      end
+    end
+
+    def class?
+      !@opts[:class].to_s.empty? && @opts[:class].is_a?(Familia)
+    end
+
+    def parent_instance?
+      parent.is_a?(Familia::Horreum)
+    end
+
+    def parent_class?
+      parent.is_a?(Class) && parent <= Familia::Horreum
+    end
+
+    def parent?
+      parent_class? || parent_instance?
+    end
+
+    def parent
+      @opts[:parent]
+    end
+
+    def logical_database
+      @opts[:logical_database] || self.class.logical_database
+    end
+
+    def uri
+      # If a specific URI is set in opts, use it
+      return @opts[:uri] if @opts[:uri]
+
+      # If parent has a DB set, create a URI with that DB
+      if parent? && parent.respond_to?(:logical_database) && parent.logical_database
+        base_uri = self.class.uri || Familia.uri
+        if base_uri
+          uri_with_db = base_uri.dup
+          uri_with_db.db = parent.logical_database
+          return uri_with_db
+        end
+      end
+
+      # Otherwise fall back to class URI
+      self.class.uri
+    end
+
+    def dump_method
+      @dump_method || self.class.dump_method
+    end
+
+    def load_method
+      @load_method || self.class.load_method
+    end
+
+    include Commands
+    include Serialization
+  end
+
+  require_relative 'datatype/types/list'
+  require_relative 'datatype/types/unsorted_set'
+  require_relative 'datatype/types/sorted_set'
+  require_relative 'datatype/types/hashkey'
+  require_relative 'datatype/types/string'
+end

data/lib/familia/errors.rb

@@ -1,5 +1,5 @@
-# frozen_string_literal: true
-
+# lib/familia/errors.rb
+#
 module Familia
   class Problem < RuntimeError; end
   class NoIdentifier < Problem; end
@@ -31,6 +31,9 @@ module Familia
     end
   end
 
+  # Set Familia.connection_provider or use middleware to provide connections.
+  class NoConnectionAvailable < Problem; end
+
   # Raised when attempting to refresh an object whose key doesn't exist in Redis
   class KeyNotFoundError < Problem
     attr_reader :key