familia 2.0.0.pre5 → 2.0.0.pre7

data/lib/familia/validation/validator.rb

@@ -0,0 +1,412 @@
+# lib/familia/validation/validator.rb
+
+module Familia
+  module Validation
+    # Main validation engine that orchestrates command recording and validation.
+    # Provides high-level interface for validating Redis operations against
+    # expectations with detailed reporting and atomicity verification.
+    #
+    # @example Basic validation
+    #   validator = Validator.new
+    #
+    #   result = validator.validate do |expect|
+    #     # Define expectations
+    #     expect.hset("user:123", "name", "John")
+    #           .incr("counter")
+    #
+    #     # Execute code under test
+    #     user = User.new(id: "123", name: "John")
+    #     user.save
+    #     Counter.increment
+    #   end
+    #
+    #   puts result.valid? ? "PASS" : "FAIL"
+    #   puts result.detailed_report
+    #
+    # @example Transaction validation
+    #   validator = Validator.new
+    #
+    #   result = validator.validate do |expect|
+    #     expect.transaction do |tx|
+    #       tx.hset("user:123", "name", "John")
+    #         .incr("counter")
+    #     end
+    #
+    #     # Code should execute atomically
+    #     Familia.transaction do |conn|
+    #       conn.hset("user:123", "name", "John")
+    #       conn.incr("counter")
+    #     end
+    #   end
+    #
+    class Validator
+      attr_reader :options
+
+      def initialize(options = {})
+        @options = {
+          auto_register_middleware: true,
+          strict_atomicity: true,
+          performance_tracking: true,
+          command_filtering: :all # :all, :familia_only, :custom
+        }.merge(options)
+
+        register_middleware if @options[:auto_register_middleware]
+      end
+
+      # Main validation method - records commands and validates against expectations
+      def validate(&block)
+        raise ArgumentError, "Block required for validation" unless block_given?
+
+        expectations = nil
+        command_sequence = nil
+
+        begin
+          # Start recording commands
+          CommandRecorder.start_recording
+          register_middleware_if_needed
+
+          # Execute the validation block
+          expectations = CommandExpectations.new
+          block.call(expectations)
+
+          # Get recorded commands
+          command_sequence = CommandRecorder.stop_recording
+
+        rescue => e
+          CommandRecorder.stop_recording
+          raise ValidationError, "Validation failed with error: #{e.message}"
+        end
+
+        # Validate and return result
+        result = expectations.validate(command_sequence)
+
+        if @options[:performance_tracking]
+          add_performance_metrics(result, command_sequence)
+        end
+
+        if @options[:strict_atomicity]
+          apply_atomicity_validation(result, command_sequence)
+        end
+
+        result
+      end
+
+      # Validate that specific code executes expected Redis commands
+      def validate_execution(expectations_block, execution_block)
+        expectations = CommandExpectations.new
+        expectations_block.call(expectations)
+
+        CommandRecorder.start_recording
+        register_middleware_if_needed
+
+        begin
+          execution_block.call
+          command_sequence = CommandRecorder.stop_recording
+        rescue => e
+          CommandRecorder.stop_recording
+          raise ValidationError, "Execution failed: #{e.message}"
+        end
+
+        result = expectations.validate(command_sequence)
+
+        if @options[:performance_tracking]
+          add_performance_metrics(result, command_sequence)
+        end
+
+        result
+      end
+
+      # Validate that code executes atomically (within transactions)
+      def validate_atomicity(&block)
+        CommandRecorder.start_recording
+        register_middleware_if_needed
+
+        begin
+          block.call
+          command_sequence = CommandRecorder.stop_recording
+        rescue => e
+          CommandRecorder.stop_recording
+          raise ValidationError, "Atomicity validation failed: #{e.message}"
+        end
+
+        AtomicityValidator.new(command_sequence, @options).validate
+      end
+
+      # Assert that specific commands were executed
+      def assert_commands_executed(expected_commands, actual_commands = nil)
+        actual_commands ||= get_last_recorded_sequence
+
+        expectations = CommandExpectations.new
+        expected_commands.each do |cmd_spec|
+          case cmd_spec
+          when Array
+            expectations.command(cmd_spec[0], *cmd_spec[1..-1])
+          when Hash
+            cmd_spec.each do |cmd, args|
+              expectations.command(cmd, *Array(args))
+            end
+          when String
+            expectations.match_pattern(cmd_spec)
+          end
+        end
+
+        expectations.validate(actual_commands)
+      end
+
+      # Performance analysis of recorded commands
+      def analyze_performance(command_sequence)
+        PerformanceAnalyzer.new(command_sequence).analyze
+      end
+
+      # Capture and return Redis commands without validation
+      def capture_redis_commands(&block)
+        CommandRecorder.start_recording
+        register_middleware_if_needed
+        block.call if block_given?
+        CommandRecorder.stop_recording
+      end
+
+      private
+
+      def register_middleware
+        return if @middleware_registered
+
+        # Register our command recording middleware using the same pattern as connection.rb
+        if defined?(RedisClient)
+          RedisClient.register(CommandRecorder::Middleware)
+        end
+        @middleware_registered = true
+      end
+
+      def register_middleware_if_needed
+        register_middleware unless @middleware_registered
+      end
+
+      def get_last_recorded_sequence
+        CommandRecorder.current_sequence
+      end
+
+      def add_performance_metrics(result, command_sequence)
+        analyzer = PerformanceAnalyzer.new(command_sequence)
+        metrics = analyzer.analyze
+
+        result.instance_variable_set(:@performance_metrics, metrics)
+
+        # Add singleton methods to result
+        result.define_singleton_method(:performance_metrics) { @performance_metrics }
+        result.define_singleton_method(:total_duration_ms) { @performance_metrics[:total_duration_ms] }
+        result.define_singleton_method(:command_efficiency) { @performance_metrics[:efficiency_score] }
+      end
+
+      def apply_atomicity_validation(result, command_sequence)
+        atomicity_validator = AtomicityValidator.new(command_sequence, @options)
+        atomicity_result = atomicity_validator.validate
+
+        unless atomicity_result.valid?
+          result.instance_variable_get(:@errors).concat(atomicity_result.error_messages)
+          result.instance_variable_get(:@warnings).concat(atomicity_result.warning_messages)
+        end
+      end
+    end
+
+    # Validates that operations that should be atomic actually execute within transactions
+    class AtomicityValidator
+      attr_reader :command_sequence, :options
+
+      def initialize(command_sequence, options = {})
+        @command_sequence = command_sequence
+        @options = options
+        @errors = []
+        @warnings = []
+      end
+
+      def validate
+        check_transaction_boundaries
+        check_orphaned_commands
+        check_nested_transactions
+
+        ValidationResult.new(nil, @command_sequence).tap do |result|
+          result.instance_variable_set(:@errors, @errors)
+          result.instance_variable_set(:@warnings, @warnings)
+          result.instance_variable_set(:@valid, @errors.empty?)
+        end
+      end
+
+      private
+
+      def check_transaction_boundaries
+        @command_sequence.transaction_blocks.each_with_index do |tx_block, i|
+          unless tx_block.valid?
+            @errors << "Transaction block #{i + 1} is invalid (missing MULTI or EXEC)"
+          end
+
+          if tx_block.command_count == 0
+            @warnings << "Transaction block #{i + 1} contains no commands"
+          end
+        end
+      end
+
+      def check_orphaned_commands
+        # Commands that should be in transactions but aren't
+        orphaned_commands = @command_sequence.commands.select do |cmd|
+          !cmd.atomic_command? && should_be_atomic?(cmd)
+        end
+
+        orphaned_commands.each do |cmd|
+          @warnings << "Command #{cmd} should be executed atomically but was not in a transaction"
+        end
+      end
+
+      def check_nested_transactions
+        transaction_depth = 0
+
+        @command_sequence.commands.each do |cmd|
+          case cmd.command
+          when 'MULTI'
+            transaction_depth += 1
+            if transaction_depth > 1
+              @errors << "Nested transactions detected - Redis does not support nested MULTI/EXEC"
+            end
+          when 'EXEC', 'DISCARD'
+            transaction_depth -= 1
+            if transaction_depth < 0
+              @errors << "EXEC/DISCARD without matching MULTI command"
+            end
+          end
+        end
+
+        if transaction_depth > 0
+          @errors << "Unclosed transaction detected - MULTI without matching EXEC/DISCARD"
+        end
+      end
+
+      def should_be_atomic?(cmd)
+        # Define patterns for commands that should typically be atomic
+        atomic_patterns = [
+          /^HSET.*counter/i,  # Counter updates
+          /^INCR/i,           # Increments
+          /^DECR/i,           # Decrements
+          /batch_update/i     # Batch operations
+        ]
+
+        atomic_patterns.any? { |pattern| cmd.to_s.match?(pattern) }
+      end
+    end
+
+    # Analyzes performance characteristics of recorded commands
+    class PerformanceAnalyzer
+      attr_reader :command_sequence
+
+      def initialize(command_sequence)
+        @command_sequence = command_sequence
+      end
+
+      def analyze
+        {
+          total_commands: @command_sequence.command_count,
+          total_duration_ms: total_duration_ms,
+          average_command_time_us: average_command_time,
+          slowest_commands: slowest_commands(5),
+          command_type_breakdown: command_type_breakdown,
+          transaction_efficiency: transaction_efficiency,
+          potential_n_plus_one: detect_n_plus_one_patterns,
+          efficiency_score: calculate_efficiency_score
+        }
+      end
+
+      private
+
+      def total_duration_ms
+        @command_sequence.commands.sum(&:duration_us) / 1000.0
+      end
+
+      def average_command_time
+        return 0 if @command_sequence.command_count == 0
+
+        total_time = @command_sequence.commands.sum(&:duration_us)
+        total_time / @command_sequence.command_count
+      end
+
+      def slowest_commands(limit = 5)
+        @command_sequence.commands
+          .sort_by(&:duration_us)
+          .reverse
+          .first(limit)
+          .map { |cmd| { command: cmd.to_s, duration_us: cmd.duration_us } }
+      end
+
+      def command_type_breakdown
+        @command_sequence.commands
+          .group_by(&:command_type)
+          .transform_values(&:count)
+      end
+
+      def transaction_efficiency
+        return { score: 1.0, details: "No transactions" } if @command_sequence.transaction_count == 0
+
+        total_tx_commands = @command_sequence.transaction_blocks.sum(&:command_count)
+        total_commands = @command_sequence.command_count
+        tx_overhead = @command_sequence.transaction_count * 2 # MULTI + EXEC
+
+        efficiency = total_tx_commands.to_f / (total_tx_commands + tx_overhead)
+
+        {
+          score: efficiency,
+          total_transaction_commands: total_tx_commands,
+          transaction_overhead: tx_overhead,
+          details: "#{@command_sequence.transaction_count} transactions with #{total_tx_commands} commands"
+        }
+      end
+
+      def detect_n_plus_one_patterns
+        patterns = []
+
+        # Look for repeated similar commands that could be batched
+        command_groups = @command_sequence.commands.group_by { |cmd| cmd.command }
+
+        command_groups.each do |command, commands|
+          next unless commands.length > 3 # Threshold for N+1 detection
+
+          # Check if commands are similar (same command, similar keys)
+          if similar_commands?(commands)
+            patterns << {
+              command: command,
+              count: commands.length,
+              suggestion: "Consider batching #{command} operations"
+            }
+          end
+        end
+
+        patterns
+      end
+
+      def similar_commands?(commands)
+        return false if commands.length < 2
+
+        first_cmd = commands.first
+        commands.drop(1).all? do |cmd|
+          cmd.command == first_cmd.command &&
+          cmd.args.length == first_cmd.args.length
+        end
+      end
+
+      def calculate_efficiency_score
+        base_score = 100.0
+
+        # Penalize for potential N+1 patterns
+        n_plus_one_penalty = detect_n_plus_one_patterns.sum { |pattern| pattern[:count] * 2 }
+
+        # Penalize for non-atomic operations that should be atomic
+        non_atomic_penalty = @command_sequence.commands.count { |cmd| !cmd.atomic_command? } * 1
+
+        # Bonus for using transactions appropriately
+        transaction_bonus = @command_sequence.transaction_count > 0 ? 10 : 0
+
+        [base_score - n_plus_one_penalty - non_atomic_penalty + transaction_bonus, 0].max
+      end
+    end
+
+    # Custom error class for validation failures
+    class ValidationError < StandardError; end
+  end
+end

data/lib/familia/validation.rb

@@ -0,0 +1,140 @@
+# lib/familia/validation.rb
+
+# Redis Command Validation Framework for Familia
+#
+# Provides comprehensive validation of Redis operations to ensure commands
+# execute exactly as expected, with particular focus on atomicity verification
+# for transaction-based operations.
+#
+# @example Basic command validation
+#   include Familia::Validation
+#
+#   validator = Validator.new
+#   result = validator.validate do |expect|
+#     expect.hset("user:123", "name", "John")
+#           .incr("counter")
+#
+#     # Execute code that should perform these operations
+#     user = User.new(id: "123", name: "John")
+#     user.save
+#     Counter.increment
+#   end
+#
+#   puts result.valid? ? "PASS" : "FAIL"
+#
+# @example Using test helpers in try files
+#   require_relative 'lib/familia/validation'
+#   extend Familia::Validation::TestHelpers
+#
+#   ## User save executes expected Redis commands
+#   user = TestUser.new(id: "123", name: "John")
+#   assert_redis_commands do |expect|
+#     expect.hset("testuser:123:object", "name", "John")
+#     user.save
+#   end
+#   #=> true
+#
+# @example Transaction atomicity validation
+#   extend Familia::Validation::TestHelpers
+#
+#   ## Transfer should be atomic
+#   assert_atomic_operation do |expect|
+#     expect.transaction do |tx|
+#       tx.hset("account:123", "balance", "500")
+#         .hset("account:456", "balance", "1500")
+#     end
+#
+#     transfer_funds(from: "123", to: "456", amount: 500)
+#   end
+#   #=> true
+
+require_relative 'validation/command_recorder'
+require_relative 'validation/expectations'
+require_relative 'validation/validator'
+require_relative 'validation/test_helpers'
+
+module Familia
+  module Validation
+    # Quick access to main validator
+    def self.validator(options = {})
+      Validator.new(options)
+    end
+
+    # Validate a block of code against expected Redis commands
+    def self.validate(options = {}, &block)
+      validator(options).validate(&block)
+    end
+
+    # Validate that code executes atomically
+    def self.validate_atomicity(options = {}, &block)
+      validator(options).validate_atomicity(&block)
+    end
+
+    # Capture Redis commands without validation
+    def self.capture_commands(&block)
+      CommandRecorder.start_recording
+      block.call if block_given?
+      CommandRecorder.stop_recording
+    end
+
+    # Quick performance analysis
+    def self.analyze_performance(&block)
+      commands = capture_commands(&block)
+      PerformanceAnalyzer.new(commands).analyze
+    end
+
+    # Register validation middleware with Redis client
+    def self.register_middleware!
+      if defined?(RedisClient)
+        RedisClient.register(CommandRecorder::Middleware)
+      else
+        warn "RedisClient not available - command recording will not work"
+      end
+    end
+
+    # Configuration for validation framework
+    module Config
+      # Default options for validators
+      DEFAULT_OPTIONS = {
+        auto_register_middleware: true,
+        strict_atomicity: true,
+        performance_tracking: true,
+        command_filtering: :all
+      }.freeze
+
+      @options = DEFAULT_OPTIONS.dup
+
+      class << self
+        attr_accessor :options
+
+        def configure
+          yield self if block_given?
+        end
+
+        def reset!
+          @options = DEFAULT_OPTIONS.dup
+        end
+
+        # Option accessors
+        def auto_register_middleware?
+          @options[:auto_register_middleware]
+        end
+
+        def strict_atomicity?
+          @options[:strict_atomicity]
+        end
+
+        def performance_tracking?
+          @options[:performance_tracking]
+        end
+
+        def command_filtering
+          @options[:command_filtering]
+        end
+      end
+    end
+  end
+end
+
+# Auto-register middleware if enabled
+Familia::Validation.register_middleware! if Familia::Validation::Config.auto_register_middleware?

data/lib/familia/version.rb

@@ -3,6 +3,6 @@
 module Familia
   # Version information for the Familia
   unless defined?(Familia::VERSION)
-    VERSION = '2.0.0.pre5'
+    VERSION = '2.0.0.pre7'
   end
 end

data/lib/familia.rb

@@ -73,9 +73,9 @@ module Familia
   require_relative 'familia/utils'
 
   extend SecureIdentifier
-  extend Logging
   extend Connection
   extend Settings
+  extend Logging
   extend Utils
 end