familia 2.0.0.pre18 → 2.0.0.pre21

data/lib/familia/connection/handlers.rb

@@ -1,4 +1,6 @@
 # lib/familia/connection/handlers.rb
+#
+# frozen_string_literal: true
 
 # Familia
 #
@@ -219,5 +221,100 @@ module Familia
         dbclient
       end
     end
+
+    # Handler for delegating connection resolution to parent object
+    #
+    # Used by DataType objects that are attached to a parent (Horreum instance or class).
+    # Delegates the connection resolution to the parent's dbclient method, which allows
+    # DataType objects to inherit connection settings, logical_database, and transaction
+    # context from their parent.
+    #
+    # This preserves the existing architectural pattern where DataType objects owned by
+    # Horreum models use the parent's connection chain. This is the primary behavior
+    # for DataType objects in typical usage.
+    #
+    # @example Instance-level DataType with parent
+    #   user = User.new(userid: 'user_123')
+    #   user.tags  # DataType that delegates to user.dbclient
+    #
+    # @example Class-level DataType with parent
+    #   User.global_users  # DataType that delegates to User.dbclient
+    #
+    class ParentDelegationHandler < BaseConnectionHandler
+      @allows_transaction = true
+      @allows_pipelined = true
+
+      def initialize(data_type)
+        @data_type = data_type
+      end
+
+      def handle(uri)
+        return nil unless @data_type.parent
+
+        # Delegate to parent's connection chain
+        # Parent can be either a Horreum class or instance
+        parent_connection = @data_type.parent.dbclient(uri)
+
+        if parent_connection
+          Familia.trace :DBCLIENT_PARENT_DELEGATION, @data_type.dbkey,
+                       "Using parent connection from #{@data_type.parent.class}"
+        end
+
+        parent_connection
+      end
+    end
+
+    # Handler for standalone DataType objects without a parent
+    #
+    # Provides connection resolution for DataType objects that are created independently
+    # rather than being attached to a Horreum model. Checks for instance-level @dbclient
+    # first, then falls back to creating a connection based on logical_database option
+    # or global Familia connection.
+    #
+    # This enables standalone DataType usage patterns like Rack::Session implementations
+    # where DataType objects need independent connection management and transaction support.
+    #
+    # @example Standalone DataType with custom connection
+    #   leaderboard = Familia::SortedSet.new('game:leaderboard')
+    #   leaderboard.dbclient = ConnectionPool.new { Redis.new }
+    #
+    # @example Standalone DataType with logical_database option
+    #   cache = Familia::HashKey.new('app:cache', logical_database: 2)
+    #
+    class StandaloneConnectionHandler < BaseConnectionHandler
+      @allows_transaction = true
+      @allows_pipelined = true
+
+      def initialize(data_type)
+        @data_type = data_type
+      end
+
+      def handle(uri)
+        # If a specific URI is provided, always use it to get a connection.
+        if uri
+          connection = Familia.dbclient(uri)
+          Familia.trace :DBCLIENT_STANDALONE_DATATYPE, @data_type.dbkey,
+                       "Created standalone connection for specific URI: #{uri}"
+          return connection
+        end
+
+        # Use instance @dbclient if explicitly set and no URI was passed
+        instance_dbclient = @data_type.instance_variable_get(:@dbclient)
+        if instance_dbclient
+          Familia.trace :DBCLIENT_DATATYPE_INSTANCE, @data_type.dbkey,
+                       'Using DataType instance @dbclient'
+          return instance_dbclient
+        end
+
+        # Fall back to creating connection based on opts or global
+        target_uri = @data_type.opts[:logical_database]
+        connection = Familia.dbclient(target_uri)
+
+        Familia.trace :DBCLIENT_STANDALONE_DATATYPE, @data_type.dbkey,
+                     "Created standalone connection for #{target_uri || 'default'}"
+
+        connection
+      end
+    end
   end
 end

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
@@ -45,7 +47,7 @@ module Familia
         when :transaction
           Familia.transaction_mode
         when :pipeline
-          Familia.pipeline_mode
+          Familia.pipelined_mode
         else
           :strict
         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/{pipeline_core.rb → pipelined_core.rb}

@@ -1,3 +1,5 @@
+# lib/familia/connection/pipelined_core.rb
+#
 # frozen_string_literal: true
 
 module Familia
@@ -16,7 +18,7 @@ module Familia
       #
       # Handles pipeline execution based on connection handler capabilities.
       # When handler doesn't support pipelines, fallback behavior is controlled
-      # by Familia.pipeline_mode setting.
+      # by Familia.pipelined_mode setting.
       #
       # @param dbclient_proc [Proc] Lambda that returns the Redis connection
       # @param block [Proc] Block containing Redis commands to execute
@@ -32,7 +34,7 @@ module Familia
       #   result.results     # => ["OK", 1]
       #
       # @example With fallback modes
-      #   Familia.configure { |c| c.pipeline_mode = :permissive }
+      #   Familia.configure { |c| c.pipelined_mode = :permissive }
       #   result = PipelineCore.execute_pipeline(-> { cached_conn }) do |conn|
       #     conn.set('key', 'value')  # Executes individually, no error
       #   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
@@ -34,27 +92,25 @@ module Familia
       #   result.successful?  # => true/false
       #   result.results     # => ["OK", 1]
       #
-      def self.execute_transaction(dbclient_proc, &block)
+      def self.execute_transaction(dbclient_proc, &)
         # First, get the connection to populate the handler class
-        connection = dbclient_proc.call
+        dbclient_proc.call
         handler_class = Fiber[:familia_connection_handler_class]
 
         # Check transaction capability
         transaction_capability = handler_class&.allows_transaction
 
         if transaction_capability == false
-          handle_transaction_fallback(dbclient_proc, handler_class, &block)
+          handle_transaction_fallback(dbclient_proc, handler_class, &)
         elsif transaction_capability == :reentrant
           # Already in transaction, just yield the connection
           yield(Fiber[:familia_transaction])
         else
           # Normal transaction flow (includes nil, true, and other values)
-          execute_normal_transaction(dbclient_proc, &block)
+          execute_normal_transaction(dbclient_proc, &)
         end
       end
 
-      private
-
       # Handles transaction fallback based on configured transaction mode
       #
       # Delegates to OperationCore.handle_fallback for consistent behavior
@@ -65,8 +121,8 @@ module Familia
       # @param block [Proc] Block containing Redis commands to execute
       # @return [MultiResult] Result from individual command execution or raises error
       #
-      def self.handle_transaction_fallback(dbclient_proc, handler_class, &block)
-        OperationCore.handle_fallback(:transaction, dbclient_proc, handler_class, &block)
+      def self.handle_transaction_fallback(dbclient_proc, handler_class, &)
+        OperationCore.handle_fallback(:transaction, dbclient_proc, handler_class, &)
       end
 
       # Executes a normal Redis transaction using MULTI/EXEC
@@ -74,11 +130,21 @@ 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
       #
-      def self.execute_normal_transaction(dbclient_proc, &block)
+      def self.execute_normal_transaction(dbclient_proc)
         # Check for existing transaction context
         return yield(Fiber[:familia_transaction]) if Fiber[:familia_transaction]
 

data/lib/familia/connection.rb

@@ -1,12 +1,15 @@
 # lib/familia/connection.rb
+#
+# frozen_string_literal: true
 
+require_relative 'connection/behavior'
 require_relative 'connection/handlers'
 require_relative 'connection/middleware'
 require_relative 'connection/operations'
 require_relative 'connection/individual_command_proxy'
 require_relative 'connection/operation_core'
 require_relative 'connection/transaction_core'
-require_relative 'connection/pipeline_core'
+require_relative 'connection/pipelined_core'
 
 # Familia
 #
@@ -15,7 +18,10 @@ require_relative 'connection/pipeline_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
@@ -42,7 +48,7 @@ module Familia
       @connection_chain = nil # Force rebuild of chain
     end
 
-# Sets the default URI for Database connections.
+    # Sets the default URI for Database connections.
     #
     # NOTE: uri is not a property of the Settings module b/c it's not
     # configured in class defintions like default_expiration or logical DB index.
@@ -85,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,25 +1,110 @@
 # lib/familia/data_type/connection.rb
+#
+# frozen_string_literal: true
 
 module Familia
   class DataType
     # Connection - Instance-level connection and key generation methods
     #
     # This module provides instance methods for database connection resolution
-    # and Redis key generation for DataType objects.
+    # and Redis key generation for DataType objects. It includes shared connection
+    # behavior from Familia::Connection::Behavior, enabling transaction and pipeline
+    # support for both parent-owned and standalone DataType objects.
     #
     # Key features:
     # * Database connection resolution with Chain of Responsibility pattern
     # * Redis key generation based on parent context
     # * Direct database access for advanced operations
+    # * Transaction support (MULTI/EXEC) for atomic operations
+    # * Pipeline support for batched command execution
+    # * Parent delegation for owned DataType objects
+    # * Standalone connection management for independent DataType objects
+    #
+    # Connection Chain Priority:
+    # 1. FiberTransactionHandler - Active transaction context
+    # 2. FiberConnectionHandler - Fiber-local connections
+    # 3. ProviderConnectionHandler - User-defined connection provider
+    # 4. ParentDelegationHandler - Delegate to parent object (primary for owned DataTypes)
+    # 5. StandaloneConnectionHandler - Independent DataType connection
+    #
+    # @example Parent-owned DataType (automatic delegation)
+    #   class User < Familia::Horreum
+    #     logical_database 2
+    #     zset :scores
+    #   end
+    #
+    #   user = User.new(userid: 'user_123')
+    #   user.scores.transaction do |conn|
+    #     conn.zadd(user.scores.dbkey, 100, 'level1')
+    #     conn.zadd(user.scores.dbkey, 200, 'level2')
+    #   end
+    #
+    # @example Standalone DataType with transaction
+    #   leaderboard = Familia::SortedSet.new('game:leaderboard')
+    #   leaderboard.transaction do |conn|
+    #     conn.zadd(leaderboard.dbkey, 500, 'player1')
+    #     conn.zadd(leaderboard.dbkey, 600, 'player2')
+    #   end
     #
     module Connection
-      # TODO: Replace with Chain of Responsibility pattern
-      def dbclient
+      include Familia::Connection::Behavior
+
+      # Returns the effective URI this DataType will use for connections
+      #
+      # For parent-owned DataTypes, delegates to parent's URI.
+      # For standalone DataTypes with logical_database option, constructs URI with that database.
+      # For standalone DataTypes without options, returns global Familia.uri.
+      # Explicit @uri assignment (via uri=) takes precedence.
+      #
+      # @return [URI, nil] The URI for database connections
+      #
+      def uri
+        return @uri if defined?(@uri) && @uri
+        return parent.uri if parent && parent.respond_to?(:uri)
+
+        # Check opts[:logical_database] first, then parent's logical_database
+        db_num = opts[:logical_database]
+        db_num ||= parent.logical_database if parent && parent.respond_to?(:logical_database)
+
+        if db_num
+          # Create a new URI with the database number but without custom port
+          # This ensures consistent URI representation (e.g., redis://host/db not redis://host:port/db)
+          base_uri = Familia.uri
+          URI.parse("redis://#{base_uri.host}/#{db_num}")
+        else
+          Familia.uri
+        end
+      end
+
+      # Retrieves a Database connection using the Chain of Responsibility pattern
+      #
+      # Implements connection resolution optimized for DataType usage patterns:
+      # - Fast path check for active transaction context
+      # - Full connection chain for comprehensive resolution
+      # - Parent delegation as primary behavior for owned DataTypes
+      # - Standalone connection handling for independent DataTypes
+      #
+      # Note: We don't cache the connection chain in an instance variable because
+      # DataType objects are frozen for thread safety. Building the chain is cheap
+      # (just creating handler objects), and the actual connection resolution work
+      # is done by the handlers themselves.
+      #
+      # @param uri [String, URI, Integer, nil] Optional URI for database selection
+      # @return [Redis] The Database client for the specified URI
+      #
+      # @example Getting connection from parent-owned DataType
+      #   user.tags.dbclient  # Delegates to user.dbclient
+      #
+      # @example Getting connection from standalone DataType
+      #   cache = Familia::HashKey.new('app:cache', logical_database: 2)
+      #   cache.dbclient  # Uses standalone handler with db 2
+      #
+      def dbclient(uri = nil)
+        # Fast path for transaction context (highest priority)
         return Fiber[:familia_transaction] if Fiber[:familia_transaction]
-        return @dbclient if @dbclient
 
-        # Delegate to parent if present, otherwise fall back to Familia
-        parent ? parent.dbclient : Familia.dbclient(opts[:logical_database])
+        # Build connection chain (not cached due to frozen objects)
+        build_connection_chain.handle(uri)
       end
 
       # Produces the full dbkey for this object.
@@ -75,8 +160,69 @@ module Familia
       # Provides a structured way to "gear down" to run db commands that are
       # not implemented in our DataType classes since we intentionally don't
       # have a method_missing method.
+      #
+      # Enhanced to work seamlessly with transactions and pipelines. When called
+      # within a transaction or pipeline context, uses that connection automatically.
+      #
+      # @yield [Redis, String] Yields the connection and dbkey to the block
+      # @return The return value of the block
+      #
+      # @example Basic usage
+      #   datatype.direct_access do |conn, key|
+      #     conn.zadd(key, 100, 'member')
+      #   end
+      #
+      # @example Within transaction (automatic context detection)
+      #   datatype.transaction do |trans_conn|
+      #     datatype.direct_access do |conn, key|
+      #       # conn is the same as trans_conn
+      #       conn.zadd(key, 200, 'member')
+      #     end
+      #   end
+      #
       def direct_access
-        yield(dbclient, dbkey)
+        if Fiber[:familia_transaction]
+          # Already in transaction, use that connection
+          yield(Fiber[:familia_transaction], dbkey)
+        elsif Fiber[:familia_pipeline]
+          # Already in pipeline, use that connection
+          yield(Fiber[:familia_pipeline], dbkey)
+        else
+          yield(dbclient, dbkey)
+        end
+      end
+
+      private
+
+      # Builds the connection chain with handlers in priority order
+      #
+      # Creates the Chain of Responsibility for connection resolution with
+      # DataType-specific handlers. Handlers are checked in order:
+      #
+      # 1. FiberTransactionHandler - Return active transaction connection
+      # 2. FiberConnectionHandler - Use fiber-local connection
+      # 3. ProviderConnectionHandler - Delegate to connection provider
+      # 4. ParentDelegationHandler - Delegate to parent's connection (primary for owned DataTypes)
+      # 5. StandaloneConnectionHandler - Handle standalone DataTypes
+      #
+      # @return [ResponsibilityChain] Configured connection chain
+      #
+      def build_connection_chain
+        # Create fresh handler instances each time since DataType objects are frozen
+        # The chain itself is cached in @connection_chain, so this only runs once
+        fiber_connection_handler = Familia::Connection::FiberConnectionHandler.new
+        provider_connection_handler = Familia::Connection::ProviderConnectionHandler.new
+
+        # DataType-specific handlers for parent delegation and standalone usage
+        parent_delegation_handler = Familia::Connection::ParentDelegationHandler.new(self)
+        standalone_connection_handler = Familia::Connection::StandaloneConnectionHandler.new(self)
+
+        Familia::Connection::ResponsibilityChain.new
+          .add_handler(Familia::Connection::FiberTransactionHandler.instance)
+          .add_handler(fiber_connection_handler)
+          .add_handler(provider_connection_handler)
+          .add_handler(parent_delegation_handler)
+          .add_handler(standalone_connection_handler)
       end
     end
   end