familia 2.0.0.pre21 → 2.0.0.pre23

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

@@ -76,7 +76,7 @@ module Familia
           #     batch_size: 100
           #   ) { |p| puts "#{p[:completed]}/#{p[:total]} (#{p[:rate]}/s)" }
           #
-          def rebuild_via_instances(indexed_class, field, add_method, batch_size: 100, &progress)
+          def rebuild_via_instances(indexed_class, field, add_method, index_hashkey, batch_size: 100, &progress)
             unless indexed_class.respond_to?(:instances)
               raise ArgumentError, "#{indexed_class.name} does not have an instances collection"
             end
@@ -104,8 +104,8 @@ module Familia
             processed = 0
             indexed_count = 0
 
-            # Process in batches - use membersraw to get raw identifiers without deserialization
-            instances.membersraw.each_slice(batch_size) do |identifiers|
+            # Process in batches - use members to get deserialized identifiers
+            instances.members.each_slice(batch_size) do |identifiers|
               # Bulk load objects, filtering out nils (deleted/missing objects)
               objects = indexed_class.load_multi(identifiers).compact
 
@@ -117,8 +117,8 @@ module Familia
                   # Skip nil/empty field values gracefully
                   next unless value && !value.to_s.strip.empty?
 
-                  # For class-level indexes, use HSET directly into temp key
-                  tx.hset(temp_key, value.to_s, obj.identifier.to_s)
+                  # For class-level indexes, use HSET with serialized value for consistency
+                  tx.hset(temp_key, value.to_s, index_hashkey.serialize_value(obj))
                   batch_indexed += 1
                 end
               end
@@ -177,7 +177,7 @@ module Familia
           #     batch_size: 100
           #   )
           #
-          def rebuild_via_participation(scope_instance, indexed_class, field, add_method, collection, cardinality, batch_size: 100, &progress)
+          def rebuild_via_participation(scope_instance, indexed_class, field, add_method, collection, cardinality, index_hashkey, batch_size: 100, &progress)
             total = collection.size
             start_time = Familia.now
 
@@ -222,8 +222,8 @@ module Familia
             processed = 0
             indexed_count = 0
 
-            # Process in batches - use membersraw to get raw identifiers
-            collection.membersraw.each_slice(batch_size) do |identifiers|
+            # Process in batches - use members to get deserialized identifiers
+            collection.members.each_slice(batch_size) do |identifiers|
               objects = indexed_class.load_multi(identifiers).compact
 
               # Transaction per batch
@@ -233,9 +233,9 @@ module Familia
                   value = obj.send(field)
                   next unless value && !value.to_s.strip.empty?
 
-                  # For unique index: HSET temp_key field_value identifier
+                  # For unique index: HSET temp_key field_value serialized_identifier
                   # For multi-index: SADD temp_key:field_value identifier
-                  tx.hset(temp_key, value.to_s, obj.identifier.to_s)
+                  tx.hset(temp_key, value.to_s, index_hashkey.serialize_value(obj))
                   batch_indexed += 1
                 end
               end
@@ -295,7 +295,7 @@ module Familia
           #     batch_size: 100
           #   )
           #
-          def rebuild_via_scan(indexed_class, field, add_method, scope_instance: nil, batch_size: 100, &progress)
+          def rebuild_via_scan(indexed_class, field, add_method, index_hashkey, scope_instance: nil, batch_size: 100, &progress)
             start_time = Familia.now
 
             # Build key pattern for SCAN
@@ -342,7 +342,7 @@ module Familia
 
               # Process in batches
               if batch.size >= batch_size
-                batch_indexed = RebuildStrategies.process_scan_batch(batch, indexed_class, field, temp_key, scope_instance)
+                batch_indexed = RebuildStrategies.process_scan_batch(batch, indexed_class, field, temp_key, index_hashkey, scope_instance)
                 processed += batch.size
                 indexed_count += batch_indexed
 
@@ -362,7 +362,7 @@ module Familia
 
             # Process remaining batch
             unless batch.empty?
-              batch_indexed = RebuildStrategies.process_scan_batch(batch, indexed_class, field, temp_key, scope_instance)
+              batch_indexed = RebuildStrategies.process_scan_batch(batch, indexed_class, field, temp_key, index_hashkey, scope_instance)
               processed += batch.size
               indexed_count += batch_indexed
             end
@@ -385,7 +385,7 @@ module Familia
           # @param scope_instance [Object, nil] Optional scope instance. If provided, only objects belonging to this scope will be indexed.
           # @return [Integer] Number of objects indexed in this batch
           #
-          def process_scan_batch(keys, indexed_class, field, temp_key, scope_instance)
+          def process_scan_batch(keys, indexed_class, field, temp_key, index_hashkey, scope_instance)
             # Load objects by keys
             objects = indexed_class.load_multi_by_keys(keys).compact
 
@@ -411,7 +411,7 @@ module Familia
                 value = obj.send(field)
                 next unless value && !value.to_s.strip.empty?
 
-                tx.hset(temp_key, value.to_s, obj.identifier.to_s)
+                tx.hset(temp_key, value.to_s, index_hashkey.serialize_value(obj))
                 batch_indexed += 1
               end
             end

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

@@ -191,6 +191,7 @@ module Familia
                   index_config = indexed_class.indexing_relationships.find { |rel| rel.index_name == index_name }
 
                   # Strategy 2: Use participation-based rebuild
+                  index_hashkey = send(index_name)  # Get the index HashKey for serialization
                   Familia::Features::Relationships::Indexing::RebuildStrategies.rebuild_via_participation(
                     self,                                      # scope_instance (e.g., company)
                     indexed_class,                             # e.g., Employee
@@ -198,15 +199,18 @@ module Familia
                     :"add_to_#{scope_class_config}_#{index_name}",  # e.g., :add_to_company_badge_index
                     collection,
                     index_config.cardinality,                  # :unique or :multi
+                    index_hashkey,                             # Pass index for serialization
                     batch_size: batch_size,
                     &progress_block
                   )
                 else
                   # Strategy 3: Fall back to SCAN with filtering
+                  index_hashkey = send(index_name)  # Get the index HashKey for serialization
                   Familia::Features::Relationships::Indexing::RebuildStrategies.rebuild_via_scan(
                     indexed_class,
                     field,
                     :"add_to_#{scope_class_config}_#{index_name}",
+                    index_hashkey,                             # Pass index for serialization
                     scope_instance: self,
                     batch_size: batch_size,
                     &progress_block
@@ -373,19 +377,23 @@ module Familia
             indexed_class.define_singleton_method(:"rebuild_#{index_name}") do |batch_size: 100, &progress_block|
               if respond_to?(:instances)
                 # Strategy 1: Use instances collection (fastest)
+                index_hashkey = send(index_name)  # Get the index HashKey for serialization
                 Familia::Features::Relationships::Indexing::RebuildStrategies.rebuild_via_instances(
                   self,                                 # indexed_class (e.g., User)
                   field,                                # e.g., :email
                   :"add_to_class_#{index_name}",       # e.g., :add_to_class_email_lookup
+                  index_hashkey,                        # Pass index for serialization
                   batch_size: batch_size,
                   &progress_block
                 )
               else
                 # Strategy 3: Fall back to SCAN
+                index_hashkey = send(index_name)  # Get the index HashKey for serialization
                 Familia::Features::Relationships::Indexing::RebuildStrategies.rebuild_via_scan(
                   self,
                   field,
                   :"add_to_class_#{index_name}",
+                  index_hashkey,                        # Pass index for serialization
                   batch_size: batch_size,
                   &progress_block
                 )

data/lib/familia/features/relationships/participation/participant_methods.rb

@@ -3,6 +3,7 @@
 # frozen_string_literal: true
 
 require_relative '../collection_operations'
+require_relative 'through_model_operations'
 
 module Familia
   module Features
@@ -33,6 +34,9 @@ module Familia
         module Builder
           extend CollectionOperations
 
+          # Include ThroughModelOperations for through model lifecycle
+          extend Participation::ThroughModelOperations
+
           # Build all participant methods for a participation relationship
           #
           # @param participant_class [Class] The class receiving these methods (e.g., Domain)
@@ -40,8 +44,9 @@ module Familia
           # @param collection_name [Symbol] Name of the collection (e.g., :domains)
           # @param type [Symbol] Collection type (:sorted_set, :set, :list)
           # @param as [Symbol, nil] Optional custom name for relationship methods (e.g., :employees)
+          # @param through [Symbol, Class, nil] Through model class for join table pattern
           #
-          def self.build(participant_class, target_class, collection_name, type, as)
+          def self.build(participant_class, target_class, collection_name, type, as, through = nil, method_prefix = nil)
             # Determine target name based on participation context:
             # - Instance-level: target_class is a Class object (e.g., Team) → use config_name ("project_team")
             # - Class-level: target_class is the string 'class' (from class_participates_in) → use as-is
@@ -55,8 +60,8 @@ module Familia
 
             # Core participant methods
             build_membership_check(participant_class, target_name, collection_name, type)
-            build_add_to_target(participant_class, target_name, collection_name, type)
-            build_remove_from_target(participant_class, target_name, collection_name, type)
+            build_add_to_target(participant_class, target_name, collection_name, type, through)
+            build_remove_from_target(participant_class, target_name, collection_name, type, through)
 
             # Type-specific methods
             case type
@@ -73,18 +78,23 @@ module Familia
             # - Class-level collections are accessed directly on the class (User.all_users)
             return if target_class.is_a?(String)  # 'class' indicates class-level participation
 
-            # If `as` is specified, create a custom method for just this collection
-            # Otherwise, add to the default pluralized method that unions all collections
+            # Priority for method naming:
+            # 1. `as:` - most specific, applies to just this collection
+            # 2. `method_prefix:` - applies to all collections for this target class
+            # 3. Default - uses target_class.config_name
             if as
               # Custom method for just this specific collection
               build_reverse_collection_methods(participant_class, target_class, as, [collection_name])
+            elsif method_prefix
+              # Custom prefix for all methods related to this target class
+              build_reverse_collection_methods(participant_class, target_class, method_prefix, nil)
             else
               # Default pluralized method - will include ALL collections for this target
               build_reverse_collection_methods(participant_class, target_class, nil, nil)
             end
           end
 
-          # Generate reverse collection methods on participant class for bidirectional access
+          # Generate reverse collection methods on participant class for symmetric access
           #
           # Creates methods like:
           # - user.team_instances (returns Array of Team instances)
@@ -186,11 +196,11 @@ module Familia
           end
 
           # Build method to add self to target's collection
-          # Creates: domain.add_to_customer_domains(customer, score)
-          def self.build_add_to_target(participant_class, target_name, collection_name, type)
+          # Creates: domain.add_to_customer_domains(customer, score, through_attrs: {})
+          def self.build_add_to_target(participant_class, target_name, collection_name, type, through = nil)
             method_name = "add_to_#{target_name}_#{collection_name}"
 
-            participant_class.define_method(method_name) do |target_instance, score = nil|
+            participant_class.define_method(method_name) do |target_instance, score = nil, through_attrs: {}|
               return unless target_instance&.identifier
 
               # Use Horreum's DataType accessor instead of manual creation
@@ -201,6 +211,9 @@ module Familia
                 score = calculate_participation_score(target_instance.class, collection_name)
               end
 
+              # Resolve through class if specified
+              through_class = through ? Familia.resolve_class(through) : nil
+
               # Use transaction for atomicity between collection add and reverse index tracking
               # All operations use Horreum's DataType methods (not direct Redis calls)
               target_instance.transaction do |_tx|
@@ -217,12 +230,34 @@ module Familia
                 # Track participation for efficient cleanup using DataType method (SADD)
                 track_participation_in(collection.dbkey) if respond_to?(:track_participation_in)
               end
+
+              # TRANSACTION BOUNDARY: Through model operations intentionally happen AFTER
+              # the transaction block closes. This is a deliberate design decision because:
+              #
+              # 1. ThroughModelOperations.find_or_create performs load operations that would
+              #    return Redis::Future objects inside a transaction, breaking the flow
+              # 2. The core participation (collection add + tracking) is atomic within the tx
+              # 3. Through model creation is logically separate - if it fails, the participation
+              #    itself succeeded and can be cleaned up or retried independently
+              #
+              # If Familia's transaction handling changes in the future, revisit this boundary.
+              through_model = if through_class
+                Participation::ThroughModelOperations.find_or_create(
+                  through_class: through_class,
+                  target: target_instance,
+                  participant: self,
+                  attrs: through_attrs
+                )
+              end
+
+              # Return through model if using :through, otherwise self for backward compat
+              through_model || self
             end
           end
 
           # Build method to remove self from target's collection
           # Creates: domain.remove_from_customer_domains(customer)
-          def self.build_remove_from_target(participant_class, target_name, collection_name, type)
+          def self.build_remove_from_target(participant_class, target_name, collection_name, type, through = nil)
             method_name = "remove_from_#{target_name}_#{collection_name}"
 
             participant_class.define_method(method_name) do |target_instance|
@@ -231,6 +266,9 @@ module Familia
               # Use Horreum's DataType accessor instead of manual creation
               collection = target_instance.send(collection_name)
 
+              # Resolve through class if specified
+              through_class = through ? Familia.resolve_class(through) : nil
+
               # Use transaction for atomicity between collection remove and reverse index untracking
               # All operations use Horreum's DataType methods (not direct Redis calls)
               target_instance.transaction do |_tx|
@@ -240,6 +278,17 @@ module Familia
                 # Remove from participation tracking using DataType method (SREM)
                 untrack_participation_in(collection.dbkey) if respond_to?(:untrack_participation_in)
               end
+
+              # TRANSACTION BOUNDARY: Through model destruction intentionally happens AFTER
+              # the transaction block. See build_add_to_target for detailed rationale.
+              # The core removal is atomic; through model cleanup is a separate operation.
+              if through_class
+                Participation::ThroughModelOperations.find_and_destroy(
+                  through_class: through_class,
+                  target: target_instance,
+                  participant: self
+                )
+              end
             end
           end
 

data/lib/familia/features/relationships/participation/target_methods.rb

@@ -3,6 +3,7 @@
 # frozen_string_literal: true
 
 require_relative '../collection_operations'
+require_relative 'through_model_operations'
 
 module Familia
   module Features
@@ -30,18 +31,22 @@ module Familia
         module Builder
           extend CollectionOperations
 
+          # Include ThroughModelOperations for through model lifecycle
+          extend Participation::ThroughModelOperations
+
           # Build all target methods for a participation relationship
           # @param target_class [Class] The class receiving these methods (e.g., Customer)
           # @param collection_name [Symbol] Name of the collection (e.g., :domains)
           # @param type [Symbol] Collection type (:sorted_set, :set, :list)
-          def self.build(target_class, collection_name, type)
+          # @param through [Symbol, Class, nil] Through model class for join table pattern
+          def self.build(target_class, collection_name, type, through = nil)
             # FIRST: Ensure the DataType field is defined on the target class
             TargetMethods::Builder.ensure_collection_field(target_class, collection_name, type)
 
             # Core target methods
             build_collection_getter(target_class, collection_name, type)
-            build_add_item(target_class, collection_name, type)
-            build_remove_item(target_class, collection_name, type)
+            build_add_item(target_class, collection_name, type, through)
+            build_remove_item(target_class, collection_name, type, through)
             build_bulk_add(target_class, collection_name, type)
 
             # Type-specific methods
@@ -74,11 +79,11 @@ module Familia
           end
 
           # Build method to add an item to the collection
-          # Creates: customer.add_domains_instance(domain, score)
-          def self.build_add_item(target_class, collection_name, type)
+          # Creates: customer.add_domains_instance(domain, score, through_attrs: {})
+          def self.build_add_item(target_class, collection_name, type, through = nil)
             method_name = "add_#{collection_name}_instance"
 
-            target_class.define_method(method_name) do |item, score = nil|
+            target_class.define_method(method_name) do |item, score = nil, through_attrs: {}|
               collection = send(collection_name)
 
               # Calculate score if needed and not provided
@@ -86,6 +91,9 @@ module Familia
                 score = item.calculate_participation_score(self.class, collection_name)
               end
 
+              # Resolve through class if specified
+              through_class = through ? Familia.resolve_class(through) : nil
+
               # Use transaction for atomicity between collection add and reverse index tracking
               # All operations use Horreum's DataType methods (not direct Redis calls)
               transaction do |_tx|
@@ -102,17 +110,42 @@ module Familia
                 # Track participation in reverse index using DataType method (SADD)
                 item.track_participation_in(collection.dbkey) if item.respond_to?(:track_participation_in)
               end
+
+              # TRANSACTION BOUNDARY: Through model operations intentionally happen AFTER
+              # the transaction block closes. This is a deliberate design decision because:
+              #
+              # 1. ThroughModelOperations.find_or_create performs load operations that would
+              #    return Redis::Future objects inside a transaction, breaking the flow
+              # 2. The core participation (collection add + tracking) is atomic within the tx
+              # 3. Through model creation is logically separate - if it fails, the participation
+              #    itself succeeded and can be cleaned up or retried independently
+              #
+              # If Familia's transaction handling changes in the future, revisit this boundary.
+              through_model = if through_class
+                Participation::ThroughModelOperations.find_or_create(
+                  through_class: through_class,
+                  target: self,
+                  participant: item,
+                  attrs: through_attrs
+                )
+              end
+
+              # Return through model if using :through, otherwise self for backward compat
+              through_model || self
             end
           end
 
           # Build method to remove an item from the collection
           # Creates: customer.remove_domains_instance(domain)
-          def self.build_remove_item(target_class, collection_name, type)
+          def self.build_remove_item(target_class, collection_name, type, through = nil)
             method_name = "remove_#{collection_name}_instance"
 
             target_class.define_method(method_name) do |item|
               collection = send(collection_name)
 
+              # Resolve through class if specified
+              through_class = through ? Familia.resolve_class(through) : nil
+
               # Use transaction for atomicity between collection remove and reverse index untracking
               # All operations use Horreum's DataType methods (not direct Redis calls)
               transaction do |_tx|
@@ -122,6 +155,17 @@ module Familia
                 # Remove from participation tracking using DataType method (SREM)
                 item.untrack_participation_in(collection.dbkey) if item.respond_to?(:untrack_participation_in)
               end
+
+              # TRANSACTION BOUNDARY: Through model destruction intentionally happens AFTER
+              # the transaction block. See build_add_item for detailed rationale.
+              # The core removal is atomic; through model cleanup is a separate operation.
+              if through_class
+                Participation::ThroughModelOperations.find_and_destroy(
+                  through_class: through_class,
+                  target: self,
+                  participant: item
+                )
+              end
             end
           end
 

data/lib/familia/features/relationships/participation/through_model_operations.rb

@@ -0,0 +1,150 @@
+# lib/familia/features/relationships/participation/through_model_operations.rb
+#
+# frozen_string_literal: true
+
+module Familia
+  module Features
+    module Relationships
+      module Participation
+        # ThroughModelOperations provides lifecycle management for through models
+        # in participation relationships.
+        #
+        # Through models implement the join table pattern, creating an intermediate
+        # object between target and participant that can carry additional attributes
+        # (e.g., role, permissions, metadata).
+        #
+        # Key characteristics:
+        # - Deterministic identifier: Built from target, participant, and through class
+        # - Auto-lifecycle: Created on add, destroyed on remove
+        # - Idempotent: Re-adding updates existing model
+        # - Atomic: All operations use transactions
+        # - Cache-friendly: Auto-updates updated_at for invalidation
+        #
+        # Example:
+        #   class Membership < Familia::Horreum
+        #     feature :object_identifier
+        #     field :customer_objid
+        #     field :domain_objid
+        #     field :role
+        #     field :updated_at
+        #   end
+        #
+        #   class Domain < Familia::Horreum
+        #     participates_in Customer, :domains, through: :Membership
+        #   end
+        #
+        #   # Through model auto-created with deterministic key
+        #   customer.add_domains_instance(domain, through_attrs: { role: 'admin' })
+        #   # => #<Membership objid="customer:123:domain:456:membership">
+        #
+        module ThroughModelOperations
+          module_function
+
+          # Build a deterministic key for the through model
+          #
+          # The key format ensures uniqueness and allows direct lookup:
+          # {target.prefix}:{target.objid}:{participant.prefix}:{participant.objid}:{through.prefix}
+          #
+          # @param target [Object] The target instance (e.g., customer)
+          # @param participant [Object] The participant instance (e.g., domain)
+          # @param through_class [Class] The through model class
+          # @return [String] Deterministic key for the through model
+          #
+          def build_key(target:, participant:, through_class:)
+            "#{target.class.config_name}:#{target.objid}:" \
+            "#{participant.class.config_name}:#{participant.objid}:" \
+            "#{through_class.config_name}"
+          end
+
+          # Find or create a through model instance
+          #
+          # This method is idempotent - calling it multiple times with the same
+          # target/participant pair will update the existing through model rather
+          # than creating duplicates.
+          #
+          # The through model's updated_at is set on both create and update for
+          # cache invalidation.
+          #
+          # @param through_class [Class] The through model class
+          # @param target [Object] The target instance
+          # @param participant [Object] The participant instance
+          # @param attrs [Hash] Additional attributes to set on through model
+          # @return [Object] The created or updated through model instance
+          #
+          def find_or_create(through_class:, target:, participant:, attrs: {})
+            key = build_key(target: target, participant: participant, through_class: through_class)
+
+            # Try to load existing model - load returns nil if key doesn't exist
+            existing = through_class.load(key)
+
+            # Check if we got a valid loaded object using the public API
+            # This is called outside transaction boundaries (see participant_methods.rb
+            # and target_methods.rb for the transaction boundary documentation)
+            if existing&.exists?
+              # Update existing through model with validated attributes
+              safe_attrs = validated_attrs(through_class, attrs)
+              safe_attrs.each { |k, v| existing.send("#{k}=", v) }
+              existing.updated_at = Familia.now.to_f if existing.respond_to?(:updated_at=)
+              # Save returns boolean, but we want to return the model instance
+              existing.save if safe_attrs.any? || existing.respond_to?(:updated_at=)
+              existing  # Return the model, not the save result
+            else
+              # Create new through model with our deterministic key as objid
+              # Pass objid during initialization to prevent auto-generation
+              inst = through_class.new(objid: key)
+
+              # Set foreign key fields if they exist (validated via respond_to?)
+              target_field = "#{target.class.config_name}_objid"
+              participant_field = "#{participant.class.config_name}_objid"
+              inst.send("#{target_field}=", target.objid) if inst.respond_to?("#{target_field}=")
+              inst.send("#{participant_field}=", participant.objid) if inst.respond_to?("#{participant_field}=")
+
+              # Set updated_at for cache invalidation
+              inst.updated_at = Familia.now.to_f if inst.respond_to?(:updated_at=)
+
+              # Set custom attributes (validated against field schema)
+              safe_attrs = validated_attrs(through_class, attrs)
+              safe_attrs.each { |k, v| inst.send("#{k}=", v) }
+
+              # Save returns boolean, but we want to return the model instance
+              inst.save
+              inst  # Return the model, not the save result
+            end
+          end
+
+          # Find and destroy a through model instance
+          #
+          # Used during remove operations to clean up the join table entry.
+          #
+          # @param through_class [Class] The through model class
+          # @param target [Object] The target instance
+          # @param participant [Object] The participant instance
+          # @return [void]
+          #
+          def find_and_destroy(through_class:, target:, participant:)
+            key = build_key(target: target, participant: participant, through_class: through_class)
+            existing = through_class.load(key)
+            # Use the public exists? method for a more robust check
+            existing&.destroy! if existing&.exists?
+          end
+
+          # Validate attribute keys against the through model's field schema
+          #
+          # This prevents arbitrary method invocation by ensuring only defined
+          # fields can be set via the attrs hash.
+          #
+          # @param through_class [Class] The through model class
+          # @param attrs [Hash] Attributes to validate
+          # @return [Hash] Only attributes whose keys match defined fields
+          #
+          def validated_attrs(through_class, attrs)
+            return {} if attrs.nil? || attrs.empty?
+
+            valid_fields = through_class.fields.map(&:to_sym)
+            attrs.select { |k, _v| valid_fields.include?(k.to_sym) }
+          end
+        end
+      end
+    end
+  end
+end