familia 2.0.0.pre15 → 2.0.0.pre16

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

@@ -5,7 +5,7 @@ module Familia
     module Relationships
       # Score encoding using bit flags for permissions
       #
-      # Encodes permissions as bit flags in the decimal portion of Redis sorted set scores:
+      # Encodes permissions as bit flags in the decimal portion of Valkey/Redis sorted set scores:
       # - Integer part: Unix timestamp for time-based ordering
       # - Decimal part: 8-bit permission flags (0-255)
       #
@@ -48,7 +48,7 @@ module Familia
           viewer:     PERMISSION_FLAGS[:read],
           editor:     PERMISSION_FLAGS[:read] | PERMISSION_FLAGS[:write] | PERMISSION_FLAGS[:edit],
           moderator:  PERMISSION_FLAGS[:read] | PERMISSION_FLAGS[:write] | PERMISSION_FLAGS[:edit] | PERMISSION_FLAGS[:delete],
-          admin:      0b11111111 # All permissions
+          admin:      0b11111111, # All permissions
         }.freeze
 
         # Categorical masks for efficient broad queries
@@ -57,7 +57,7 @@ module Familia
           content_editor: 0b00001110,  # Can modify content (append|write|edit)
           administrator:  0b11110000,  # Has any admin powers
           privileged:     0b11111110,  # Has beyond read-only
-          owner:          0b11111111   # All permissions
+          owner:          0b11111111, # All permissions
         }.freeze
 
         class << self
@@ -74,7 +74,7 @@ module Familia
           #
           # @param timestamp [Time, Integer] The timestamp to encode
           # @param permission [Symbol, Integer, Array] Permission(s) to encode
-          # @return [Float] Encoded score suitable for Redis sorted sets
+          # @return [Float] Encoded score suitable for Valkey/Redis sorted sets
           def permission_encode(timestamp, permission)
             encode_score(timestamp, permission)
           end
@@ -88,26 +88,26 @@ module Familia
             {
               timestamp: decoded[:timestamp],
               permissions: decoded[:permissions],
-              permission_list: decoded[:permission_list]
+              permission_list: decoded[:permission_list],
             }
           end
 
-          # Encode a timestamp and permissions into a Redis score
+          # Encode a timestamp and permissions into a Valkey/Redis score
           #
           # @param timestamp [Time, Integer] The timestamp to encode
           # @param permissions [Integer, Symbol, Array] Permissions to encode
-          # @return [Float] Encoded score suitable for Redis sorted sets
+          # @return [Float] Encoded score suitable for Valkey/Redis sorted sets
           #
           # @example Basic encoding with bit flag
-          #   encode_score(Time.now, 5)  # read(1) + write(4) = 5
+          #   encode_score(Familia.now, 5)  # read(1) + write(4) = 5
           #   #=> 1704067200.005
           #
           # @example Permission symbol encoding
-          #   encode_score(Time.now, :read)
+          #   encode_score(Familia.now, :read)
           #   #=> 1704067200.001
           #
           # @example Multiple permissions
-          #   encode_score(Time.now, [:read, :write, :delete])
+          #   encode_score(Familia.now, [:read, :write, :delete])
           #   #=> 1704067200.037
           def encode_score(timestamp, permissions = 0)
             time_part = timestamp.respond_to?(:to_i) ? timestamp.to_i : timestamp
@@ -127,7 +127,7 @@ module Familia
             time_part + (permission_bits / METADATA_PRECISION)
           end
 
-          # Decode a Redis score back into timestamp and permissions
+          # Decode a Valkey/Redis score back into timestamp and permissions
           #
           # @param score [Float] The encoded score
           # @return [Hash] Hash with :timestamp, :permissions, and :permission_list keys
@@ -144,7 +144,7 @@ module Familia
             {
               timestamp: time_part,
               permissions: permission_bits,
-              permission_list: decode_permission_flags(permission_bits)
+              permission_list: decode_permission_flags(permission_bits),
             }
           end
 
@@ -211,7 +211,7 @@ module Familia
           #
           # @param min_permissions [Array<Symbol>, nil] Minimum required permissions
           # @param max_permissions [Array<Symbol>, nil] Maximum allowed permissions
-          # @return [Array<Float>] Min and max scores for Redis range queries
+          # @return [Array<Float>] Min and max scores for Valkey/Redis range queries
           #
           # @example
           #   permission_range([:read], [:read, :write])
@@ -231,20 +231,20 @@ module Familia
 
           # Get current timestamp as score (no permissions)
           #
-          # @return [Float] Current time as Redis score
+          # @return [Float] Current time as Valkey/Redis score
           def current_score
-            encode_score(Time.now, 0)
+            encode_score(Familia.now, 0)
           end
 
-          # Create score range for Redis operations based on time bounds
+          # Create score range for db operations based on time bounds
           #
           # @param start_time [Time, nil] Start time (nil for -inf)
           # @param end_time [Time, nil] End time (nil for +inf)
           # @param min_permissions [Array<Symbol>, nil] Minimum required permissions
-          # @return [Array] Array suitable for Redis ZRANGEBYSCORE operations
+          # @return [Array] Array suitable for Valkey/Redis ZRANGEBYSCORE operations
           #
           # @example Time range
-          #   score_range(1.hour.ago, Time.now)
+          #   score_range(1.hour.ago, Familia.now)
           #   #=> [1704063600.0, 1704067200.255]
           #
           # @example Permission filter
@@ -367,13 +367,13 @@ module Familia
           # @param category [Symbol] Category to create range for
           # @param start_time [Time, nil] Optional start time filter
           # @param end_time [Time, nil] Optional end time filter
-          # @return [Array<String>] Min and max range strings for Redis queries
+          # @return [Array<String>] Min and max range strings for Valkey/Redis queries
           def category_score_range(category, start_time = nil, end_time = nil)
             PERMISSION_CATEGORIES[category] || 0
 
             # Any permission matching the category mask
             min_score = start_time ? start_time.to_i : 0
-            max_score = end_time ? end_time.to_i : Time.now.to_i
+            max_score = end_time ? end_time.to_i : Familia.now.to_i
 
             # Return range that includes any matching permissions
             ["#{min_score}.000", "#{max_score}.999"]

data/lib/familia/features/relationships.rb

@@ -2,80 +2,61 @@
 
 require 'securerandom'
 require_relative 'relationships/score_encoding'
-require_relative 'relationships/redis_operations'
-require_relative 'relationships/tracking'
+require_relative 'relationships/participation'
 require_relative 'relationships/indexing'
-require_relative 'relationships/membership'
-require_relative 'relationships/cascading'
-require_relative 'relationships/querying'
-require_relative 'relationships/permission_management'
 
 module Familia
   module Features
     # Unified Relationships feature for Familia v2
     #
     # This feature merges the functionality of relatable_objects and relationships
-    # into a single, Redis-native implementation that embraces the "where does this appear?"
+    # into a single, Valkey/Redis-native implementation that embraces the "where does this appear?"
     # philosophy rather than "who owns this?".
     #
-    # Key improvements in v2:
-    # - Multi-presence: Objects can exist in multiple collections simultaneously
-    # - Score encoding: Metadata embedded in Redis scores for efficiency
-    # - Collision-free: Method names include collection names to prevent conflicts
-    # - Redis-native: All operations use Redis commands, no Ruby iteration
-    # - Atomic operations: Multi-collection updates happen atomically
-    #
-    # Breaking changes from v1:
-    # - Single feature: Use `feature :relationships` instead of separate features
-    # - Simplified identifier: Use `identifier :field` instead of `identifier_field :field`
-    # - No ownership concept: Remove `owned_by`, use multi-presence instead
-    # - Method naming: Generated methods include collection names for uniqueness
-    # - Score encoding: Scores can carry metadata like permissions
-    #
     # @example Basic usage
     #   class Domain < Familia::Horreum
-    #     feature :relationships
     #
-    #     identifier :domain_id
+    #     identifier_field :domain_id
+    #
     #     field :domain_id
     #     field :display_name
     #     field :created_at
     #     field :permission_bits
     #
-    #     # Multi-presence tracking with score encoding
-    #     tracked_in Customer, :domains,
-    #                score: -> { permission_encode(created_at, permission_bits) }
-    #     tracked_in Team, :domains, score: :added_at
-    #     tracked_in Organization, :all_domains, score: :created_at
+    #     feature :relationships
+    #
+    #     # Multi-presence participation with score encoding
+    #     participates_in Customer, :domains,
+    #                     score: -> { permission_encode(created_at, permission_bits) }
+    #     participates_in Team, :domains, score: :added_at
+    #     participates_in Organization, :all_domains, score: :created_at
     #
-    #     # O(1) lookups with Redis hashes
-    #     indexed_by :display_name, :domain_index, context: Customer
-    #     indexed_by :display_name, :global_domain_index, context: :global
+    #     # O(1) lookups with Valkey/Redis hashes
+    #     indexed_by :display_name, :domain_index, target: Customer
     #
-    #     # Context-aware membership (no method collisions)
-    #     member_of Customer, :domains
-    #     member_of Team, :domains
-    #     member_of Organization, :domains
+    #     # Participation with bidirectional control (no method collisions)
+    #     participates_in Customer, :domains
+    #     participates_in Team, :domains, bidirectional: false
+    #     participates_in Organization, :domains, type: :set
     #   end
     #
     # @example Generated methods (collision-free)
-    #   # Tracking methods
+    #   # Participation methods
     #   Customer.domains                    # => Familia::SortedSet
     #   Customer.add_domain(domain, score)  # Add to customer's domains
     #   domain.in_customer_domains?(customer) # Check membership
     #
     #   # Indexing methods
     #   Customer.find_by_display_name(name) # O(1) lookup
-    #   Domain.find_by_display_name(name) # Global lookup
     #
-    #   # Membership methods (collision-free naming)
+    #   # Bidirectional methods (collision-free naming)
     #   domain.add_to_customer_domains(customer)  # Specific collection
     #   domain.add_to_team_domains(team)          # Different collection
     #   domain.in_customer_domains?(customer)     # Check specific membership
     #
     # @example Score encoding for permissions
     #   # Encode permission in score
-    #   score = domain.permission_encode(Time.now, :write)
+    #   score = domain.permission_encode(Familia.now, :write)
     #   # => 1704067200.004 (timestamp + permission bits)
     #
     #   # Decode permission from score
@@ -89,43 +70,32 @@ module Familia
     #   # Atomic updates across multiple collections
     #   domain.update_multiple_presence([
     #     { key: "customer:123:domains", score: current_score },
-    #     { key: "team:456:domains", score: permission_encode(Time.now, :read) }
+    #     { key: "team:456:domains", score: permission_encode(Familia.now, :read) }
     #   ], :add, domain.identifier)
     #
-    #   # Set operations on collections
+    #   # UnsortedSet operations on collections
     #   accessible = Domain.union_collections([
     #     { owner: customer, collection: :domains },
     #     { owner: team, collection: :domains }
     #   ], min_permission: :read)
     module Relationships
-
       # Register the feature with Familia
       Familia::Base.add_feature Relationships, :relationships
 
       # Feature initialization
       def self.included(base)
         Familia.ld "[#{base}] Relationships included"
-        base.extend ClassMethods
-        base.include InstanceMethods
+        base.extend ModelClassMethods
+        base.include ModelInstanceMethods
 
         # Include all relationship submodules and their class methods
         base.include ScoreEncoding
-        base.include RedisOperations
 
-        base.include Tracking
-        base.extend Tracking::ClassMethods
+        base.include Participation
+        base.extend Participation::ModelClassMethods
 
         base.include Indexing
-        base.extend Indexing::ClassMethods
-
-        base.include Membership
-        base.extend Membership::ClassMethods
-
-        base.include Cascading
-        base.extend Cascading::ClassMethods
-
-        base.include Querying
-        base.extend Querying::ClassMethods
+        base.extend Indexing::ModelClassMethods
       end
 
       # Error classes
@@ -134,7 +104,7 @@ module Familia
       class InvalidScoreError < RelationshipError; end
       class CascadeError < RelationshipError; end
 
-      module ClassMethods
+      module ModelClassMethods
         # Define the identifier for this class (replaces identifier_field)
         # This is a compatibility wrapper around the existing identifier_field method
         #
@@ -149,21 +119,6 @@ module Familia
           identifier_field
         end
 
-        # Generate a secure temporary identifier
-        def generate_identifier
-          SecureRandom.hex(8)
-        end
-
-        # Get all relationship configurations for this class
-        def relationship_configs
-          configs = {}
-
-          configs[:tracking] = tracking_relationships if respond_to?(:tracking_relationships)
-          configs[:indexing] = indexing_relationships if respond_to?(:indexing_relationships)
-          configs[:membership] = membership_relationships if respond_to?(:membership_relationships)
-
-          configs
-        end
 
         # Validate relationship configurations
         def validate_relationships!
@@ -172,25 +127,14 @@ module Familia
           # Check for method name collisions
           method_names = []
 
-          if respond_to?(:tracking_relationships)
-            tracking_relationships.each do |config|
-              context_name = config[:context_class_name].downcase
-              collection_name = config[:collection_name]
-
-              method_names << "in_#{context_name}_#{collection_name}?"
-              method_names << "add_to_#{context_name}_#{collection_name}"
-              method_names << "remove_from_#{context_name}_#{collection_name}"
-            end
-          end
-
-          if respond_to?(:membership_relationships)
-            membership_relationships.each do |config|
-              owner_name = config[:owner_class_name].downcase
+          if respond_to?(:participation_relationships)
+            participation_relationships.each do |config|
+              target_name = config[:target_class_name].downcase
               collection_name = config[:collection_name]
 
-              method_names << "in_#{owner_name}_#{collection_name}?"
-              method_names << "add_to_#{owner_name}_#{collection_name}"
-              method_names << "remove_from_#{owner_name}_#{collection_name}"
+              method_names << "in_#{target_name}_#{collection_name}?"
+              method_names << "add_to_#{target_name}_#{collection_name}"
+              method_names << "remove_from_#{target_name}_#{collection_name}"
             end
           end
 
@@ -209,20 +153,13 @@ module Familia
           true
         end
 
-        # Create a new instance with relationships initialized
-        def create_with_relationships(attributes = {})
-          instance = new(attributes)
-          instance.initialize_relationships
-          instance
-        end
-
         # Class method wrapper for create_temp_key
         def create_temp_key(base_name, ttl = 300)
-          timestamp = Time.now.to_i
+          timestamp = Familia.now.to_i
           random_suffix = SecureRandom.hex(3)
           temp_key = "temp:#{base_name}:#{timestamp}:#{random_suffix}"
 
-          # Set immediate expiry to ensure cleanup even if operation fails
+          # UnsortedSet immediate expiry to ensure cleanup even if operation fails
           if respond_to?(:dbclient)
             dbclient.expire(temp_key, ttl)
           else
@@ -236,116 +173,60 @@ module Familia
         include ScoreEncoding
 
         private
-
-        # Simple constantize method to convert string to constant
-        def constantize_class_name(class_name)
-          class_name.split('::').reduce(Object) { |mod, name| mod.const_get(name) }
-        rescue NameError
-          # If the class doesn't exist, return nil
-          nil
-        end
       end
 
-      module InstanceMethods
-        # Get the identifier value for this instance
-        # Uses the existing Horreum identifier infrastructure
-        def identifier
-          id_field = self.class.identifier_field
-          send(id_field) if respond_to?(id_field)
-        end
-
-        # Set the identifier value for this instance
-        def identifier=(value)
-          id_field = self.class.identifier_field
-          send("#{id_field}=", value) if respond_to?("#{id_field}=")
-        end
-
-        # Initialize relationships (called after object creation)
-        def initialize_relationships
-          # This can be overridden by subclasses to set up initial relationships
-        end
+      module ModelInstanceMethods
+        # NOTE: identifier and identifier= methods are provided by Horreum base class
+        # No need to override them here - use the existing infrastructure
 
         # Override save to update relationships automatically
         def save(update_expiration: true)
           result = super
 
-          if result
+          if result && respond_to?(:update_all_indexes)
             # Automatically update all indexes when object is saved
-            if respond_to?(:update_all_indexes)
-              update_all_indexes
-            end
-
-            # Auto-add to class-level tracking collections
-            if respond_to?(:add_to_class_tracking_collections)
-              add_to_class_tracking_collections
-            end
+            update_all_indexes
 
-            # NOTE: Relationship-specific membership and tracking updates are done explicitly
+            # NOTE: Relationship-specific participation updates are done explicitly
             # since we need to know which specific collections this object should be in
           end
 
           result
         end
 
-        # Override destroy to handle cascade operations
-        def destroy!
-          # Execute cascade operations before destroying the object
-          execute_cascade_operations if respond_to?(:execute_cascade_operations)
-
-          super
-        end
-
         # Get comprehensive relationship status for this object
         def relationship_status
           status = {
             identifier: identifier,
-            tracking_memberships: [],
-            membership_collections: [],
-            index_memberships: []
+            current_participations: [],
+            index_memberships: [],
           }
 
-          # Get tracking memberships
-          if respond_to?(:tracking_collections_membership)
-            status[:tracking_memberships] = tracking_collections_membership
-          end
-
-          # Get membership collections
-          status[:membership_collections] = membership_collections if respond_to?(:membership_collections)
+          # Get participation memberships
+          status[:current_participations] = current_participations if respond_to?(:current_participations)
 
           # Get index memberships
-          status[:index_memberships] = indexing_memberships if respond_to?(:indexing_memberships)
+          status[:index_memberships] = current_indexings if respond_to?(:current_indexings)
 
           status
         end
 
         # Comprehensive cleanup - remove from all relationships
+        #
+        # @deprecated This method is poorly implemented and will be removed in v3.0.
+        #   The participation collection removal logic was repetitive and difficult to debug.
+        #   A cleaner implementation will be provided in a future version.
+        #   See pull #115 for details.
+        #
+        # @note Currently only removes from indexes, not participation collections
         def cleanup_all_relationships!
-          # Remove from tracking collections
-          remove_from_all_tracking_collections if respond_to?(:remove_from_all_tracking_collections)
-
-          # Remove from membership collections
-          remove_from_all_memberships if respond_to?(:remove_from_all_memberships)
+          warn '[DEPRECATED] cleanup_all_relationships! will be removed in v3.0. See pull #115.'
+          warn 'Not currently removing from participation collections. Only indexes will be cleaned.'
 
           # Remove from indexes
           remove_from_all_indexes if respond_to?(:remove_from_all_indexes)
         end
 
-        # Dry run for relationship cleanup (preview what would be affected)
-        def cleanup_preview
-          preview = {
-            tracking_collections: [],
-            membership_collections: [],
-            index_entries: []
-          }
-
-          if respond_to?(:cascade_dry_run)
-            cascade_preview = cascade_dry_run
-            preview.merge!(cascade_preview)
-          end
-
-          preview
-        end
-
         # Validate that this object's relationships are consistent
         def validate_relationships!
           errors = []
@@ -353,11 +234,11 @@ module Familia
           # Validate identifier exists
           errors << 'Object identifier is nil' unless identifier
 
-          # Validate tracking memberships
-          if respond_to?(:tracking_collections_membership)
-            tracking_collections_membership.each do |membership|
+          # Validate participation memberships
+          if respond_to?(:current_participations)
+            current_participations.each do |membership|
               score = membership[:score]
-              errors << "Invalid score in tracking membership: #{membership}" if score && !score.is_a?(Numeric)
+              errors << "Invalid score in participation membership: #{membership}" if score && !score.is_a?(Numeric)
             end
           end
 
@@ -366,107 +247,25 @@ module Familia
           true
         end
 
-        # Refresh relationship data from Redis (useful after external changes)
-        def refresh_relationships!
-          # Clear any cached relationship data
-          @relationship_status = nil
-          @tracking_memberships = nil
-          @membership_collections = nil
-          @index_memberships = nil
-
-          # Reload fresh data
-          relationship_status
-        end
-
-        # Create a snapshot of current relationship state (for debugging)
-        def relationship_snapshot
-          {
-            timestamp: Time.now,
-            identifier: identifier,
-            class: self.class.name,
-            status: relationship_status,
-            redis_keys: find_related_redis_keys
-          }
-        end
-
-        # Direct Redis access for instance methods
-        def redis
+        # Direct Valkey/Redis access for instance methods
+        def dbclient
           self.class.dbclient
         end
 
         # Instance method wrapper for create_temp_key
         def create_temp_key(base_name, ttl = 300)
-          timestamp = Time.now.to_i
+          timestamp = Familia.now.to_i
           random_suffix = SecureRandom.hex(3)
           temp_key = "temp:#{base_name}:#{timestamp}:#{random_suffix}"
 
-          # Set immediate expiry to ensure cleanup even if operation fails
-          redis.expire(temp_key, ttl)
+          # UnsortedSet immediate expiry to ensure cleanup even if operation fails
+          dbclient.expire(temp_key, ttl)
 
           temp_key
         end
 
-        # Instance method wrapper for cleanup_temp_keys
-        def cleanup_temp_keys(pattern = 'temp:*', batch_size = 100)
-          cursor = 0
-
-          loop do
-            cursor, keys = redis.scan(cursor, match: pattern, count: batch_size)
-
-            if keys.any?
-              # Check TTL and remove keys that should have expired
-              keys.each_slice(batch_size) do |key_batch|
-                redis.pipelined do |pipeline|
-                  key_batch.each do |key|
-                    ttl = redis.ttl(key)
-                    pipeline.del(key) if ttl == -1 # Key exists but has no TTL
-                  end
-                end
-              end
-            end
-
-            break if cursor.zero?
-          end
-        end
-
         private
-
-        # Find all Redis keys related to this object
-        def find_related_redis_keys
-          related_keys = []
-          id = identifier
-          return related_keys unless id
-
-          # Scan for keys that might contain this object
-          patterns = [
-            '*:*:*',  # General pattern for relationship keys
-            "*#{id}*" # Keys containing the identifier
-          ]
-
-          patterns.each do |pattern|
-            redis.scan_each(match: pattern, count: 100) do |key|
-              # Check if this key actually contains our object
-              key_type = redis.type(key)
-
-              case key_type
-              when 'zset'
-                related_keys << key if redis.zscore(key, id)
-              when 'set'
-                related_keys << key if redis.sismember(key, id)
-              when 'list'
-                related_keys << key if redis.lpos(key, id)
-              when 'hash'
-                # For hash keys, check if any field values match our identifier
-                hash_values = redis.hvals(key)
-                related_keys << key if hash_values.include?(id.to_s)
-              end
-            end
-          end
-
-          related_keys.uniq
-        end
       end
-
     end
   end
 end