familia 2.0.0.pre4 → 2.0.0.pre6

data/lib/familia/horreum/{class_methods.rb → subclass/management.rb}

@@ -1,255 +1,21 @@
-# lib/familia/horreum/class_methods.rb
+# lib/familia/horreum/subclass/management.rb
 
 require_relative 'related_fields_management'
 
 module Familia
   class Horreum
-    # Class-level instance variables
-    # These are set up as nil initially and populated later
-    @dbclient = nil # TODO
-    @identifier_field = nil
-    @default_expiration = nil
-    @logical_database = nil
-    @uri = nil
-    @suffix = nil
-    @prefix = nil
-    @fields = nil # []
-    @class_related_fields = nil # {}
-    @related_fields = nil # {}
-    @dump_method = nil
-    @load_method = nil
-
-    # ClassMethods: Provides class-level functionality for Horreum
+    # ManagementMethods: Provides class-level functionality for Horreum
+    # records.
     #
     # This module is extended into classes that include Familia::Horreum,
     # providing methods for Database operations and object management.
     #
-    # Key features:
+    # # Key features:
     # * Includes RelatedFieldsManagement for DataType field handling
-    # * Defines methods for managing fields, identifiers, and dbkeys
     # * Provides utility methods for working with Database objects
     #
-    module ClassMethods
-      include Familia::Settings
-      include Familia::Horreum::RelatedFieldsManagement
-
-      # Sets or retrieves the unique identifier field for the class.
-      #
-      # This method defines or returns the field or method that contains the unique
-      # identifier used to generate the dbkey for the object. If a value is provided,
-      # it sets the identifier field; otherwise, it returns the current identifier field.
-      #
-      # @param [Object] val the field name or method to set as the identifier field (optional).
-      # @return [Object] the current identifier field.
-      #
-      def identifier_field(val = nil)
-        if val
-          # Validate identifier field definition at class definition time
-          case val
-          when Symbol, String, Proc
-            @identifier_field = val
-          else
-            raise Problem, <<~ERROR
-              Invalid identifier field definition: #{val.inspect}.
-              Use a field name (Symbol/String) or Proc.
-            ERROR
-          end
-        end
-        @identifier_field
-      end
-
-      # Defines a field for the class and creates accessor methods.
-      #
-      # This method defines a new field for the class, creating getter and setter
-      # instance methods similar to `attr_accessor`. It also generates a fast
-      # writer method for immediate persistence to Redis.
-      #
-      # @param [Symbol, String] name the name of the field to define.
-      #
-      def field(name)
-        fields << name
-        attr_accessor name
-
-        # Every field gets a fast attribute method for immediately persisting
-        fast_attribute! name
-      end
-
-      # Defines a fast attribute method with a bang (!) suffix for a given
-      # attribute name. Fast attribute methods are used to immediately read or
-      # write attribute values from/to Redis. Calling a fast attribute method
-      # has no effect on any of the object's other attributes and does not
-      # trigger a call to update the object's expiration time.
-      #
-      # The dynamically defined method performs the following:
-      # - Acts as both a reader and a writer method.
-      # - When called without arguments, retrieves the current value from Redis.
-      # - When called with an argument, persists the value to Database immediately.
-      # - Checks if the correct number of arguments is provided (zero or one).
-      # - Converts the provided value to a format suitable for Database storage.
-      # - Uses the existing accessor method to set the attribute value when
-      #   writing.
-      # - Persists the value to Database immediately using the hset command when
-      #   writing.
-      # - Includes custom error handling to raise an ArgumentError if the wrong
-      #   number of arguments is given.
-      # - Raises a custom error message if an exception occurs during the
-      #   execution of the method.
-      #
-      # @param [Symbol, String] name the name of the attribute for which the
-      #   fast method is defined.
-      # @return [Object] the current value of the attribute when called without
-      #   arguments.
-      # @raise [ArgumentError] if more than one argument is provided.
-      # @raise [RuntimeError] if an exception occurs during the execution of the
-      #   method.
-      #
-      def fast_attribute!(name = nil)
-        # Fast attribute accessor method for the '#{name}' attribute.
-        # This method provides immediate read and write access to the attribute
-        # in Redis.
-        #
-        # When called without arguments, it retrieves the current value of the
-        # attribute from Redis.
-        # When called with an argument, it immediately persists the new value to
-        # Redis.
-        #
-        # @overload #{name}!
-        #   Retrieves the current value of the attribute from Redis.
-        #   @return [Object] the current value of the attribute.
-        #
-        # @overload #{name}!(value)
-        #   Sets and immediately persists the new value of the attribute to
-        #   Redis.
-        #   @param value [Object] the new value to set for the attribute.
-        #   @return [Object] the newly set value.
-        #
-        # @raise [ArgumentError] if more than one argument is provided.
-        # @raise [RuntimeError] if an exception occurs during the execution of
-        #   the method.
-        #
-        # @note This method bypasses any object-level caching and interacts
-        #   directly with Redis. It does not trigger updates to other attributes
-        #   or the object's expiration time.
-        #
-        # @example
-        #
-        #      def #{name}!(*args)
-        #        # Method implementation
-        #      end
-        #
-        define_method :"#{name}!" do |*args|
-          # Check if the correct number of arguments is provided (exactly one).
-          raise ArgumentError, "wrong number of arguments (given #{args.size}, expected 0 or 1)" if args.size > 1
-
-          val = args.first
-
-          # If no value is provided to this fast attribute method, make a call
-          # to the db to return the current stored value of the hash field.
-          return hget name if val.nil?
-
-          begin
-            # Trace the operation if debugging is enabled.
-            Familia.trace :FAST_WRITER, dbclient, "#{name}: #{val.inspect}", caller(1..1) if Familia.debug?
-
-            # Convert the provided value to a format suitable for Database storage.
-            prepared = serialize_value(val)
-            Familia.ld "[.fast_attribute!] #{name} val: #{val.class} prepared: #{prepared.class}"
-
-            # Use the existing accessor method to set the attribute value.
-            send :"#{name}=", val
-
-            # Persist the value to Database immediately using the hset command.
-            hset name, prepared
-          rescue Familia::Problem => e
-            # Raise a custom error message if an exception occurs during the execution of the method.
-            raise "#{name}! method failed: #{e.message}", e.backtrace
-          end
-        end
-      end
-
-      # Returns the list of field names defined for the class in the order
-      # that they were defined. i.e. `field :a; field :b; fields => [:a, :b]`.
-      def fields
-        @fields ||= []
-        @fields
-      end
-
-      def class_related_fields
-        @class_related_fields ||= {}
-        @class_related_fields
-      end
-
-      def related_fields
-        @related_fields ||= {}
-        @related_fields
-      end
-
-      def has_relations?
-        @has_relations ||= false
-      end
-
-      def logical_database(v = nil)
-        Familia.trace :DB, Familia.dbclient, "#{@logical_database} #{v}", caller(1..1) if Familia.debug?
-        @logical_database = v unless v.nil?
-        @logical_database || parent&.logical_database
-      end
-
-      def all(suffix = nil)
-        suffix ||= self.suffix
-        # objects that could not be parsed will be nil
-        keys(suffix).filter_map { |k| find_by_key(k) }
-      end
-
-      def any?(filter = '*')
-        matching_keys_count(filter) > 0
-      end
-
-      # Returns the number of dbkeys matching the given filter pattern
-      # @param filter [String] dbkey pattern to match (default: '*')
-      # @return [Integer] Number of matching keys
-      def matching_keys_count(filter = '*')
-        dbclient.keys(dbkey(filter)).compact.size
-      end
-      alias size matching_keys_count # For backwards compatibility
-
-      def suffix(a = nil, &blk)
-        @suffix = a || blk if a || !blk.nil?
-        @suffix || Familia.default_suffix
-      end
-
-      # Sets or retrieves the prefix for generating Redis keys.
-      #
-      # @param a [String, Symbol, nil] the prefix to set (optional).
-      # @return [String, Symbol] the current prefix.
-      #
-      # The exception is only raised when both @prefix is nil/falsy AND name is nil,
-      # which typically occurs with anonymous classes that haven't had their prefix
-      # explicitly set.
-      #
-      def prefix(a = nil)
-        @prefix = a if a
-        @prefix || begin
-          if name.nil?
-            raise Problem, 'Cannot generate prefix for anonymous class. ' \
-                           'Use `prefix` method to set explicitly.'
-          end
-          name.downcase.gsub('::', Familia.delim).to_sym
-        end
-      end
-
-      # Converts the class name into a string that can be used to look up
-      # configuration values. This is particularly useful when mapping
-      # familia models with specific database numbers in the configuration.
-      #
-      # @example V2::Session.config_name => 'session'
-      #
-      # @return [String] The underscored class name as a string
-      def config_name
-        name.split('::').last
-          .gsub(/([A-Z]+)([A-Z][a-z])/, '\1_\2')
-          .gsub(/([a-z\d])([A-Z])/, '\1_\2')
-          .downcase
-      end
+    module ManagementMethods
+      include Familia::Horreum::RelatedFieldsManagement # Provides DataType query methods
 
       # Creates and persists a new instance of the class.
       #
@@ -289,9 +55,7 @@ module Familia
       #
       def create(*, **)
         fobj = new(*, **)
-        raise Familia::Problem, "#{self} already exists: #{fobj.dbkey}" if fobj.exists?
-
-        fobj.save
+        fobj.save_if_not_exists
         fobj
       end
 
@@ -406,8 +170,8 @@ module Familia
       #   User.exists?(123)  # Returns true if user:123:object exists in Redis
       #
       def exists?(identifier, suffix = nil)
+        raise NoIdentifier, "Empty identifier" if identifier.to_s.empty?
         suffix ||= self.suffix
-        return false if identifier.to_s.empty?
 
         objkey = dbkey identifier, suffix
 
@@ -468,21 +232,34 @@ module Familia
       # distinction b/c passing in an explicitly nil is how DataType objects
       # at the class level are created without the global default 'object'
       # suffix. See DataType#dbkey "parent_class?" for more details.
+      #
       def dbkey(identifier, suffix = self.suffix)
-        # Familia.ld "[.dbkey] #{identifier} for #{self} (suffix:#{suffix})"
-        raise NoIdentifier, self if identifier.to_s.empty?
+        if identifier.to_s.empty?
+          raise NoIdentifier, "#{self} requires non-empty identifier, got: #{identifier.inspect}"
+        end
 
         identifier &&= identifier.to_s
         Familia.dbkey(prefix, identifier, suffix)
       end
 
-      def dump_method
-        @dump_method || :to_json # Familia.dump_method
+      def all(suffix = nil)
+        suffix ||= self.suffix
+        # objects that could not be parsed will be nil
+        keys(suffix).filter_map { |k| find_by_key(k) }
+      end
+
+      def any?(filter = '*')
+        matching_keys_count(filter) > 0
       end
 
-      def load_method
-        @load_method || :from_json # Familia.load_method
+      # Returns the number of dbkeys matching the given filter pattern
+      # @param filter [String] dbkey pattern to match (default: '*')
+      # @return [Integer] Number of matching keys
+      #
+      def matching_keys_count(filter = '*')
+        dbclient.keys(dbkey(filter)).compact.size
       end
+      alias size matching_keys_count # For backwards compatibility
     end
   end
 end

data/lib/familia/horreum/{related_fields_management.rb → subclass/related_fields_management.rb}

@@ -15,7 +15,7 @@ module Familia
     #
     # Usage:
     #   Include this module in classes that need DataType management
-    #   Call setup_relations_accessors to initialize the feature
+    #   Call setup_related_fields_accessors to initialize the feature
     #
     module RelatedFieldsManagement
       # A practical flag to indicate that a Horreum member has relations,
@@ -23,17 +23,22 @@ module Familia
       @has_relations = nil
 
       def self.included(base)
-        base.extend(ClassMethods)
-        base.setup_relations_accessors
+        base.extend(RelatedFieldsAccessors)
+        base.setup_related_fields_accessors
       end
 
-      module ClassMethods
+      module RelatedFieldsAccessors
         # Sets up all DataType related methods
-        # This method is the core of the metaprogramming logic
+        # This method generates the following for each registered DataType:
         #
-        def setup_relations_accessors
+        # Instance methods: set(), list(), hashkey(), sorted_set(), etc.
+        # Query methods: set?(), list?(), hashkey?(), sorted_set?(), etc.
+        # Collection methods: sets(), lists(), hashkeys(), sorted_sets(), etc.
+        # Class methods: class_set(), class_list(), etc.
+        #
+        def setup_related_fields_accessors
           Familia::DataType.registered_types.each_pair do |kind, klass|
-            Familia.ld "[registered_types] #{kind} => #{klass}"
+            Familia.trace :registered_types, kind, klass, caller(1..1) if Familia.debug?
 
             # Dynamically define instance-level relation methods
             #
@@ -86,11 +91,11 @@ module Familia
           end
         end
       end
-      # End of ClassMethods module
+      # End of RelatedFieldsAccessors module
 
       # Creates an instance-level relation
       def attach_instance_related_field(name, klass, opts)
-        Familia.ld "[#{self}##{name}] Attaching instance-level #{klass} #{opts}"
+        Familia.trace :attach_instance, "#{name} #{klass}", opts, caller(1..1) if Familia.debug?
         raise ArgumentError, "Name is blank (#{klass})" if name.to_s.empty?
 
         name = name.to_s.to_sym
@@ -115,7 +120,7 @@ module Familia
 
       # Creates a class-level relation
       def attach_class_related_field(name, klass, opts)
-        Familia.ld "[#{self}.#{name}] Attaching class-level #{klass} #{opts}"
+        Familia.trace :attach_class_related_field, "#{name} #{klass}", opts, caller(1..1) if Familia.debug?
         raise ArgumentError, 'Name is blank (klass)' if name.to_s.empty?
 
         name = name.to_s.to_sym

data/lib/familia/horreum.rb

@@ -1,5 +1,10 @@
 # lib/familia/horreum.rb
 
+require_relative 'horreum/subclass/definition'
+require_relative 'horreum/subclass/management'
+require_relative 'horreum/shared/settings'
+require_relative 'horreum/core'
+
 module Familia
   #
   # Horreum: A module for managing Redis-based object storage and relationships
@@ -23,6 +28,8 @@ module Familia
   #
   class Horreum
     include Familia::Base
+    include Familia::Horreum::Core
+    include Familia::Horreum::Settings
 
     # Singleton Class Context
     #
@@ -62,12 +69,14 @@ module Familia
       # Extends ClassMethods to subclasses and tracks Familia members
       def inherited(member)
         Familia.trace :HORREUM, nil, "Welcome #{member} to the family", caller(1..1) if Familia.debug?
-        member.extend(ClassMethods)
-        member.extend(Connection)
-        member.extend(Features)
 
-        # Tracks all the classes/modules that include Familia. It's
-        # 10pm, do you know where you Familia members are?
+        # Class-level functionality extensions:
+        member.extend(Familia::Horreum::DefinitionMethods)    # field(), identifier_field(), dbkey()
+        member.extend(Familia::Horreum::ManagementMethods)    # create(), find(), destroy!()
+        member.extend(Familia::Horreum::Connection)           # dbclient, connection management
+        member.extend(Familia::Features)             # feature() method for optional modules
+
+        # Track all classes that inherit from Horreum
         Familia.members << member
         super
       end
@@ -83,7 +92,7 @@ module Familia
     #   Session.new({sessid: "abc123", custid: "user456"}) # legacy hash (robust)
     #
     def initialize(*args, **kwargs)
-      Familia.ld "[Horreum] Initializing #{self.class}"
+      Familia.trace :INITIALIZE, dbclient, "Initializing #{self.class}", caller(1..1) if Familia.debug?
       initialize_relatives
 
       # No longer auto-create a key field - the identifier method will
@@ -122,7 +131,7 @@ module Familia
       elsif args.any?
         initialize_with_positional_args(*args)
       else
-        Familia.ld "[Horreum] #{self.class} initialized with no arguments"
+      Familia.trace :INITIALIZE, dbclient, "#{self.class} initialized with no arguments", caller(1..1) if Familia.debug?
         # Default values are intentionally NOT set here to:
         # - Maintain Database memory efficiency (only store non-nil values)
         # - Avoid conflicts with nil-skipping serialization logic
@@ -133,7 +142,11 @@ module Familia
       # Implementing classes can define an init method to do any
       # additional initialization. Notice that this is called
       # after the fields are set.
-      init if respond_to?(:init)
+      init
+    end
+
+    def init(*args, **kwargs)
+      # Default no-op
     end
 
     # Sets up related Database objects for the instance
@@ -150,10 +163,10 @@ module Familia
       #     familia_object.dbkey              == v1:bone:INDEXVALUE:object
       #     familia_object.related_object.dbkey == v1:bone:INDEXVALUE:name
       #
-      self.class.related_fields.each_pair do |name, datatype_definition|
-        klass = datatype_definition.klass
-        opts = datatype_definition.opts
-        Familia.ld "[#{self.class}] initialize_relatives #{name} => #{klass} #{opts.keys}"
+      self.class.related_fields.each_pair do |name, data_type_definition|
+        klass = data_type_definition.klass
+        opts = data_type_definition.opts
+        Familia.trace :INITIALIZE_RELATIVES, dbclient, "#{name} => #{klass} #{opts.keys}", caller(1..1) if Familia.debug?
 
         # As a subclass of Familia::Horreum, we add ourselves as the parent
         # automatically. This is what determines the dbkey for DataType
@@ -215,7 +228,9 @@ module Familia
         # we use symbols. So we check for both.
         value = fields[field.to_sym] || fields[field.to_s]
         if value
-          send(:"#{field}=", value)
+          # Use the mapped method name, not the field name
+          method_name = self.class.field_method_map[field] || field
+          send(:"#{method_name}=", value)
           field.to_sym
         end
       end
@@ -283,9 +298,8 @@ module Familia
     #   # => #<Redis client v5.4.1 for redis://localhost:6379/0>
     #
     def dbclient
-      conn = Fiber[:familia_transaction] || @dbclient || self.class.dbclient
+      Fiber[:familia_transaction] || @dbclient || self.class.dbclient
       # conn.select(self.class.logical_database)
-      conn
     end
 
     def generate_id
@@ -299,14 +313,8 @@ module Familia
       # This allows passing Familia objects directly where strings are expected
       # without requiring explicit .identifier calls
       return super if identifier.to_s.empty?
+
       identifier.to_s
     end
   end
 end
-
-require_relative 'horreum/class_methods'
-require_relative 'horreum/commands'
-require_relative 'horreum/connection'
-require_relative 'horreum/serialization'
-require_relative 'horreum/settings'
-require_relative 'horreum/utils'

data/lib/familia/logging.rb

@@ -6,14 +6,14 @@ require 'logger'
 module Familia
   @logger = Logger.new($stdout)
   @logger.progname = name
-  @logger.formatter = proc do |severity, datetime, progname, msg|
-    severity_letter = severity[0]  # Get the first letter of the severity
+  @logger.formatter = proc do |severity, datetime, _progname, msg|
+    severity_letter = severity[0] # Get the first letter of the severity
     pid = Process.pid
     thread_id = Thread.current.object_id
-    full_path, line = caller[4].split(":")[0..1]
+    full_path, line = caller(5..5).first.split(':')[0..1]
     parent_path = Pathname.new(full_path).ascend.find { |p| p.basename.to_s == 'familia' }
     relative_path = full_path.sub(parent_path.to_s, 'familia')
-    utc_datetime = datetime.utc.strftime("%m-%d %H:%M:%S.%6N")
+    utc_datetime = datetime.utc.strftime('%m-%d %H:%M:%S.%6N')
 
     # Get the severity letter from the thread local variable or use
     # the default. The thread local variable is set in the trace
@@ -115,6 +115,7 @@ module Familia
 
     def ld(*msg)
       return unless Familia.debug?
+
       @logger.debug(*msg)
     end
 
@@ -152,15 +153,15 @@ module Familia
       # and multi blocks. In some contexts it's nil where the
       # database connection isn't relevant.
       instance_id = if dbclient
-        case dbclient
-        when Redis
-          dbclient.id.respond_to?(:to_s) ? dbclient.id.to_s : dbclient.class.name
-        when Redis::Future
-          "Redis::Future"
-        else
-        dbclient.class.name
-        end
-      end
+                      case dbclient
+                      when Redis
+                        dbclient.id.respond_to?(:to_s) ? dbclient.id.to_s : dbclient.class.name
+                      when Redis::Future
+                        'Redis::Future'
+                      else
+                        dbclient.class.name
+                      end
+                    end
 
       codeline = if context
                    context = [context].flatten
@@ -170,7 +171,6 @@ module Familia
 
       @logger.trace format('[%s] %s -> %s <- at %s', label, instance_id, ident, codeline)
     end
-
   end
 end
 

data/lib/familia/settings.rb

@@ -1,16 +1,18 @@
 # lib/familia/settings.rb
 
 module Familia
-
   @delim = ':'
   @prefix = nil
   @suffix = :object
   @default_expiration = 0 # see update_expiration. Zero is skip. nil is an exception.
   @logical_database = nil
+  @encryption_keys = nil
+  @current_key_version = nil
+  @encryption_personalization = 'FamilialMatters'
 
   module Settings
-
-    attr_writer :delim, :suffix, :default_expiration, :logical_database, :prefix
+    attr_writer :delim, :suffix, :default_expiration, :logical_database, :prefix, :encryption_keys,
+                :current_key_version, :encryption_personalization
 
     def delim(val = nil)
       @delim = val if val
@@ -44,5 +46,39 @@ module Familia
       suffix
     end
 
+    def encryption_keys(val = nil)
+      @encryption_keys = val if val
+      @encryption_keys
+    end
+
+    def current_key_version(val = nil)
+      @current_key_version = val if val
+      @current_key_version
+    end
+
+    # Personalization string for BLAKE2b key derivation in XChaCha20Poly1305.
+    # This provides cryptographic domain separation, ensuring derived keys are
+    # unique per application even with identical master keys and contexts.
+    # Must be 16 bytes or less (automatically padded with null bytes).
+    #
+    # @example
+    #   Familia.configure do |config|
+    #     config.encryption_personalization = 'MyApp1.0'
+    #   end
+    #
+    # @param val [String, nil] The personalization string, or nil to get current value
+    # @return [String] Current personalization string
+    def encryption_personalization(val = nil)
+      if val
+        raise ArgumentError, 'Personalization string cannot exceed 16 bytes' if val.bytesize > 16
+
+        @encryption_personalization = val
+      end
+      @encryption_personalization
+    end
+
+    def config
+      self
+    end
   end
 end

data/lib/familia/utils.rb

@@ -1,6 +1,9 @@
 # lib/familia/utils.rb
 
 module Familia
+
+  # Family-related utility methods
+  #
   module Utils
 
     # Joins array elements with Familia delimiter
@@ -145,5 +148,47 @@ module Familia
       end
     end
 
+    # Converts an absolute file path to a path relative to the current working
+    # directory. This simplifies logging and error reporting by showing
+    # only the relevant parts of file paths instead of lengthy absolute paths.
+    #
+    # @param filepath [String, Pathname] The file path to convert
+    # @return [Pathname, String, nil] A relative path from current directory,
+    #   basename if path goes outside current directory, or nil if filepath is nil
+    #
+    # @example Using current directory as base
+    #   Utils.pretty_path("/home/dev/project/lib/config.rb") # => "lib/config.rb"
+    #
+    # @example Path outside current directory
+    #   Utils.pretty_path("/etc/hosts") # => "hosts"
+    #
+    # @example Nil input
+    #   Utils.pretty_path(nil) # => nil
+    #
+    # @see Pathname#relative_path_from Ruby standard library documentation
+    def pretty_path(filepath)
+      return nil if filepath.nil?
+
+      basepath = Dir.pwd
+      relative_path = Pathname.new(filepath).relative_path_from(basepath)
+      if relative_path.to_s.start_with?('..')
+        File.basename(filepath)
+      else
+        relative_path
+      end
+    end
+
+    # Formats a stack trace with pretty file paths for improved readability
+    #
+    # @param limit [Integer] Maximum number of stack frames to include (default: 3)
+    # @return [String] Formatted stack trace with relative paths joined by newlines
+    #
+    # @example
+    #   Utils.pretty_stack(limit: 10)
+    #   # => "lib/models/user.rb:25:in `save'\n lib/controllers/app.rb:45:in `create'"
+    def pretty_stack(skip: 1, limit: 5)
+      caller(skip..(skip + limit + 1)).first(limit).map { |frame| pretty_path(frame) }.join("\n")
+    end
+
   end
 end