familia 2.0.0.pre15 → 2.0.0.pre17

data/lib/{familia/multi_result.rb → multi_result.rb}

@@ -1,30 +1,29 @@
-# lib/familia/multi_result.rb
+# lib/multi_result.rb
 
-# The magical MultiResult, keeper of Redis's deepest secrets!
+# Represents the result of a Valkey/Redis transaction operation.
 #
-# This quirky little class wraps up the outcome of a Database "transaction"
-# (or as I like to call it, a "Database dance party") with a bow made of
-# pure Ruby delight. It knows if your commands were successful and
-# keeps the results safe in its pocket dimension.
+# This class encapsulates the outcome of a Database transaction,
+# providing access to both the success status and the individual
+# command results returned by the transaction.
 #
-# @attr_reader success [Boolean] The golden ticket! True if all your
-#   Database wishes came true in the transaction.
-# @attr_reader results [Array<String>] A mystical array of return values,
-#   each one a whisper from the Database gods.
+# @attr_reader success [Boolean] Indicates whether all commands
+#   in the transaction completed successfully.
+# @attr_reader results [Array<String>] Array of return values
+#   from the Database commands executed in the transaction.
 #
-# @example Summoning a MultiResult from the void
+# @example Creating a MultiResult instance
 #   result = MultiResult.new(true, ["OK", "OK"])
 #
-# @example Divining the success of your Database ritual
+# @example Checking transaction success
 #   if result.successful?
-#     puts "Huzzah! The Database spirits smile upon you!"
+#     puts "Transaction completed successfully"
 #   else
-#     puts "Alas! The Database gremlins have conspired against us!"
+#     puts "Transaction failed"
 #   end
 #
-# @example Peering into the raw essence of results
+# @example Accessing individual command results
 #   result.results.each_with_index do |value, index|
-#     puts "Command #{index + 1} whispered back: #{value}"
+#     puts "Command #{index + 1} returned: #{value}"
 #   end
 #
 class MultiResult
@@ -58,6 +57,13 @@ class MultiResult
   end
   alias to_a tuple
 
+  # Returns the number of results in the multi-operation.
+  #
+  # @return [Integer] The number of individual command results returned by the transaction.
+  def size
+    results.size
+  end
+
   def to_h
     { success: successful?, results: results }
   end
@@ -69,4 +75,5 @@ class MultiResult
     @success
   end
   alias success? successful?
+  alias areyouhappynow? successful?
 end

data/try/configuration/scenarios_try.rb

@@ -24,11 +24,11 @@ rescue StandardError => e
 end
 #=> false
 
-## custom Redis URI configuration doesn't always work
+## custom Valkey/Redis URI configuration doesn't always work
 begin
   # Test with custom URI
   original_uri = Familia.uri
-  test_uri = 'redis://localhost:6379/10'
+  test_uri = 'redis://localhost:2525/10'
 
   Familia.uri = test_uri
   current_uri = Familia.uri

data/try/connection/fiber_context_preservation_try.rb

@@ -0,0 +1,250 @@
+# Fiber Context Preservation Tryouts
+#
+# Tests that verify the removal of previous_conn preservation logic
+# in transaction and pipelined methods is safe with the new operation
+# guard system. The operation guards prevent unsafe handlers from
+# reaching the transaction/pipeline blocks, making fiber preservation
+# redundant and safe to remove.
+#
+# Key scenarios tested:
+# - Transaction/pipeline blocks don't interfere with safe handlers
+# - Fiber context is properly managed without manual preservation
+# - Operation guards prevent unsafe scenarios before fiber issues arise
+# - Method aliases work correctly
+
+require_relative '../helpers/test_helpers'
+
+## Transaction method works without previous_conn preservation
+customer = Customer.new(custid: 'tx_test')
+original_fiber_conn = Fiber[:familia_connection]
+
+# Test transaction execution
+result = Familia.transaction do |conn|
+  conn.set('familia:tx_test', 'transaction_success')
+  conn.get('familia:tx_test')
+end
+
+# Verify transaction succeeded and fiber state is clean
+transaction_worked = result.results.last == 'transaction_success'
+fiber_state_clean = Fiber[:familia_connection] == original_fiber_conn
+transaction_worked && fiber_state_clean
+#=> true
+
+## Pipelined method works without previous_conn preservation
+original_fiber_conn = Fiber[:familia_connection]
+
+# Test pipeline execution
+result = Familia.pipelined do |conn|
+  conn.set('familia:pipe_test', 'pipeline_success')
+  conn.get('familia:pipe_test')
+end
+
+# Verify pipeline succeeded and fiber state is clean
+pipeline_worked = result.results.last == 'pipeline_success'
+fiber_state_clean = Fiber[:familia_connection] == original_fiber_conn
+pipeline_worked && fiber_state_clean
+#=> true
+
+## Transaction method cleans up fiber context on success
+Fiber[:familia_transaction]
+#=> nil
+
+## Pipelined method cleans up fiber context on success
+Fiber[:familia_pipeline]
+#=> nil
+
+## Transaction method cleans up fiber context on exception
+begin
+  Familia.transaction do |conn|
+    conn.set('test', 'value')
+    raise StandardError, 'test error'
+  end
+rescue StandardError
+  # Expected error
+end
+
+# Fiber should be clean even after exception
+Fiber[:familia_transaction]
+#=> nil
+
+## Pipelined method cleans up fiber context on exception
+begin
+  Familia.pipelined do |conn|
+    conn.set('test', 'value')
+    raise StandardError, 'test error'
+  end
+rescue StandardError
+  # Expected error
+end
+
+# Fiber should be clean even after exception
+Fiber[:familia_pipeline]
+#=> nil
+
+## Nested transactions work with reentrant handler
+result = Familia.transaction do |outer_conn|
+  outer_value = outer_conn.set('outer', 'outer_value')
+
+  inner_result = Familia.transaction do |inner_conn|
+    inner_conn.set('inner', 'inner_value')
+    inner_conn.get('inner')
+  end
+
+  [outer_value, inner_result]
+end
+
+# Both outer and inner operations should succeed
+result.results.first == 'OK' && result.results.last == 'inner_value'
+#=> true
+
+## Safe handlers don't trigger preservation logic
+# Test with CreateConnectionHandler (fresh connections)
+customer = Customer.new(custid: 'safe_test')
+
+# Transaction should work normally
+tx_result = customer.transaction do |conn|
+  conn.set(customer.dbkey('tx_field'), 'tx_value')
+end
+
+# Pipeline should work normally
+pipe_result = customer.pipelined do |conn|
+  conn.set(customer.dbkey('pipe_field'), 'pipe_value')
+end
+
+tx_result.results.first == 'OK' && pipe_result.results.first == 'OK'
+#=> true
+
+## Connection provider works with transactions and pipelines
+original_provider = Familia.connection_provider
+Familia.connection_provider = ->(uri) { Redis.new(url: uri) }
+
+begin
+  customer = Customer.new(custid: 'provider_test')
+
+  # Transaction with provider
+  tx_result = customer.transaction do |conn|
+    conn.set('provider:tx', 'tx_success')
+    conn.get('provider:tx')
+  end
+
+  # Pipeline with provider
+  pipe_result = customer.pipelined do |conn|
+    conn.set('provider:pipe', 'pipe_success')
+    conn.get('provider:pipe')
+  end
+
+  tx_result.results.last == 'tx_success' && pipe_result.results.last == 'pipe_success'
+ensure
+  Familia.connection_provider = original_provider
+end
+#=> true
+
+## Operation guards prevent fiber issues before they occur
+# FiberConnectionHandler blocks transactions before fiber interference
+begin
+  # Set strict mode to ensure OperationModeError is raised
+  original_mode = Familia.transaction_mode
+  Familia.configure { |config| config.transaction_mode = :strict }
+
+  Fiber[:familia_connection] = [Customer.create_dbclient, Familia.middleware_version]
+  Fiber[:familia_connection_handler_class] = Familia::Connection::FiberConnectionHandler
+
+  customer = Customer.new
+  customer.transaction { |conn| conn.set('should_not_execute', 'value') }
+  false
+rescue Familia::OperationModeError => e
+  # Operation was blocked - no fiber interference possible
+  e.message.include?('FiberConnectionHandler')
+ensure
+  Fiber[:familia_connection] = nil
+  Fiber[:familia_connection_handler_class] = nil
+  # Restore original mode
+  Familia.configure { |config| config.transaction_mode = original_mode }
+end
+#=> true
+
+## Operation guards prevent pipeline fiber issues before they occur
+begin
+  # Ensure we're in strict mode for this test
+  Familia.configure { |config| config.pipeline_mode = :strict }
+
+  Fiber[:familia_connection] = [Customer.create_dbclient, Familia.middleware_version]
+  Fiber[:familia_connection_handler_class] = Familia::Connection::FiberConnectionHandler
+
+  customer = Customer.new
+  customer.pipelined { |conn| conn.set('should_not_execute', 'value') }
+  false
+rescue Familia::OperationModeError => e
+  # Operation was blocked - no fiber interference possible
+  e.message.include?('FiberConnectionHandler')
+ensure
+  Fiber[:familia_connection] = nil
+  Fiber[:familia_connection_handler_class] = nil
+end
+#=> true
+
+## Method aliases work correctly
+# pipeline alias for pipelined
+result1 = Familia.pipeline do |conn|
+  conn.set('alias_test', 'alias_success')
+  conn.get('alias_test')
+end
+
+# pipelined method
+result2 = Familia.pipelined do |conn|
+  conn.set('alias_test2', 'alias_success2')
+  conn.get('alias_test2')
+end
+
+result1.results.last == 'alias_success' && result2.results.last == 'alias_success2'
+#=> true
+
+## Horreum instance method aliases work correctly
+customer = Customer.new(custid: 'alias_test')
+
+# pipeline alias
+result1 = customer.pipeline do |conn|
+  conn.set('horreum:alias1', 'success1')
+  conn.get('horreum:alias1')
+end
+
+# pipelined method
+result2 = customer.pipelined do |conn|
+  conn.set('horreum:alias2', 'success2')
+  conn.get('horreum:alias2')
+end
+
+result1.results.last == 'success1' && result2.results.last == 'success2'
+#=> true
+
+## Fiber context remains isolated per operation
+# Set up initial fiber state
+initial_connection = Customer.create_dbclient
+Fiber[:test_marker] = 'initial_state'
+
+# Transaction should not affect unrelated fiber state
+Familia.transaction do |conn|
+  Fiber[:test_marker] = 'modified_in_transaction'
+  conn.set('isolation_test', 'success')
+end
+
+# Unrelated fiber state should be preserved
+Fiber[:test_marker] == 'modified_in_transaction'
+#=> true
+
+## Pipeline context remains isolated per operation
+# Reset test marker
+Fiber[:test_marker] = 'initial_state'
+
+# Pipeline should not affect unrelated fiber state
+Familia.pipelined do |conn|
+  Fiber[:test_marker] = 'modified_in_pipeline'
+  conn.set('isolation_test2', 'success')
+end
+
+# Unrelated fiber state should be preserved
+Fiber[:test_marker] == 'modified_in_pipeline'
+#=> true
+
+# Cleanup
+Fiber[:test_marker] = nil

data/try/connection/handler_constraints_try.rb

@@ -0,0 +1,59 @@
+# Handler Constraint Methods Tryouts
+#
+# Tests that each connection handler class correctly defines its operation
+# constraints through class methods. These constraints determine what Redis
+# operations are safe for each connection type:
+#
+# - Single connections (middleware/cached) → unsafe for multi-mode operations
+# - Fresh connections (provider/create) → safe for all operations
+# - Transaction connections → safe for reentrant transactions only
+
+require_relative '../helpers/test_helpers'
+
+## FiberTransactionHandler constraints
+Familia::Connection::FiberTransactionHandler.allows_transaction
+#=> :reentrant
+
+## FiberTransactionHandler blocks pipelines
+Familia::Connection::FiberTransactionHandler.allows_pipelined
+#=> false
+
+## FiberConnectionHandler blocks transactions
+Familia::Connection::FiberConnectionHandler.allows_transaction
+#=> false
+
+## FiberConnectionHandler blocks pipelines
+Familia::Connection::FiberConnectionHandler.allows_pipelined
+#=> false
+
+## CachedConnectionHandler blocks transactions
+Familia::Connection::CachedConnectionHandler.allows_transaction
+#=> false
+
+## CachedConnectionHandler blocks pipelines
+Familia::Connection::CachedConnectionHandler.allows_pipelined
+#=> false
+
+## ProviderConnectionHandler allows transactions
+Familia::Connection::ProviderConnectionHandler.allows_transaction
+#=> true
+
+## ProviderConnectionHandler allows pipelines
+Familia::Connection::ProviderConnectionHandler.allows_pipelined
+#=> true
+
+## CreateConnectionHandler allows transactions
+Familia::Connection::CreateConnectionHandler.allows_transaction
+#=> true
+
+## CreateConnectionHandler allows pipelines
+Familia::Connection::CreateConnectionHandler.allows_pipelined
+#=> true
+
+## BaseConnectionHandler defaults to allow all
+Familia::Connection::BaseConnectionHandler.allows_transaction
+#=> true
+
+## BaseConnectionHandler defaults to allow all pipelines
+Familia::Connection::BaseConnectionHandler.allows_pipelined
+#=> true

data/try/connection/operation_mode_guards_try.rb

@@ -0,0 +1,208 @@
+# Operation Mode Guards Tryouts
+#
+# Tests the connection handler operation mode enforcement that prevents Redis
+# mode confusion bugs. Each handler type has specific operation constraints:
+#
+# - FiberTransactionHandler: Allow reentrant transactions, block pipelines
+# - FiberConnectionHandler: Block all multi-mode operations (middleware single conn)
+# - CachedConnectionHandler: Block all multi-mode operations (cached single conn)
+# - ProviderConnectionHandler: Allow all operations (fresh checkout each time)
+# - CreateConnectionHandler: Allow all operations (new connection each time)
+#
+# This prevents bugs where middleware/cached connections return "QUEUED" instead
+# of actual values, breaking conditional logic and business rules.
+
+require_relative '../helpers/test_helpers'
+
+## FiberConnectionHandler blocks transactions in strict mode
+begin
+  # Ensure we're in strict mode for this test
+  Familia.configure { |config| config.transaction_mode = :strict }
+
+  # Simulate middleware connection
+  Fiber[:familia_connection] = [Customer.create_dbclient, Familia.middleware_version]
+  Fiber[:familia_connection_handler_class] = Familia::Connection::FiberConnectionHandler
+  customer = Customer.new
+  customer.transaction { |conn| conn.set('test', 'value') }
+  false
+rescue Familia::OperationModeError
+  true
+ensure
+  Fiber[:familia_connection] = nil
+  Fiber[:familia_connection_handler_class] = nil
+end
+#=> true
+
+## FiberConnectionHandler blocks pipelines
+begin
+  # Ensure we're in strict mode for this test
+  Familia.configure { |config| config.pipeline_mode = :strict }
+
+  # Simulate middleware connection
+  Fiber[:familia_connection] = [Customer.create_dbclient, Familia.middleware_version]
+  Fiber[:familia_connection_handler_class] = Familia::Connection::FiberConnectionHandler
+  customer = Customer.new
+  customer.pipelined { |conn| conn.set('test', 'value') }
+  false
+rescue Familia::OperationModeError
+  true
+ensure
+  Fiber[:familia_connection] = nil
+  Fiber[:familia_connection_handler_class] = nil
+end
+#=> true
+
+## CreateConnectionHandler allows transactions
+begin
+  customer = Customer.new
+  customer.custid = 'test_tx'
+  result = customer.transaction { |conn| conn.set('tx_test', 'success') }
+  true
+rescue Familia::OperationModeError
+  false
+end
+#=> true
+
+## CreateConnectionHandler allows pipelines
+begin
+  customer = Customer.new
+  customer.custid = 'test_pipe'
+  result = customer.dbclient.pipelined { |conn| conn.set('pipe_test', 'success') }
+  true
+rescue Familia::OperationModeError
+  false
+end
+#=> true
+
+## ProviderConnectionHandler allows all operations
+# Set up connection provider
+original_provider = Familia.connection_provider
+Familia.connection_provider = ->(uri) { Redis.new(url: uri) }
+
+begin
+  customer = Customer.new
+  customer.custid = 'test_provider'
+  tx_result = customer.transaction { |conn| conn.set('provider_tx', 'success') }
+  pipe_result = customer.dbclient.pipelined { |conn| conn.set('provider_pipe', 'success') }
+  true
+rescue Familia::OperationModeError
+  false
+ensure
+  Familia.connection_provider = original_provider
+end
+#=> true
+
+## Handler class tracking works correctly
+customer = Customer.new
+customer.dbclient # Trigger connection
+Fiber[:familia_connection_handler_class]
+#=> Familia::Connection::CreateConnectionHandler
+
+## Error messages are descriptive
+begin
+  Fiber[:familia_connection] = [Customer.create_dbclient, Familia.middleware_version]
+  Fiber[:familia_connection_handler_class] = Familia::Connection::FiberConnectionHandler
+  customer = Customer.new
+  customer.transaction { }
+rescue Familia::OperationModeError => e
+  e.message.include?('FiberConnectionHandler') && e.message.include?('connection pools')
+ensure
+  Fiber[:familia_connection] = nil
+  Fiber[:familia_connection_handler_class] = nil
+end
+#=> true
+
+# Transaction Mode Backward Compatibility Tests
+# Ensure new configurable transaction modes don't break existing behavior
+
+# Store original transaction mode
+@original_transaction_mode = Familia.transaction_mode
+
+## Transaction mode reflects current setting
+# Note: May be :warn (default) or :strict (if changed by previous tests)
+[:warn, :strict].include?(Familia.transaction_mode)
+#=> true
+
+## CachedConnectionHandler still blocks transactions in strict mode
+begin
+  # Ensure we're in strict mode
+  Familia.configure { |config| config.transaction_mode = :strict }
+
+  # Force CachedConnectionHandler
+  Customer.instance_variable_set(:@dbclient, Familia.create_dbclient)
+
+  customer = Customer.new
+  customer.custid = 'strict_compat_test'
+  customer.transaction { |conn| conn.set('should_fail', 'value') }
+  false  # Should not reach here
+rescue Familia::OperationModeError => e
+  e.message.include?('CachedConnectionHandler')
+ensure
+  Customer.remove_instance_variable(:@dbclient)
+end
+#=> true
+
+## Normal transactions still work exactly as before
+begin
+  customer = Customer.new
+  customer.custid = 'normal_compat_test'
+
+  result = customer.transaction do |conn|
+    conn.set('compat_test', 'success')
+    conn.get('compat_test')
+  end
+
+  # Should return MultiResult as before
+  result.is_a?(MultiResult) && result.results.last == 'success'
+end
+#=> true
+
+## Pipeline operations maintain existing behavior
+begin
+  customer = Customer.new
+  customer.custid = 'pipeline_compat_test'
+
+  result = customer.pipelined do |conn|
+    conn.set('pipe_compat', 'pipeline_success')
+    conn.get('pipe_compat')
+  end
+
+  result.is_a?(MultiResult) && result.results.last == 'pipeline_success'
+end
+#=> true
+
+## Connection handler capabilities unchanged for CreateConnectionHandler allows_transaction
+Familia::Connection::CreateConnectionHandler.allows_transaction
+#=> true
+
+## Connection handler capabilities unchanged for CreateConnectionHandler allows_pipelined
+Familia::Connection::CreateConnectionHandler.allows_pipelined
+#=> true
+
+## Connection handler capabilities unchanged for CachedConnectionHandler allows_transaction
+Familia::Connection::CachedConnectionHandler.allows_transaction
+#=> false
+
+## Connection handler capabilities unchanged for CachedConnectionHandler allows_pipelined
+Familia::Connection::CachedConnectionHandler.allows_pipelined
+#=> false
+
+## Transaction modes don't affect normal connection resolution
+begin
+  # Change to permissive mode
+  Familia.configure { |config| config.transaction_mode = :permissive }
+
+  # Normal operations should still work the same way
+  customer = Customer.new
+  customer.custid = 'resolution_test'
+
+  # Should still use CreateConnectionHandler for normal transactions
+  conn = customer.dbclient
+  Fiber[:familia_connection_handler_class] == Familia::Connection::CreateConnectionHandler
+ensure
+  Familia.configure { |config| config.transaction_mode = :strict }
+end
+#=> true
+
+# Restore original transaction mode
+Familia.configure { |config| config.transaction_mode = @original_transaction_mode }