familia 2.0.0.pre15 → 2.0.0.pre17

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

@@ -1,274 +0,0 @@
-# lib/familia/features/relationships/redis_operations.rb
-
-module Familia
-  module Features
-    module Relationships
-      # Redis operations module providing atomic multi-collection operations
-      # and native Redis set operations for relationships
-      module RedisOperations
-        # Execute multiple Redis operations atomically using MULTI/EXEC
-        #
-        # @param redis [Redis] Redis connection to use
-        # @yield [Redis] Yields Redis connection in transaction context
-        # @return [Array] Results from Redis transaction
-        #
-        # @example Atomic multi-collection update
-        #   atomic_operation(redis) do |tx|
-        #     tx.zadd("customer:123:domains", score, domain_id)
-        #     tx.zadd("team:456:domains", score, domain_id)
-        #     tx.hset("domain_index", domain_name, domain_id)
-        #   end
-        def atomic_operation(redis = nil)
-          redis ||= redis_connection
-
-          redis.multi do |tx|
-            yield tx if block_given?
-          end
-        end
-
-        # Update object presence in multiple collections atomically
-        #
-        # @param collections [Array<Hash>] Array of collection configurations
-        # @param action [Symbol] Action to perform (:add, :remove)
-        # @param identifier [String] Object identifier
-        # @param default_score [Float] Default score if not specified per collection
-        #
-        # @example Update presence in multiple collections
-        #   update_multiple_presence([
-        #     { key: "customer:123:domains", score: current_score },
-        #     { key: "team:456:domains", score: permission_encode(Time.now, :read) },
-        #     { key: "org:789:all_domains", score: current_score }
-        #   ], :add, domain.identifier)
-        def update_multiple_presence(collections, action, identifier, default_score = nil)
-          return unless collections&.any?
-
-          redis = self.class.dbclient
-
-          atomic_operation(redis) do |tx|
-            collections.each do |collection_config|
-              redis_key = collection_config[:key]
-              score = collection_config[:score] || default_score || current_score
-
-              case action
-              when :add
-                tx.zadd(redis_key, score, identifier)
-              when :remove
-                tx.zrem(redis_key, identifier)
-              when :update
-                # Use ZADD with XX flag to only update existing members
-                tx.zadd(redis_key, score, identifier, xx: true)
-              end
-            end
-          end
-        end
-
-        # Perform Redis set operations (union, intersection, difference) on sorted sets
-        #
-        # @param operation [Symbol] Operation type (:union, :intersection, :difference)
-        # @param destination [String] Redis key for result storage
-        # @param source_keys [Array<String>] Source Redis keys to operate on
-        # @param weights [Array<Float>] Optional weights for union operations
-        # @param aggregate [Symbol] Aggregation method (:sum, :min, :max)
-        # @param ttl [Integer] TTL for destination key in seconds
-        # @return [Integer] Number of elements in resulting set
-        #
-        # @example Union of accessible domains
-        #   set_operation(:union, "temp:accessible_domains:#{user_id}",
-        #                 ["customer:domains", "team:domains", "org:domains"],
-        #                 ttl: 300)
-        def set_operation(operation, destination, source_keys, weights: nil, aggregate: :sum, ttl: nil)
-          return 0 if source_keys.empty?
-
-          redis = redis_connection
-
-          atomic_operation(redis) do |tx|
-            case operation
-            when :union
-              if weights
-                tx.zunionstore(destination, source_keys.zip(weights).to_h, aggregate: aggregate)
-              else
-                tx.zunionstore(destination, source_keys, aggregate: aggregate)
-              end
-            when :intersection
-              if weights
-                tx.zinterstore(destination, source_keys.zip(weights).to_h, aggregate: aggregate)
-              else
-                tx.zinterstore(destination, source_keys, aggregate: aggregate)
-              end
-            when :difference
-              first_key = source_keys.first
-              other_keys = source_keys[1..] || []
-
-              tx.zunionstore(destination, [first_key])
-              other_keys.each do |key|
-                members = redis.zrange(key, 0, -1)
-                tx.zrem(destination, members) if members.any?
-              end
-            end
-
-            tx.expire(destination, ttl) if ttl
-          end
-
-          redis.zcard(destination)
-        end
-
-        # Create temporary Redis key with automatic cleanup
-        #
-        # @param base_name [String] Base name for the temporary key
-        # @param ttl [Integer] TTL in seconds (default: 300)
-        # @return [String] Generated temporary key name
-        #
-        # @example
-        #   temp_key = create_temp_key("user_accessible_domains", 600)
-        #   #=> "temp:user_accessible_domains:1704067200:abc123"
-        def create_temp_key(base_name, ttl = 300)
-          timestamp = Time.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_connection.expire(temp_key, ttl)
-
-          temp_key
-        end
-
-        # Batch add multiple items to a sorted set
-        #
-        # @param redis_key [String] Redis sorted set key
-        # @param items [Array<Hash>] Array of {member: String, score: Float} hashes
-        # @param mode [Symbol] Add mode (:normal, :nx, :xx, :lt, :gt)
-        #
-        # @example Batch add domains with scores
-        #   batch_zadd("customer:domains", [
-        #     { member: "domain1", score: encode_score(Time.now, permission: :read) },
-        #     { member: "domain2", score: encode_score(Time.now, permission: :write) }
-        #   ])
-        def batch_zadd(redis_key, items, mode: :normal)
-          return 0 if items.empty?
-
-          redis = redis_connection
-          zadd_args = items.flat_map { |item| [item[:score], item[:member]] }
-
-          case mode
-          when :nx
-            redis.zadd(redis_key, zadd_args, nx: true)
-          when :xx
-            redis.zadd(redis_key, zadd_args, xx: true)
-          when :lt
-            redis.zadd(redis_key, zadd_args, lt: true)
-          when :gt
-            redis.zadd(redis_key, zadd_args, gt: true)
-          else
-            redis.zadd(redis_key, zadd_args)
-          end
-        end
-
-        # Query sorted set with score filtering and permission checking
-        #
-        # @param redis_key [String] Redis sorted set key
-        # @param start_score [Float] Minimum score (inclusive)
-        # @param end_score [Float] Maximum score (inclusive)
-        # @param offset [Integer] Offset for pagination
-        # @param count [Integer] Maximum number of results
-        # @param with_scores [Boolean] Include scores in results
-        # @param min_permission [Symbol] Minimum permission level required
-        # @return [Array] Query results
-        #
-        # @example Query domains with read permission or higher
-        #   query_by_score("customer:domains",
-        #                  encode_score(1.hour.ago, 0),
-        #                  encode_score(Time.now, MAX_METADATA),
-        #                  min_permission: :read)
-        def query_by_score(redis_key, start_score = '-inf', end_score = '+inf',
-                           offset: 0, count: -1, with_scores: false, min_permission: nil)
-          self.class.dbclient
-
-          # Adjust score range for permission filtering
-          if min_permission
-            permission_value = ScoreEncoding.permission_level_value(min_permission)
-            # Ensure minimum score includes required permission level
-            if start_score.is_a?(Numeric)
-              decoded = decode_score(start_score)
-              if decoded[:permissions] < permission_value
-                start_score = encode_score(decoded[:timestamp],
-                                           permission_value)
-              end
-            else
-              start_score = encode_score(0, permission_value)
-            end
-          end
-
-          options = {
-            limit: (count.positive? ? [offset, count] : nil),
-            with_scores: with_scores
-          }.compact
-
-          results = dbclient.zrangebyscore(redis_key, start_score, end_score, **options)
-
-          # Filter results by permission if needed using correct bitwise operations
-          if min_permission && with_scores
-            permission_mask = ScoreEncoding.permission_level_value(min_permission)
-            results = results.select do |_member, score|
-              decoded = decode_score(score)
-              # Use bitwise AND to check if permission mask is satisfied
-              decoded[:permissions].allbits?(permission_mask)
-            end
-          end
-
-          results
-        end
-
-        # Clean up expired temporary keys
-        #
-        # @param pattern [String] Pattern to match temporary keys
-        # @param batch_size [Integer] Number of keys to process at once
-        #
-        # @example Clean up old temporary keys
-        #   cleanup_temp_keys("temp:user_*", 100)
-        def cleanup_temp_keys(pattern = 'temp:*', batch_size = 100)
-          self.class.dbclient
-          cursor = 0
-
-          loop do
-            cursor, keys = dbclient.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|
-                dbclient.pipelined do |pipeline|
-                  key_batch.each do |key|
-                    ttl = dbclient.ttl(key)
-                    pipeline.del(key) if ttl == -1 # Key exists but has no TTL
-                  end
-                end
-              end
-            end
-
-            break if cursor.zero?
-          end
-        end
-
-        # Get Redis connection for the current class or instance
-        def redis_connection
-          if self.class.respond_to?(:dbclient)
-            self.class.dbclient
-          elsif respond_to?(:dbclient)
-            dbclient
-          else
-            Familia.dbclient
-          end
-        end
-
-        private
-
-        # Validate Redis key format
-        def validate_redis_key(key)
-          raise ArgumentError, 'Redis key cannot be nil or empty' if key.nil? || key.empty?
-          raise ArgumentError, 'Redis key must be a string' unless key.is_a?(String)
-
-          key
-        end
-      end
-    end
-  end
-end

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

@@ -1,418 +0,0 @@
-# lib/familia/features/relationships/tracking.rb
-
-module Familia
-  module Features
-    module Relationships
-      # Tracking module for tracked_in relationships using Redis sorted sets
-      # Provides multi-presence support where objects can exist in multiple collections
-      module Tracking
-        # Class-level tracking configurations
-        def self.included(base)
-          base.extend ClassMethods
-          base.include InstanceMethods
-          super
-        end
-
-        module ClassMethods
-          # Simple singularize method (basic implementation)
-          def singularize_word(word)
-            word = word.to_s
-            # Basic English pluralization rules (simplified)
-            if word.end_with?('ies')
-              "#{word[0..-4]}y"
-            elsif word.end_with?('es') && word.length > 3
-              word[0..-3]
-            elsif word.end_with?('s') && word.length > 1
-              word[0..-2]
-            else
-              word
-            end
-          end
-
-          # Simple camelize method (basic implementation)
-          def camelize_word(word)
-            word.to_s.split('_').map(&:capitalize).join
-          end
-
-          # Define a class-level tracked collection
-          #
-          # @param collection_name [Symbol] Name of the class-level collection
-          # @param score [Symbol, Proc, nil] How to calculate the score
-          # @param on_destroy [Symbol] What to do when object is destroyed (:remove, :ignore)
-          #
-          # @example Class-level tracking (using class_ prefix convention)
-          #   class_tracked_in :all_customers, score: :created_at
-          #   class_tracked_in :active_users, score: -> { status == 'active' ? Time.now.to_i : 0 }
-          def class_tracked_in(collection_name, score: nil, on_destroy: :remove)
-
-            klass_name = (name || self.to_s).downcase
-
-            # Store metadata for this tracking relationship
-            tracking_relationships << {
-              context_class: klass_name,
-              context_class_name: name || self.to_s,
-              collection_name: collection_name,
-              score: score,
-              on_destroy: on_destroy
-            }
-
-            # Generate class-level collection methods
-            generate_tracking_class_methods(self, collection_name)
-
-            # Generate instance methods for class-level tracking
-            generate_tracking_instance_methods('class', collection_name, score)
-          end
-
-          # Define a tracked_in relationship
-          #
-          # @param context_class [Class, Symbol] The class that owns the collection
-          # @param collection_name [Symbol] Name of the collection
-          # @param score [Symbol, Proc, nil] How to calculate the score
-          # @param on_destroy [Symbol] What to do when object is destroyed (:remove, :ignore)
-          #
-          # @example Basic tracking
-          #   tracked_in Customer, :domains, score: :created_at
-          #
-          # @example Multi-presence tracking
-          #   tracked_in Customer, :domains, score: -> { permission_encode(created_at, permission_level) }
-          #   tracked_in Team, :domains, score: :added_at
-          #   tracked_in Organization, :all_domains, score: :created_at
-          def tracked_in(context_class, collection_name, score: nil, on_destroy: :remove)
-
-            # Handle class context
-            if context_class.is_a?(Class)
-              class_name = context_class.name
-              context_class_name = if class_name.include?('::')
-                                     # Extract the last part after the last ::
-                                     class_name.split('::').last
-                                   else
-                                     class_name
-                                   end
-            else
-              context_class_name = camelize_word(context_class)
-            end
-
-            # Store metadata for this tracking relationship
-            tracking_relationships << {
-              context_class: context_class,
-              context_class_name: context_class_name,
-              collection_name: collection_name,
-              score: score,
-              on_destroy: on_destroy
-            }
-
-            # Generate context class methods
-            generate_context_class_methods(context_class, collection_name)
-
-            # Generate instance methods on this class
-            generate_tracking_instance_methods(context_class_name, collection_name, score)
-          end
-
-          # Get all tracking relationships for this class
-          def tracking_relationships
-            @tracking_relationships ||= []
-          end
-
-          private
-
-          # Generate class-level collection methods (e.g., User.all_users)
-          def generate_tracking_class_methods(target_class, collection_name)
-            # Generate class-level collection getter method
-            target_class.define_singleton_method("#{collection_name}") do
-              collection_key = "#{self.name.downcase}:#{collection_name}"
-              Familia::SortedSet.new(nil, dbkey: collection_key, logical_database: logical_database)
-            end
-
-            # Generate class-level add method (e.g., User.add_to_all_users)
-            target_class.define_singleton_method("add_to_#{collection_name}") do |item, score = nil|
-              collection = send("#{collection_name}")
-
-              # Calculate score if not provided
-              score ||= if item.respond_to?(:calculate_tracking_score)
-                          item.calculate_tracking_score('class', collection_name)
-                        else
-                          item.current_score
-                        end
-
-              # Ensure score is never nil
-              score = item.current_score if score.nil?
-
-              collection.add(score, item.identifier)
-            end
-
-            # Generate class-level remove method
-            target_class.define_singleton_method("remove_from_#{collection_name}") do |item|
-              collection = send("#{collection_name}")
-              collection.delete(item.identifier)
-            end
-          end
-
-          # Generate methods on the context class (e.g., Customer.domains)
-          def generate_context_class_methods(context_class, collection_name)
-            # Resolve context class if it's a symbol/string
-            actual_context_class = context_class.is_a?(Class) ? context_class : Object.const_get(camelize_word(context_class))
-
-            # Generate collection getter method
-            actual_context_class.define_method(collection_name) do
-              collection_key = "#{self.class.name.downcase}:#{identifier}:#{collection_name}"
-              Familia::SortedSet.new(nil, dbkey: collection_key, logical_database: self.class.logical_database)
-            end
-
-            # Generate add method (e.g., Customer#add_domain)
-            actual_context_class.define_method("add_#{singularize_word(collection_name)}") do |item, score = nil|
-              collection = send(collection_name)
-
-              # Calculate score if not provided
-              score ||= if item.respond_to?(:calculate_tracking_score)
-                          item.calculate_tracking_score(self.class, collection_name)
-                        else
-                          item.current_score
-                        end
-
-              # Ensure score is never nil
-              score = item.current_score if score.nil?
-
-              collection.add(score, item.identifier)
-            end
-
-            # Generate remove method (e.g., Customer#remove_domain)
-            actual_context_class.define_method("remove_#{singularize_word(collection_name)}") do |item|
-              collection = send(collection_name)
-              collection.delete(item.identifier)
-            end
-
-            # Generate bulk add method (e.g., Customer#add_domains)
-            actual_context_class.define_method("add_#{collection_name}") do |items|
-              return if items.empty?
-
-              collection = send(collection_name)
-
-              # Prepare batch data
-              batch_data = items.map do |item|
-                score = if item.respond_to?(:calculate_tracking_score)
-                          item.calculate_tracking_score(self.class, collection_name)
-                        else
-                          item.current_score
-                        end
-                # Ensure score is never nil
-                score = item.current_score if score.nil?
-                { member: item.identifier, score: score }
-              end
-
-              # Use batch operation from RedisOperations
-              collection.dbclient.pipelined do |pipeline|
-                batch_data.each do |data|
-                  pipeline.zadd(collection.rediskey, data[:score], data[:member])
-                end
-              end
-            end
-
-            # Generate query methods with score filtering
-            actual_context_class.define_method("#{collection_name}_with_permission") do |min_permission = :read|
-              collection = send(collection_name)
-              permission_score = ScoreEncoding.permission_encode(0, min_permission)
-
-              collection.zrangebyscore(permission_score, '+inf', with_scores: true)
-            end
-          end
-
-          # Generate instance methods on the tracked class
-          def generate_tracking_instance_methods(context_class_name, collection_name, _score_calculator)
-            # Method to check if this object is in a specific collection
-            # e.g., domain.in_customer_domains?(customer)
-            define_method("in_#{context_class_name.downcase}_#{collection_name}?") do |context_instance|
-              collection_key = "#{context_class_name.downcase}:#{context_instance.identifier}:#{collection_name}"
-              dbclient.zscore(collection_key, identifier) != nil
-            end
-
-            # Method to add this object to a specific collection
-            # e.g., domain.add_to_customer_domains(customer, score)
-            define_method("add_to_#{context_class_name.downcase}_#{collection_name}") do |context_instance, score = nil|
-              collection_key = "#{context_class_name.downcase}:#{context_instance.identifier}:#{collection_name}"
-
-              score ||= calculate_tracking_score(context_class_name, collection_name)
-
-              # Ensure score is never nil
-              score = current_score if score.nil?
-
-              dbclient.zadd(collection_key, score, identifier)
-            end
-
-            # Method to remove this object from a specific collection
-            # e.g., domain.remove_from_customer_domains(customer)
-            define_method("remove_from_#{context_class_name.downcase}_#{collection_name}") do |context_instance|
-              collection_key = "#{context_class_name.downcase}:#{context_instance.identifier}:#{collection_name}"
-              dbclient.zrem(collection_key, identifier)
-            end
-
-            # Method to get score in a specific collection
-            # e.g., domain.score_in_customer_domains(customer)
-            define_method("score_in_#{context_class_name.downcase}_#{collection_name}") do |context_instance|
-              collection_key = "#{context_class_name.downcase}:#{context_instance.identifier}:#{collection_name}"
-              dbclient.zscore(collection_key, identifier)
-            end
-
-            # Method to update score in a specific collection
-            # e.g., domain.update_score_in_customer_domains(customer, new_score)
-            define_method("update_score_in_#{context_class_name.downcase}_#{collection_name}") do |context_instance, new_score|
-              collection_key = "#{context_class_name.downcase}:#{context_instance.identifier}:#{collection_name}"
-              dbclient.zadd(collection_key, new_score, identifier, xx: true) # Only update existing
-            end
-          end
-        end
-
-        # Instance methods for tracked objects
-        module InstanceMethods
-          # Calculate the appropriate score for a tracking relationship
-          #
-          # @param context_class [Class] The context class (e.g., Customer)
-          # @param collection_name [Symbol] The collection name (e.g., :domains)
-          # @return [Float] Calculated score
-          def calculate_tracking_score(context_class, collection_name)
-            # Find the tracking configuration
-            tracking_config = self.class.tracking_relationships.find do |config|
-              config[:context_class] == context_class && config[:collection_name] == collection_name
-            end
-
-            return current_score unless tracking_config
-
-            score_calculator = tracking_config[:score]
-
-            case score_calculator
-            when Symbol
-              # Field name or method name
-              if respond_to?(score_calculator)
-                value = send(score_calculator)
-                if value.respond_to?(:to_f)
-                  value.to_f
-                elsif value.respond_to?(:to_i)
-                  encode_score(value, 0)
-                else
-                  current_score
-                end
-              else
-                current_score
-              end
-            when Proc
-              # Execute proc in context of this instance
-              result = instance_exec(&score_calculator)
-              # Ensure we get a numeric result
-              if result.nil?
-                current_score
-              elsif result.respond_to?(:to_f)
-                result.to_f
-              else
-                current_score
-              end
-            when Numeric
-              score_calculator.to_f
-            else
-              current_score
-            end
-          end
-
-          # Update presence in all tracked collections atomically
-          def update_all_tracking_collections
-            return unless self.class.respond_to?(:tracking_relationships)
-
-            []
-
-            self.class.tracking_relationships.each do |config|
-              config[:context_class_name]
-              config[:collection_name]
-
-              # This is a simplified version - in practice, you'd need to know
-              # which specific instances this object should be tracked in
-              # For now, we'll skip the automatic update and rely on explicit calls
-            end
-          end
-
-          # Add to class-level tracking collections automatically
-          def add_to_class_tracking_collections
-            return unless self.class.respond_to?(:tracking_relationships)
-
-            self.class.tracking_relationships.each do |config|
-              context_class_name = config[:context_class_name]
-              context_class = config[:context_class]
-              collection_name = config[:collection_name]
-
-              # Only auto-add to class-level collections (where context_class matches self.class)
-              if context_class_name.downcase == self.class.name.downcase
-                # Call the class method to add this object
-                self.class.send("add_to_#{collection_name}", self)
-              end
-            end
-          end
-
-          # Remove from all tracking collections (used during destroy)
-          def remove_from_all_tracking_collections
-            return unless self.class.respond_to?(:tracking_relationships)
-
-            # Get all possible collection keys this object might be in
-            # This is expensive but necessary for cleanup
-            redis_conn = redis
-            pattern = '*:*:*' # This could be optimized with better key patterns
-
-            cursor = 0
-            matching_keys = []
-
-            loop do
-              cursor, keys = redis_conn.scan(cursor, match: pattern, count: 1000)
-              matching_keys.concat(keys)
-              break if cursor.zero?
-            end
-
-            # Filter keys that might contain this object and remove it
-            redis_conn.pipelined do |pipeline|
-              matching_keys.each do |key|
-                # Check if this key matches any of our tracking relationships
-                self.class.tracking_relationships.each do |config|
-                  context_class_name = config[:context_class_name].downcase
-                  collection_name = config[:collection_name]
-
-                  if key.include?(context_class_name) && key.include?(collection_name.to_s)
-                    pipeline.zrem(key, identifier)
-                  end
-                end
-              end
-            end
-          end
-
-          # Get all collections this object appears in
-          #
-          # @return [Array<Hash>] Array of collection information
-          def tracking_collections_membership
-            return [] unless self.class.respond_to?(:tracking_relationships)
-
-            memberships = []
-
-            self.class.tracking_relationships.each do |config|
-              context_class_name = config[:context_class_name]
-              collection_name = config[:collection_name]
-
-              # Find all instances of context_class where this object appears
-              # This is simplified - in practice you'd need a more efficient approach
-              pattern = "#{context_class_name.downcase}:*:#{collection_name}"
-
-              dbclient.scan_each(match: pattern) do |key|
-                score = dbclient.zscore(key, identifier)
-                if score
-                  context_id = key.split(':')[1]
-                  memberships << {
-                    context_class: context_class_name,
-                    context_id: context_id,
-                    collection_name: collection_name,
-                    score: score,
-                    decoded_score: decode_score(score)
-                  }
-                end
-              end
-            end
-
-            memberships
-          end
-        end
-      end
-    end
-  end
-end