familia 2.0.0.pre7 → 2.0.0.pre8

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7a93de51c8a35c420067d9e48895af37862866667af224a8e13f44647c4e4c76
-  data.tar.gz: bbdf64f77c182a0498fc757c393071b04b5da3594b4c7d5c12992fe058b44777
+  metadata.gz: c5ab18b134425a370c5d40f464e87747e85e713dc44c2a7906b7b024a66b23a4
+  data.tar.gz: f5a2e3fd2ca4553781b7f58f4f0e7a6d5e9228c18f34c7a1f5cf1af7695d580d
 SHA512:
-  metadata.gz: 59a39a481db42739bbebabab9211645b2f7e9eb605742ab936c0b65dfc32973931b1b1f8a1c5d725fed5f5eb0ebdbb87c1c405f87108390ad3b6eb8f5ca89c5a
-  data.tar.gz: 4dc7dededb21bd7ee988a4d260e30eceb43f19be4c3f5d99f87bac5d632af6e517af5eab2633758e0c6b1552a2635bd0e024ace2210ee1ee83362aa811458b8c
+  metadata.gz: fba2c7586cb19181461f90ef2718c767de34f034d51ebc23c1643c8b526cc9c28fe64a2c3e3e46857bc1d816c8e9db9f76a6b57510f9b918756558b5e09c6fc9
+  data.tar.gz: 2f98337dbe62a833b310e9ddcd5916a7971e2b551a0603dbb153fa3ba5c99a81e9dfe86270a0d0500b359625ea23efbebc58ab26b327a03fc5138ee643475472

data/Gemfile

@@ -9,7 +9,7 @@ group :test do
     gem 'tryouts', path: '../tryouts'
     gem 'uri-valkey', path: '..//uri-valkey/gems', glob: 'uri-valkey.gemspec'
   else
-    gem 'tryouts', '~> 3.5.1', require: false
+    gem 'tryouts', '~> 3.5.2', require: false
   end
   gem 'concurrent-ruby', '~> 1.3.5', require: false
   gem 'ruby-prof'

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    familia (2.0.0.pre6)
+    familia (2.0.0.pre8)
       benchmark
       connection_pool
       csv
@@ -113,7 +113,7 @@ GEM
     ruby-progressbar (1.13.0)
     stackprof (0.2.27)
     stringio (3.1.7)
-    tryouts (3.5.1)
+    tryouts (3.5.2)
       concurrent-ruby (~> 1.0)
       irb
       minitest (~> 5.0)
@@ -148,7 +148,7 @@ DEPENDENCIES
   rubocop-thread_safety
   ruby-prof
   stackprof
-  tryouts (~> 3.5.1)
+  tryouts (~> 3.5.2)
   yard (~> 0.9)
 
 BUNDLED WITH

data/README.md

@@ -118,6 +118,41 @@ user.transaction do |conn|
 end
 ```
 
+## Organizing Complex Models
+
+For large applications, you can organize model complexity using custom features:
+
+### Self-Registering Features
+
+```ruby
+# app/features/customer_management.rb
+module MyApp::Features::CustomerManagement
+  Familia::Base.add_feature(self, :customer_management)
+
+  def self.included(base)
+    base.extend(ClassMethods)
+  end
+
+  module ClassMethods
+    def create_with_validation(attrs)
+      # Complex creation logic
+    end
+  end
+
+  def complex_business_method
+    # Instance methods
+  end
+end
+
+# models/customer.rb
+class Customer < Familia::Horreum
+  field :email, :name
+  feature :customer_management  # Clean model definition
+end
+```
+
+This keeps complex models organized while maintaining Familia's clean, declarative style.
+
 ## Conclusion
 
 Familia provides a powerful and flexible way to work with Valkey-compatible in Ruby applications. Its features like automatic expiration, safe dumping, and quantization make it suitable for a wide range of use cases, from simple key-value storage to complex time-series data management.

data/docs/wiki/Feature-System-Guide.md

@@ -517,21 +517,6 @@ class ConfigurableModel < Familia::Horreum
 end
 ```
 
-### Runtime Feature Checking
-
-```ruby
-class Model < Familia::Horreum
-  feature :expiration
-
-  def available_features
-    self.class.features_enabled
-  end
-end
-
-model = Model.new
-model.available_features  # => [:expiration]
-```
-
 ## Testing Features
 
 ### Feature Testing

data/lib/familia/features/external_identifiers/external_identifier_field_type.rb

@@ -0,0 +1,120 @@
+# lib/familia/features/external_identifiers/external_identifier_field_type.rb
+
+require 'familia/field_type'
+
+module Familia
+  module Features
+    module ExternalIdentifiers
+      # ExternalIdentifierFieldType - Fields that generate deterministic external identifiers
+      #
+      # External identifier fields generate shorter, public-facing identifiers that are
+      # deterministically derived from object identifiers. These IDs are safe for use
+      # in URLs, APIs, and other external contexts where shorter IDs are preferred.
+      #
+      # Key characteristics:
+      # - Deterministic generation from objid ensures consistency
+      # - Shorter than objid (128-bit vs 256-bit) for external use
+      # - Base-36 encoding for URL-safe identifiers
+      # - 'ext_' prefix for clear identification as external IDs
+      # - Lazy generation preserves values from initialization
+      #
+      # @example Using external identifier fields
+      #   class User < Familia::Horreum
+      #     feature :object_identifiers
+      #     feature :external_identifiers
+      #     field :email
+      #   end
+      #
+      #   user = User.new(email: 'user@example.com')
+      #   user.objid  # => "01234567-89ab-7def-8000-123456789abc"
+      #   user.extid  # => "ext_abc123def456ghi789" (deterministic from objid)
+      #
+      #   # Same objid always produces same extid
+      #   user2 = User.new(objid: user.objid, email: 'user@example.com')
+      #   user2.extid  # => "ext_abc123def456ghi789" (identical to user.extid)
+      #
+      class ExternalIdentifierFieldType < FieldType
+        # Override getter to provide lazy generation from objid
+        #
+        # Generates the external identifier deterministically from the object's
+        # objid. This ensures consistency - the same objid will always produce
+        # the same extid. Only generates when objid is available.
+        #
+        # @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 external identifier from objid if available
+              generated_extid = generate_external_identifier
+              return unless generated_extid
+
+              instance_variable_set(:"@#{field_name}", generated_extid)
+
+              # Update mapping if we have an identifier
+              if respond_to?(:identifier) && identifier
+                self.class.extid_lookup[generated_extid] = identifier
+              end
+
+              generated_extid
+            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|
+              # Remove old mapping if extid is changing
+              old_value = instance_variable_get(:"@#{field_name}")
+              if old_value && old_value != value && respond_to?(:identifier)
+                self.class.extid_lookup.del(old_value)
+              end
+
+              # Set the new value
+              instance_variable_set(:"@#{field_name}", value)
+
+              # Update mapping if we have both extid and identifier
+              if value && respond_to?(:identifier) && identifier
+                self.class.extid_lookup[value] = identifier
+              end
+            end
+          end
+        end
+
+        # External identifier fields are persisted to database
+        #
+        # @return [Boolean] true - external identifiers are always persisted
+        #
+        def persistent?
+          true
+        end
+
+        # Category for external identifier fields
+        #
+        # @return [Symbol] :external_identifier
+        #
+        def category
+          :external_identifier
+        end
+      end
+    end
+  end
+end

data/lib/familia/features/external_identifiers.rb

@@ -0,0 +1,111 @@
+# lib/familia/features/external_identifiers.rb
+
+require_relative 'external_identifiers/external_identifier_field_type'
+
+module Familia
+  module Features
+
+    # Familia::Features::ExternalIdentifiers
+    #
+    module ExternalIdentifiers
+      def self.included(base)
+        Familia.trace :LOADED, self, base, caller(1..1) if Familia.debug?
+        base.extend ClassMethods
+
+        # Ensure default prefix is set in feature options
+        base.add_feature_options(:external_identifiers, prefix: 'ext')
+
+        # Add class-level mapping for extid -> id lookups
+        base.class_hashkey :extid_lookup
+
+        # Register the extid field using our custom field type
+        base.register_field_type(
+          ExternalIdentifiers::ExternalIdentifierFieldType.new(:extid, as: :extid, fast_method: false)
+        )
+      end
+
+      # ExternalIdentifiers::ClassMethods
+      #
+      module ClassMethods
+        def generate_extid(objid = nil)
+          unless features_enabled.include?(:object_identifiers)
+            raise Familia::Problem,
+                  'ExternalIdentifiers requires ObjectIdentifiers feature'
+          end
+          return nil if objid.to_s.empty?
+
+          objid_hex = objid.to_s.delete('-')
+          external_part = Familia.shorten_to_external_id(objid_hex, base: 36)
+          prefix = feature_options(:external_identifiers)[:prefix] || 'ext'
+          "#{prefix}_#{external_part}"
+        end
+
+        # Find an object by its external identifier
+        #
+        # @param extid [String] The external identifier to search for
+        # @return [Object, nil] The object if found, nil otherwise
+        #
+        def find_by_extid(extid)
+          return nil if extid.to_s.empty?
+
+          if Familia.debug?
+            reference = caller(1..1).first
+            Familia.trace :FIND_BY_EXTID, Familia.dbclient, extid, reference
+          end
+
+          # Look up the primary ID from the external ID mapping
+          primary_id = extid_lookup[extid]
+          return nil if primary_id.nil?
+
+          # Find the object by its primary ID
+          find_by_id(primary_id)
+        rescue Familia::NotFound
+          # If the object was deleted but mapping wasn't cleaned up
+          extid_lookup.del(extid)
+          nil
+        end
+      end
+
+      # Generate external identifier deterministically from objid
+      def generate_external_identifier
+        return nil unless respond_to?(:objid)
+
+        current_objid = objid
+        return nil if current_objid.nil? || current_objid.to_s.empty?
+
+        # Convert objid to hex string for processing
+        objid_hex = current_objid.delete('-') # Remove UUID hyphens if present
+
+        # Generate deterministic external ID using SecureIdentifier
+        external_part = Familia.shorten_to_external_id(objid_hex, base: 36)
+
+        # Get prefix from feature options, default to "ext"
+        options = self.class.feature_options(:external_identifiers)
+        prefix = options[:prefix] || 'ext'
+
+        "#{prefix}_#{external_part}"
+      end
+
+      def external_identifier
+        extid
+      end
+
+      def init
+        super if defined?(super)
+        # External IDs are generated from objid, so no additional setup needed
+      end
+
+      def destroy!
+        # Clean up extid mapping when object is destroyed
+        current_extid = instance_variable_get(:@extid)
+        if current_extid
+          self.class.extid_lookup.del(current_extid)
+        end
+
+        super if defined?(super)
+      end
+
+      Familia::Base.add_feature self, :external_identifiers, depends_on: [:object_identifiers]
+    end
+  end
+end

data/lib/familia/features/object_identifiers/object_identifier_field_type.rb

@@ -0,0 +1,91 @@
+# lib/familia/features/object_identifiers/object_identifier_field_type.rb
+
+require 'familia/field_type'
+
+module Familia
+  module Features
+    module ObjectIdentifiers
+      # ObjectIdentifierFieldType - Fields that generate unique object identifiers
+      #
+      # 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.
+      #
+      # @example Using object identifier fields
+      #   class User < Familia::Horreum
+      #     feature :object_identifiers, generator: :uuid_v7
+      #   end
+      #
+      #   user = User.new
+      #   user.objid  # Generates UUID v7 on first access
+      #
+      #   # Loading existing object preserves ID
+      #   user2 = User.new(objid: "existing-uuid")
+      #   user2.objid  # Returns "existing-uuid", not regenerated
+      #
+      class ObjectIdentifierFieldType < 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)
+              generated_id
+            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)
+            end
+          end
+        end
+
+        # Object identifier fields are persisted to database
+        #
+        # @return [Boolean] true - object identifiers are always persisted
+        #
+        def persistent?
+          true
+        end
+
+        # Category for object identifier fields
+        #
+        # @return [Symbol] :object_identifier
+        #
+        def category
+          :object_identifier
+        end
+      end
+    end
+  end
+end

data/lib/familia/features/object_identifiers.rb

@@ -0,0 +1,194 @@
+# lib/familia/features/object_identifiers.rb
+
+require_relative 'object_identifiers/object_identifier_field_type'
+
+module Familia
+  module Features
+    # ObjectIdentifiers 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_identifiers
+    #     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_identifiers, 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_identifiers, 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_identifiers, 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 object identifiers 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 ObjectIdentifiers
+      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_identifiers, generator: DEFAULT_GENERATOR)
+
+        # Register the objid field using our custom field type
+        base.register_field_type(
+          ObjectIdentifiers::ObjectIdentifierFieldType.new(:objid, as: :objid, fast_method: false)
+        )
+      end
+
+      module ClassMethods
+        # Generate a new object identifier using the configured strategy
+        #
+        # @return [String] A new unique identifier
+        #
+        def generate_objid
+          options = feature_options(:object_identifiers)
+          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_objid
+      end
+
+      # Alias for objid for consistency with naming conventions
+      #
+      # @return [String] The object identifier
+      #
+      def object_identifier
+        objid
+      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_identifiers)
+        generator = options[:generator] || DEFAULT_GENERATOR
+        Familia.trace :OBJID_INIT, dbclient, "Generator strategy: #{generator}", caller(1..1)
+      end
+
+      Familia::Base.add_feature self, :object_identifiers, depends_on: []
+    end
+  end
+end

data/lib/familia/features/relationships/cascading.rb

@@ -431,7 +431,6 @@ module Familia
             affected_keys
           end
         end
-
       end
     end
   end

data/lib/familia/features/relationships/indexing.rb

@@ -363,7 +363,6 @@ module Familia
             dbclient.hexists(index_key, field_value.to_s)
           end
         end
-
       end
     end
   end

data/lib/familia/features/relationships/membership.rb

@@ -496,7 +496,6 @@ module Familia
             true
           end
         end
-
       end
     end
   end