familia 2.0.0.pre15 → 2.0.0.pre17

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/class_methods.rb

@@ -0,0 +1,63 @@
+# lib/familia/data_type/definition.rb
+
+module Familia
+  class DataType
+    # ClassMethods - Class-level DSL methods for defining DataType behavior
+    #
+    # This module is extended into classes that inherit from Familia::DataType,
+    # providing class methods for type registration, configuration, and inheritance.
+    #
+    # Key features:
+    # * Type registration system for creating DataType subclasses
+    # * Database and connection configuration
+    # * Inheritance hooks for propagating settings
+    # * Option validation and filtering
+    #
+    module ClassMethods
+      attr_accessor :parent, :suffix, :prefix, :uri
+      attr_writer :logical_database
+
+      # To be called inside every class that inherits DataType
+      # +methname+ is the term used for the class and instance methods
+      # that are created for the given +klass+ (e.g. set, list, etc)
+      def register(klass, methname)
+        Familia.trace :REGISTER, nil, "[#{self}] Registering #{klass} as #{methname.inspect}" if Familia.debug?
+
+        @registered_types[methname] = klass
+      end
+
+      # Get the registered type class from a given method name
+      # +methname+ is the method name used to register the class (e.g. :set, :list, etc)
+      # Returns the registered class or nil if not found
+      def registered_type(methname)
+        @registered_types[methname]
+      end
+
+      def logical_database(val = nil)
+        @logical_database = val unless val.nil?
+        @logical_database || parent&.logical_database
+      end
+
+      def uri(val = nil)
+        @uri = val unless val.nil?
+        @uri || (parent ? parent.uri : Familia.uri)
+      end
+
+      def inherited(obj)
+        Familia.trace :DATATYPE, nil, "#{obj} is my kinda type" if Familia.debug?
+        obj.logical_database = logical_database
+        obj.default_expiration = default_expiration # method added via Features::Expiration
+        obj.uri = uri
+        super
+      end
+
+      def valid_keys_only(opts)
+        opts.slice(*DataType.valid_options)
+      end
+
+      def relations?
+        @has_related_fields ||= false
+      end
+    end
+  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/connection.rb

@@ -0,0 +1,83 @@
+# lib/familia/data_type/connection.rb
+
+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.
+    #
+    # Key features:
+    # * Database connection resolution with Chain of Responsibility pattern
+    # * Redis key generation based on parent context
+    # * Direct database access for advanced operations
+    #
+    module Connection
+      # TODO: Replace with Chain of Responsibility pattern
+      def dbclient
+        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])
+      end
+
+      # Produces the full dbkey for this object.
+      #
+      # @return [String] The full dbkey.
+      #
+      # This method determines the appropriate dbkey based on the context of the DataType object:
+      #
+      # 1. If a hardcoded key is set in the options, it returns that key.
+      # 2. For instance-level DataType objects, it uses the parent instance's dbkey method.
+      # 3. For class-level DataType objects, it uses the parent class's dbkey method.
+      # 4. For standalone DataType objects, it uses the keystring as the full dbkey.
+      #
+      # For class-level DataType objects (parent_class? == true):
+      # - The suffix is optional and used to differentiate between different types of objects.
+      # - If no suffix is provided, the class's default suffix is used (via the self.suffix method).
+      # - If a nil suffix is explicitly passed, it won't appear in the resulting dbkey.
+      # - Passing nil as the suffix is how class-level DataType objects are created without
+      #   the global default 'object' suffix.
+      #
+      # @example Instance-level DataType
+      #   user_instance.some_datatype.dbkey  # => "user:123:some_datatype"
+      #
+      # @example Class-level DataType
+      #   User.some_datatype.dbkey  # => "user:some_datatype"
+      #
+      # @example Standalone DataType
+      #   DataType.new("mykey").dbkey  # => "mykey"
+      #
+      # @example Class-level DataType with explicit nil suffix
+      #   User.dbkey("123", nil)  # => "user:123"
+      #
+      def dbkey
+        # Return the hardcoded key if it's set. This is useful for
+        # support legacy keys that aren't derived in the same way.
+        return opts[:dbkey] if opts[:dbkey]
+
+        if parent_instance?
+          # This is an instance-level datatype object so the parent instance's
+          # dbkey method is defined in Familia::Horreum::InstanceMethods.
+          parent.dbkey(keystring)
+        elsif parent_class?
+          # This is a class-level datatype object so the parent class' dbkey
+          # method is defined in Familia::Horreum::DefinitionMethods.
+          parent.dbkey(keystring, nil)
+        else
+          # This is a standalone DataType object where it's keystring
+          # is the full database key (dbkey).
+          keystring
+        end
+      end
+
+      # 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.
+      def direct_access
+        yield(dbclient, dbkey)
+      end
+    end
+  end
+end