familia 2.0.0.pre15 → 2.0.0.pre16

data/lib/familia/connection.rb

@@ -1,7 +1,12 @@
 # lib/familia/connection.rb
 
-require_relative '../../lib/middleware/database_middleware'
-require_relative 'multi_result'
+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'
 
 # Familia
 #
@@ -9,7 +14,8 @@ require_relative 'multi_result'
 #
 module Familia
   @uri = URI.parse 'redis://127.0.0.1:6379'
-  @database_clients = {}
+  @middleware_registered = false
+  @middleware_version = 0
 
   # The Connection module provides Database connection management for Familia.
   # It allows easy setup and access to Database clients across different URIs
@@ -18,222 +24,86 @@ module Familia
     # @return [URI] The default URI for Database connections
     attr_reader :uri
 
-    # @return [Hash] A hash of Database clients, keyed by server ID
-    attr_reader :database_clients
-
-    # @return [Boolean] Whether Database command logging is enabled
-    attr_accessor :enable_database_logging
-
-    # @return [Boolean] Whether Database command counter is enabled
-    attr_accessor :enable_database_counter
-
     # @return [Proc] A callable that provides Database connections
-    attr_accessor :connection_provider
+    # The provider should accept a URI string and return a Redis connection
+    # already connected to the correct database specified in the URI.
+    #
+    # @example Setting a connection provider
+    #   Familia.connection_provider = ->(uri) do
+    #     pool = ConnectionPool.new { Redis.new(url: uri) }
+    #     pool.with { |conn| conn }
+    #   end
+    attr_reader :connection_provider
 
-    # @return [Boolean] Whether to require external connections (no fallback)
-    attr_accessor :connection_required
+    # Sets the connection provider and bumps middleware version
+    def connection_provider=(provider)
+      @connection_provider = provider
+      increment_middleware_version! if provider
+      @connection_chain = nil # Force rebuild of chain
+    end
 
     # 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.
     #
-    # @param v [String, URI] The new default URI
-    # @example
-    #   Familia.uri = 'redis://localhost:6379'
+    # @param uri [String, URI] The new default URI
+    # @example Familia.uri = 'redis://localhost:6379'
     def uri=(uri)
       @uri = normalize_uri(uri)
     end
     alias url uri
     alias url= uri=
 
-    # Establishes a connection to a Database server.
+    # Creates a new Database connection instance.
+    #
+    # This method always creates a fresh connection and does not use caching.
+    # Each call returns a new Redis client instance that you are responsible
+    # for managing and closing when done.
     #
     # @param uri [String, URI, nil] The URI of the Database server to connect to.
-    #   If nil, uses the default URI from `@database_clients` or `Familia.uri`.
-    # @return [Redis] The connected Database client.
+    #   If nil, uses the default URI from Familia.uri.
+    # @return [Redis] A new Database client connection.
     # @raise [ArgumentError] If no URI is specified.
-    # @example
-    #   Familia.connect('redis://localhost:6379')
-    def connect(uri = nil)
+    #
+    # @example Creating a new connection
+    #   client = Familia.create_dbclient('redis://localhost:6379')
+    #   client.ping
+    #   client.close
+    #
+    def create_dbclient(uri = nil)
       parsed_uri = normalize_uri(uri)
 
-      if Familia.enable_database_logging
-        DatabaseLogger.logger = Familia.logger
-        RedisClient.register(DatabaseLogger)
-      end
-
-      if Familia.enable_database_counter
-        # NOTE: This middleware uses AtommicFixnum from concurrent-ruby which is
-        # less contentious than Mutex-based counters. Safe for
-        RedisClient.register(DatabaseCommandCounter)
-      end
+      # Register middleware only once, globally
+      register_middleware_once
 
       Redis.new(parsed_uri.conf)
     end
+    alias connect create_dbclient # backwards compatibility
+    alias isolated_dbclient create_dbclient # matches with_isolated_dbclient api
 
-    def reconnect(uri = nil)
-      parsed_uri = normalize_uri(uri)
-      serverid = parsed_uri.serverid
-
-      # Close the existing connection if it exists
-      @database_clients[serverid].close if @database_clients.key?(serverid)
-      @database_clients.delete(serverid)
-
-      connect(parsed_uri)
-    end
-
-    # Retrieves a Database connection from the appropriate pool.
+    # Retrieves a Database connection using the Chain of Responsibility pattern.
     # Handles DB selection automatically based on the URI.
     #
     # @return [Redis] The Database client for the specified URI
-    # @example
-    #   Familia.dbclient('redis://localhost:6379/1')
+    # @example Familia.dbclient('redis://localhost:6379/1')
     #   Familia.dbclient(2)  # Use DB 2 with default server
     def dbclient(uri = nil)
-      # First priority: Thread-local connection (middleware pattern)
-      return Thread.current[:familia_connection] if Thread.current.key?(:familia_connection)
-
-      # Second priority: Connection provider
-      if connection_provider
-        # Always pass normalized URI with database to provider
-        # Provider MUST return connection already on the correct database
-        parsed_uri = normalize_uri(uri)
-        client = connection_provider.call(parsed_uri.to_s)
-
-        # In debug mode, verify the provider honored the contract
-        if Familia.debug? && client.respond_to?(:client)
-          current_db = client.connection[:db]
-          expected_db = parsed_uri.db || 0
-          Familia.ld "Connection provider returned client on DB #{current_db}, expected #{expected_db}"
-          if current_db != expected_db
-            Familia.warn "Connection provider returned client on DB #{current_db}, expected #{expected_db}"
-          end
-        end
-
-        return client
-      end
-
-      # Third priority: Fallback behavior or error
-      raise Familia::NoConnectionAvailable, 'No connection available.' if connection_required
-
-      # Legacy behavior: create connection
-      parsed_uri = normalize_uri(uri)
-      serverid = parsed_uri.serverid
-
-      @database_clients[serverid] ||= connect(parsed_uri)
-    end
-
-    # Executes Database commands atomically within a transaction (MULTI/EXEC).
-    #
-    # Database transactions queue commands and execute them atomically as a single unit.
-    # All commands succeed together or all fail together, ensuring data consistency.
-    #
-    # @yield [Redis] The Database transaction connection
-    # @return [Array] Results of all commands executed in the transaction
-    #
-    # @example Basic transaction usage
-    #   Familia.transaction do |trans|
-    #     trans.set("key1", "value1")
-    #     trans.incr("counter")
-    #     trans.lpush("list", "item")
-    #   end
-    #   # Returns: ["OK", 2, 1] - results of all commands
-    #
-    # @note **Comparison of Database batch operations:**
-    #
-    #   | Feature         | Multi/Exec      | Pipeline        |
-    #   |-----------------|-----------------|-----------------|
-    #   | Atomicity       | Yes             | No              |
-    #   | Performance     | Good            | Better          |
-    #   | Error handling  | All-or-nothing  | Per-command     |
-    #   | Use case        | Data consistency| Bulk operations |
-    #
-    def transaction(&)
-      block_result = nil
-      result = dbclient.multi do |conn|
-        Fiber[:familia_transaction] = conn
-        begin
-          block_result = yield(conn)
-        ensure
-          Fiber[:familia_transaction] = nil # cleanup reference
-        end
-      end
-      # Return the multi result which contains the transaction results
-      result
+      @connection_chain ||= build_connection_chain
+      @connection_chain.handle(uri)
     end
-    alias multi transaction
 
-    # Executes Database commands in a pipeline for improved performance.
-    #
-    # Pipelines send multiple commands without waiting for individual responses,
-    # reducing network round-trips. Commands execute independently and can
-    # succeed or fail without affecting other commands in the pipeline.
-    #
-    # @yield [Redis] The Database pipeline connection
-    # @return [Array] Results of all commands executed in the pipeline
-    #
-    # @example Basic pipeline usage
-    #   Familia.pipeline do |pipe|
-    #     pipe.set("key1", "value1")
-    #     pipe.incr("counter")
-    #     pipe.lpush("list", "item")
-    #   end
-    #   # Returns: ["OK", 2, 1] - results of all commands
-    #
-    # @example Error handling - commands succeed/fail independently
-    #   results = Familia.pipeline do |conn|
-    #     conn.set("valid_key", "value")     # This will succeed
-    #     conn.incr("string_key")            # This will fail (wrong type)
-    #     conn.set("another_key", "value2")  # This will still succeed
-    #   end
-    #   # Returns: ["OK", Redis::CommandError, "OK"]
-    #   # Notice how the error doesn't prevent other commands from executing
-    #
-    # @example Contrast with transaction behavior
-    #   results = Familia.transaction do |conn|
-    #     conn.set("inventory:item1", 100)
-    #     conn.incr("invalid_key")        # Fails, rolls back everything
-    #     conn.set("inventory:item2", 200) # Won't be applied
-    #   end
-    #   # Result: neither item1 nor item2 are set due to the error
-    #
-    def pipeline(&)
-      block_result = nil
-      result = dbclient.pipelined do |conn|
-        Fiber[:familia_pipeline] = conn
-        begin
-          block_result = yield(conn)
-        ensure
-          Fiber[:familia_pipeline] = nil # cleanup reference
-        end
-      end
-      # Return the pipeline result which contains the command results
-      result
+    # Builds the connection chain with handlers in priority order
+    def build_connection_chain
+      ResponsibilityChain.new
+        .add_handler(Familia::Connection::FiberTransactionHandler.new)
+        .add_handler(FiberConnectionHandler.new)
+        .add_handler(ProviderConnectionHandler.new)
+        .add_handler(CreateConnectionHandler.new)
     end
 
-    # Provides explicit access to a Database connection.
-    #
-    # This method is useful when you need direct access to a connection
-    # for operations not covered by other methods. The connection is
-    # properly managed and returned to the pool (if using connection_provider).
-    #
-    # @yield [Redis] A Database connection
-    # @return The result of the block
-    #
-    # @example Using with_connection for custom operations
-    #   Familia.with_connection do |conn|
-    #     conn.set("custom_key", "value")
-    #     conn.expire("custom_key", 3600)
-    #   end
-    #
-    def with_connection(&)
-      yield dbclient
-    end
-
-    private
-
     # Normalizes various URI formats to a consistent URI object
+    # Made public so handlers can use it
     def normalize_uri(uri)
       case uri
       when Integer
@@ -250,5 +120,9 @@ module Familia
         raise ArgumentError, "Invalid URI type: #{uri.class.name}"
       end
     end
+
+    # Extend self with submodules to make their methods available as module methods
+    include Familia::Connection::Middleware
+    include Familia::Connection::Operations
   end
 end

data/lib/familia/data_type/commands.rb

@@ -1,56 +1,58 @@
 # lib/familia/data_type/commands.rb
 
-class Familia::DataType
-  # Must be included in all DataType classes to provide Redis
-  # commands. The class must have a dbkey method.
-  module Commands
-    def move(logical_database)
-      dbclient.move dbkey, logical_database
-    end
-
-    def rename(newkey)
-      dbclient.rename dbkey, newkey
-    end
-
-    def renamenx(newkey)
-      dbclient.renamenx dbkey, newkey
-    end
-
-    def type
-      dbclient.type dbkey
-    end
-
-    # Deletes the entire dbkey
-    # @return [Boolean] true if the key was deleted, false otherwise
-    def delete!
-      Familia.trace :DELETE!, dbclient, uri, caller(1..1) if Familia.debug?
-      ret = dbclient.del dbkey
-      ret.positive?
-    end
-    alias clear delete!
-
-    def exists?
-      dbclient.exists(dbkey) && !size.zero?
-    end
-
-    def current_expiration
-      dbclient.ttl dbkey
-    end
-
-    def expire(sec)
-      dbclient.expire dbkey, sec.to_i
-    end
-
-    def expireat(unixtime)
-      dbclient.expireat dbkey, unixtime
-    end
-
-    def persist
-      dbclient.persist dbkey
-    end
-
-    def echo(meth, trace)
-      dbclient.echo "[#{self.class}##{meth}] #{trace} (#{@opts[:class]}#)"
+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
+      def move(logical_database)
+        dbclient.move dbkey, logical_database
+      end
+
+      def rename(newkey)
+        dbclient.rename dbkey, newkey
+      end
+
+      def renamenx(newkey)
+        dbclient.renamenx dbkey, newkey
+      end
+
+      def type
+        dbclient.type dbkey
+      end
+
+      # Deletes the entire dbkey
+      # @return [Boolean] true if the key was deleted, false otherwise
+      def delete!
+        Familia.trace :DELETE!, nil, uri if Familia.debug?
+        ret = dbclient.del dbkey
+        ret.positive?
+      end
+      alias clear delete!
+
+      def exists?
+        dbclient.exists(dbkey) && !size.zero?
+      end
+
+      def current_expiration
+        dbclient.ttl dbkey
+      end
+
+      def expire(sec)
+        dbclient.expire dbkey, sec.to_i
+      end
+
+      def expireat(unixtime)
+        dbclient.expireat dbkey, unixtime
+      end
+
+      def persist
+        dbclient.persist dbkey
+      end
+
+      def echo(*args)
+        dbclient.echo "[#{self.class}] #{args.join(' ')} (#{opts&.fetch(:class, '<no opts>')})"
+      end
     end
   end
 end

data/lib/familia/data_type/serialization.rb

@@ -1,127 +1,128 @@
 # lib/familia/data_type/serialization.rb
 
-class Familia::DataType
-  module Serialization
-    # Serializes a value for storage in Redis.
-    #
-    # @param val [Object] The value to be serialized.
-    # @param strict_values [Boolean] Whether to enforce strict value
-    #   serialization (default: true).
-    # @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.
-    #
-    # @example With a class option
-    #   serialize_value(User.new(name: "Cloe"), strict_values: false) #=> '{"name":"Cloe"}'
-    #
-    # @example Without a class option
-    #   serialize_value(123) #=> "123"
-    #   serialize_value("hello") #=> "hello"
-    #
-    # @raise [Familia::HighRiskFactor] If serialization fails under strict
-    #   mode.
-    #
-    def serialize_value(val, strict_values: true)
-      prepared = nil
+module Familia
+  class DataType
+    module Serialization
+      # Serializes a value for storage in the database.
+      #
+      # @param val [Object] The value to be serialized.
+      # @param strict_values [Boolean] Whether to enforce strict value
+      #   serialization (default: true).
+      # @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.
+      #
+      # @example With a class option
+      #   serialize_value(User.new(name: "Cloe"), strict_values: false) #=> '{"name":"Cloe"}'
+      #
+      # @example Without a class option
+      #   serialize_value(123) #=> "123"
+      #   serialize_value("hello") #=> "hello"
+      #
+      # @raise [Familia::NotDistinguishableError] If serialization fails under strict
+      #   mode.
+      #
+      def serialize_value(val, strict_values: true)
+        prepared = nil
 
-      Familia.trace :TOREDIS, dbclient, "#{val}<#{val.class}|#{opts[:class]}>", caller(1..1) if Familia.debug?
+        Familia.trace :TOREDIS, nil, "#{val}<#{val.class}|#{opts[:class]}>" if Familia.debug?
 
-      if opts[:class]
-        prepared = Familia.distinguisher(opts[:class], strict_values: strict_values)
-        Familia.ld "  from opts[class] <#{opts[:class]}>: #{prepared || '<nil>'}"
-      end
+        if opts[:class]
+          prepared = Familia.distinguisher(opts[:class], strict_values: strict_values)
+          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)
-        Familia.ld "  from <#{val.class}> => <#{prepared.class}>"
-      end
+        if prepared.nil?
+          # Enforce strict values when no class option is specified
+          prepared = Familia.distinguisher(val, strict_values: true)
+          Familia.ld "  from <#{val.class}> => <#{prepared.class}>"
+        end
+
+        if Familia.debug?
+          Familia.trace :TOREDIS, nil, "#{val}<#{val.class}|#{opts[:class]}> => #{prepared}<#{prepared.class}>"
+        end
 
-      if Familia.debug?
-        Familia.trace :TOREDIS, dbclient, "#{val}<#{val.class}|#{opts[:class]}> => #{prepared}<#{prepared.class}>",
-                      caller(1..1)
+        Familia.warn "[#{self.class}#serialize_value] nil returned for #{opts[:class]}##{name}" if prepared.nil?
+        prepared
       end
 
-      Familia.warn "[#{self.class}#serialize_value] nil returned for #{opts[:class]}##{name}" if prepared.nil?
-      prepared
-    end
+      # Deserializes multiple values from Valkey/Redis, removing nil values.
+      #
+      # @param values [Array<String>] The values to deserialize.
+      # @return [Array<Object>] Deserialized objects, with nil values removed.
+      #
+      # @see #deserialize_values_with_nil
+      #
+      def deserialize_values(*values)
+        # Avoid using compact! here. Using compact! as the last expression in the
+        # method can unintentionally return nil if no changes are made, which is
+        # not desirable. Instead, use compact to ensure the method returns the
+        # expected value.
+        deserialize_values_with_nil(*values).compact
+      end
 
-    # Deserializes multiple values from Redis, removing nil values.
-    #
-    # @param values [Array<String>] The values to deserialize.
-    # @return [Array<Object>] Deserialized objects, with nil values removed.
-    #
-    # @see #deserialize_values_with_nil
-    #
-    def deserialize_values(*values)
-      # Avoid using compact! here. Using compact! as the last expression in the
-      # method can unintentionally return nil if no changes are made, which is
-      # not desirable. Instead, use compact to ensure the method returns the
-      # expected value.
-      deserialize_values_with_nil(*values).compact
-    end
+      # Deserializes multiple values from Valkey/Redis, preserving nil values.
+      #
+      # @param values [Array<String>] The values to deserialize.
+      # @return [Array<Object, nil>] Deserialized objects, including nil values.
+      #
+      # @raise [Familia::Problem] If the specified class doesn't respond to the
+      #   load method.
+      #
+      # @note This method attempts to deserialize each value using the specified
+      #   class's load method. If deserialization fails for a value, it's
+      #   replaced with nil.
+      #
+      def deserialize_values_with_nil(*values)
+        Familia.ld "deserialize_values: (#{@opts}) #{values}"
+        return [] if values.empty?
+        return values.flatten unless @opts[:class]
 
-    # Deserializes multiple values from Redis, preserving nil values.
-    #
-    # @param values [Array<String>] The values to deserialize.
-    # @return [Array<Object, nil>] Deserialized objects, including nil values.
-    #
-    # @raise [Familia::Problem] If the specified class doesn't respond to the
-    #   load method.
-    #
-    # @note This method attempts to deserialize each value using the specified
-    #   class's load method. If deserialization fails for a value, it's
-    #   replaced with nil.
-    #
-    def deserialize_values_with_nil(*values)
-      Familia.ld "deserialize_values: (#{@opts}) #{values}"
-      return [] if values.empty?
-      return values.flatten unless @opts[:class]
+        unless @opts[:class].respond_to?(load_method)
+          raise Familia::Problem, "No such method: #{@opts[:class]}##{load_method}"
+        end
 
-      unless @opts[:class].respond_to?(load_method)
-        raise Familia::Problem, "No such method: #{@opts[:class]}##{load_method}"
-      end
+        values.collect! do |obj|
+          next if obj.nil?
 
-      values.collect! do |obj|
-        next if obj.nil?
+          val = @opts[:class].send load_method, obj
+          Familia.ld "[#{self.class}#deserialize_values] nil returned for #{@opts[:class]}##{name}" if val.nil?
 
-        val = @opts[:class].send load_method, obj
-        Familia.ld "[#{self.class}#deserialize_values] nil returned for #{@opts[:class]}##{name}" if val.nil?
+          val
+        rescue StandardError => e
+          Familia.info val
+          Familia.info "Parse error for #{dbkey} (#{load_method}): #{e.message}"
+          Familia.info e.backtrace
+          nil
+        end
 
-        val
-      rescue StandardError => e
-        Familia.info val
-        Familia.info "Parse error for #{dbkey} (#{load_method}): #{e.message}"
-        Familia.info e.backtrace
-        nil
+        values
       end
 
-      values
-    end
+      # Deserializes a single value from the database.
+      #
+      # @param val [String, nil] The value to deserialize.
+      # @return [Object, nil] The deserialized object, the default value if
+      #   val is nil, or nil if deserialization fails.
+      #
+      # @note If no class option is specified, the original value is
+      #   returned unchanged.
+      #
+      # NOTE: Currently only the DataType class uses this method. Horreum
+      # fields are a newer addition and don't support the full range of
+      # deserialization options that DataType supports. It uses serialize_value
+      # for serialization since everything becomes a string in Valkey.
+      #
+      def deserialize_value(val)
+        return @opts[:default] if val.nil?
+        return val unless @opts[:class]
 
-    # Deserializes a single value from the database.
-    #
-    # @param val [String, nil] The value to deserialize.
-    # @return [Object, nil] The deserialized object, the default value if
-    #   val is nil, or nil if deserialization fails.
-    #
-    # @note If no class option is specified, the original value is
-    #   returned unchanged.
-    #
-    # NOTE: Currently only the DataType class uses this method. Horreum
-    # fields are a newer addition and don't support the full range of
-    # deserialization options that DataType supports. It uses serialize_value
-    # for serialization since everything becomes a string in Valkey.
-    #
-    def deserialize_value(val)
-      return @opts[:default] if val.nil?
-      return val unless @opts[:class]
-
-      ret = deserialize_values val
-      ret&.first # return the object or nil
+        ret = deserialize_values val
+        ret&.first # return the object or nil
+      end
     end
   end
 end

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

@@ -1,7 +1,7 @@
 # lib/familia/data_type/types/counter.rb
 
 module Familia
-  class Counter < String
+  class Counter < StringKey
     def initialize(*args)
       super
       @opts[:default] ||= 0