familia 2.0.0.pre10 → 2.0.0.pre13

data/lib/familia/features/object_identifier.rb

@@ -0,0 +1,307 @@
+# lib/familia/features/object_identifier.rb
+
+module Familia
+  module Features
+    # ObjectIdentifier is a feature that provides unique object identifier management
+    # with configurable generation strategies. Object identifiers are crucial for
+    # distinguishing objects in distributed systems and providing stable references.
+    #
+    # Object identifiers are:
+    # - Unique across the system
+    # - Persistent (stored in Redis/Valkey)
+    # - Lazily generated (only when first accessed)
+    # - Configurable (multiple generation strategies available)
+    # - Preserved during initialization (existing IDs never regenerated)
+    #
+    # Generation Strategies:
+    # - :uuid_v7 (default) - UUID version 7 with embedded timestamp for sortability
+    # - :uuid_v4 - UUID version 4 for compatibility with legacy systems
+    # - :hex - High-entropy hexadecimal identifier using SecureIdentifier
+    # - Proc - Custom generation logic provided as a callable
+    #
+    # Example Usage:
+    #
+    #   # Default UUID v7 generation
+    #   class User < Familia::Horreum
+    #     feature :object_identifier
+    #     field :email
+    #   end
+    #
+    #   user = User.new(email: 'user@example.com')
+    #   user.objid  # => "01234567-89ab-7def-8000-123456789abc" (UUID v7)
+    #
+    #   # UUID v4 for legacy compatibility
+    #   class LegacyUser < Familia::Horreum
+    #     feature :object_identifier, generator: :uuid_v4
+    #     field :email
+    #   end
+    #
+    #   legacy = LegacyUser.new(email: 'legacy@example.com')
+    #   legacy.objid  # => "f47ac10b-58cc-4372-a567-0e02b2c3d479" (UUID v4)
+    #
+    #   # High-entropy hex for security-sensitive applications
+    #   class SecureDocument < Familia::Horreum
+    #     feature :object_identifier, generator: :hex
+    #     field :title
+    #   end
+    #
+    #   doc = SecureDocument.new(title: 'Classified')
+    #   doc.objid  # => "a1b2c3d4e5f6..." (256-bit hex)
+    #
+    #   # Custom generation strategy
+    #   class TimestampedItem < Familia::Horreum
+    #     feature :object_identifier, generator: -> { "item_#{Time.now.to_i}_#{SecureRandom.hex(4)}" }
+    #     field :data
+    #   end
+    #
+    #   item = TimestampedItem.new(data: 'test')
+    #   item.objid  # => "item_1693857600_a1b2c3d4"
+    #
+    # Data Integrity Guarantees:
+    #
+    # The feature preserves the object identifier passed during initialization,
+    # ensuring that existing objects loaded from Redis maintain their IDs:
+    #
+    #   # Loading existing object from Redis preserves ID
+    #   existing = User.new(objid: 'existing-uuid-value', email: 'existing@example.com')
+    #   existing.objid  # => "existing-uuid-value" (preserved, not regenerated)
+    #
+    # Performance Characteristics:
+    #
+    # - Lazy Generation: IDs generated only when first accessed
+    # - Thread-Safe: Generator strategy configured once during initialization
+    # - Memory Efficient: No unnecessary ID generation for unused objects
+    # - Redis Efficient: Only persists non-nil values to conserve memory
+    #
+    # Security Considerations:
+    #
+    # - UUID v7 includes timestamp information (may leak timing data)
+    # - UUID v4 provides strong randomness without timing correlation
+    # - Hex generator provides maximum entropy (256 bits) for security-critical use cases
+    # - Custom generators allow domain-specific security requirements
+    #
+    module ObjectIdentifier
+      DEFAULT_GENERATOR = :uuid_v7
+
+      def self.included(base)
+        Familia.trace :LOADED, self, base, caller(1..1) if Familia.debug?
+        base.extend ClassMethods
+
+        # Ensure default generator is set in feature options
+        base.add_feature_options(:object_identifier, generator: DEFAULT_GENERATOR)
+
+        # Register the objid field using a simple custom field type
+        base.register_field_type(ObjectIdentifierFieldType.new(:objid, as: :objid, fast_method: false))
+      end
+
+      # ObjectIdentifierFieldType - Generate a unique object identifier
+      #
+      # Object identifier fields automatically generate unique identifiers when first
+      # accessed if not already set. The generation strategy is configurable via
+      # feature options. These fields preserve any values set during initialization
+      # to ensure data integrity when loading existing objects from Redis.
+      #
+      # The field type tracks the generator used for each objid to provide provenance
+      # information for security-sensitive operations like external identifier generation.
+      # This ensures that downstream features can validate the source and format of
+      # object identifiers without relying on string pattern matching, which cannot
+      # reliably distinguish between uuid7, uuid4, or hex formats in all cases.
+      #
+      # @example Using object identifier fields
+      #   class User < Familia::Horreum
+      #     feature :object_identifier, generator: :uuid_v7
+      #   end
+      #
+      #   user = User.new
+      #   user.objid  # Generates UUID v7 on first access
+      #   user.objid_generator_used  # => :uuid_v7
+      #
+      #   # Loading existing object preserves ID but cannot determine original generator
+      #   user2 = User.new(objid: "existing-uuid")
+      #   user2.objid  # Returns "existing-uuid", not regenerated
+      #   user2.objid_generator_used  # => nil (unknown provenance)
+      #
+      class ObjectIdentifierFieldType < Familia::FieldType
+        # Override getter to provide lazy generation with configured strategy
+        #
+        # Generates the identifier using the configured strategy if not already set.
+        # This preserves any values set during initialization while providing
+        # automatic generation for new objects.
+        #
+        # @param klass [Class] The class to define the method on
+        #
+        def define_getter(klass)
+          field_name = @name
+          method_name = @method_name
+
+          handle_method_conflict(klass, method_name) do
+            klass.define_method method_name do
+              # Check if we already have a value (from initialization or previous generation)
+              existing_value = instance_variable_get(:"@#{field_name}")
+              return existing_value unless existing_value.nil?
+
+              # Generate new identifier using configured strategy
+              generated_id = generate_object_identifier
+              instance_variable_set(:"@#{field_name}", generated_id)
+
+              # Track which generator was used for provenance
+              options = self.class.feature_options(:object_identifier)
+              generator = options[:generator] || DEFAULT_GENERATOR
+              instance_variable_set(:"@#{field_name}_generator_used", generator)
+
+              generated_id
+            end
+          end
+
+          # Define getter for generator provenance tracking
+          handle_method_conflict(klass, :"#{method_name}_generator_used") do
+            klass.define_method :"#{method_name}_generator_used" do
+              instance_variable_get(:"@#{field_name}_generator_used")
+            end
+          end
+        end
+
+        # Override setter to preserve values during initialization
+        #
+        # This ensures that values passed during object initialization
+        # (e.g., when loading from Redis) are preserved and not overwritten
+        # by the lazy generation logic.
+        #
+        # @param klass [Class] The class to define the method on
+        #
+        def define_setter(klass)
+          field_name = @name
+          method_name = @method_name
+
+          handle_method_conflict(klass, :"#{method_name}=") do
+            klass.define_method :"#{method_name}=" do |value|
+              instance_variable_set(:"@#{field_name}", value)
+
+              # When setting objid from external source (e.g., loading from Redis),
+              # we cannot determine the original generator, so we clear the provenance
+              # tracking to indicate unknown origin. This prevents false assumptions
+              # about the security properties of externally-provided identifiers.
+              instance_variable_set(:"@#{field_name}_generator_used", nil)
+            end
+          end
+        end
+
+        # Object identifier fields are persisted to database
+        #
+        # @return [Boolean] true - An object identifier is always persisted
+        #
+        def persistent?
+          true
+        end
+
+        # Category for object identifier fields
+        #
+        # @return [Symbol] :object_identifier
+        #
+        def category
+          :object_identifier
+        end
+      end
+
+      module ClassMethods
+        # Generate a new object identifier using the configured strategy
+        #
+        # @return [String] A new unique identifier
+        #
+        def generate_object_identifier
+          options = feature_options(:object_identifier)
+          generator = options[:generator] || DEFAULT_GENERATOR
+
+          case generator
+          when :uuid_v7
+            SecureRandom.uuid_v7
+          when :uuid_v4
+            SecureRandom.uuid_v4
+          when :hex
+            Familia.generate_hex_id
+          when Proc
+            generator.call
+          else
+            unless generator.respond_to?(:call)
+              raise Familia::Problem, "Invalid object identifier generator: #{generator.inspect}"
+            end
+
+            generator.call
+
+          end
+        end
+
+        # Find an object by its object identifier
+        #
+        # @param objid [String] The object identifier to search for
+        # @return [Object, nil] The object if found, nil otherwise
+        #
+        def find_by_objid(objid)
+          return nil if objid.to_s.empty?
+
+          if Familia.debug?
+            reference = caller(1..1).first
+            Familia.trace :FIND_BY_OBJID, Familia.dbclient, objid, reference
+          end
+
+          # Use the object identifier as the key for lookup
+          # This is a simple stub implementation - would need more sophisticated
+          # search logic in a real application
+          find_by_id(objid)
+        rescue Familia::NotFound
+          nil
+        end
+      end
+
+      # Instance method for generating object identifier using configured strategy
+      #
+      # This method is called by the ObjectIdentifierFieldType when lazy generation
+      # is needed. It uses the class-level generator configuration to create new IDs.
+      #
+      # @return [String] A newly generated unique identifier
+      # @private
+      #
+      def generate_object_identifier
+        self.class.generate_object_identifier
+      end
+
+      # Full-length alias for objid for clarity when needed
+      #
+      # @return [String] The object identifier
+      #
+      def object_identifier
+        objid
+      end
+
+      # Full-length alias setter for objid
+      #
+      # @param value [String] The object identifier to set
+      #
+      def object_identifier=(value)
+        self.objid = value
+      end
+
+      # Initialize object identifier configuration
+      #
+      # Called during object initialization to set up the ID generation strategy.
+      # This hook is called AFTER field initialization, ensuring that any objid
+      # values passed during construction are preserved.
+      #
+      def init
+        super if defined?(super)
+
+        # The generator strategy is configured at the class level via feature options.
+        # We don't need to store it per-instance since it's consistent for the class.
+        # The actual generation happens lazily in the getter when needed.
+
+        return unless Familia.debug?
+
+        options = self.class.feature_options(:object_identifier)
+        generator = options[:generator] || DEFAULT_GENERATOR
+        Familia.trace :OBJID_INIT, dbclient, "Generator strategy: #{generator}", caller(1..1)
+      end
+
+      Familia::Base.add_feature self, :object_identifier, depends_on: []
+    end
+  end
+end

data/lib/familia/features/quantization.rb

@@ -245,11 +245,16 @@ module Familia
     #   NoDefault.qstamp()  # Uses 10.minutes as fallback quantum
     #
     module Quantization
+
+      using Familia::Refinements::TimeUtils
+
       def self.included(base)
         Familia.trace :LOADED, self, base, caller(1..1) if Familia.debug?
         base.extend ClassMethods
       end
 
+      # Familia::Quantization::ClassMethods
+      #
       module ClassMethods
         # Generates a quantized timestamp based on the given parameters
         #

data/lib/familia/features/safe_dump.rb

@@ -1,12 +1,19 @@
 # lib/familia/features/safe_dump.rb
 
+
+# rubocop:disable ThreadSafety/ClassInstanceVariable
+#
+#   Class instance variables are used here for feature configuration
+#   (e.g., @dump_method, @load_method). These are set once and not mutated
+#   at runtime, so thread safety is not a concern for this feature.
+#
 module Familia::Features
   # SafeDump is a mixin that allows models to define a list of fields that are
   # safe to dump. This is useful for serializing objects to JSON or other
   # formats where you want to ensure that only certain fields are exposed.
   #
-  # To use SafeDump, include it in your model and define a list of fields that
-  # are safe to dump. The fields can be either symbols or hashes. If a field is
+  # To use SafeDump, include it in your model and use the DSL methods to define
+  # safe dump fields. The fields can be either symbols or hashes. If a field is
   # a symbol, the method with the same name will be called on the object to
   # retrieve the value. If the field is a hash, the key is the field name and
   # the value is a lambda that will be called with the object as an argument.
@@ -19,97 +26,91 @@ module Familia::Features
   #
   #   feature :safe_dump
   #
-  #   @safe_dump_fields = [
-  #     :objid,
-  #     :updated,
-  #     :created,
-  #     { :active => ->(obj) { obj.active? } }
-  #   ]
-  #
-  # Internally, all fields are normalized to the hash syntax and stored in
-  # @safe_dump_field_map. `SafeDump.safe_dump_fields` returns only the list
-  # of symbols in the order they were defined. From the example above, it would
-  # return `[:objid, :updated, :created, :active]`.
+  #   safe_dump_field :objid
+  #   safe_dump_field :updated
+  #   safe_dump_field :created
+  #   safe_dump_field :active, ->(obj) { obj.active? }
   #
-  # Standalone Usage:
-  #
-  # You can also use SafeDump by including it in your model and defining the
-  # safe dump fields using the class instance variable `@safe_dump_fields`.
-  #
-  # Example:
+  # Alternatively, you can define multiple fields at once:
   #
-  #   class MyModel
-  #     include Familia::Features::SafeDump
+  #   safe_dump_fields :objid, :updated, :created,
+  #                    { active: ->(obj) { obj.active? } }
   #
-  #     @safe_dump_fields = [
-  #       :id, :name, { active: ->(obj) { obj.active? } }
-  #     ]
-  #   end
+  # Internally, all fields are normalized to the hash syntax and stored in
+  # @safe_dump_field_map. `SafeDump.safe_dump_fields` returns only the list
+  # of symbols in the order they were defined.
   #
   module SafeDump
+    include Familia::Features::Autoloadable
+    using Familia::Refinements::SnakeCase
+
     @dump_method = :to_json
     @load_method = :from_json
 
-    @safe_dump_fields = []
-    @safe_dump_field_map = {}
-
     def self.included(base)
-      Familia.trace :LOADED, self, base, caller(1..1) if Familia.debug?
-      base.extend ClassMethods
-
-      # Optionally define safe_dump_fields in the class to make
-      # sure we always have an array to work with.
-      base.instance_variable_set(:@safe_dump_fields, []) unless base.instance_variable_defined?(:@safe_dump_fields)
+      # Call the Autoloadable module's included method for post-inclusion setup
+      super
 
-      # Ditto for the field map
-      return if base.instance_variable_defined?(:@safe_dump_field_map)
+      Familia.trace(:LOADED, self, base, caller(1..1)) if Familia.debug?
+      base.extend ClassMethods
 
+      # Initialize the safe dump field map
       base.instance_variable_set(:@safe_dump_field_map, {})
     end
 
+    # SafeDump::ClassMethods
+    #
+    # These methods become available on the model class
     module ClassMethods
-      def set_safe_dump_fields(*fields)
-        @safe_dump_fields = fields
+      # Define a single safe dump field
+      # @param field_name [Symbol] The name of the field
+      # @param callable [Proc, nil] Optional callable to transform the value
+      def safe_dump_field(field_name, callable = nil)
+        @safe_dump_field_map ||= {}
+
+        field_name = field_name.to_sym
+        field_value = callable || lambda { |obj|
+          if obj.respond_to?(:[]) && obj[field_name]
+            obj[field_name] # Familia::DataType classes
+          elsif obj.respond_to?(field_name)
+            obj.send(field_name) # Regular method calls
+          end
+        }
+
+        @safe_dump_field_map[field_name] = field_value
       end
 
-      # `SafeDump.safe_dump_fields` returns only the list
-      # of symbols in the order they were defined.
-      def safe_dump_fields
-        @safe_dump_fields.map do |field|
-          field.is_a?(Symbol) ? field : field.keys.first
+      # Define multiple safe dump fields at once
+      # @param fields [Array] Mixed array of symbols and hashes
+      def safe_dump_fields(*fields)
+        # If no arguments, return field names (getter behavior)
+        return safe_dump_field_names if fields.empty?
+
+        # Otherwise, define fields (setter behavior)
+        fields.each do |field|
+          if field.is_a?(Symbol)
+            safe_dump_field(field)
+          elsif field.is_a?(Hash)
+            field.each do |name, callable|
+              safe_dump_field(name, callable)
+            end
+          end
         end
       end
 
-      # `SafeDump.safe_dump_field_map` returns the field map
-      # that is used to dump the fields. The keys are the
-      # field names and the values are callables that will
-      # expect to receive the instance object as an argument.
-      #
-      # The map is cached on the first call to this method.
-      #
+      # Returns an array of safe dump field names in the order they were defined
+      def safe_dump_field_names
+        (@safe_dump_field_map || {}).keys
+      end
+
+      # Returns the field map used for dumping
       def safe_dump_field_map
-        return @safe_dump_field_map if @safe_dump_field_map.any?
-
-        # Operate directly on the @safe_dump_fields array to
-        # build the map. This way we'll get the elements defined
-        # in the hash syntax (i.e. since the safe_dump_fields getter
-        # method returns only the symbols).
-        @safe_dump_field_map = @safe_dump_fields.each_with_object({}) do |el, map|
-          if el.is_a?(Symbol)
-            field_name = el
-            callable = lambda { |obj|
-              if obj.respond_to?(:[]) && obj[field_name]
-                obj[field_name] # Familia::DataType classes
-              elsif obj.respond_to?(field_name)
-                obj.send(field_name) # Onetime::Models::RedisHash classes via method_missing 😩
-              end
-            }
-          else
-            field_name = el.keys.first
-            callable = el.values.first
-          end
-          map[field_name] = callable
-        end
+        @safe_dump_field_map || {}
+      end
+
+      # Legacy method for setting safe dump fields (for backward compatibility)
+      def set_safe_dump_fields(*fields)
+        safe_dump_fields(*fields)
       end
     end
 
@@ -155,5 +156,5 @@ module Familia::Features
 
     Familia::Base.add_feature self, :safe_dump
   end
-  # end SafeDump
 end
+# rubocop:enable ThreadSafety/ClassInstanceVariable

data/lib/familia/features.rb

@@ -1,22 +1,117 @@
 # lib/familia/features.rb
 
+# Load the Autoloader first, then use it to load all other features
+require_relative 'autoloader'
+
 module Familia
   FeatureDefinition = Data.define(:name, :depends_on)
 
   # Familia::Features
   #
+  # This module provides the feature system for Familia classes. Features are
+  # modular capabilities that can be mixed into classes with configurable options.
+  # Features provide a powerful way to:
+  #
+  # - **Add new methods**: Both class and instance methods can be added
+  # - **Override existing methods**: Extend or replace default behavior
+  # - **Add new fields**: Define additional data storage capabilities
+  # - **Manage complexity**: Large, complex model classes can use features to
+  #   organize functionality into focused, reusable modules
+  #
+  # ## Feature Options Storage
+  #
+  # Feature options are stored **per-class** using class-level instance variables.
+  # This means each Familia::Horreum subclass maintains its own isolated set of
+  # feature options. When you enable a feature with options in different models,
+  # each model stores its own separate configuration without interference.
+  #
+  # ## Project Organization with Autoloadable
+  #
+  # For large projects, use {Familia::Features::Autoloadable} to automatically load
+  # project-specific features from a dedicated directory structure. This helps
+  # organize complex models by separating features into individual files.
+  #
+  # @example Different models with different feature options
+  #   class UserModel < Familia::Horreum
+  #     feature :object_identifier, generator: :uuid_v4
+  #   end
+  #
+  #   class SessionModel < Familia::Horreum
+  #     feature :object_identifier, generator: :hex
+  #   end
+  #
+  #   UserModel.feature_options(:object_identifier)    #=> {generator: :uuid_v4}
+  #   SessionModel.feature_options(:object_identifier) #=> {generator: :hex}
+  #
+  # @example Using features for complexity management
+  #   class ComplexModel < Familia::Horreum
+  #     # Organize functionality using features
+  #     feature :expiration           # TTL management
+  #     feature :safe_dump           # API-safe serialization
+  #     feature :relationships       # CRUD operations for related objects
+  #     feature :custom_validation   # Project-specific validation logic
+  #     feature :audit_trail         # Change tracking
+  #   end
+  #
+  # @example Project-specific features with autoloader
+  #   # In your model file: app/models/customer.rb
+  #   class Customer < Familia::Horreum
+  #     module Features
+  #       include Familia::Features::Autoloadable
+  #       # Automatically loads all .rb files from app/models/customer/features/
+  #     end
+  #   end
+  #
+  # @see Familia::Features::Autoloadable For automatic feature loading
+  #
   module Features
+    include Familia::Autoloader
+
     @features_enabled = nil
     attr_reader :features_enabled
 
+    # Enables a feature for the current class with optional configuration.
+    #
+    # Features are modular capabilities that can be mixed into Familia::Horreum
+    # classes. Each feature can be configured with options that are stored
+    # **per-class**, ensuring complete isolation between different models.
+    #
+    # @param feature_name [Symbol, String, nil] the name of the feature to enable.
+    #   If nil, returns the list of currently enabled features.
+    # @param options [Hash] configuration options for the feature. These are
+    #   stored per-class and do not interfere with other models' configurations.
+    # @return [Array, nil] the list of enabled features if feature_name is nil,
+    #   otherwise nil
+    #
+    # @example Enable feature without options
+    #   class User < Familia::Horreum
+    #     feature :expiration
+    #   end
+    #
+    # @example Enable feature with options (per-class storage)
+    #   class User < Familia::Horreum
+    #     feature :object_identifier, generator: :uuid_v4
+    #   end
+    #
+    #   class Session < Familia::Horreum
+    #     feature :object_identifier, generator: :hex  # Different options
+    #   end
+    #
+    #   # Each class maintains separate options:
+    #   User.feature_options(:object_identifier)    #=> {generator: :uuid_v4}
+    #   Session.feature_options(:object_identifier) #=> {generator: :hex}
+    #
+    # @raise [Familia::Problem] if the feature is not supported
+    #
     def feature(feature_name = nil, **options)
       @features_enabled ||= []
 
       return features_enabled if feature_name.nil?
 
-      # If there's a value provied check that it's a valid feature
+      # If there's a value provided check that it's a valid feature
       feature_name = feature_name.to_sym
-      unless Familia::Base.features_available.key?(feature_name)
+      feature_class = Familia::Base.find_feature(feature_name, self)
+      unless feature_class
         raise Familia::Problem, "Unsupported feature: #{feature_name}"
       end
 
@@ -41,15 +136,22 @@ module Familia
       # Add it to the list available features_enabled for Familia::Base classes.
       features_enabled << feature_name
 
-      # Store feature options if any were provided using the new pattern
-      if options.any?
+      # Always capture and store the calling location for every feature
+      calling_location = caller_locations(1, 1)&.first
+      options[:calling_location] = calling_location&.path
+
+      # Add feature options if the class supports them (Horreum classes)
+      if respond_to?(:add_feature_options)
         add_feature_options(feature_name, **options)
       end
 
-      klass = Familia::Base.features_available[feature_name]
-
       # Extend the Familia::Base subclass (e.g. Customer) with the feature module
-      include klass
+      include feature_class
+
+      # Trigger post-inclusion autoloading for features that support it
+      if feature_class.respond_to?(:post_inclusion_autoload)
+        feature_class.post_inclusion_autoload(self, feature_name, options)
+      end
 
       # NOTE: Do we want to extend Familia::DataType here? That would make it
       # possible to call safe_dump on relations fields (e.g. list, zset, hashkey).
@@ -64,13 +166,3 @@ module Familia
     end
   end
 end
-
-# Load all feature files from the features directory
-features_dir = File.join(__dir__, 'features')
-Familia.ld "[DEBUG] Loading features from #{features_dir}"
-if Dir.exist?(features_dir)
-  Dir.glob(File.join(features_dir, '*.rb')).each do |feature_file|
-    Familia.ld "[DEBUG] Loading feature #{feature_file}"
-    require_relative feature_file
-  end
-end

data/lib/familia/field_type.rb

@@ -29,6 +29,8 @@ module Familia
   class FieldType
     attr_reader :name, :options, :method_name, :fast_method_name, :on_conflict, :loggable
 
+    using Familia::Refinements::TimeUtils
+
     # Initialize a new field type
     #
     # @param name [Symbol] The field name