familia 2.0.0.pre19 → 2.0.0.pre21

data/try/unit/core/middleware_thread_safety_try.rb

@@ -0,0 +1,245 @@
+# try/unit/core/middleware_thread_safety_try.rb
+#
+# frozen_string_literal: true
+
+# Thread Safety Tests for DatabaseLogger Middleware
+#
+# These tests specifically target potential race conditions and concurrency issues
+# in the DatabaseLogger middleware that could lead to nil entries in the @commands array.
+#
+# Covers:
+# - Concurrent append_command operations
+# - Thread-safe pipeline command logging
+# - Mixed operation types under contention
+# - Sampling counter atomicity
+# - Rapid sequential calls within threads
+# - clear_commands during active logging
+#
+# Background:
+# An intermittent NoMethodError was observed where .command was called on nil
+# during teardown of middleware_sampling_try.rb. The error suggests potential
+# corruption of the @commands Concurrent::Array, possibly due to race conditions
+# between append_command, clear_commands, or middleware state management.
+
+require_relative '../../support/helpers/test_helpers'
+require 'concurrent'
+
+# Setup: Reset DatabaseLogger and ensure middleware is registered
+Familia.connection_provider = nil
+Familia.enable_database_logging = true
+Familia.reconnect!
+DatabaseLogger.clear_commands
+DatabaseLogger.sample_rate = nil
+DatabaseLogger.structured_logging = false
+
+## DatabaseLogger.append_command is thread-safe under concurrent access from 50 threads
+# First verify middleware is working in main thread
+DatabaseLogger.clear_commands
+test_client = Familia.dbclient
+test_client.set("setup_test", "value")
+setup_commands = DatabaseLogger.commands.size
+
+# Now run the actual test
+DatabaseLogger.clear_commands
+barrier = Concurrent::CyclicBarrier.new(50)
+threads = []
+dbclient = Familia.dbclient  # Get connection in main thread (has middleware)
+
+50.times do |i|
+  threads << Thread.new do
+    barrier.wait  # Synchronize start to maximize contention
+    dbclient.set("thread_key_#{i}", "value_#{i}")
+  end
+end
+
+threads.each(&:join)
+commands = DatabaseLogger.commands
+
+# All commands should be captured (no lost writes)
+# No nil entries should exist in the commands array
+# Note: setup_commands verifies middleware is working (should be 1)
+[setup_commands, commands.size, commands.any?(nil), commands.all? { |cmd| cmd.respond_to?(:command) }]
+#=> [1, 50, false, true]
+
+## Pipelined commands are thread-safe under concurrent access from 25 threads
+DatabaseLogger.clear_commands
+barrier = Concurrent::CyclicBarrier.new(25)
+threads = []
+dbclient = Familia.dbclient  # Get connection in main thread (has middleware)
+
+25.times do |i|
+  threads << Thread.new do
+    barrier.wait
+    dbclient.pipelined do |pipeline|
+      pipeline.set("pipeline_thread_#{i}_key1", "val1")
+      pipeline.set("pipeline_thread_#{i}_key2", "val2")
+    end
+  end
+end
+
+threads.each(&:join)
+commands = DatabaseLogger.commands
+
+# Each thread creates one pipeline command (25 total)
+# Verify no nil entries and all are proper CommandMessage objects
+[commands.size, commands.any?(nil), commands.all? { |cmd| cmd.respond_to?(:command) }]
+#=> [25, false, true]
+
+## Mixed middleware operations (call, call_pipelined, call_once) are thread-safe
+DatabaseLogger.clear_commands
+barrier = Concurrent::CyclicBarrier.new(60)
+threads = []
+dbclient = Familia.dbclient  # Get connection in main thread (has middleware)
+
+60.times do |i|
+  threads << Thread.new do
+    barrier.wait
+
+    case i % 3
+    when 0  # Regular call
+      dbclient.set("mixed_#{i}", "val")
+    when 1  # Pipelined
+      dbclient.pipelined { |p| p.get("mixed_#{i}") }
+    when 2  # Multiple rapid calls
+      3.times { dbclient.get("mixed_#{i}") }
+    end
+  end
+end
+
+threads.each(&:join)
+commands = DatabaseLogger.commands
+
+# Verify no nil entries regardless of operation type
+# All entries should be valid CommandMessage instances
+[commands.any?(nil), commands.all? { |cmd| cmd.is_a?(DatabaseLogger::CommandMessage) }]
+#=> [false, true]
+
+## sample_rate counter is thread-safe with 100 concurrent operations
+# REMOVED: This test had incorrect expectations. The sample_rate controls LOGGING
+# output, not COMMAND CAPTURE. Per database_logger.rb:153-154:
+# "Command capture is unaffected - only logger output is sampled."
+# The commands array always contains all commands regardless of sample_rate.
+# Thread safety of the AtomicFixnum counter is verified by other tests.
+
+## Rapid sequential calls within threads don't corrupt shared state
+DatabaseLogger.clear_commands
+DatabaseLogger.sample_rate = nil  # Log everything
+latch = Concurrent::CountDownLatch.new(20)
+threads = []
+dbclient = Familia.dbclient  # Get connection in main thread (has middleware)
+
+20.times do |i|
+  threads << Thread.new do
+    # Rapid-fire 10 operations per thread to test state isolation
+    10.times do |j|
+      dbclient.set("rapid_#{i}_#{j}", "val")
+    end
+    latch.count_down
+  end
+end
+
+latch.wait(5)  # 5 second timeout
+commands = DatabaseLogger.commands
+
+# Should have 200 commands (20 threads × 10 calls)
+# Most importantly: NO nil entries from rapid sequential access
+[commands.size, commands.any?(nil)]
+#=> [200, false]
+
+## clear_commands doesn't cause nil entries during concurrent logging
+DatabaseLogger.clear_commands
+DatabaseLogger.sample_rate = nil
+barrier = Concurrent::CyclicBarrier.new(51)  # 50 loggers + 1 clearer
+threads = []
+dbclient = Familia.dbclient  # Get connection in main thread (has middleware)
+
+# 50 threads logging continuously
+50.times do |i|
+  threads << Thread.new do
+    barrier.wait
+    10.times do |j|
+      dbclient.set("clear_test_#{i}_#{j}", "val")
+    end
+  end
+end
+
+# 1 thread clearing repeatedly to create contention
+clearer = Thread.new do
+  barrier.wait
+  5.times do
+    sleep 0.001  # Small delay between clears
+    DatabaseLogger.clear_commands
+  end
+end
+
+threads.each(&:join)
+clearer.join
+
+# After clearing, commands should be empty or valid (never contain nil)
+# This tests whether clear_commands can corrupt the array during active logging
+commands = DatabaseLogger.commands
+[commands.any?(nil)]
+#=> [false]
+
+## CommandMessage structure is preserved under concurrent access
+DatabaseLogger.clear_commands
+barrier = Concurrent::CyclicBarrier.new(30)
+threads = []
+dbclient = Familia.dbclient  # Get connection in main thread (has middleware)
+
+30.times do |i|
+  threads << Thread.new do
+    barrier.wait
+    dbclient.set("structure_test_#{i}", "value_#{i}")
+  end
+end
+
+threads.each(&:join)
+commands = DatabaseLogger.commands
+
+# Verify all CommandMessage fields are properly initialized
+# This ensures the Data.define structure isn't corrupted by concurrency
+all_valid = commands.all? do |cmd|
+  cmd.command.is_a?(String) &&
+  cmd.μs.is_a?(Integer) &&
+  cmd.timeline.is_a?(Float)
+end
+
+[commands.size, commands.any?(nil), all_valid]
+#=> [30, false, true]
+
+## Concurrent pipelined operations with varying sizes don't cause corruption
+# REMOVED: This test was checking exact pipeline command count which can vary
+# due to intentionally non-atomic append_command trimming logic.
+# See database_logger.rb:214-217 - we don't care about exact count when trimming.
+# The important invariants (no nil entries, successful operations) are tested elsewhere.
+
+## AtomicFixnum counter increments correctly under high contention
+DatabaseLogger.clear_commands
+DatabaseLogger.sample_rate = 1.0  # Track every increment but log everything
+counter_start = DatabaseLogger.instance_variable_get(:@sample_counter).value
+
+barrier = Concurrent::CyclicBarrier.new(100)
+threads = []
+dbclient = Familia.dbclient  # Get connection in main thread (has middleware)
+
+100.times do |i|
+  threads << Thread.new do
+    barrier.wait
+    dbclient.set("counter_test_#{i}", "val")
+  end
+end
+
+threads.each(&:join)
+counter_end = DatabaseLogger.instance_variable_get(:@sample_counter).value
+commands = DatabaseLogger.commands
+
+# Counter should have incremented by exactly 100
+# Commands should have all 100 entries with no nil values
+[counter_end - counter_start, commands.size, commands.any?(nil)]
+#=> [100, 100, false]
+
+# Teardown: Reset to defaults
+DatabaseLogger.sample_rate = nil
+DatabaseLogger.structured_logging = false
+DatabaseLogger.clear_commands

data/try/unit/core/middleware_try.rb

@@ -1,3 +1,7 @@
+# try/unit/core/middleware_try.rb
+#
+# frozen_string_literal: true
+
 # try/core/middleware_try.rb
 
 # Test Valkey/Redis middleware components

data/try/unit/core/settings_try.rb

@@ -1,3 +1,7 @@
+# try/unit/core/settings_try.rb
+#
+# frozen_string_literal: true
+
 # try/core/settings_try.rb
 
 require_relative '../../support/helpers/test_helpers'

data/try/unit/core/time_utils_try.rb

@@ -1,3 +1,7 @@
+# try/unit/core/time_utils_try.rb
+#
+# frozen_string_literal: true
+
 require_relative '../../support/helpers/test_helpers'
 
 module RefinedContext

data/try/unit/core/tools_try.rb

@@ -1,3 +1,7 @@
+# try/unit/core/tools_try.rb
+#
+# frozen_string_literal: true
+
 # try/core/tools_try.rb
 
 # Test Familia::Tools - key migration and utility functions

data/try/unit/core/utils_try.rb

@@ -1,3 +1,7 @@
+# try/unit/core/utils_try.rb
+#
+# frozen_string_literal: true
+
 # try/core/utils_try.rb
 
 require_relative '../../support/helpers/test_helpers'
@@ -85,6 +89,39 @@ rescue Familia::NotDistinguishableError => e
 end
 #=> Familia::NotDistinguishableError
 
+##
+## Time utilities
+##
+
+## now returns Float timestamp in seconds
+time_result = Familia.now
+[time_result.is_a?(Float), time_result > 0]
+#=> [true, true]
+
+## now accepts Time argument
+test_time = Time.utc(2023, 6, 15, 14, 30, 0)
+result_time = Familia.now(test_time)
+[result_time.is_a?(Float), result_time == test_time.utc.to_f]
+#=> [true, true]
+
+## now_in_μs returns Integer microseconds
+μs_result = Familia.now_in_μs
+[μs_result.is_a?(Integer), μs_result > 0]
+#=> [true, true]
+
+## now_in_microseconds is an alias for now_in_μs
+alias_result = Familia.now_in_microseconds
+[alias_result.is_a?(Integer), alias_result > 0]
+#=> [true, true]
+
+## now_in_μs returns monotonic time suitable for duration measurement
+start = Familia.now_in_μs
+sleep 0.001  # Sleep for at least 1ms
+finish = Familia.now_in_μs
+duration = finish - start
+[duration.is_a?(Integer), duration >= 1000]  # At least 1000 microseconds (1ms)
+#=> [true, true]
+
 # Cleanup - restore defaults, leave nothing but footprints
 Familia.delim(':')
 Familia.suffix(:object)

data/try/unit/data_types/boolean_try.rb

@@ -1,3 +1,7 @@
+# try/unit/data_types/boolean_try.rb
+#
+# frozen_string_literal: true
+
 # try/data_types/boolean_try.rb
 
 require_relative '../../support/helpers/test_helpers'

data/try/unit/data_types/counter_try.rb

@@ -1,3 +1,7 @@
+# try/unit/data_types/counter_try.rb
+#
+# frozen_string_literal: true
+
 # try/data_types/counter_try.rb
 
 require_relative '../../support/helpers/test_helpers'

data/try/unit/data_types/datatype_base_try.rb

@@ -1,3 +1,7 @@
+# try/unit/data_types/datatype_base_try.rb
+#
+# frozen_string_literal: true
+
 # try/data_types/base_try.rb
 
 require_relative '../../support/helpers/test_helpers'

data/try/unit/data_types/hash_try.rb

@@ -1,3 +1,7 @@
+# try/unit/data_types/hash_try.rb
+#
+# frozen_string_literal: true
+
 # try/data_types/hash_try.rb
 
 require_relative '../../support/helpers/test_helpers'

data/try/unit/data_types/list_try.rb

@@ -1,3 +1,7 @@
+# try/unit/data_types/list_try.rb
+#
+# frozen_string_literal: true
+
 # try/data_types/list_try.rb
 
 require_relative '../../support/helpers/test_helpers'

data/try/unit/data_types/lock_try.rb

@@ -1,3 +1,7 @@
+# try/unit/data_types/lock_try.rb
+#
+# frozen_string_literal: true
+
 # try/data_types/lock_try.rb
 
 require_relative '../../support/helpers/test_helpers'

data/try/unit/data_types/sorted_set_try.rb

@@ -1,3 +1,7 @@
+# try/unit/data_types/sorted_set_try.rb
+#
+# frozen_string_literal: true
+
 # try/data_types/sorted_set_try.rb
 
 require_relative '../../support/helpers/test_helpers'

data/try/unit/data_types/sorted_set_zadd_options_try.rb

@@ -1,3 +1,7 @@
+# try/unit/data_types/sorted_set_zadd_options_try.rb
+#
+# frozen_string_literal: true
+
 # try/features/data_type/sorted_set_zadd_options_try.rb
 
 require_relative '../../support/helpers/test_helpers'

data/try/unit/data_types/string_try.rb

@@ -1,3 +1,7 @@
+# try/unit/data_types/string_try.rb
+#
+# frozen_string_literal: true
+
 # try/data_types/string_try.rb
 
 require_relative '../../support/helpers/test_helpers'

data/try/unit/data_types/unsortedset_try.rb

@@ -1,3 +1,7 @@
+# try/unit/data_types/unsortedset_try.rb
+#
+# frozen_string_literal: true
+
 # try/data_types/unsortedset_try.rb
 
 require_relative '../../support/helpers/test_helpers'

data/try/unit/familia_resolve_class_try.rb

@@ -0,0 +1,116 @@
+# try/unit/familia_resolve_class_try.rb
+#
+# frozen_string_literal: true
+
+# Unit tests for Familia.resolve_class method
+#
+# This test ensures the public API for resolving class references works
+# correctly across different input types (Class, Symbol, String).
+#
+# Related to the fix for NoMethodError in participates_in where the private
+# method member_by_config_name was being called directly instead of using
+# the public resolve_class API.
+
+require_relative '../support/helpers/test_helpers'
+
+# Test class for resolution
+class ResolveTestClass < Familia::Horreum
+  identifier_field :id
+  field :id
+  field :name
+end
+
+# Test class in module for modularized class resolution
+module ResolveTestModule
+  class ModularClass < Familia::Horreum
+    identifier_field :id
+    field :id
+  end
+end
+
+## Test resolve_class with Class object returns the class unchanged
+@resolved_class = Familia.resolve_class(ResolveTestClass)
+@resolved_class == ResolveTestClass
+#=> true
+
+## Test resolve_class with Symbol returns the correct class
+@resolved_symbol = Familia.resolve_class(:ResolveTestClass)
+@resolved_symbol == ResolveTestClass
+#=> true
+
+## Test resolve_class with String returns the correct class
+@resolved_string = Familia.resolve_class('ResolveTestClass')
+@resolved_string == ResolveTestClass
+#=> true
+
+## Test resolve_class with PascalCase symbol works
+@resolved_pascal_sym = Familia.resolve_class(:ResolveTestClass)
+@resolved_pascal_sym == ResolveTestClass
+#=> true
+
+## Test resolve_class with PascalCase string works
+@resolved_pascal_str = Familia.resolve_class('ResolveTestClass')
+@resolved_pascal_str == ResolveTestClass
+#=> true
+
+## Test resolve_class with snake_case symbol works
+@resolved_snake = Familia.resolve_class(:resolve_test_class)
+@resolved_snake == ResolveTestClass
+#=> true
+
+## Test resolve_class with snake_case string works
+@resolved_snake_str = Familia.resolve_class('resolve_test_class')
+@resolved_snake_str == ResolveTestClass
+#=> true
+
+## Test resolve_class raises ArgumentError for invalid types
+begin
+  Familia.resolve_class(123)
+  @raised = false
+rescue ArgumentError => e
+  @raised = true
+  @error_message = e.message
+end
+@raised
+#=> true
+
+## Test error message is descriptive
+@error_message.include?('Expected Class, String, or Symbol')
+#=> true
+
+## Test resolve_class returns nil for non-existent class
+@nonexistent = Familia.resolve_class(:NonExistentClass)
+@nonexistent.nil?
+#=> true
+
+## Test resolve_class with variations of proper naming
+# Note: All-caps or all-lowercase don't work because snake_case needs case boundaries
+# Realistic usage: PascalCase, snake_case, or mixed-case with boundaries
+@case_variant_snake = Familia.resolve_class('resolve_test_class')
+@case_variant_snake == ResolveTestClass
+#=> true
+
+## Test resolve_class handles already snake_cased symbols
+@already_snake = Familia.resolve_class(:resolve_test_class)
+@already_snake == ResolveTestClass
+#=> true
+
+## Test resolve_class with modularized Symbol (without module prefix)
+@modular_resolved = Familia.resolve_class(:ModularClass)
+@modular_resolved == ResolveTestModule::ModularClass
+#=> true
+
+## Test resolve_class with modularized String (without module prefix)
+@modular_resolved_str = Familia.resolve_class('ModularClass')
+@modular_resolved_str == ResolveTestModule::ModularClass
+#=> true
+
+## Test resolve_class with snake_case modularized Symbol
+@modular_snake = Familia.resolve_class(:modular_class)
+@modular_snake == ResolveTestModule::ModularClass
+#=> true
+
+## Test resolve_class with Class object for modularized class
+@modular_class_obj = Familia.resolve_class(ResolveTestModule::ModularClass)
+@modular_class_obj == ResolveTestModule::ModularClass
+#=> true

data/try/unit/horreum/auto_indexing_on_save_try.rb

@@ -1,3 +1,7 @@
+# try/unit/horreum/auto_indexing_on_save_try.rb
+#
+# frozen_string_literal: true
+
 # try/horreum/auto_indexing_on_save_try.rb
 
 #
@@ -182,7 +186,7 @@ AutoIndexWithTransient.find_by_email(@transient_email)&.id
 begin
   @transient_dup.save
 rescue Familia::RecordExistsError => ex
-  Familia.ld ex.backtrace.join("\n")
+  Familia.debug ex.backtrace.join("\n")
   ex.message
 end
 #=:> String

data/try/unit/horreum/automatic_index_validation_try.rb

@@ -1,4 +1,6 @@
 # try/unit/horreum/automatic_index_validation_try.rb
+#
+# frozen_string_literal: true
 
 #
 # Automatic index validation tests

data/try/unit/horreum/base_try.rb

@@ -1,3 +1,7 @@
+# try/unit/horreum/base_try.rb
+#
+# frozen_string_literal: true
+
 # try/horreum/base_try.rb
 
 require_relative '../../support/helpers/test_helpers'

data/try/unit/horreum/class_methods_try.rb

@@ -1,3 +1,7 @@
+# try/unit/horreum/class_methods_try.rb
+#
+# frozen_string_literal: true
+
 # try/horreum/class_methods_try.rb
 
 # Test Horreum class methods

data/try/unit/horreum/commands_try.rb

@@ -1,3 +1,7 @@
+# try/unit/horreum/commands_try.rb
+#
+# frozen_string_literal: true
+
 # try/horreum/commands_try.rb
 
 # Test Horreum Valkey/Redis commands

data/try/unit/horreum/defensive_initialization_try.rb

@@ -1,3 +1,7 @@
+# try/unit/horreum/defensive_initialization_try.rb
+#
+# frozen_string_literal: true
+
 # try/horreum/defensive_initialization_try.rb
 
 require_relative '../../support/helpers/test_helpers'

data/try/unit/horreum/destroy_related_fields_cleanup_try.rb

@@ -1,3 +1,7 @@
+# try/unit/horreum/destroy_related_fields_cleanup_try.rb
+#
+# frozen_string_literal: true
+
 # try/horreum/destroy_related_fields_cleanup_try.rb
 
 # Horreum destroy! Related Fields Cleanup Tryouts

data/try/unit/horreum/enhanced_conflict_handling_try.rb

@@ -1,3 +1,7 @@
+# try/unit/horreum/enhanced_conflict_handling_try.rb
+#
+# frozen_string_literal: true
+
 # try/horreum/enhanced_conflict_handling_try.rb
 
 require_relative '../../support/helpers/test_helpers'

data/try/unit/horreum/field_categories_try.rb

@@ -1,3 +1,7 @@
+# try/unit/horreum/field_categories_try.rb
+#
+# frozen_string_literal: true
+
 # try/horreum/field_categories_try.rb
 
 require_relative '../../support/helpers/test_helpers'

data/try/unit/horreum/field_definition_try.rb

@@ -1,3 +1,7 @@
+# try/unit/horreum/field_definition_try.rb
+#
+# frozen_string_literal: true
+
 # try/horreum/field_definition_try.rb
 
 require_relative '../../support/helpers/test_helpers'

data/try/unit/horreum/initialization_try.rb

@@ -1,3 +1,7 @@
+# try/unit/horreum/initialization_try.rb
+#
+# frozen_string_literal: true
+
 # try/horreum/initialization_try.rb
 
 require_relative '../../support/helpers/test_helpers'

data/try/unit/horreum/json_type_preservation_try.rb

@@ -1,3 +1,5 @@
+# try/unit/horreum/json_type_preservation_try.rb
+#
 # frozen_string_literal: true
 
 require_relative '../../support/helpers/test_helpers'