familia 2.0.0.pre15 → 2.0.0.pre17

data/lib/familia/connection/handlers.rb

@@ -0,0 +1,223 @@
+# lib/familia/connection/handlers.rb
+
+# Familia
+#
+# A family warehouse for your keystore data.
+#
+module Familia
+  module Connection
+    # Manages ordered chain of connection handlers
+    #
+    # NOTE: It is important that the last handler in a responsibility chain
+    # either always provides a connection or raises an error. Otherwise the
+    # end result will simply be `nil` without any guidance to the caller.
+    #
+    class ResponsibilityChain
+      def initialize
+        @handlers = []
+      end
+
+      def add_handler(handler)
+        @handlers << handler
+        self
+      end
+
+      def handle(uri)
+        @handlers.each do |handler|
+          connection = handler.handle(uri)
+          if connection
+            Fiber[:familia_connection_handler_class] = handler.class
+            return connection
+          end
+        end
+
+        # If we get here, no handler provided a connection
+        nil
+      end
+    end
+
+    # Connection handler base class for Chain of Responsibility pattern.
+    # When no arguments are passed, all behaviour is based on the top
+    # Familia module itself. e.g. Familia.create_dbclient.
+    #
+    # Summary of Behaviors
+    #
+    #   | Handler | Transaction | Pipeline | Ad-hoc Commands |
+    #   |---------|------------|----------|-----------------|
+    #   | **FiberTransaction** | Reentrant (same conn) | Error | Use transaction conn |
+    #   | **FiberConnection** | Error | Error | ✓ Allowed |
+    #   | **Provider** | ✓ New checkout | ✓ New checkout | ✓ New checkout |
+    #   | **Default** | ✓ With guards | ✓ With guards | ✓ Check mode |
+    #   | **Create** | ✓ Fresh conn | ✓ Fresh conn | ✓ Fresh conn |
+    #
+    # NOTE: Every subclass must provide values for the @allows_transaction
+    # and @allows_pipelined attributes.
+    #
+    class BaseConnectionHandler
+      @allows_transaction = true
+      @allows_pipelined = true
+
+      class << self
+        attr_reader :allows_transaction, :allows_pipelined
+      end
+
+      def initialize(familia_module = nil)
+        @familia_module = familia_module || Familia
+      end
+
+      def handle(uri)
+        raise NotImplementedError, 'Subclasses must implement handle'
+      end
+    end
+
+    # Creates new connections directly, with no caching of any kind. If
+    # the make it to here in the chain, it'll create a new connection
+    # every time.
+    #
+    # Fresh connection each time - all operations safe (transactions,
+    # pipelined, ad-hoc)
+    #
+    class CreateConnectionHandler < BaseConnectionHandler
+      @allows_transaction = true
+      @allows_pipelined = true
+
+      def handle(uri)
+        # Create new connection (no module-level caching)
+        parsed_uri = @familia_module.normalize_uri(uri)
+        client = @familia_module.create_dbclient(parsed_uri)
+        Familia.trace :DBCLIENT_DEFAULT, nil, "Created new connection for #{parsed_uri.serverid}"
+        client
+      end
+    end
+    DefaultConnectionHandler = CreateConnectionHandler
+
+    # Delegates to user-defined connection provider
+    #
+    # Provider pattern = full flexibility. Use ad-hoc, operations, whatever you
+    # like. For each connection, choose one and then get another connection.
+    # Rapid-fire sub ms connection pool connection checkouts are all good
+    # and also expected how they are to be used.
+    # This is where connection pools live
+    #
+    class ProviderConnectionHandler < BaseConnectionHandler
+      @allows_transaction = true
+      @allows_pipelined = true
+
+      def handle(uri)
+        return nil unless @familia_module.connection_provider
+
+        @familia_module.trace :DBCLIENT_PROVIDER, nil, 'Using connection provider'
+
+        # Determine the correct URI including logical database if needed
+        if uri.nil? && @familia_module.respond_to?(:logical_database) && @familia_module.logical_database
+          uri = @familia_module.logical_database
+        end
+
+        # Always pass normalized URI with database to provider
+        # Provider MUST return connection already on the correct database
+        parsed_uri = @familia_module.normalize_uri(uri)
+        @familia_module.connection_provider.call(parsed_uri.to_s)
+      end
+    end
+
+    # Checks for fiber-local connections with version validation
+    #
+    # Strict Ad-hoc Only. Raise error for transaction, pipeline etc operations.
+    #
+    #     # Enforce middleware connection constraints
+    #     case request.operation
+    #     when :transaction
+    #       raise Familia::MiddlewareConnectionError,
+    #         "Cannot start transaction on middleware-provided connection. " \
+    #         "Middleware connections are for ad-hoc commands only."
+    #     when :pipeline
+    #       raise Familia::MiddlewareConnectionError,
+    #         "Cannot start pipeline on middleware-provided connection. " \
+    #         "Middleware connections are for ad-hoc commands only."
+    #     when :command, nil
+    #       # Ad-hoc commands are fine
+    #       conn
+    #     else
+    #       raise "Unknown operation: #{request.operation}"
+    #     end
+    #
+    class FiberConnectionHandler < BaseConnectionHandler
+      @allows_transaction = false
+      @allows_pipelined = false
+
+      def handle(uri)
+        return nil unless Fiber[:familia_connection]
+
+        conn, version = Fiber[:familia_connection]
+        if version == @familia_module.middleware_version
+          @familia_module.trace :DBCLIENT_FIBER, nil, "Using fiber-local connection for #{uri}"
+          conn
+        else
+          # Version mismatch, clear stale connection
+          Fiber[:familia_connection] = nil
+          @familia_module.trace :DBCLIENT_FIBER, nil, 'Cleared stale fiber connection (version mismatch)'
+          nil
+        end
+      end
+    end
+
+    # Checks for fiber-local transaction connections (highest priority for Horreum)
+    #
+    # Key insight: Mark that we're in reentrant mode and also track of
+    # depth. This allows nested transaction calls to be safely reentrant
+    # without breaking Redis's single-level MULTI/EXEC.
+    #
+    # Reentrant transaction - just yield the existing connection
+    # No new MULTI/EXEC, just participate in existing transaction
+    # Fiber[:familia_transaction_depth] ||= 0
+    # Fiber[:familia_transaction_depth] += 1
+    #
+    class FiberTransactionHandler < BaseConnectionHandler
+      @allows_transaction = :reentrant
+      @allows_pipelined = false
+
+      # Singleton pattern for stateless handler
+      @instance = new.freeze
+
+      def self.instance
+        @instance
+      end
+
+      def handle(_uri)
+        return nil unless Fiber[:familia_transaction]
+
+        Familia.trace :DBCLIENT_FIBER_TRANSACTION, nil, 'Using fiber-local transaction connection'
+        Fiber[:familia_transaction]
+      end
+    end
+
+    # Checks for a dbclient class instance variable with a cached client instance
+    #
+    # This works on any module, class, or instance that implements has a
+    # dbclient method. From a Horreum model instance, if you call
+    # CachedConnectionHandler.new(self) it'll return self.dbclient or
+    # nil, or you can call CachedConnectionHandler(self.class) and it'll
+    # attempt the same using the model's class.
+    #
+    # +familia_module+ is required.
+    #
+    # CachedConnectionHandler - Single cached connection - block all multi-mode operations
+    #
+    class CachedConnectionHandler < BaseConnectionHandler
+      @allows_transaction = false
+      @allows_pipelined = false
+
+      def initialize(familia_module)
+        @familia_module = familia_module
+      end
+
+      def handle(_uri)
+        dbclient = @familia_module.instance_variable_get(:@dbclient)
+        return nil unless dbclient
+
+        Familia.trace :DBCLIENT_INSTVAL_OVERRIDE, nil, "Using @dbclient from #{@familia_module.class}"
+        dbclient
+      end
+    end
+  end
+end

data/lib/familia/connection/individual_command_proxy.rb

@@ -0,0 +1,64 @@
+# lib/familia/connection/individual_command_proxy.rb
+
+module Familia
+  module Connection
+    # Proxy class that executes Redis commands individually instead of in a transaction
+    #
+    # This class intercepts Redis method calls and executes them immediately against
+    # the underlying connection, collecting results as if they were part of a transaction.
+    # Used as a fallback when transaction mode is unavailable but graceful degradation
+    # is preferred over raising an error.
+    #
+    # @example Usage in transaction fallback
+    #   conn = dbclient
+    #   proxy = IndividualCommandProxy.new(conn)
+    #
+    #   proxy.set('key1', 'value1')  # Executes immediately
+    #   proxy.incr('counter')        # Executes immediately
+    #   proxy.get('key1')           # Executes immediately
+    #
+    #   results = proxy.collected_results  # => ["OK", 1, "value1"]
+    #
+    class IndividualCommandProxy
+      attr_reader :collected_results
+
+      def initialize(redis_connection)
+        @connection = redis_connection
+        @collected_results = []
+      end
+
+      # Intercepts Redis method calls and executes them immediately
+      #
+      # @param method_name [Symbol] The Redis method being called
+      # @param args [Array] Arguments passed to the Redis method
+      # @param kwargs [Hash] Keyword arguments passed to the Redis method
+      # @param block [Proc] Block passed to the Redis method
+      # @return The result of the Redis command execution
+      #
+      def method_missing(method_name, *args, **kwargs, &block)
+        if @connection.respond_to?(method_name)
+          result = @connection.public_send(method_name, *args, **kwargs, &block)
+          @collected_results << result
+          result
+        else
+          super
+        end
+      end
+
+      def respond_to_missing?(method_name, include_private = false)
+        @connection.respond_to?(method_name, include_private) || super
+      end
+
+      # Returns debug information about the proxy state
+      #
+      # @return [Hash] Debug information including connection class and result count
+      def debug_info
+        {
+          connection_class: @connection.class.name,
+          results_count: @collected_results.size,
+          results: @collected_results.dup
+        }
+      end
+    end
+  end
+end

data/lib/familia/connection/middleware.rb

@@ -0,0 +1,75 @@
+# lib/familia/connection/middleware.rb
+
+require_relative '../../middleware/database_middleware'
+
+module Familia
+  module Connection
+    module Middleware
+      # @return [Boolean] Whether Database command logging is enabled
+      attr_reader :enable_database_logging
+
+      # @return [Boolean] Whether Database command counter is enabled
+      attr_reader :enable_database_counter
+
+      # @return [Integer] Current middleware version for cache invalidation
+      def middleware_version
+        @middleware_version
+      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}" if Familia.debug?
+      end
+
+      # Sets a versioned fiber-local connection
+      def set_fiber_connection(connection)
+        Fiber[:familia_connection] = [connection, middleware_version]
+        Familia.trace :FIBER_CONNECTION, nil, "Set with version #{middleware_version}" if Familia.debug?
+      end
+
+      # Clears the fiber-local connection
+      def clear_fiber_connection!
+        Fiber[:familia_connection] = nil
+        Familia.trace :FIBER_CONNECTION, nil, 'Cleared' if Familia.debug?
+      end
+
+      # Sets whether Database command logging is enabled
+      # Registers middleware immediately when enabled
+      def enable_database_logging=(value)
+        @enable_database_logging = value
+        register_middleware_once if value
+        increment_middleware_version! if value
+      end
+
+      # Sets whether Database command counter is enabled
+      # Registers middleware immediately when enabled
+      def enable_database_counter=(value)
+        @enable_database_counter = value
+        register_middleware_once if value
+        increment_middleware_version! if value
+      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
+        return if @middleware_registered
+
+        if Familia.enable_database_logging
+          DatabaseLogger.logger = Familia.logger
+          RedisClient.register(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)
+        end
+
+        @middleware_registered = true
+      end
+    end
+  end
+end

data/lib/familia/connection/operation_core.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+module Familia
+  module Connection
+    # Shared logic for transaction and pipeline operation fallback handling
+    #
+    # Provides configurable fallback behavior when connection handlers don't
+    # support specific operation modes (transaction/pipeline).
+    #
+    module OperationCore
+      # Handles operation fallback based on configured mode
+      #
+      # @param operation_type [Symbol] Either :transaction or :pipeline
+      # @param dbclient_proc [Proc] Lambda that returns the Redis connection
+      # @param handler_class [Class] The connection handler that blocked operation
+      # @param block [Proc] Block containing Redis commands to execute
+      # @return [MultiResult] Result from individual command execution or raises error
+      #
+      def self.handle_fallback(operation_type, dbclient_proc, handler_class, &block)
+        mode = get_operation_mode(operation_type)
+
+        case mode
+        when :strict
+          raise Familia::OperationModeError,
+                "Cannot start #{operation_type} with #{handler_class.name} connection. Use connection pools."
+        when :warn
+          log_fallback_warning(operation_type, handler_class)
+          execute_individual_commands(dbclient_proc, &block)
+        when :permissive
+          execute_individual_commands(dbclient_proc, &block)
+        else
+          # Default to strict mode if invalid setting
+          raise Familia::OperationModeError,
+                "Cannot start #{operation_type} with #{handler_class.name} connection. Use connection pools."
+        end
+      end
+
+      # Gets the configured mode for the operation type
+      #
+      # @param operation_type [Symbol] Either :transaction or :pipeline
+      # @return [Symbol] The configured mode (:strict, :warn, :permissive)
+      #
+      def self.get_operation_mode(operation_type)
+        case operation_type
+        when :transaction
+          Familia.transaction_mode
+        when :pipeline
+          Familia.pipeline_mode
+        else
+          :strict
+        end
+      end
+
+      # Logs fallback warning message
+      #
+      # @param operation_type [Symbol] Either :transaction or :pipeline
+      # @param handler_class [Class] The connection handler class
+      #
+      def self.log_fallback_warning(operation_type, handler_class)
+        message = "#{operation_type.capitalize} unavailable with #{handler_class.name}. Using individual commands."
+
+        if Familia.respond_to?(:logger) && Familia.logger
+          Familia.logger.warn message
+        else
+          warn message
+        end
+      end
+
+      # Executes commands individually using a proxy that collects results
+      #
+      # Creates an IndividualCommandProxy that executes each Redis command immediately
+      # instead of queuing them in a transaction or pipeline. Results are collected to
+      # maintain the same interface as normal operations.
+      #
+      # @param dbclient_proc [Proc] Lambda that returns the Redis connection
+      # @param block [Proc] Block containing Redis commands to execute
+      # @return [MultiResult] Result object with collected command results
+      #
+      def self.execute_individual_commands(dbclient_proc, &block)
+        conn = dbclient_proc.call
+        proxy = IndividualCommandProxy.new(conn)
+
+        # Execute the block with the proxy
+        block.call(proxy)
+
+        # Return MultiResult format for consistency
+        results = proxy.collected_results
+        summary_boolean = results.all? { |ret| !ret.is_a?(Exception) }
+        MultiResult.new(summary_boolean, results)
+      end
+    end
+  end
+end