familia 2.0.0.pre15 → 2.0.0.pre16

data/lib/familia/connection/operations.rb

@@ -0,0 +1,277 @@
+# lib/familia/connection/operations.rb
+
+# Familia
+#
+# A family warehouse for your keystore data.
+#
+module Familia
+  module Connection
+    module Operations
+      # 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 |
+      #
+      # Executes a Redis transaction (MULTI/EXEC) with proper connection handling.
+      #
+      # Provides atomic execution of multiple Redis commands with automatic connection
+      # management and operation mode enforcement. Returns a MultiResult object containing
+      # both success status and command results.
+      #
+      # @param [Proc] block The block containing Redis commands to execute atomically
+      # @yield [Redis] conn The Redis connection configured for transaction mode
+      # @return [MultiResult] Result object with success status and command results
+      #
+      # @raise [Familia::OperationModeError] When called with incompatible connection handlers
+      #   (e.g., FiberConnectionHandler or DefaultConnectionHandler that don't support transactions)
+      #
+      # @example Basic transaction usage
+      #   result = Familia.transaction do |conn|
+      #     conn.set('key1', 'value1')
+      #     conn.set('key2', 'value2')
+      #     conn.get('key1')
+      #   end
+      #   result.successful?    # => true (if all commands succeeded)
+      #   result.results        # => ["OK", "OK", "value1"]
+      #   result.results.first  # => "OK"
+      #
+      # @example Checking transaction success
+      #   result = Familia.transaction do |conn|
+      #     conn.incr('counter')
+      #     conn.decr('other_counter')
+      #   end
+      #
+      #   if result.successful?
+      #     puts "All commands succeeded: #{result.results}"
+      #   else
+      #     puts "Some commands failed: #{result.results}"
+      #   end
+      #
+      # @example Nested transactions (reentrant behavior)
+      #   result = Familia.transaction do |outer_conn|
+      #     outer_conn.set('outer', 'value')
+      #
+      #     # Nested transaction reuses the same connection
+      #     inner_result = Familia.transaction do |inner_conn|
+      #       inner_conn.set('inner', 'value')
+      #       inner_conn.get('inner')  # Returns the value directly in nested context
+      #     end
+      #
+      #     [outer_result, inner_result]
+      #   end
+      #
+      # @note Connection Handler Compatibility:
+      #   - FiberTransactionHandler: Supports reentrant transactions
+      #   - ProviderConnectionHandler: Full transaction support
+      #   - CreateConnectionHandler: Full transaction support
+      #   - FiberConnectionHandler: Blocked (raises OperationModeError)
+      #   - DefaultConnectionHandler: Blocked (raises OperationModeError)
+      #
+      # @note Thread Safety:
+      #   Uses Fiber-local storage to maintain transaction context across nested calls
+      #   and ensure proper cleanup even when exceptions occur.
+      #
+      # @see MultiResult For details on the return value structure
+      # @see Familia.pipelined For non-atomic command batching
+      # @see #batch_update For similar MultiResult pattern in Horreum models
+      def transaction(&)
+        Familia::Connection::TransactionCore.execute_transaction(-> { dbclient }, &)
+      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.pipelined 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.pipelined 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
+      #
+      # Executes Redis commands in a pipeline for improved performance.
+      #
+      # Batches multiple Redis commands together and sends them in a single network
+      # round-trip, improving performance for multiple independent operations. Returns
+      # a MultiResult object containing both success status and command results.
+      #
+      # @param [Proc] block The block containing Redis commands to execute in pipeline
+      # @yield [Redis] conn The Redis connection configured for pipelined mode
+      # @return [MultiResult] Result object with success status and command results
+      #
+      # @raise [Familia::OperationModeError] When called with incompatible connection handlers
+      #   (e.g., FiberConnectionHandler or DefaultConnectionHandler that don't support pipelines)
+      #
+      # @example Basic pipeline usage
+      #   result = Familia.pipelined do |conn|
+      #     conn.set('key1', 'value1')
+      #     conn.set('key2', 'value2')
+      #     conn.get('key1')
+      #     conn.incr('counter')
+      #   end
+      #   result.successful?    # => true (if all commands succeeded)
+      #   result.results        # => ["OK", "OK", "value1", 1]
+      #   result.results.length # => 4
+      #
+      # @example Performance optimization with pipeline
+      #   # Instead of multiple round-trips:
+      #   # value1 = redis.get('key1')  # Round-trip 1
+      #   # value2 = redis.get('key2')  # Round-trip 2
+      #   # value3 = redis.get('key3')  # Round-trip 3
+      #
+      #   # Use pipeline for single round-trip:
+      #   result = Familia.pipelined do |conn|
+      #     conn.get('key1')
+      #     conn.get('key2')
+      #     conn.get('key3')
+      #   end
+      #   values = result.results  # => ["value1", "value2", "value3"]
+      #
+      # @example Checking pipeline success
+      #   result = Familia.pipelined do |conn|
+      #     conn.set('temp_key', 'temp_value')
+      #     conn.expire('temp_key', 60)
+      #     conn.get('temp_key')
+      #   end
+      #
+      #   if result.successful?
+      #     puts "Pipeline completed: #{result.results}"
+      #   else
+      #     puts "Some operations failed: #{result.results}"
+      #   end
+      #
+      # @example Nested pipelines (reentrant behavior)
+      #   result = Familia.pipelined do |outer_conn|
+      #     outer_conn.set('outer', 'value')
+      #
+      #     # Nested pipeline reuses the same connection
+      #     inner_result = Familia.pipelined do |inner_conn|
+      #       inner_conn.get('outer')  # Returns Redis::Future in nested context
+      #     end
+      #
+      #     outer_conn.get('outer')
+      #   end
+      #
+      # @note Pipeline vs Transaction Differences:
+      #   - Pipeline: Commands executed independently, some may succeed while others fail
+      #   - Transaction: All-or-nothing execution, commands are atomic as a group
+      #   - Pipeline: Better performance for independent operations
+      #   - Transaction: Better consistency for related operations
+      #
+      # @note Connection Handler Compatibility:
+      #   - ProviderConnectionHandler: Full pipeline support
+      #   - CreateConnectionHandler: Full pipeline support
+      #   - FiberTransactionHandler: Blocked (raises OperationModeError)
+      #   - FiberConnectionHandler: Blocked (raises OperationModeError)
+      #   - DefaultConnectionHandler: Blocked (raises OperationModeError)
+      #
+      # @note Thread Safety:
+      #   Uses Fiber-local storage to maintain pipeline context across nested calls
+      #   and ensure proper cleanup even when exceptions occur.
+      #
+      # @see MultiResult For details on the return value structure
+      # @see Familia.transaction For atomic command execution
+      # @see #batch_update For similar MultiResult pattern in Horreum models
+      def pipelined(&block)
+        PipelineCore.execute_pipeline(-> { dbclient }, &block)
+      end
+      alias pipeline pipelined
+
+      # 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_dbclient for custom operations
+      #   Familia.with_dbclient do |conn|
+      #     conn.set("custom_key", "value")
+      #     conn.expire("custom_key", 3600)
+      #   end
+      #
+      def with_dbclient(&)
+        yield dbclient
+      end
+
+      # Provides explicit access to an isolated Database connection for temporary operations.
+      #
+      # This method creates a new connection that won't interfere with the cached
+      # connection pool, executes the given block with that connection, and ensures
+      # the connection is properly closed afterward.
+      #
+      # Perfect for database scanning, inspection, or migration operations where
+      # you need to access different databases without affecting your models'
+      # normal connections.
+      #
+      # @param uri [String, URI, Integer, nil] The URI or database number to connect to.
+      # @yield [Redis] An isolated Database connection
+      # @return The result of the block
+      #
+      # @example Safely scanning for legacy data
+      #   Familia.with_isolated_dbclient(5) do |conn|
+      #     conn.keys("session:*")
+      #   end
+      #
+      # @example Performing migration tasks
+      #   Familia.with_isolated_dbclient(1) do |conn|
+      #     conn.scan_each(match: "user:*") { |key| puts key }
+      #   end
+      #
+      def with_isolated_dbclient(uri = nil, &)
+        client = isolated_dbclient(uri)
+        begin
+          yield client
+        ensure
+          client&.close
+        end
+      end
+    end
+  end
+end

data/lib/familia/connection/pipeline_core.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+module Familia
+  module Connection
+    # Pipeline execution with configurable fallback behavior
+    #
+    # Handles two pipeline scenarios based on connection handler capabilities:
+    # 1. Normal pipeline when handler supports pipelines
+    # 2. Individual command execution with configurable error/warn/silent modes
+    #
+    # @see OperationCore For shared fallback logic
+    # @see TransactionCore For similar transaction handling
+    #
+    module PipelineCore
+      # Executes a pipeline with configurable fallback behavior
+      #
+      # Handles pipeline execution based on connection handler capabilities.
+      # When handler doesn't support pipelines, fallback behavior is controlled
+      # by Familia.pipeline_mode setting.
+      #
+      # @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
+      # @yield [Redis] Redis connection or proxy for command execution
+      #
+      # @example Basic usage
+      #   result = PipelineCore.execute_pipeline(-> { dbclient }) do |conn|
+      #     conn.set('key1', 'value1')
+      #     conn.incr('counter')
+      #   end
+      #   result.successful?  # => true/false
+      #   result.results     # => ["OK", 1]
+      #
+      # @example With fallback modes
+      #   Familia.configure { |c| c.pipeline_mode = :permissive }
+      #   result = PipelineCore.execute_pipeline(-> { cached_conn }) do |conn|
+      #     conn.set('key', 'value')  # Executes individually, no error
+      #   end
+      #
+      def self.execute_pipeline(dbclient_proc, &block)
+        # First, get the connection to populate the handler class
+        connection = dbclient_proc.call
+        handler_class = Fiber[:familia_connection_handler_class]
+
+        # Check pipeline capability
+        pipeline_capability = handler_class&.allows_pipelined
+
+        if pipeline_capability == false
+          OperationCore.handle_fallback(:pipeline, dbclient_proc, handler_class, &block)
+        else
+          # Normal pipeline flow (includes nil, true, and other values)
+          execute_normal_pipeline(dbclient_proc, &block)
+        end
+      end
+
+      private
+
+      # Executes a normal Redis pipeline
+      #
+      # Handles proper Fiber-local state management and cleanup in ensure blocks.
+      # Manages nested pipeline contexts by checking for existing pipeline state.
+      #
+      # @param dbclient_proc [Proc] Lambda that returns the Redis connection
+      # @param block [Proc] Block containing Redis commands to execute
+      # @return [MultiResult] Result object with pipeline command results
+      #
+      def self.execute_normal_pipeline(dbclient_proc, &block)
+        # Check for existing pipeline context
+        return yield(Fiber[:familia_pipeline]) if Fiber[:familia_pipeline]
+
+        command_return_values = dbclient_proc.call.pipelined do |conn|
+          Fiber[:familia_pipeline] = conn
+          begin
+            yield(conn)
+          ensure
+            Fiber[:familia_pipeline] = nil
+          end
+        end
+
+        # Return same MultiResult format as other methods
+        # Pipeline success is true if no exceptions occurred (all commands executed)
+        summary_boolean = command_return_values.none? { |ret| ret.is_a?(Exception) }
+        MultiResult.new(summary_boolean, command_return_values)
+      end
+    end
+  end
+end

data/lib/familia/connection/transaction_core.rb

@@ -0,0 +1,100 @@
+# lib/familia/connection/transaction_core.rb
+
+module Familia
+  module Connection
+    # Core transaction logic shared between global and instance transaction methods
+    #
+    # This module provides unified transaction handling with configurable fallback
+    # behavior when transactions are unavailable due to connection handler constraints.
+    # Eliminates code duplication between Operations and Horreum Connection modules.
+    #
+    # @example Usage in transaction methods
+    #   def transaction(&block)
+    #     TransactionCore.execute_transaction(-> { dbclient }, &block)
+    #   end
+    #
+    module TransactionCore
+      # Executes a transaction with configurable fallback behavior
+      #
+      # Handles three transaction scenarios based on connection handler capabilities:
+      # 1. Normal transaction (MULTI/EXEC) when handler supports transactions
+      # 2. Reentrant transaction when already within a transaction context
+      # 3. Individual command execution with configurable error/warn/silent modes
+      #
+      # @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
+      # @yield [Redis] Redis connection or proxy for command execution
+      #
+      # @example Basic usage
+      #   result = TransactionCore.execute_transaction(-> { dbclient }) do |conn|
+      #     conn.set('key1', 'value1')
+      #     conn.incr('counter')
+      #   end
+      #   result.successful?  # => true/false
+      #   result.results     # => ["OK", 1]
+      #
+      def self.execute_transaction(dbclient_proc, &block)
+        # First, get the connection to populate the handler class
+        connection = 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)
+        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)
+        end
+      end
+
+      private
+
+      # Handles transaction fallback based on configured transaction mode
+      #
+      # Delegates to OperationCore.handle_fallback for consistent behavior
+      # across transaction and pipeline operations.
+      #
+      # @param dbclient_proc [Proc] Lambda that returns the Redis connection
+      # @param handler_class [Class] The connection handler class that blocked transaction
+      # @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)
+      end
+
+      # Executes a normal Redis transaction using MULTI/EXEC
+      #
+      # Handles the standard transaction flow including nested transaction detection,
+      # proper Fiber-local state management, and cleanup in ensure blocks.
+      #
+      # @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)
+        # Check for existing transaction context
+        return yield(Fiber[:familia_transaction]) if Fiber[:familia_transaction]
+
+        command_return_values = dbclient_proc.call.multi do |conn|
+          Fiber[:familia_transaction] = conn
+          begin
+            yield(conn)
+          ensure
+            Fiber[:familia_transaction] = nil
+          end
+        end
+
+        # Return same MultiResult format as other methods
+        summary_boolean = command_return_values.all? { |ret| %w[OK 0 1].include?(ret.to_s) }
+        MultiResult.new(summary_boolean, command_return_values)
+      end
+    end
+  end
+end