familia 1.2.3 → 2.0.0.pre.pre

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

data/lib/familia/features/expiration.rb

@@ -1,19 +1,18 @@
-# rubocop:disable all
-# frozen_string_literal: true
+# lib/familia/features/expiration.rb
 
 
 module Familia::Features
 
   module Expiration
-    @ttl = nil
+    @default_expiration = nil
 
     module ClassMethods
 
-      attr_writer :ttl
+      attr_writer :default_expiration
 
-      def ttl(v = nil)
-        @ttl = v.to_f unless v.nil?
-        @ttl || parent&.ttl || Familia.ttl
+      def default_expiration(v = nil)
+        @default_expiration = v.to_f unless v.nil?
+        @default_expiration || parent&.default_expiration || Familia.default_expiration
       end
 
     end
@@ -22,51 +21,51 @@ module Familia::Features
       Familia.ld "[#{base}] Loaded #{self}"
       base.extend ClassMethods
 
-      # Optionally define ttl in the class to make
+      # Optionally define default_expiration in the class to make
       # sure we always have an array to work with.
-      unless base.instance_variable_defined?(:@ttl)
-        base.instance_variable_set(:@ttl, @ttl) # set above
+      unless base.instance_variable_defined?(:@default_expiration)
+        base.instance_variable_set(:@default_expiration, @default_expiration) # set above
       end
     end
 
-    def ttl=(v)
-      @ttl = v.to_f
+    def default_expiration=(v)
+      @default_expiration = v.to_f
     end
 
-    def ttl
-      @ttl || self.class.ttl
+    def default_expiration
+      @default_expiration || self.class.default_expiration
     end
 
-    # Sets an expiration time for the Redis data associated with this object.
+    # Sets an expiration time for the Database data associated with this object.
     #
     # This method allows setting a Time To Live (TTL) for the data in Redis,
     # after which it will be automatically removed.
     #
-    # @param ttl [Integer, nil] The Time To Live in seconds. If nil, the default
+    # @param default_expiration [Integer, nil] The Time To Live in seconds. If nil, the default
     #   TTL will be used.
     #
     # @return [Boolean] Returns true if the expiration was set successfully,
     #   false otherwise.
     #
     # @example Setting an expiration of one day
-    #   object.update_expiration(ttl: 86400)
+    #   object.update_expiration(default_expiration: 86400)
     #
-    # @note If TTL is set to zero, the expiration will be removed, making the
+    # @note If Default expiration is set to zero, the expiration will be removed, making the
     #   data persist indefinitely.
     #
-    # @raise [Familia::Problem] Raises an error if the TTL is not a non-negative
+    # @raise [Familia::Problem] Raises an error if the default expiration is not a non-negative
     #   integer.
     #
-    def update_expiration(ttl: nil)
-      ttl ||= self.ttl
+    def update_expiration(default_expiration: nil)
+      default_expiration ||= self.default_expiration
 
       if self.class.has_relations?
-        Familia.ld "[update_expiration] #{self.class} has relations: #{self.class.redis_types.keys}"
-        self.class.redis_types.each do |name, definition|
-          next if definition.opts[:ttl].nil?
+        Familia.ld "[update_expiration] #{self.class} has relations: #{self.class.related_fields.keys}"
+        self.class.related_fields.each do |name, definition|
+          next if definition.opts[:default_expiration].nil?
           obj = send(name)
-          Familia.ld "[update_expiration] Updating expiration for #{name} (#{obj.rediskey}) to #{ttl}"
-          obj.update_expiration(ttl: ttl)
+          Familia.ld "[update_expiration] Updating expiration for #{name} (#{obj.dbkey}) to #{default_expiration}"
+          obj.update_expiration(default_expiration: default_expiration)
         end
       end
 
@@ -75,23 +74,23 @@ module Familia::Features
       # retention issues (e.g. not removed in a timely fashion).
       #
       # For the same reason, we don't want to default to 0 bc there's not a
-      # good reason for the ttl to not be set in the first place. If the
-      # class doesn't have a ttl, the default comes from Familia.ttl (which
+      # good reason for the default_expiration to not be set in the first place. If the
+      # class doesn't have a default_expiration, the default comes from Familia.default_expiration (which
       # is 0).
-      unless ttl.is_a?(Numeric)
-        raise Familia::Problem, "TTL must be a number (#{ttl.class} in #{self.class})"
+      unless default_expiration.is_a?(Numeric)
+        raise Familia::Problem, "Default expiration must be a number (#{default_expiration.class} in #{self.class})"
       end
 
-      if ttl.zero?
-        return Familia.ld "[update_expiration] No expiration for #{self.class} (#{rediskey})"
+      if default_expiration.zero?
+        return Familia.ld "[update_expiration] No expiration for #{self.class} (#{dbkey})"
       end
 
-      Familia.ld "[update_expiration] Expires #{rediskey} in #{ttl} seconds"
+      Familia.ld "[update_expiration] Expires #{dbkey} in #{default_expiration} seconds"
 
       # Redis' EXPIRE command returns 1 if the timeout was set, 0 if key does
       # not exist or the timeout could not be set. Via redis-rb here, it's
       # a bool.
-      expire(ttl)
+      expire(default_expiration)
     end
 
     extend ClassMethods

data/lib/familia/features/quantization.rb

@@ -1,4 +1,4 @@
-# rubocop:disable all
+# lib/familia/features/quantization.rb
 
 module Familia::Features
 
@@ -28,7 +28,13 @@ module Familia::Features
         if quantum.is_a?(Array)
           quantum, pattern = quantum
         end
-        quantum ||= @opts[:quantize] || ttl || 10.minutes
+
+        # Previously we erronously included `@opts.fetch(:quantize, nil)` in
+        # the list of default values here, but @opts is for horreum instances
+        # not at the class level. This method `qstamp` is part of the initial
+        # definition for whatever horreum subclass we're in right now. That's
+        # why default_expiration works (e.g. `class Plop; feature :quantization; default_expiration 90; end`).
+        quantum ||= default_expiration || 10.minutes
 
         # Validate quantum
         unless quantum.is_a?(Numeric) && quantum.positive?
@@ -46,7 +52,7 @@ module Familia::Features
     end
 
     def qstamp(quantum = nil, pattern: nil, time: nil)
-      self.class.qstamp(quantum || self.class.ttl, pattern: pattern, time: time)
+      self.class.qstamp(quantum || self.class.default_expiration, pattern: pattern, time: time)
     end
 
     extend ClassMethods

data/lib/familia/features/safe_dump.rb

@@ -1,5 +1,4 @@
-# rubocop:disable all
-# frozen_string_literal: true
+# lib/familia/features/safe_dump.rb
 
 
 module Familia::Features
@@ -87,7 +86,7 @@ module Familia::Features
             field_name = el
             callable = lambda { |obj|
               if obj.respond_to?(:[]) && obj[field_name]
-                obj[field_name] # Familia::RedisType classes
+                obj[field_name] # Familia::DataType classes
               elsif obj.respond_to?(field_name)
                 obj.send(field_name) # Onetime::Models::RedisHash classes via method_missing 😩
               end

data/lib/familia/features.rb

@@ -1,4 +1,4 @@
-# rubocop:disable all
+# lib/familia/features.rb
 
 module Familia
 
@@ -28,7 +28,7 @@ module Familia
         # Extend the Familia::Base subclass (e.g. Customer) with the feature module
         include klass
 
-        # NOTE: We may also want to extend Familia::RedisType here so that we can
+        # NOTE: We may also want to extend Familia::DataType here so that we can
         # call safe_dump on relations fields (e.g. list, set, zset, hashkey). Or
         # maybe that only makes sense for hashk/object relations.
         #