familia 2.0.0.pre17 → 2.0.0.pre19

data/lib/familia/connection/middleware.rb

@@ -1,6 +1,6 @@
 # lib/familia/connection/middleware.rb
 
-require_relative '../../middleware/database_middleware'
+require_relative '../../middleware/database_logger'
 
 module Familia
   module Connection
@@ -19,13 +19,13 @@ module Familia
       # Increments the middleware version, invalidating all cached connections
       def increment_middleware_version!
         @middleware_version += 1
-        Familia.trace :MIDDLEWARE_VERSION, nil, "Incremented to #{@middleware_version}" if Familia.debug?
+        Familia.trace :MIDDLEWARE_VERSION, nil, "Incremented to #{@middleware_version}"
       end
 
       # Sets a versioned fiber-local connection
-      def set_fiber_connection(connection)
+      def fiber_connection=(connection)
         Fiber[:familia_connection] = [connection, middleware_version]
-        Familia.trace :FIBER_CONNECTION, nil, "Set with version #{middleware_version}" if Familia.debug?
+        Familia.trace :FIBER_CONNECTION, nil, "Set with version #{middleware_version}"
       end
 
       # Clears the fiber-local connection
@@ -50,24 +50,78 @@ module Familia
         increment_middleware_version! if value
       end
 
+      # Reconnects with fresh middleware registration
+      #
+      # This method is useful when middleware needs to be applied to connection pools
+      # that were created before middleware was enabled. It:
+      #
+      # 1. Clears the middleware registration flag to allow re-registration
+      # 2. Re-runs the middleware registration logic
+      # 3. Clears connection chain to force rebuild
+      # 4. Increments middleware version to invalidate cached connections
+      # 5. Clears fiber-local connections
+      #
+      # The next connection request will use the updated middleware configuration.
+      # Existing connection pools will naturally create new connections with middleware
+      # as old connections are cycled out.
+      #
+      # @note If no middleware is enabled, this method safely clears connection state
+      #       but won't register any middleware until it's enabled.
+      #
+      # @example Enable middleware and reconnect
+      #   Familia.enable_database_logging = true
+      #   Familia.reconnect!
+      #
+      # @example In test suites
+      #   # Test file A creates pools
+      #   Familia.connection_provider = ->(uri) { pool.with { |c| c } }
+      #
+      #   # Test file B enables middleware
+      #   Familia.enable_database_logging = true
+      #   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!
+
+        Familia.trace :RECONNECT, nil, 'Connection chain cleared, will rebuild with current middleware on next use'
+      end
+
       private
 
       # 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
           DatabaseLogger.logger = Familia.logger
           RedisClient.register(DatabaseLogger)
+          Familia.trace :MIDDLEWARE_REGISTERED, nil, 'Registered DatabaseLogger'
         end
 
         if Familia.enable_database_counter
           # 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'
         end
 
+        # Set flag after successful registration
         @middleware_registered = true
       end
     end

data/lib/familia/connection/operation_core.rb

@@ -45,7 +45,7 @@ module Familia
         when :transaction
           Familia.transaction_mode
         when :pipeline
-          Familia.pipeline_mode
+          Familia.pipelined_mode
         else
           :strict
         end

data/lib/familia/connection/{pipeline_core.rb → pipelined_core.rb}

@@ -16,7 +16,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 +32,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

@@ -34,27 +34,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 +63,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
@@ -78,7 +76,7 @@ module Familia
       # @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,13 @@
 # lib/familia/connection.rb
 
+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
 #

data/lib/familia/data_type/connection.rb

@@ -5,21 +5,104 @@ module Familia
     # 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 +158,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

data/lib/familia/data_type/{commands.rb → database_commands.rb}

@@ -1,10 +1,10 @@
-# lib/familia/data_type/commands.rb
+# lib/familia/data_type/database_commands.rb
 
 module Familia
   class DataType
     # Must be included in all DataType classes to provide Valkey/Redis
     # commands. The class must have a dbkey method.
-    module Commands
+    module DatabaseCommands
       def move(logical_database)
         dbclient.move dbkey, logical_database
       end
@@ -22,11 +22,14 @@ module Familia
       end
 
       # Deletes the entire dbkey
-      # @return [Boolean] true if the key was deleted, false otherwise
+      #
+      # We return the dbclient.del command's return value instead of a friendly
+      # boolean b/c that logic doesn't work inside of a transaction. The return
+      # value in that case is a Redis::Future which based on the name indicates
+      # that the commend hasn't even run yet.
       def delete!
-        Familia.trace :DELETE!, nil, uri if Familia.debug?
-        ret = dbclient.del dbkey
-        ret.positive?
+        Familia.trace :DELETE!, nil, self.class.uri if Familia.debug?
+         dbclient.del dbkey
       end
       alias clear delete!
 

data/lib/familia/data_type/serialization.rb

@@ -11,9 +11,9 @@ module Familia
       # @return [String, nil] The serialized representation of the value, or nil
       #   if serialization fails.
       #
-      # @note When a class option is specified, it uses that class's
-      #   serialization method. Otherwise, it relies on Familia.distinguisher for
-      #   serialization.
+      # @note When a class option is specified, it uses Familia.identifier_extractor
+      #   to extract the identifier from objects. Otherwise, it extracts identifiers
+      #   from Familia::Base instances or class names.
       #
       # @example With a class option
       #   serialize_value(User.new(name: "Cloe"), strict_values: false) #=> '{"name":"Cloe"}'
@@ -31,13 +31,13 @@ module Familia
         Familia.trace :TOREDIS, nil, "#{val}<#{val.class}|#{opts[:class]}>" if Familia.debug?
 
         if opts[:class]
-          prepared = Familia.distinguisher(opts[:class], strict_values: strict_values)
+          prepared = Familia.identifier_extractor(opts[:class])
           Familia.ld "  from opts[class] <#{opts[:class]}>: #{prepared || '<nil>'}"
         end
 
         if prepared.nil?
           # Enforce strict values when no class option is specified
-          prepared = Familia.distinguisher(val, strict_values: true)
+          prepared = Familia.identifier_extractor(val)
           Familia.ld "  from <#{val.class}> => <#{prepared.class}>"
         end
 
@@ -117,7 +117,11 @@ module Familia
       # for serialization since everything becomes a string in Valkey.
       #
       def deserialize_value(val)
+        # Handle Redis::Future objects during transactions first
+        return val if val.is_a?(Redis::Future)
+
         return @opts[:default] if val.nil?
+
         return val unless @opts[:class]
 
         ret = deserialize_values val

data/lib/familia/data_type/types/hashkey.rb

@@ -152,7 +152,7 @@ module Familia
     #     puts "Oops! Our hash seems to have vanished into the Database void!"
     #   end
     def refresh!
-      Familia.trace :REFRESH, nil, uri if Familia.debug?
+      Familia.trace :REFRESH, nil, self.class.uri if Familia.debug?
       raise Familia::KeyNotFoundError, dbkey unless dbclient.exists(dbkey)
 
       fields = hgetall

data/lib/familia/data_type.rb

@@ -3,7 +3,7 @@
 require_relative 'data_type/class_methods'
 require_relative 'data_type/settings'
 require_relative 'data_type/connection'
-require_relative 'data_type/commands'
+require_relative 'data_type/database_commands'
 require_relative 'data_type/serialization'
 
 # Familia
@@ -77,7 +77,7 @@ module Familia
 
     include Settings
     include Connection
-    include Commands
+    include DatabaseCommands
     include Serialization
   end
 

data/lib/familia/encryption/encrypted_data.rb

@@ -44,8 +44,18 @@ module Familia
         new(**parsed)
       end
 
-      def self.from_json(json_string)
-        validate!(json_string)
+      def self.from_json(json_string_or_hash)
+        # Support both JSON strings (legacy) and already-parsed Hashes (v2.0 deserialization)
+        if json_string_or_hash.is_a?(Hash)
+          # Already parsed - use directly
+          parsed = json_string_or_hash
+          # Symbolize keys if they're strings
+          parsed = parsed.transform_keys(&:to_sym) if parsed.keys.first.is_a?(String)
+          new(**parsed)
+        else
+          # JSON string - validate and parse
+          validate!(json_string_or_hash)
+        end
       end
 
       # Instance methods for decryptability validation

data/lib/familia/encryption/manager.rb

@@ -32,15 +32,22 @@ module Familia
         Familia::Encryption.secure_wipe(key) if key
       end
 
-      def decrypt(encrypted_json, context:, additional_data: nil)
-        return nil if encrypted_json.nil? || encrypted_json.empty?
+      def decrypt(encrypted_json_or_hash, context:, additional_data: nil)
+        return nil if encrypted_json_or_hash.nil? || (encrypted_json_or_hash.respond_to?(:empty?) && encrypted_json_or_hash.empty?)
 
         # Increment counter immediately to track all decryption attempts, even failed ones
         Familia::Encryption.derivation_count.increment
 
         begin
-          data = Familia::Encryption::EncryptedData.new(**Familia::JsonSerializer.parse(encrypted_json,
-                                                                                        symbolize_names: true))
+          # Delegate parsing and instantiation to EncryptedData.from_json
+          # Wrap validation errors for security (don't expose internal structure details)
+          begin
+            data = Familia::Encryption::EncryptedData.from_json(encrypted_json_or_hash)
+            raise EncryptionError, 'Failed to parse encrypted data' unless data
+          rescue EncryptionError => e
+            # Re-wrap validation errors with generic message for security
+            raise EncryptionError, "Decryption failed: #{e.message}"
+          end
 
           # Validate algorithm support
           provider = Registry.get(data.algorithm)

data/lib/familia/errors.rb

@@ -1,19 +1,52 @@
 # lib/familia/errors.rb
 #
 module Familia
+  # Base exception class for all Familia errors
   class Problem < RuntimeError; end
-  class NoIdentifier < Problem; end
-  class NonUniqueKey < Problem; end
 
-  class FieldTypeError < Problem; end
-  class AutoloadError < Problem; end
+  # Base exception class for Redis/persistence-related errors
+  class PersistenceError < Problem; end
 
-  class SerializerError < Problem; end
+  # Base exception class for Horreum models
+  class HorreumError < Problem; end
 
-  # Raised when attempting to start transactions or pipelines on connection types that don't support them
-  class OperationModeError < Problem; end
+  # Raised when an object creation fails (e.g. the identifier
+  # is already in use)
+  class CreationError < HorreumError; end
 
-  class NotDistinguishableError < Problem
+  # Raised when an object lacks a required identifier
+  class NoIdentifier < HorreumError; end
+
+  # Raised when a key is expected to be unique but isn't
+  class NonUniqueKey < PersistenceError; end
+
+  # Raised when watch failed (e.g. key was modified), typically
+  # retry
+  class OptimisticLockError < PersistenceError; end
+
+  # Raised when a field type is invalid or unexpected
+  class FieldTypeError < HorreumError; end
+
+  # Raised when autoloading fails
+  class AutoloadError < HorreumError; end
+
+  # Raised when serialization or deserialization fails
+  class SerializerError < HorreumError; end
+
+  # Raised when attempting to start transactions or pipelines on
+  # connection types that don't support them
+  class OperationModeError < PersistenceError; end
+
+  # Raised when attempting to call a major method like save when
+  # inside a transaction or pipeline
+  class NestedTransactionError < OperationModeError; end
+
+  # Raised when attempting to reference a field that doesn't exist
+  class UnknownFieldError < HorreumError; end
+
+  # Raised when a value cannot be converted to a distinguishable
+  # string representation
+  class NotDistinguishableError < HorreumError
     attr_reader :value
 
     def initialize(value)
@@ -26,7 +59,8 @@ module Familia
     end
   end
 
-  class NotConnected < Problem
+  # Raised when no connection is available for a given URI
+  class NotConnected < PersistenceError
     attr_reader :uri
 
     def initialize(uri)
@@ -39,13 +73,15 @@ module Familia
     end
   end
 
-  # UnsortedSet Familia.connection_provider or use middleware to provide connections.
-  class NoConnectionAvailable < Problem; end
+  # UnsortedSet Familia.connection_provider or use middleware
+  # to provide connections.
+  class NoConnectionAvailable < PersistenceError; end
 
   # Raised when a load method fails to find the requested object
-  class NotFound < Problem; end
+  class NotFound < PersistenceError; end
 
-  # Raised when attempting to refresh an object whose key doesn't exist in the database
+  # Raised when attempting to refresh an object whose key
+  # doesn't exist in the database
   class KeyNotFoundError < NonUniqueKey
     attr_reader :key
 
@@ -59,7 +95,8 @@ module Familia
     end
   end
 
-  # Raised when attempting to create an object that already exists in the database
+  # Raised when attempting to create an object that already
+  # exists in the database
   class RecordExistsError < NonUniqueKey
     attr_reader :key
 

data/lib/familia/features/autoloader.rb

@@ -28,7 +28,9 @@ module Familia::Features
       ]
 
       # Ensure the Features module exists within the base module
-      base.const_set(:Features, Module.new) unless base.const_defined?(:Features) || config_name.eql?('features')
+      unless base.const_defined?(:Features) || config_name.eql?('features')
+        base.const_set(:Features, Module.new)
+      end
 
       # Use the shared autoload_files method
       autoload_files(dir_patterns, log_prefix: "Autoloader[#{config_name}]")