familia 2.0.0.pre18 → 2.0.0.pre21

data/lib/familia/horreum/utils.rb

@@ -1,5 +1,7 @@
 # lib/familia/horreum/utils.rb
 #
+# frozen_string_literal: true
+
 module Familia
   # InstanceMethods - Module containing instance-level methods for Familia
   #
@@ -11,14 +13,6 @@ module Familia
     # Provides identifier handling, dbkey generation, and object inspection
     #
     module Utils
-      # def uri
-      #   base_uri = self.class.uri || Familia.uri
-      #   u = base_uri.dup # make a copy to modify safely
-      #   u.logical_database = logical_database if logical_database
-      #   u.key = dbkey
-      #   u
-      # end
-
       # +suffix+ is the value to be used at the end of the db key
       # (e.g. `customer:customer_id:scores` would have `scores` as the suffix
       # and `customer_id` would have been the identifier in that case).

data/lib/familia/horreum.rb

@@ -1,4 +1,6 @@
 # lib/familia/horreum.rb
+#
+# frozen_string_literal: true
 
 require_relative 'horreum/settings'
 require_relative 'horreum/connection'
@@ -51,7 +53,6 @@ module Familia
     include Familia::Base
     include Familia::Horreum::Persistence
     include Familia::Horreum::Serialization
-    include Familia::Horreum::Connection
     include Familia::Horreum::DatabaseCommands
     include Familia::Horreum::Settings
     include Familia::Horreum::Utils
@@ -187,6 +188,7 @@ module Familia
     #   `Session.new({sessid: "abc123", custid: "user456"})` # legacy hash (robust)
     #
     def initialize(*args, **kwargs)
+      start_time = Familia.now_in_μs if Familia.debug?
       Familia.trace :INITIALIZE, nil, "Initializing #{self.class}" if Familia.debug?
       initialize_relatives
 
@@ -226,23 +228,54 @@ module Familia
         # Default values are intentionally NOT set here
       end
 
-      # Implementing classes can define an init method to do any
-      # additional initialization. Notice that this is called
-      # after the fields are set.
+      # Implementing classes can define an init method to do any additional
+      # initialization. Notice that this is called AFTER fields are set from
+      # kwargs, so kwargs have been consumed and are no longer available.
+      #
+      # IMPORTANT: Use ||= in init to apply defaults without overriding:
+      #   def init
+      #     @email ||= email               # Preserves value already set
+      #     @status ||= 'pending'          # Applies default if nil
+      #   end
+      #
       init
+
+      # Structured lifecycle logging and instrumentation
+      if Familia.debug? && start_time
+        duration = Familia.now_in_μs - start_time
+        Familia.debug "Horreum initialized",
+          class: self.class.name,
+          duration: duration,
+          identifier: (identifier rescue nil)
+
+        Familia::Instrumentation.notify_lifecycle(:initialize, self, duration: duration)
+      end
     end
 
-    # Override this method in subclasses for custom initialization logic.
-    # This is called AFTER fields are set and relatives are initialized.
+    # Initialization method called at the end of initialize
     #
-    # DO NOT override initialize() - use this init() hook instead.
+    # Override this method to apply defaults, run validations, or setup
+    # callbacks. It's recommended to call super as other modules like
+    # features can also override init.
     #
-    # Example:
-    #   def init(name = nil)
-    #     @name = name || SecureRandom.hex(4)
+    # IMPORTANT: The init method receieves no arguments. By the time this runs,
+    # all arguments to initialize have already been consumed and used to set
+    # fields. Use the ||= operator to preserve values already set:
+    #
+    #   def init(email: nil, user_id: nil, **kwargs)
+    #     @email ||= email                  # Preserves value from new()
+    #     @user_id ||= user_id              # Preserves value from new()
+    #     @created_at ||= Familia.now       # Applies default if not set
+    #
+    #     # Example of additional initialization logic
+    #     validate_email_format if @email
+    #     setup_callbacks
     #   end
-    def init(*args, **kwargs)
-      # Default no-op
+    #
+    # @return [void]
+    #
+    def init
+      # Default no-op - override in subclasses
     end
 
     # Sets up related Database objects for the instance
@@ -319,7 +352,7 @@ module Familia
     #   the object with.
     # @return [Array] The list of field names that were updated.
     def naive_refresh(**fields)
-      Familia.ld "[naive_refresh] #{self.class} #{dbkey} #{fields.keys}"
+      Familia.debug "[naive_refresh] #{self.class} #{dbkey} #{fields.keys}"
       initialize_with_keyword_args_deserialize_value(**fields)
     end
 

data/lib/familia/identifier_extractor.rb

@@ -1,4 +1,6 @@
 # lib/familia/identifier_extractor.rb
+#
+# frozen_string_literal: true
 
 module Familia
   # IdentifierExtractor - Extracts identifiers from Familia objects for storage

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.
@@ -142,12 +144,9 @@ module Familia
         SEVERITY_LETTERS.fetch(severity, severity[0])
       end
 
-      utc_datetime = datetime.utc.strftime('%m-%d %H:%M:%S.%3N')
-      pid = Process.pid
-      thread_id = Thread.current.object_id
-      fiber_id = Fiber.current.object_id
+      utc_datetime = datetime.utc.strftime('%H:%M:%S.%3N')
 
-      "#{severity_letter}, #{utc_datetime} pid:#{pid} [#{thread_id}/#{fiber_id}]: #{msg}\n"
+      "#{severity_letter}, #{utc_datetime} #{msg}\n"
     end
   end
 
@@ -176,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
@@ -187,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.
@@ -198,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
     #
@@ -210,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.
     #
@@ -237,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.
@@ -296,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
 #
@@ -11,7 +13,7 @@ module Familia
   @encryption_keys = nil
   @current_key_version = nil
   @encryption_personalization = 'FamilialMatters'.freeze
-  @pipeline_mode = :warn
+  @pipelined_mode = :warn
 
   # Familia::Settings
   #
@@ -118,24 +120,24 @@ module Familia
     #
     # @example Setting pipeline mode
     #   Familia.configure do |config|
-    #     config.pipeline_mode = :permissive
+    #     config.pipelined_mode = :permissive
     #   end
     #
-    def pipeline_mode(val = nil)
+    def pipelined_mode(val = nil)
       if val
         unless [:strict, :warn, :permissive].include?(val)
           raise ArgumentError, 'Pipeline mode must be :strict, :warn, or :permissive'
         end
-        @pipeline_mode = val
+        @pipelined_mode = val
       end
-      @pipeline_mode || :warn  # default to warn mode
+      @pipelined_mode || :warn  # default to warn mode
     end
 
-    def pipeline_mode=(val)
+    def pipelined_mode=(val)
       unless [:strict, :warn, :permissive].include?(val)
         raise ArgumentError, 'Pipeline mode must be :strict, :warn, or :permissive'
       end
-      @pipeline_mode = val
+      @pipelined_mode = val
     end
 
     # Configure Familia settings