familia 2.0.0.pre19 → 2.0.0.pre21

data/lib/familia/thread_safety/monitor.rb

@@ -0,0 +1,328 @@
+# lib/familia/thread_safety/monitor.rb
+#
+# frozen_string_literal: true
+
+require 'concurrent-ruby'
+
+module Familia
+  module ThreadSafety
+    # Thread safety monitoring for production observability
+    #
+    # Tracks mutex contention, race conditions, and synchronization metrics
+    # to provide insights into thread safety behavior in production.
+    #
+    # @example Basic usage
+    #   Familia::ThreadSafety::Monitor.start!
+    #   # ... application runs ...
+    #   report = Familia::ThreadSafety::Monitor.report
+    #   puts report[:summary]
+    #
+    # @example Custom instrumentation
+    #   Familia::ThreadSafety::Monitor.record_contention('connection_chain')
+    #   Familia::ThreadSafety::Monitor.time_critical_section('field_registration') do
+    #     # ... critical code ...
+    #   end
+    class Monitor
+      class << self
+        def instance
+          @instance ||= new
+        end
+
+        # Delegate all methods to singleton instance
+        def method_missing(method, *args, &block)
+          if instance.respond_to?(method)
+            instance.send(method, *args, &block)
+          else
+            super
+          end
+        end
+
+        def respond_to_missing?(method, include_private = false)
+          instance.respond_to?(method) || super
+        end
+      end
+
+      attr_reader :enabled, :started_at
+
+      def initialize
+        @enabled = false
+        @started_at = nil
+        @mutex_contentions = Concurrent::AtomicFixnum.new(0)
+        @race_detections = Concurrent::AtomicFixnum.new(0)
+        @critical_sections = Concurrent::AtomicFixnum.new(0)
+        @deadlock_checks = Concurrent::AtomicFixnum.new(0)
+
+        # Track contention points with counts
+        @contention_points = Concurrent::Map.new
+
+        # Track wait time aggregates for critical sections (removed @wait_times to prevent memory leak)
+        @wait_time_totals = Concurrent::Map.new
+        @wait_time_counts = Concurrent::Map.new
+
+        # Track thread-local state for nested monitoring
+        @thread_state = Concurrent::Map.new
+
+        # Track concurrent operation counts
+        @concurrent_operations = Concurrent::Map.new
+
+        # Performance metrics
+        @section_timings = Concurrent::Map.new
+        @section_counts = Concurrent::Map.new
+      end
+
+      # Start monitoring
+      def start!
+        @enabled = true
+        @started_at = Time.now
+        reset_metrics
+        Familia.info("[ThreadSafety] Monitoring started")
+        true
+      end
+
+      # Stop monitoring
+      def stop!
+        @enabled = false
+        duration = @started_at ? Time.now - @started_at : 0
+        Familia.info("[ThreadSafety] Monitoring stopped after #{duration.round(2)}s")
+        @started_at = nil
+        true
+      end
+
+      # Reset all metrics
+      def reset_metrics
+        @mutex_contentions.value = 0
+        @race_detections.value = 0
+        @critical_sections.value = 0
+        @deadlock_checks.value = 0
+        @contention_points.clear
+        # @wait_times.clear - removed to prevent memory leak
+        @wait_time_totals.clear
+        @wait_time_counts.clear
+        @thread_state.clear
+        @concurrent_operations.clear
+        @section_timings.clear
+        @section_counts.clear
+      end
+
+      # Record a mutex contention event
+      def record_contention(location, wait_time = nil)
+        return unless @enabled
+
+        @mutex_contentions.increment
+        @contention_points[location] = @contention_points.fetch(location, 0) + 1
+
+        if wait_time
+          record_wait_time(location, wait_time)
+        end
+
+        Familia.trace(:THREAD_CONTENTION, nil, "Contention at #{location} (wait: #{wait_time&.round(4)}s)")
+      end
+
+      # Record wait time for a location
+      def record_wait_time(location, wait_time)
+        # Note: @wait_times was removed to prevent memory leak from unbounded array growth
+        # We only need the aggregated totals and counts for calculations
+        @wait_time_totals[location] = @wait_time_totals.fetch(location, 0.0) + wait_time
+        @wait_time_counts[location] = @wait_time_counts.fetch(location, 0) + 1
+      end
+
+      # Record a potential race condition detection
+      def record_race_condition(location, details = nil)
+        return unless @enabled
+
+        @race_detections.increment
+        msg = "Potential race condition at #{location}"
+        msg += ": #{details}" if details
+        Familia.warn("[ThreadSafety] #{msg}")
+      end
+
+      # Time a critical section with contention tracking
+      def time_critical_section(name)
+        return yield unless @enabled
+
+        thread_id = Thread.current.object_id
+        start_time = Familia.now_in_μs
+
+        # Check for concurrent execution
+        concurrent_count = @concurrent_operations[name] = @concurrent_operations.fetch(name, 0) + 1
+        if concurrent_count > 1
+          record_contention(name)
+        end
+
+        @critical_sections.increment
+
+        begin
+          result = yield
+        ensure
+          end_time = Familia.now_in_μs
+          duration_μs = end_time - start_time
+
+          # Record timing in microseconds
+          @section_timings[name] = @section_timings.fetch(name, 0) + duration_μs
+          @section_counts[name] = @section_counts.fetch(name, 0) + 1
+
+          # Decrement concurrent count
+          @concurrent_operations[name] = @concurrent_operations.fetch(name, 1) - 1
+
+          if duration_μs > 100_000  # Log slow critical sections (> 100ms = 100,000μs)
+            Familia.warn("[ThreadSafety] Slow critical section '#{name}': #{(duration_μs / 1000.0).round(2)}ms")
+          end
+        end
+
+        result
+      end
+
+      # NOTE: monitor_mutex method was removed as it was unused and had flawed
+      # exception handling that could lead to deadlocks. The InstrumentedMutex
+      # class should be used instead for mutex monitoring.
+
+      # Check for potential deadlocks
+      def check_deadlock
+        return unless @enabled
+
+        @deadlock_checks.increment
+
+        # This is a simple check - in production you might want more sophisticated detection
+        thread_count = Thread.list.count
+        if thread_count > 100
+          Familia.warn("[ThreadSafety] High thread count: #{thread_count}")
+        end
+
+        # Check for threads waiting on mutexes (simplified)
+        waiting_threads = Thread.list.select { |t| t.status == "sleep" }
+        if waiting_threads.size > thread_count * 0.8
+          Familia.warn("[ThreadSafety] Potential deadlock: #{waiting_threads.size}/#{thread_count} threads sleeping")
+        end
+      end
+
+      # Generate a comprehensive report
+      def report
+        return { enabled: false, message: "Monitoring not enabled" } unless @started_at
+
+        duration = Time.now - @started_at
+
+        # Calculate hot spots
+        hot_spots = []
+        @contention_points.each_pair do |location, count|
+          hot_spots << [location, count]
+        end
+        hot_spots = hot_spots
+          .sort_by { |_, count| -count }
+          .first(10)
+          .map { |location, count|
+            avg_wait_μs = if @wait_time_counts[location] && @wait_time_counts[location] > 0
+              (@wait_time_totals[location] / @wait_time_counts[location]).round(0)
+            else
+              0
+            end
+            {
+              location: location,
+              contentions: count,
+              avg_wait_μs: avg_wait_μs
+            }
+          }
+
+        # Calculate critical section performance
+        section_performance = []
+        @section_counts.each_pair do |name, count|
+          avg_time_μs = (@section_timings[name] / count).round(0)
+          section_performance << {
+            section: name,
+            calls: count,
+            avg_time_μs: avg_time_μs,
+            total_time_μs: @section_timings[name]
+          }
+        end
+        section_performance.sort_by! { |s| -s[:total_time_μs] }
+
+        {
+          summary: {
+            monitoring_duration_s: duration.round(2),
+            mutex_contentions: @mutex_contentions.value,
+            race_detections: @race_detections.value,
+            critical_sections: @critical_sections.value,
+            deadlock_checks: @deadlock_checks.value
+          },
+          hot_spots: hot_spots,
+          section_performance: section_performance,
+          health: calculate_health_score,
+          recommendations: generate_recommendations(hot_spots)
+        }
+      end
+
+      # Calculate a health score (0-100)
+      def calculate_health_score
+        return 100 unless @started_at
+
+        duration = Time.now - @started_at
+        return 100 if duration < 60  # Need at least 1 minute of data
+
+        contentions_per_hour = (@mutex_contentions.value / duration) * 3600
+        races_per_hour = (@race_detections.value / duration) * 3600
+
+        score = 100
+        score -= [contentions_per_hour / 10.0, 30].min  # -3 points per 100 contentions/hour, max -30
+        score -= [races_per_hour * 10, 50].min  # -10 points per race/hour, max -50
+
+        [score, 0].max.round
+      end
+
+      # Generate recommendations based on metrics
+      def generate_recommendations(hot_spots)
+        recommendations = []
+
+        if @race_detections.value > 0
+          recommendations << {
+            severity: 'critical',
+            message: "#{@race_detections.value} potential race conditions detected - investigate immediately"
+          }
+        end
+
+        if hot_spots.any? { |h| h[:contentions] > 100 }
+          high_contention = hot_spots.select { |h| h[:contentions] > 100 }
+          locations = high_contention.map { |h| h[:location] }.join(', ')
+          recommendations << {
+            severity: 'warning',
+            message: "High contention detected at: #{locations}"
+          }
+        end
+
+        if hot_spots.any? { |h| h[:avg_wait_μs] > 100_000 }  # > 100ms in microseconds
+          slow_spots = hot_spots.select { |h| h[:avg_wait_μs] > 100_000 }
+          recommendations << {
+            severity: 'warning',
+            message: "Long wait times at: #{slow_spots.map { |h| "#{h[:location]} (#{(h[:avg_wait_μs] / 1000.0).round(1)}ms)" }.join(', ')}"
+          }
+        end
+
+        if @deadlock_checks.value > 0 && Thread.list.count > 50
+          recommendations << {
+            severity: 'info',
+            message: "Consider connection pooling - high thread count detected"
+          }
+        end
+
+        recommendations
+      end
+
+      # Export metrics in a format suitable for APM tools
+      def export_metrics
+        {
+          'familia.thread_safety.mutex_contentions' => @mutex_contentions.value,
+          'familia.thread_safety.race_detections' => @race_detections.value,
+          'familia.thread_safety.critical_sections' => @critical_sections.value,
+          'familia.thread_safety.deadlock_checks' => @deadlock_checks.value,
+          'familia.thread_safety.health_score' => calculate_health_score
+        }
+      end
+
+      # Hook for APM integration
+      def apm_transaction(name, &block)
+        return yield unless @enabled
+
+        # This is where you'd integrate with NewRelic, DataDog, etc.
+        time_critical_section(name, &block)
+      end
+    end
+  end
+end

data/lib/familia/utils.rb

@@ -1,4 +1,6 @@
 # lib/familia/utils.rb
+#
+# frozen_string_literal: true
 
 module Familia
   # Family-related utility methods
@@ -42,6 +44,17 @@ module Familia
       current_time.utc.to_f
     end
 
+    # Returns the current time in microseconds.
+    # This is used to measure the duration of Database commands.
+    #
+    # Alias: now_in_microseconds
+    #
+    # @return [Integer] The current time in microseconds.
+    def now_in_μs
+      Process.clock_gettime(Process::CLOCK_MONOTONIC, :microsecond)
+    end
+    alias now_in_microseconds now_in_μs
+
     # A quantized timestamp
     #
     # @param quantum [Integer] The time quantum in seconds (default: 10 minutes).

data/lib/familia/verifiable_identifier.rb

@@ -1,4 +1,6 @@
 # lib/familia/verifiable_identifier.rb
+#
+# frozen_string_literal: true
 
 require 'openssl'
 require_relative 'secure_identifier'
@@ -33,7 +35,7 @@ module Familia
     #        $ openssl rand -hex 32
     #        > cafef00dcafef00dcafef00dcafef00dcafef00dcafef00d
     #
-    #     2. UnsortedSet it as an environment variable in your production environment:
+    #     2. Set it as an environment variable in your production environment:
     #        export VERIFIABLE_ID_HMAC_SECRET="cafef00dcafef00dcafef00dcafef00dcafef00dcafef00d"
     #
     SECRET_KEY = ENV.fetch('VERIFIABLE_ID_HMAC_SECRET', 'cafef00dcafef00dcafef00dcafef00dcafef00dcafef00d')

data/lib/familia/version.rb

@@ -1,6 +1,8 @@
 # lib/familia/version.rb
+#
+# frozen_string_literal: true
 
 module Familia
   # Version information for the Familia
-  VERSION = '2.0.0.pre19'.freeze unless defined?(Familia::VERSION)
+  VERSION = '2.0.0.pre21'.freeze unless defined?(Familia::VERSION)
 end

data/lib/familia.rb

@@ -1,9 +1,12 @@
 # lib/familia.rb
+#
+# frozen_string_literal: true
 
 require 'oj'
 require 'redis'
 require 'uri/valkey'
 require 'connection_pool'
+require 'concurrent-ruby'
 
 # OJ configuration is handled internally by Familia::JsonSerializer
 
@@ -11,6 +14,8 @@ require_relative 'multi_result'
 require_relative 'familia/refinements'
 require_relative 'familia/errors'
 require_relative 'familia/version'
+require_relative 'familia/thread_safety/monitor'
+require_relative 'familia/thread_safety/instrumented_mutex'
 
 # Familia - A family warehouse for Valkey/Redis
 #
@@ -39,9 +44,30 @@ module Familia
   using Refinements::StylizeWords
 
   class << self
-    attr_accessor :debug
+    attr_writer :debug
     attr_reader :members
 
+    # Thread safety monitoring controls
+    def thread_safety_monitor
+      ThreadSafety::Monitor.instance
+    end
+
+    def start_monitoring!
+      thread_safety_monitor.start!
+    end
+
+    def stop_monitoring!
+      thread_safety_monitor.stop!
+    end
+
+    def thread_safety_report
+      thread_safety_monitor.report
+    end
+
+    def thread_safety_metrics
+      thread_safety_monitor.export_metrics
+    end
+
     def included(member)
       raise Problem, "#{member} should subclass Familia::Horreum"
     end
@@ -87,7 +113,7 @@ module Familia
     # @param klass [Class] The class to remove from members
     # @return [Class, nil] The removed class or nil if not found
     def unload_member(klass)
-      Familia.ld "[unload_member] Removing #{klass} from members"
+      Familia.debug "[unload_member] Removing #{klass} from members"
       @members.delete(klass)
     end
 
@@ -97,7 +123,7 @@ module Familia
     # @return [Array<Class>] The removed anonymous classes
     def clear_anonymous_members
       anonymous_classes = @members.select { |m| m.name.nil? }
-      Familia.ld "[clear_anonymous_members] Removing #{anonymous_classes.size} anonymous classes"
+      Familia.debug "[clear_anonymous_members] Removing #{anonymous_classes.size} anonymous classes"
       @members.reject! { |m| m.name.nil? }
       anonymous_classes
     end
@@ -128,7 +154,7 @@ module Familia
     #   Familia.member_by_config_name(:nonexistent) # => nil
     #
     def member_by_config_name(config_name)
-      Familia.ld "[member_by_config_name] #{members.map(&:config_name)} #{config_name}"
+      Familia.debug "[member_by_config_name] #{members.map(&:config_name)} #{config_name}"
 
       members.find { |m| m.config_name.to_s.eql?(config_name.to_s) }
     end
@@ -149,6 +175,7 @@ module Familia
   extend Utils
 end
 
+require_relative 'familia/instrumentation'
 require_relative 'familia/base'
 require_relative 'familia/features'
 require_relative 'familia/data_type'

data/lib/middleware/database_command_counter.rb

@@ -0,0 +1,152 @@
+# lib/middleware/database_command_counter.rb
+#
+# frozen_string_literal: true
+
+require 'concurrent-ruby'
+
+# DatabaseCommandCounter is redis-rb middleware for counting commands.
+#
+# This middleware counts the number of Redis commands executed. It can be
+# useful for performance monitoring and debugging, allowing you to track
+# the volume of Redis operations in your application.
+#
+# Familia uses the redis-rb gem (v4.8.1 to <6.0), which internally uses
+# RedisClient infrastructure. Users work with Redis.new connections - the
+# RedisClient middleware registration is handled automatically by Familia.
+#
+# ## User-Facing API
+#
+# Enable via Familia configuration:
+#   Familia.enable_database_counter = true
+#
+# Familia automatically calls RedisClient.register(DatabaseCommandCounter) internally.
+#
+# ## Middleware Chaining
+#
+# This middleware works correctly alongside DatabaseLogger because it uses
+# `super` to properly chain method calls. See {DatabaseLogger} for detailed
+# explanation of middleware chaining mechanics.
+#
+# @example Enable Redis command counting (recommended user-facing API)
+#   DatabaseCommandCounter.reset
+#   Familia.enable_database_counter = true
+#
+# @example Use with DatabaseLogger
+#   Familia.enable_database_logging = true
+#   Familia.enable_database_counter = true
+#   # Both middlewares registered automatically and execute correctly in sequence
+#
+# @see https://github.com/redis-rb/redis-client?tab=readme-ov-file#instrumentation-and-middlewares
+# @see DatabaseLogger For middleware chain architecture details
+#
+module DatabaseCommandCounter
+  @count = Concurrent::AtomicFixnum.new(0)
+
+  # Commands to skip when counting.
+  #
+  # We skip SELECT because the frequency depends on connection architecture:
+  # - Connection-per-database: Only one SELECT when connection is made
+  # - Provider/thread-local: Could theoretically double statement count
+  #
+  # @return [Set<String>] Commands that won't be counted
+  @skip_commands = ::Set.new(['SELECT']).freeze
+
+  class << self
+    # Gets the set of commands to skip counting.
+    # @return [Set<String>] The commands that won't be counted
+    attr_reader :skip_commands
+
+    # Gets the current count of Redis commands executed.
+    # @return [Integer] The number of Redis commands executed
+    def count
+      @count.value
+    end
+
+    # Resets the command count to zero.
+    # This method is thread-safe.
+    # @return [Integer] The reset count (always 0)
+    def reset
+      @count.value = 0
+    end
+
+    # Increments the command count.
+    # This method is thread-safe.
+    # @return [Integer] The new count after incrementing
+    # @api private
+    def increment
+      @count.increment
+    end
+
+    # Checks if a command should be skipped.
+    # @param command [Array] The Redis command array
+    # @return [Boolean] true if command should be skipped
+    # @api private
+    def skip_command?(command)
+      skip_commands.include?(command.first.to_s.upcase)
+    end
+
+    # Counts the number of Redis commands executed within a block.
+    #
+    # This method captures the command count before and after executing the
+    # provided block, returning the difference. This is useful for measuring
+    # how many Redis commands are executed by a specific operation.
+    #
+    # @yield [] The block of code to execute while counting commands
+    # @return [Integer] The number of Redis commands executed within the block
+    #
+    # @example Count commands in a block
+    #   commands_executed = DatabaseCommandCounter.count_commands do
+    #     dbclient.set('key1', 'value1')
+    #     dbclient.get('key1')
+    #   end
+    #   # commands_executed will be 2
+    def count_commands
+      start_count = count      # Capture the current command count before execution
+      yield                    # Execute the provided block
+      end_count = count        # Capture the command count after execution
+      end_count - start_count  # Return the difference (commands executed in block)
+    end
+  end
+
+  # Reference to the module for use in instance methods
+  # @api private
+  def klass
+    DatabaseCommandCounter
+  end
+
+  # Counts the Redis command and delegates its execution.
+  #
+  # This method is part of the RedisClient middleware chain. It MUST use `super`
+  # instead of `yield` to properly chain with other middlewares like DatabaseLogger.
+  #
+  # @param command [Array] The Redis command and its arguments
+  # @param _config [RedisClient::Config, Hash] Connection configuration (unused)
+  # @return [Object] The result of the Redis command execution
+  def call(command, _config)
+    klass.increment unless klass.skip_command?(command)
+    super  # CRITICAL: Must use super, not yield, to chain middlewares
+  end
+
+  # Counts commands in a pipeline and delegates execution.
+  #
+  # @param commands [Array<Array>] Array of command arrays
+  # @param _config [RedisClient::Config, Hash] Connection configuration (unused)
+  # @return [Array] Results from pipelined commands
+  def call_pipelined(commands, _config)
+    # Count all commands in the pipeline (except skipped ones)
+    commands.each do |command|
+      klass.increment unless klass.skip_command?(command)
+    end
+    super  # CRITICAL: Must use super, not yield, to chain middlewares
+  end
+
+  # Counts a call_once command and delegates execution.
+  #
+  # @param command [Array] The Redis command and its arguments
+  # @param _config [RedisClient::Config, Hash] Connection configuration (unused)
+  # @return [Object] The result of the Redis command execution
+  def call_once(command, _config)
+    klass.increment unless klass.skip_command?(command)
+    super  # CRITICAL: Must use super, not yield, to chain middlewares
+  end
+end