familia 2.0.0.pre19 → 2.0.0.pre22

data/lib/familia/instrumentation.rb

@@ -0,0 +1,156 @@
+# lib/familia/instrumentation.rb
+#
+# frozen_string_literal: true
+
+require 'concurrent-ruby'
+
+module Familia
+  # Provides instrumentation hooks for observability into Familia operations.
+  #
+  # This module allows applications to register callbacks for various events
+  # in Familia's lifecycle, enabling audit trails, performance monitoring,
+  # and operational observability.
+  #
+  # @example Basic usage
+  #   Familia.on_command do |cmd, duration, context|
+  #     puts "Redis command: #{cmd} (#{duration}μs)"
+  #   end
+  #
+  # @example Audit trail for secrets service
+  #   Familia.on_lifecycle do |event, instance, context|
+  #     case event
+  #     when :save
+  #       AuditLog.create!(
+  #         event: 'secret_saved',
+  #         secret_id: instance.identifier,
+  #         user_id: RequestContext.current_user_id
+  #       )
+  #     end
+  #   end
+  #
+  module Instrumentation
+    @hooks = {
+      command: Concurrent::Array.new,
+      pipeline: Concurrent::Array.new,
+      lifecycle: Concurrent::Array.new,
+      error: Concurrent::Array.new
+    }
+
+    class << self
+      # Register a callback for Redis command execution.
+      #
+      # @yield [cmd, duration, context] Callback block
+      # @yieldparam cmd [String] The Redis command name (e.g., "SET", "ZADD")
+      # @yieldparam duration [Integer] Command execution duration in microseconds
+      # @yieldparam context [Hash] Additional context including:
+      #   - :full_command [Array] Complete command with arguments
+      #   - :db [Integer] Database number
+      #   - :connection_id [String] Connection identifier
+      #
+      # @example
+      #   Familia.on_command do |cmd, duration, ctx|
+      #     StatsD.timing("familia.command.#{cmd.downcase}", duration / 1000.0)
+      #   end
+      #
+      def on_command(&block)
+        @hooks[:command] << block
+      end
+
+      # Register a callback for pipelined Redis operations.
+      #
+      # @yield [command_count, duration, context] Callback block
+      # @yieldparam command_count [Integer] Number of commands in the pipeline
+      # @yieldparam duration [Integer] Pipeline execution duration in microseconds
+      # @yieldparam context [Hash] Additional context
+      #
+      # @example
+      #   Familia.on_pipeline do |count, duration, ctx|
+      #     StatsD.timing("familia.pipeline", duration / 1000.0)
+      #     StatsD.gauge("familia.pipeline.commands", count)
+      #   end
+      #
+      def on_pipeline(&block)
+        @hooks[:pipeline] << block
+      end
+
+      # Register a callback for Horreum lifecycle events.
+      #
+      # @yield [event, instance, context] Callback block
+      # @yieldparam event [Symbol] Lifecycle event (:initialize, :save, :destroy)
+      # @yieldparam instance [Familia::Horreum] The object instance
+      # @yieldparam context [Hash] Additional context including:
+      #   - :duration [Integer] Operation duration in microseconds (for initialize/save)
+      #   - :update_expiration [Boolean] Whether TTL was updated (for save)
+      #
+      # @example
+      #   Familia.on_lifecycle do |event, instance, ctx|
+      #     case event
+      #     when :destroy
+      #       Rails.logger.info("Destroyed #{instance.class}:#{instance.identifier}")
+      #     end
+      #   end
+      #
+      def on_lifecycle(&block)
+        @hooks[:lifecycle] << block
+      end
+
+      # Register a callback for error conditions.
+      #
+      # @yield [error, context] Callback block
+      # @yieldparam error [Exception] The error that occurred
+      # @yieldparam context [Hash] Additional context including:
+      #   - :operation [Symbol] Operation that failed (:serialization, etc.)
+      #   - :field [Symbol] Field name (for serialization errors)
+      #   - :object_class [String] Class name of the object
+      #
+      # @example
+      #   Familia.on_error do |error, ctx|
+      #     Sentry.capture_exception(error, extra: ctx)
+      #   end
+      #
+      def on_error(&block)
+        @hooks[:error] << block
+      end
+
+      # Notify all registered command hooks.
+      # @api private
+      def notify_command(cmd, duration, context = {})
+        @hooks[:command].each do |hook|
+          hook.call(cmd, duration, context)
+        rescue => e
+          Familia.error("Instrumentation hook failed", error: e.message, hook_type: :command)
+        end
+      end
+
+      # Notify all registered pipeline hooks.
+      # @api private
+      def notify_pipeline(command_count, duration, context = {})
+        @hooks[:pipeline].each do |hook|
+          hook.call(command_count, duration, context)
+        rescue => e
+          Familia.error("Instrumentation hook failed", error: e.message, hook_type: :pipeline)
+        end
+      end
+
+      # Notify all registered lifecycle hooks.
+      # @api private
+      def notify_lifecycle(event, instance, context = {})
+        @hooks[:lifecycle].each do |hook|
+          hook.call(event, instance, context)
+        rescue => e
+          Familia.error("Instrumentation hook failed", error: e.message, hook_type: :lifecycle)
+        end
+      end
+
+      # Notify all registered error hooks.
+      # @api private
+      def notify_error(error, context = {})
+        @hooks[:error].each do |hook|
+          hook.call(error, context)
+        rescue => e
+          # Don't recurse on hook failures - just silently skip
+        end
+      end
+    end
+  end
+end

data/lib/familia/json_serializer.rb

@@ -1,4 +1,6 @@
 # lib/familia/json_serializer.rb
+#
+# frozen_string_literal: true
 
 module Familia
   # JsonSerializer provides a high-performance JSON interface using OJ

data/lib/familia/logging.rb

@@ -1,4 +1,6 @@
 # lib/familia/logging.rb
+#
+# frozen_string_literal: true
 
 require 'pathname'
 require 'logger'
@@ -117,7 +119,7 @@ module Familia
       'ERROR' => 'E',
       'FATAL' => 'F',
       'UNKNOWN' => 'U',
-      'ANY' => 'T'  # ANY is Logger's label for severity < 0, treat as TRACE
+      'ANY' => 'T', # ANY is Logger's label for severity < 0, treat as TRACE
     }.freeze
 
     # Format a log message with severity, timestamp, and context.
@@ -173,8 +175,16 @@ module Familia
   #   Familia.trace :LOAD, redis_client, "user:123", "from cache"
   #
   module Logging
+    # Thread-safe mutex initialization when module is extended
+    def self.extended(base)
+      base.instance_variable_set(:@logger_mutex, Mutex.new)
+    end
+
     # Get the logger instance, initializing with defaults if not yet set
     #
+    # Thread-safe lazy initialization using double-checked locking to ensure
+    # only a single logger instance is created even under concurrent logging calls.
+    #
     # @return [FamiliaLogger] the logger instance
     #
     # @example Set a custom logger
@@ -184,10 +194,18 @@ module Familia
     #   Familia.logger.info "Connection established"
     #
     def logger
-      @logger ||= FamiliaLogger.new($stderr).tap do |log|
-        log.progname = name
-        log.formatter = LogFormatter.new
+      # Fast path: return existing logger if already initialized
+      return @logger if @logger
+
+      # Slow path: thread-safe initialization
+      @logger_mutex.synchronize do
+        @logger ||= FamiliaLogger.new($stderr).tap do |log|
+          log.progname = name
+          log.formatter = LogFormatter.new
+        end
       end
+
+      @logger
     end
 
     # Set a custom logger instance.
@@ -195,6 +213,9 @@ module Familia
     # Allows replacing the default FamiliaLogger with any Logger-compatible
     # object. Useful for integrating with application logging frameworks.
     #
+    # Automatically synchronizes the logger to DatabaseLogger if it's loaded,
+    # ensuring consistent logging across Familia's middleware stack.
+    #
     # @param new_logger [Logger] The logger to use
     # @return [Logger] The logger that was set
     #
@@ -207,20 +228,14 @@ module Familia
     #   end
     #
     def logger=(new_logger)
-      @logger = new_logger
+      @logger_mutex.synchronize do
+        @logger = new_logger
+        # Auto-sync to DatabaseLogger if loaded (inside mutex for atomicity)
+        DatabaseLogger.logger = new_logger if defined?(DatabaseLogger)
+      end
+      @logger
     end
 
-    # Log an informational message.
-    #
-    # @param msg [String] The message to log
-    # @return [true]
-    #
-    # @example
-    #   Familia.info "Redis connection established"
-    #
-    def info(msg)
-      logger.info(msg)
-    end
 
     # Log a warning message.
     #
@@ -234,34 +249,58 @@ module Familia
       logger.warn(msg)
     end
 
-    # Log a debug message (only when Familia.debug? is true).
+    # Log a debug message with optional structured context.
     #
-    # Short for "log debug". Only outputs when FAMILIA_DEBUG environment
-    # variable is set to '1' or 'true'.
+    # Only outputs when FAMILIA_DEBUG environment variable is enabled.
+    # Supports both simple string messages and structured logging with
+    # keyword context for operational observability.
     #
-    # @param msg [String] The message to log
+    # @param message [String, nil] The message to log
+    # @param context [Hash] Structured context (key-value pairs)
     # @return [true, nil] Returns true if logged, nil if debug disabled
     #
-    # @example
-    #   Familia.ld "Cache lookup for user:123"
-    #   # Only outputs when FAMILIA_DEBUG=true
+    # @example Simple message
+    #   Familia.debug "Cache lookup for user:123"
+    #
+    # @example Structured context
+    #   Familia.debug "Horreum saved", class: "User", identifier: "user_123", duration: 1234
+    #   # => "Horreum saved class=User identifier=user_123 duration=1234"
     #
-    def ld(msg)
-      logger.debug(msg) if Familia.debug?
+    def debug(message = nil, **context)
+      return unless Familia.debug?
+      logger.debug(format_log(message, context))
     end
 
-    # Log an error message.
+    # Log an informational message with optional structured context.
     #
-    # Short for "log error".
+    # @param message [String, nil] The message to log
+    # @param context [Hash] Structured context (key-value pairs)
+    # @return [true]
     #
-    # @param msg [String] The message to log
+    # @example Simple message
+    #   Familia.info "Connection pool initialized"
+    #
+    # @example Structured context
+    #   Familia.info "Pipeline executed", commands: 5, duration: 2340
+    #
+    def info(message = nil, **context)
+      logger.info(format_log(message, context))
+    end
+
+    # Log an error message with optional structured context.
+    #
+    # @param message [String, nil] The message to log
+    # @param context [Hash] Structured context (key-value pairs)
     # @return [true]
     #
-    # @example
-    #   Familia.le "Failed to deserialize value: #{e.message}"
+    # @example Simple message
+    #   Familia.error "Failed to deserialize value"
+    #
+    # @example Structured context
+    #   Familia.error "Serialization failed", field: :email, error: e.message, class: "User"
     #
-    def le(msg)
-      logger.error(msg)
+    def error(message = nil, **context)
+      logger.error(format_log(message, context))
     end
 
     # Logs a structured trace message for debugging Familia operations.
@@ -293,6 +332,27 @@ module Familia
 
     private
 
+    # Format a log message with optional structured context.
+    #
+    # Combines a message string with key-value context into a single
+    # log line. Empty context returns the message unchanged.
+    #
+    # @param message [String, nil] The message to log
+    # @param context [Hash] Structured context (key-value pairs)
+    # @return [String] Formatted log message
+    # @api private
+    #
+    # @example
+    #   format_log("User saved", id: 123, duration: 1.5)
+    #   # => "User saved id=123 duration=1.5"
+    #
+    def format_log(message, context)
+      return message if context.empty?
+      parts = [message]
+      parts << context.map { |k, v| "#{k}=#{v}" }.join(' ')
+      parts.compact.join(' ')
+    end
+
     # Check if trace logging is enabled via FAMILIA_TRACE environment variable.
     #
     # Trace logging is enabled when FAMILIA_TRACE is set to '1', 'true',

data/lib/familia/refinements/dear_json.rb

@@ -1,4 +1,6 @@
 # lib/familia/refinements/dear_json.rb
+#
+# frozen_string_literal: true
 
 require 'familia/json_serializer'
 

data/lib/familia/refinements/stylize_words.rb

@@ -1,4 +1,6 @@
 # lib/familia/refinements/stylize_words.rb
+#
+# frozen_string_literal: true
 
 module Familia
   module Refinements
@@ -16,20 +18,6 @@ module Familia
           .downcase
       end
 
-      # Convert from plural to singular form using basic English rules
-      def singularize
-        word = to_s
-        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
-
       # Convert to camelCase
       def camelize
         _ize(:lower)

data/lib/familia/refinements/time_literals.rb

@@ -1,4 +1,6 @@
 # lib/familia/refinements/time_literals.rb
+#
+# frozen_string_literal: true
 
 module Familia
   module Refinements

data/lib/familia/refinements.rb

@@ -1,4 +1,6 @@
 # lib/familia/refinements.rb
+#
+# frozen_string_literal: true
 
 require_relative 'refinements/dear_json'
 require_relative 'refinements/stylize_words'

data/lib/familia/secure_identifier.rb

@@ -1,4 +1,6 @@
 # lib/familia/secure_identifier.rb
+#
+# frozen_string_literal: true
 
 require 'securerandom'
 
@@ -118,6 +120,10 @@ module Familia
 
     # @private
     #
+    # Thread-safe lazy initialization using Concurrent::Map to ensure
+    # atomic cache population and consistent calculations across all
+    # concurrent ID generation requests.
+    #
     # @param bits [Integer] The number of bits of entropy.
     # @param base [Integer] The numeric base (2-36).
     # @return [Integer] The minimum string length required.
@@ -130,8 +136,10 @@ module Familia
       }.freeze
       return hex_lengths[bits] if base == 16 && hex_lengths.key?(bits)
 
-      @min_length_for_bits_cache ||= {}
-      @min_length_for_bits_cache[[bits, base]] ||= (bits * Math.log(2) / Math.log(base)).ceil
+      @min_length_for_bits_cache ||= Concurrent::Map.new
+      @min_length_for_bits_cache.fetch_or_store([bits, base]) do
+        (bits * Math.log(2) / Math.log(base)).ceil
+      end
     end
   end
 end

data/lib/familia/settings.rb

@@ -1,4 +1,6 @@
 # lib/familia/settings.rb
+#
+# frozen_string_literal: true
 
 # Familia
 #

data/lib/familia/thread_safety/instrumented_mutex.rb

@@ -0,0 +1,166 @@
+# lib/familia/thread_safety/instrumented_mutex.rb
+#
+# frozen_string_literal: true
+
+require_relative 'monitor'
+
+module Familia
+  module ThreadSafety
+    # A Mutex wrapper that automatically reports contention metrics
+    #
+    # This class wraps Ruby's standard Mutex to provide automatic
+    # instrumentation of lock contention and wait times.
+    #
+    # @example Basic usage
+    #   mutex = Familia::ThreadSafety::InstrumentedMutex.new('connection_chain')
+    #   mutex.synchronize { # critical section }
+    #
+    # @example With monitoring
+    #   Familia::ThreadSafety::Monitor.start!
+    #   mutex = Familia::ThreadSafety::InstrumentedMutex.new('field_registration')
+    #   mutex.synchronize { # automatically tracked }
+    class InstrumentedMutex
+      attr_reader :name, :mutex
+
+      # Create a new instrumented mutex
+      #
+      # @param name [String, Symbol] Identifier for this mutex in monitoring
+      # @param monitor [Monitor, nil] Monitor instance to use (defaults to singleton)
+      def initialize(name, monitor = nil)
+        @name = name.to_s
+        @mutex = ::Mutex.new
+        @monitor = monitor || Monitor.instance
+        @lock_count = Concurrent::AtomicFixnum.new(0)
+        @contention_count = Concurrent::AtomicFixnum.new(0)
+      end
+
+      # Synchronize with automatic monitoring
+      #
+      # @yield Block to execute while holding the lock
+      # @return Result of the block
+      def synchronize
+        return yield unless @monitor.enabled
+
+        acquired = false
+        wait_start = Familia.now_in_μs
+
+        # Try non-blocking acquisition first to detect contention
+        if @mutex.try_lock
+          acquired = true
+          wait_time = 0
+          @lock_count.increment
+        else
+          # Contention detected
+          @contention_count.increment
+          @monitor.record_contention(@name)
+
+          # Now do blocking acquisition
+          @mutex.lock
+          acquired = true
+          wait_end = Familia.now_in_μs
+          wait_time_μs = wait_end - wait_start
+
+          @lock_count.increment
+          @monitor.record_wait_time(@name, wait_time_μs)
+
+          if wait_time_μs > 10_000  # Log if waited more than 10ms (10,000μs)
+            Familia.trace(:MUTEX_WAIT, nil, "Waited #{(wait_time_μs / 1000.0).round(2)}ms for #{@name}")
+          end
+        end
+
+        yield
+      ensure
+        @mutex.unlock if acquired
+      end
+
+      # Acquire the lock (with monitoring)
+      def lock
+        return @mutex.lock unless @monitor.enabled
+
+        wait_start = Familia.now_in_μs
+
+        if @mutex.try_lock
+          @lock_count.increment
+          return true
+        end
+
+        # Contention detected
+        @contention_count.increment
+        @monitor.record_contention(@name)
+
+        result = @mutex.lock
+        wait_end = Familia.now_in_μs
+        wait_time_μs = wait_end - wait_start
+
+        @lock_count.increment
+        @monitor.record_wait_time(@name, wait_time_μs)
+
+        result
+      end
+
+      # Try to acquire the lock without blocking
+      def try_lock
+        result = @mutex.try_lock
+        @lock_count.increment if result
+        result
+      end
+
+      # Release the lock
+      def unlock
+        @mutex.unlock
+      end
+
+      # Check if locked by current thread
+      def locked?
+        @mutex.locked?
+      end
+
+      # Check if owned by current thread
+      def owned?
+        @mutex.owned?
+      end
+
+      # Sleep and release the lock temporarily
+      def sleep(timeout = nil)
+        @mutex.sleep(timeout)
+      end
+
+      # Get statistics for this mutex
+      def stats
+        {
+          name: @name,
+          lock_count: @lock_count.value,
+          contention_count: @contention_count.value,
+          contention_rate: contention_rate
+        }
+      end
+
+      # Calculate contention rate (0.0 to 1.0)
+      def contention_rate
+        total = @lock_count.value
+        return 0.0 if total == 0
+
+        @contention_count.value.to_f / total
+      end
+
+      # Create a double-checked locking helper
+      #
+      # @param check [Proc] Condition to check
+      # @param init [Proc] Initialization to perform if check fails
+      # @return Result of check or init
+      def double_checked_locking(check, init)
+        # Fast path - check without lock
+        value = check.call
+        return value if value
+
+        # Slow path - check again with lock
+        synchronize do
+          value = check.call
+          return value if value
+
+          init.call
+        end
+      end
+    end
+  end
+end