familia 2.0.0.pre19 → 2.0.0.pre22

data/examples/autoloader/mega_customer/features/deprecated_fields.rb

@@ -1,4 +1,6 @@
 # examples/autoloader/mega_customer/features/deprecated_fields.rb
+#
+# frozen_string_literal: true
 
 # Extend the MegaCustomer class to organize all of the deprecated fields into one place
 class MegaCustomer < Familia::Horreum

data/examples/autoloader/mega_customer/safe_dump_fields.rb

@@ -1,4 +1,6 @@
 # examples/autoloader/mega_customer/safe_dump_fields.rb
+#
+# frozen_string_literal: true
 
 # Extend the MegaCustomer class to add safe dump fields
 class MegaCustomer < Familia::Horreum

data/examples/autoloader/mega_customer.rb

@@ -1,4 +1,6 @@
 # examples/autoloader/mega_customer.rb
+#
+# frozen_string_literal: true
 
 require_relative '../../lib/familia'
 

data/examples/datatype_standalone.rb

@@ -1,8 +1,9 @@
 #!/usr/bin/env ruby
 # examples/datatype_standalone.rb
+#
+# frozen_string_literal: true
 
 # Demonstration: Familia::StringKey for Session Storage with Atomic Transactions
-#
 # This example shows how to use Familia's DataType classes independently
 # without inheriting from Familia::Horreum. It implements a Rack-compatible
 # session store using Familia::StringKey for secure, TTL-managed storage.
@@ -146,7 +147,7 @@ class SecureSessionStore < Rack::Session::Abstract::PersistedSecure
       [sid, session_data]
     rescue Familia::PersistenceError => e
       # Log error in development/debugging
-      Familia.ld "[Session] Error reading session #{sid_string}: #{e.message}"
+      Familia.debug "[Session] Error reading session #{sid_string}: #{e.message}"
 
       # Return new session on any error
       [generate_sid, {}]
@@ -196,7 +197,7 @@ class SecureSessionStore < Rack::Session::Abstract::PersistedSecure
     sid
   rescue Familia::PersistenceError => e
     # Log error in development/debugging
-    Familia.ld "[Session] Error writing session #{sid_string}: #{e.message}"
+    Familia.debug "[Session] Error writing session #{sid_string}: #{e.message}"
 
     # Return false to indicate failure
     false

data/examples/encrypted_fields.rb

@@ -1,7 +1,8 @@
 #!/usr/bin/env ruby
-
 # examples/encrypted_fields.rb
 #
+# frozen_string_literal: true
+
 # Demonstrates the EncryptedFields feature for protecting sensitive data.
 # This feature provides transparent encryption/decryption of sensitive fields
 # using strong cryptographic algorithms with field-specific key derivation.

data/examples/json_usage_patterns.rb

@@ -1,5 +1,7 @@
 # examples/json_usage_patterns.rb
 #
+# frozen_string_literal: true
+
 # This file demonstrates the JSON serialization patterns available in Familia,
 # showing both the secure defaults and optional developer convenience features.
 

data/examples/relationships.rb

@@ -1,4 +1,7 @@
 #!/usr/bin/env ruby
+# examples/relationships.rb
+#
+# frozen_string_literal: true
 
 # Basic Relationships Example
 # This example demonstrates the core features of Familia's relationships system

data/examples/safe_dump.rb

@@ -1,7 +1,8 @@
 #!/usr/bin/env ruby
-
 # examples/safe_dump.rb
 #
+# frozen_string_literal: true
+
 # Demonstrates the SafeDump feature with the new DSL methods.
 # SafeDump allows you to control which fields are exposed when
 # serializing objects, preventing accidental exposure of sensitive data.

data/examples/sampling_demo.rb

@@ -0,0 +1,53 @@
+#!/usr/bin/env ruby
+# examples/sampling_demo.rb
+#
+# frozen_string_literal: true
+
+# Demonstrates DatabaseLogger sampling to reduce log volume in high-traffic scenarios.
+# Run with: bundle exec ruby examples/sampling_demo.rb
+
+require_relative '../lib/familia'
+require 'logger'
+
+# Enable database command logging (middleware registered automatically)
+Familia.enable_database_logging = true
+DatabaseLogger.logger = Familia::FamiliaLogger.new($stdout)
+DatabaseLogger.logger.level = Familia::FamiliaLogger::TRACE
+
+# Scenario 1: No sampling (default) - logs every command
+puts "\n=== Scenario 1: No Sampling (logs all 100 commands) ==="
+DatabaseLogger.sample_rate = nil
+100.times { |i| Familia.dbclient.set("key_#{i}", "value_#{i}") }
+puts "Commands captured: #{DatabaseLogger.commands.size}"
+puts "(Check output above - should see ~100 log lines)"
+
+# Scenario 2: 10% sampling - logs ~10 commands
+puts "\n=== Scenario 2: 10% Sampling (logs ~10 of 100 commands) ==="
+DatabaseLogger.clear_commands
+DatabaseLogger.sample_rate = 0.1
+100.times { |i| Familia.dbclient.set("sampled_10_#{i}", "value_#{i}") }
+puts "Commands captured: #{DatabaseLogger.commands.size}"
+puts "(Check output above - should see ~10 log lines)"
+
+# Scenario 3: 1% sampling - logs ~1 command (production-friendly)
+puts "\n=== Scenario 3: 1% Sampling (logs ~1 of 100 commands) ==="
+DatabaseLogger.clear_commands
+DatabaseLogger.sample_rate = 0.01
+100.times { |i| Familia.dbclient.set("sampled_1_#{i}", "value_#{i}") }
+puts "Commands captured: #{DatabaseLogger.commands.size}"
+puts "(Check output above - should see ~1 log line)"
+
+# Scenario 4: Sampling with structured logging
+puts "\n=== Scenario 4: 10% Sampling + Structured Logging ==="
+DatabaseLogger.clear_commands
+DatabaseLogger.sample_rate = 0.1
+DatabaseLogger.structured_logging = true
+100.times { |i| Familia.dbclient.set("structured_#{i}", "value_#{i}") }
+puts "Commands captured: #{DatabaseLogger.commands.size}"
+puts "(Check structured output above)"
+
+puts "\n=== Key Insights ==="
+puts "✓ Command capture is unaffected (always 100 commands captured)"
+puts "✓ Only logger output is sampled (reduces log volume)"
+puts "✓ Tests can verify commands while production logs stay clean"
+puts "✓ Deterministic sampling (every Nth command) ensures consistency"

data/examples/single_connection_transaction_confusions.rb

@@ -1,8 +1,9 @@
 #!/usr/bin/env ruby
 # examples/single_connection_transaction_confusions.rb
+#
+# frozen_string_literal: true
 
 # Redis Single Connection Mode Confusions
-#
 # This file demonstrates why mixing Redis operation modes on a single connection
 # causes subtle but critical failures in production applications.
 #

data/familia.gemspec

@@ -17,9 +17,10 @@ Gem::Specification.new do |spec|
   spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
   spec.require_paths = ['lib']
 
-  spec.required_ruby_version = Gem::Requirement.new('>= 3.4')
+  spec.required_ruby_version = Gem::Requirement.new('>= 3.3.6')
 
   spec.add_dependency 'benchmark', '~> 0.4'
+  spec.add_dependency 'concurrent-ruby', '~> 1.3'
   spec.add_dependency 'connection_pool', '~> 2.5'
   spec.add_dependency 'csv', '~> 3.3'
   spec.add_dependency 'logger', '~> 1.7'

data/lib/familia/base.rb

@@ -1,4 +1,6 @@
 # lib/familia/base.rb
+#
+# frozen_string_literal: true
 
 module Familia
   # A common module for Familia::DataType and Familia::Horreum to include.

data/lib/familia/connection/behavior.rb

@@ -1,3 +1,5 @@
+# lib/familia/connection/behavior.rb
+#
 # frozen_string_literal: true
 
 # lib/familia/connection/behavior.rb

data/lib/familia/connection/handlers.rb

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

data/lib/familia/connection/individual_command_proxy.rb

@@ -1,4 +1,6 @@
 # lib/familia/connection/individual_command_proxy.rb
+#
+# frozen_string_literal: true
 
 module Familia
   module Connection

data/lib/familia/connection/middleware.rb

@@ -1,6 +1,9 @@
 # lib/familia/connection/middleware.rb
+#
+# frozen_string_literal: true
 
 require_relative '../../middleware/database_logger'
+require_relative '../../middleware/database_command_counter'
 
 module Familia
   module Connection
@@ -13,19 +16,20 @@ module Familia
 
       # @return [Integer] Current middleware version for cache invalidation
       def middleware_version
-        @middleware_version
+        @middleware_version.value
       end
 
       # Increments the middleware version, invalidating all cached connections
       def increment_middleware_version!
-        @middleware_version += 1
-        Familia.trace :MIDDLEWARE_VERSION, nil, "Incremented to #{@middleware_version}"
+        new_version = @middleware_version.increment
+        Familia.trace :MIDDLEWARE_VERSION, nil, "Incremented to #{new_version}"
       end
 
       # Sets a versioned fiber-local connection
       def fiber_connection=(connection)
-        Fiber[:familia_connection] = [connection, middleware_version]
-        Familia.trace :FIBER_CONNECTION, nil, "Set with version #{middleware_version}"
+        current_version = middleware_version
+        Fiber[:familia_connection] = [connection, current_version]
+        Familia.trace :FIBER_CONNECTION, nil, "Set with version #{current_version}"
       end
 
       # Clears the fiber-local connection
@@ -81,18 +85,23 @@ module Familia
       #   Familia.reconnect!  # Force new connections with middleware
       #
       def reconnect!
-        # Allow middleware to be re-registered
-        @middleware_registered = false
-        register_middleware_once
-
-        # Clear connection chain to force rebuild
-        @connection_chain = nil
-
-        # Increment version to invalidate all cached connections
-        increment_middleware_version!
-
-        # Clear fiber-local connections
-        clear_fiber_connection!
+        # Thread-safe: Use same mutex as dbclient to protect @connection_chain
+        @connection_chain_mutex.synchronize do
+          # Allow middleware to be re-registered by resetting all flags
+          @middleware_registered = false
+          @logger_registered = false
+          @counter_registered = false
+          register_middleware_once
+
+          # Clear connection chain to force rebuild
+          @connection_chain = nil
+
+          # Increment version to invalidate all cached connections
+          increment_middleware_version!
+
+          # Clear fiber-local connections
+          clear_fiber_connection!
+        end
 
         Familia.trace :RECONNECT, nil, 'Connection chain cleared, will rebuild with current middleware on next use'
       end
@@ -102,27 +111,28 @@ module Familia
       # Registers middleware once globally, regardless of when clients are created.
       # This prevents duplicate middleware registration and ensures all clients get middleware.
       def register_middleware_once
-        # Skip if already registered
-        return if @middleware_registered
-
         # Check if any middleware is enabled
         return unless Familia.enable_database_logging || Familia.enable_database_counter
 
-        if Familia.enable_database_logging
+        # Register each middleware independently to avoid early return bug
+        # where enabling one middleware prevents the other from being registered
+        if Familia.enable_database_logging && !@logger_registered
           DatabaseLogger.logger = Familia.logger
           RedisClient.register(DatabaseLogger)
           Familia.trace :MIDDLEWARE_REGISTERED, nil, 'Registered DatabaseLogger'
+          @logger_registered = true
         end
 
-        if Familia.enable_database_counter
+        if Familia.enable_database_counter && !@counter_registered
           # NOTE: This middleware uses AtomicFixnum from concurrent-ruby which is
           # less contentious than Mutex-based counters. Safe for production.
           RedisClient.register(DatabaseCommandCounter)
           Familia.trace :MIDDLEWARE_REGISTERED, nil, 'Registered DatabaseCommandCounter'
+          @counter_registered = true
         end
 
-        # Set flag after successful registration
-        @middleware_registered = true
+        # Set global flag when any middleware is registered
+        @middleware_registered = @logger_registered || @counter_registered
       end
     end
   end

data/lib/familia/connection/operation_core.rb

@@ -1,3 +1,5 @@
+# lib/familia/connection/operation_core.rb
+#
 # frozen_string_literal: true
 
 module Familia
@@ -85,8 +87,7 @@ module Familia
 
         # Return MultiResult format for consistency
         results = proxy.collected_results
-        summary_boolean = results.all? { |ret| !ret.is_a?(Exception) }
-        MultiResult.new(summary_boolean, results)
+        MultiResult.new(results)
       end
     end
   end

data/lib/familia/connection/operations.rb

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

data/lib/familia/connection/pipelined_core.rb

@@ -1,3 +1,5 @@
+# lib/familia/connection/pipelined_core.rb
+#
 # frozen_string_literal: true
 
 module Familia
@@ -78,9 +80,7 @@ module Familia
         end
 
         # Return same MultiResult format as other methods
-        # Pipeline success is true if no exceptions occurred (all commands executed)
-        summary_boolean = command_return_values.none? { |ret| ret.is_a?(Exception) }
-        MultiResult.new(summary_boolean, command_return_values)
+        MultiResult.new(command_return_values)
       end
     end
   end

data/lib/familia/connection/transaction_core.rb

@@ -1,4 +1,6 @@
 # lib/familia/connection/transaction_core.rb
+#
+# frozen_string_literal: true
 
 module Familia
   module Connection
@@ -8,11 +10,62 @@ module Familia
     # behavior when transactions are unavailable due to connection handler constraints.
     # Eliminates code duplication between Operations and Horreum Connection modules.
     #
+    # ## Transaction Safety Rules
+    #
+    # ### Rule 1: No Save Operations Inside Transactions
+    # The following methods CANNOT be called within a transaction context:
+    # - `save`, `save!`, `save_if_not_exists!`, `create!`
+    # These methods require reading current state for validation, which would
+    # return uninspectable Redis::Future objects inside transactions.
+    #
+    # ### Rule 2: Reentrant Transaction Behavior
+    # Nested transaction calls reuse the same connection and do not create new
+    # MULTI/EXEC blocks. This ensures atomicity across nested operations.
+    #
+    # ### Rule 3: Read Operations Return Futures
+    # Inside transactions, read operations return Redis::Future objects that
+    # cannot be inspected until the transaction completes. Always check conditions
+    # before entering the transaction.
+    #
+    # ### Rule 4: Connection Handler Compatibility
+    # - **FiberTransactionHandler**: Supports reentrant transactions
+    # - **ProviderConnectionHandler**: Full transaction support
+    # - **CreateConnectionHandler**: Full transaction support
+    # - **FiberConnectionHandler**: Blocked (raises OperationModeError)
+    # - **DefaultConnectionHandler**: Blocked (raises OperationModeError)
+    #
+    # @example Correct Pattern: Save Before Transaction
+    #   customer = Customer.new(email: 'test@example.com')
+    #   customer.save  # Validates unique constraints here
+    #
+    #   customer.transaction do
+    #     customer.increment(:login_count)
+    #     customer.hset(:last_login, Time.now.to_i)
+    #   end
+    #
+    # @example Incorrect Pattern: Save Inside Transaction
+    #   Customer.transaction do
+    #     customer = Customer.new(email: 'test@example.com')
+    #     customer.save  # Raises Familia::OperationModeError
+    #   end
+    #
+    # @example Reentrant Transactions
+    #   Customer.transaction do |outer_conn|
+    #     outer_conn.set('key1', 'value1')
+    #
+    #     # Nested call reuses same connection - no new MULTI/EXEC
+    #     Customer.transaction do |inner_conn|
+    #       inner_conn.set('key2', 'value2')  # Same connection as outer
+    #     end
+    #   end
+    #
     # @example Usage in transaction methods
     #   def transaction(&block)
     #     TransactionCore.execute_transaction(-> { dbclient }, &block)
     #   end
     #
+    # @see docs/transaction_safety.md for complete safety guidelines
+    #
     module TransactionCore
       # Executes a transaction with configurable fallback behavior
       #
@@ -21,6 +74,11 @@ module Familia
       # 2. Reentrant transaction when already within a transaction context
       # 3. Individual command execution with configurable error/warn/silent modes
       #
+      # ## Safety Mechanisms
+      # - Fiber-local storage tracks transaction state across nested calls
+      # - Connection handler validation prevents unsafe transaction usage
+      # - Automatic cleanup ensures proper state management even on exceptions
+      #
       # @param dbclient_proc [Proc] Lambda that returns the Redis connection
       # @param block [Proc] Block containing Redis commands to execute
       # @return [MultiResult] Result object with success status and command results
@@ -72,6 +130,16 @@ module Familia
       # Handles the standard transaction flow including nested transaction detection,
       # proper Fiber-local state management, and cleanup in ensure blocks.
       #
+      # ## Implementation Details
+      # - Uses Fiber[:familia_transaction] to track active transaction connection
+      # - Reentrant behavior: yields existing connection if already in transaction
+      # - All commands queued and executed atomically on EXEC
+      # - Returns MultiResult with success status and command results
+      #
+      # ## Thread Safety
+      # Each thread has its own root fiber with isolated fiber-local storage,
+      # ensuring transactions don't interfere across threads.
+      #
       # @param dbclient_proc [Proc] Lambda that returns the Redis connection
       # @param block [Proc] Block containing Redis commands to execute
       # @return [MultiResult] Result object with transaction command results
@@ -90,8 +158,7 @@ module Familia
         end
 
         # Return same MultiResult format as other methods
-        summary_boolean = command_return_values.all? { |ret| %w[OK 0 1].include?(ret.to_s) }
-        MultiResult.new(summary_boolean, command_return_values)
+        MultiResult.new(command_return_values)
       end
     end
   end

data/lib/familia/connection.rb

@@ -1,4 +1,6 @@
 # lib/familia/connection.rb
+#
+# frozen_string_literal: true
 
 require_relative 'connection/behavior'
 require_relative 'connection/handlers'
@@ -16,7 +18,10 @@ require_relative 'connection/pipelined_core'
 module Familia
   @uri = URI.parse 'redis://127.0.0.1:6379'
   @middleware_registered = false
-  @middleware_version = 0
+  @logger_registered = false
+  @counter_registered = false
+  @middleware_version = Concurrent::AtomicFixnum.new(0)
+  @connection_chain_mutex = Familia::ThreadSafety::InstrumentedMutex.new('connection_chain')  # Thread-safe connection chain initialization
 
   # The Connection module provides Database connection management for Familia.
   # It allows easy setup and access to Database clients across different URIs
@@ -86,12 +91,22 @@ module Familia
     # Retrieves a Database connection using the Chain of Responsibility pattern.
     # Handles DB selection automatically based on the URI.
     #
+    # Thread-safe: Uses double-checked locking pattern to avoid mutex overhead
+    # on the hot path. Only acquires mutex during initial lazy initialization.
+    # MRI's GIL provides implicit memory barriers making this pattern safe.
+    #
     # @return [Redis] The Database client for the specified URI
     # @example Familia.dbclient('redis://localhost:6379/1')
     #   Familia.dbclient(2)  # Use DB 2 with default server
     def dbclient(uri = nil)
-      @connection_chain ||= build_connection_chain
-      @connection_chain.handle(uri)
+      # Fast path - read with local variable to ensure single read
+      chain = @connection_chain
+      return chain.handle(uri) if chain
+
+      # Slow path - initialization only
+      @connection_chain_mutex.synchronize do
+        @connection_chain ||= build_connection_chain
+      end.handle(uri)
     end
 
     # Builds the connection chain with handlers in priority order

data/lib/familia/data_type/class_methods.rb

@@ -1,4 +1,6 @@
-# lib/familia/data_type/definition.rb
+# lib/familia/data_type/class_methods.rb
+#
+# frozen_string_literal: true
 
 module Familia
   class DataType

data/lib/familia/data_type/connection.rb

@@ -1,4 +1,6 @@
 # lib/familia/data_type/connection.rb
+#
+# frozen_string_literal: true
 
 module Familia
   class DataType

data/lib/familia/data_type/database_commands.rb

@@ -1,4 +1,6 @@
 # lib/familia/data_type/database_commands.rb
+#
+# frozen_string_literal: true
 
 module Familia
   class DataType