familia 2.0.0.pre23 → 2.0.0.pre25

data/try/edge_cases/find_by_dbkey_race_condition_try.rb

@@ -0,0 +1,248 @@
+# try/edge_cases/find_by_dbkey_race_condition_try.rb
+#
+# frozen_string_literal: true
+
+# Test race condition handling in find_by_dbkey where a key can expire
+# between the EXISTS check and HGETALL retrieval. Also tests lazy cleanup
+# of stale instances entries.
+#
+# The race condition scenario:
+# 1. EXISTS check passes (key exists)
+# 2. Key expires via TTL (or is deleted) before HGETALL
+# 3. HGETALL returns empty hash {}
+# 4. Without fix: instantiate_from_hash({}) creates object with nil identifier
+# 5. With fix: returns nil and cleans up stale instances entry
+
+require_relative '../support/helpers/test_helpers'
+
+RaceConditionUser = Class.new(Familia::Horreum) do
+  identifier_field :user_id
+  field :user_id
+  field :name
+  field :email
+end
+
+RaceConditionSession = Class.new(Familia::Horreum) do
+  identifier_field :session_id
+  field :session_id
+  field :data
+  feature :expiration
+  default_expiration 300
+end
+
+# --- Empty Hash Handling Tests ---
+
+## find_by_dbkey returns nil for empty hash when check_exists: true
+# Simulate race condition: add stale entry to instances, then try to load
+RaceConditionUser.instances.add('stale_user_1', Familia.now)
+initial_count = RaceConditionUser.instances.size
+result = RaceConditionUser.find_by_dbkey(RaceConditionUser.dbkey('stale_user_1'), check_exists: true)
+result
+#=> nil
+
+## find_by_dbkey returns nil for empty hash when check_exists: false
+RaceConditionUser.instances.add('stale_user_2', Familia.now)
+result = RaceConditionUser.find_by_dbkey(RaceConditionUser.dbkey('stale_user_2'), check_exists: false)
+result
+#=> nil
+
+## find_by_dbkey handles both check_exists modes consistently for non-existent keys
+result_true = RaceConditionUser.find_by_dbkey(RaceConditionUser.dbkey('nonexistent_1'), check_exists: true)
+result_false = RaceConditionUser.find_by_dbkey(RaceConditionUser.dbkey('nonexistent_2'), check_exists: false)
+[result_true, result_false]
+#=> [nil, nil]
+
+# --- Lazy Cleanup Tests ---
+
+## lazy cleanup removes stale entry from instances when loading fails
+RaceConditionUser.instances.clear
+RaceConditionUser.instances.add('phantom_user_1', Familia.now)
+before_count = RaceConditionUser.instances.size
+RaceConditionUser.find_by_dbkey(RaceConditionUser.dbkey('phantom_user_1'))
+after_count = RaceConditionUser.instances.size
+[before_count, after_count]
+#=> [1, 0]
+
+## lazy cleanup handles multiple stale entries
+RaceConditionUser.instances.clear
+RaceConditionUser.instances.add('phantom_a', Familia.now)
+RaceConditionUser.instances.add('phantom_b', Familia.now)
+RaceConditionUser.instances.add('phantom_c', Familia.now)
+RaceConditionUser.find_by_dbkey(RaceConditionUser.dbkey('phantom_a'))
+RaceConditionUser.find_by_dbkey(RaceConditionUser.dbkey('phantom_b'))
+remaining = RaceConditionUser.instances.size
+remaining
+#=> 1
+
+## lazy cleanup only removes the specific stale entry
+RaceConditionUser.instances.clear
+real_user = RaceConditionUser.new(user_id: 'real_user_1', name: 'Real', email: 'real@example.com')
+real_user.save
+RaceConditionUser.instances.add('phantom_mixed', Familia.now)
+before = RaceConditionUser.instances.members.sort
+RaceConditionUser.find_by_dbkey(RaceConditionUser.dbkey('phantom_mixed'))
+after = RaceConditionUser.instances.members.sort
+real_user.destroy!
+[before.include?('phantom_mixed'), before.include?('real_user_1'), after.include?('phantom_mixed'), after.include?('real_user_1')]
+#=> [true, true, false, true]
+
+# --- Race Condition Simulation Tests ---
+
+## simulated race: key deleted between conceptual EXISTS and actual load
+# This simulates what happens when a key expires between EXISTS and HGETALL
+user = RaceConditionUser.new(user_id: 'race_user_1', name: 'Race', email: 'race@example.com')
+user.save
+dbkey = RaceConditionUser.dbkey('race_user_1')
+
+# Verify key exists
+exists_before = Familia.dbclient.exists(dbkey).positive?
+
+# Simulate TTL expiration by directly deleting the key but leaving instances entry
+Familia.dbclient.del(dbkey)
+
+# Now find_by_dbkey should return nil and clean up instances
+result = RaceConditionUser.find_by_dbkey(dbkey)
+exists_after = RaceConditionUser.instances.members.include?('race_user_1')
+[exists_before, result, exists_after]
+#=> [true, nil, false]
+
+## simulated race with check_exists: false also handles cleanup
+user2 = RaceConditionUser.new(user_id: 'race_user_2', name: 'Race2', email: 'race2@example.com')
+user2.save
+dbkey2 = RaceConditionUser.dbkey('race_user_2')
+
+# Delete key but leave instances entry
+Familia.dbclient.del(dbkey2)
+
+result = RaceConditionUser.find_by_dbkey(dbkey2, check_exists: false)
+cleaned = !RaceConditionUser.instances.members.include?('race_user_2')
+[result, cleaned]
+#=> [nil, true]
+
+# --- TTL Expiration Tests ---
+
+## TTL expiration leaves stale instances entry (demonstrating the problem)
+session = RaceConditionSession.new(session_id: 'ttl_session_1', data: 'test data')
+session.save
+session.expire(1) # 1 second TTL
+
+# Verify it's in instances
+in_instances_before = RaceConditionSession.instances.members.include?('ttl_session_1')
+
+# Wait for TTL to expire
+sleep(1.5)
+
+# Key is gone but instances entry remains (this is the stale entry problem)
+key_exists = Familia.dbclient.exists(RaceConditionSession.dbkey('ttl_session_1')).positive?
+in_instances_still = RaceConditionSession.instances.members.include?('ttl_session_1')
+[in_instances_before, key_exists, in_instances_still]
+#=> [true, false, true]
+
+## lazy cleanup fixes stale entry after TTL expiration
+# Now when we try to load, it should clean up the stale entry
+result = RaceConditionSession.find_by_dbkey(RaceConditionSession.dbkey('ttl_session_1'))
+in_instances_after = RaceConditionSession.instances.members.include?('ttl_session_1')
+[result, in_instances_after]
+#=> [nil, false]
+
+## find methods clean up stale entries after TTL expiration
+session2 = RaceConditionSession.new(session_id: 'ttl_session_2', data: 'test data 2')
+session2.save
+session2.expire(1)
+sleep(1.5)
+
+# Use find_by_id (which calls find_by_dbkey internally)
+result = RaceConditionSession.find_by_id('ttl_session_2')
+cleaned = !RaceConditionSession.instances.members.include?('ttl_session_2')
+[result, cleaned]
+#=> [nil, true]
+
+# --- Count Consistency Tests ---
+
+## count reflects reality after lazy cleanup
+RaceConditionUser.instances.clear
+# Create real user
+real = RaceConditionUser.new(user_id: 'count_real', name: 'Real', email: 'real@example.com')
+real.save
+
+# Add phantom entries
+RaceConditionUser.instances.add('count_phantom_1', Familia.now)
+RaceConditionUser.instances.add('count_phantom_2', Familia.now)
+
+count_before = RaceConditionUser.count
+
+# Trigger lazy cleanup by attempting to load phantoms
+RaceConditionUser.find_by_id('count_phantom_1')
+RaceConditionUser.find_by_id('count_phantom_2')
+
+count_after = RaceConditionUser.count
+real.destroy!
+[count_before, count_after]
+#=> [3, 1]
+
+## keys_count vs count after lazy cleanup
+RaceConditionUser.instances.clear
+real2 = RaceConditionUser.new(user_id: 'keys_count_real', name: 'Real', email: 'real@example.com')
+real2.save
+RaceConditionUser.instances.add('keys_count_phantom', Familia.now)
+
+# Before cleanup: count includes phantom, keys_count doesn't
+count_before = RaceConditionUser.count
+keys_count_before = RaceConditionUser.keys_count
+
+# Trigger lazy cleanup
+RaceConditionUser.find_by_id('keys_count_phantom')
+
+# After cleanup: both should match
+count_after = RaceConditionUser.count
+keys_count_after = RaceConditionUser.keys_count
+
+real2.destroy!
+[count_before, keys_count_before, count_after, keys_count_after]
+#=> [2, 1, 1, 1]
+
+# --- Edge Cases ---
+
+## empty identifier in key doesn't cause issues
+# Key format with empty identifier would be "prefix::suffix"
+# This shouldn't happen in practice, but we handle it gracefully
+malformed_key = "#{RaceConditionUser.prefix}::object"
+result = RaceConditionUser.find_by_dbkey(malformed_key)
+result
+#=> nil
+
+## key with unusual identifier characters
+RaceConditionUser.instances.add('user:with:colons', Familia.now)
+result = RaceConditionUser.find_by_dbkey(RaceConditionUser.dbkey('user:with:colons'))
+# Should return nil (key doesn't exist) and attempt cleanup
+# Note: cleanup may not work perfectly for identifiers with delimiters
+result
+#=> nil
+
+## concurrent load attempts on same stale entry
+RaceConditionUser.instances.clear
+RaceConditionUser.instances.add('concurrent_phantom', Familia.now)
+
+threads = []
+results = []
+mutex = Mutex.new
+
+5.times do
+  threads << Thread.new do
+    r = RaceConditionUser.find_by_id('concurrent_phantom')
+    mutex.synchronize { results << r }
+  end
+end
+
+threads.each(&:join)
+
+# All should return nil, and instances should be cleaned
+all_nil = results.all?(&:nil?)
+cleaned = !RaceConditionUser.instances.members.include?('concurrent_phantom')
+[all_nil, cleaned, results.size]
+#=> [true, true, 5]
+
+# --- Cleanup ---
+
+RaceConditionUser.instances.clear
+RaceConditionSession.instances.clear

data/try/features/relationships/class_level_multi_index_auto_try.rb

@@ -0,0 +1,318 @@
+# try/features/relationships/class_level_multi_index_auto_try.rb
+#
+# frozen_string_literal: true
+
+# Tests for class-level multi_index auto-indexing and helper methods
+#
+# This file tests:
+# 1. Auto-indexing on save - objects should automatically be added to class-level indexes
+# 2. Index updates when field values change
+# 3. Helper methods (update_all_indexes, remove_from_all_indexes, current_indexings)
+#
+# Auto-indexing for class-level indexes (within: :class) should work similarly
+# to unique_index (within: nil), calling add_to_class_* methods on save.
+
+require_relative '../../support/helpers/test_helpers'
+
+# Test class for auto-indexing with class-level multi_index
+class ::AutoIndexCustomer < Familia::Horreum
+  feature :relationships
+  include Familia::Features::Relationships::Indexing
+
+  identifier_field :custid
+  field :custid
+  field :name
+  field :status
+  field :tier
+
+  # Class-level multi_index (within: :class is default)
+  multi_index :status, :status_index
+
+  # Explicit within: :class for second index
+  multi_index :tier, :tier_index, within: :class
+
+  # Track instances for rebuild testing
+  class_sorted_set :instances, class: self, reference: true
+end
+
+# Clean up stale data from previous runs
+%w[active pending inactive premium standard basic].each do |value|
+  AutoIndexCustomer.dbclient.del(AutoIndexCustomer.status_index_for(value).dbkey)
+  AutoIndexCustomer.dbclient.del(AutoIndexCustomer.tier_index_for(value).dbkey)
+end
+# Clean up any stale customer objects
+%w[auto_001 auto_002 auto_003 auto_004 auto_nil auto_empty auto_ws].each do |custid|
+  existing = AutoIndexCustomer.find_by_identifier(custid, check_exists: false)
+  existing&.delete! if existing&.exists?
+end
+
+# =============================================
+# 1. Auto-Indexing on Save Tests
+# =============================================
+
+## New object saved - auto-indexed in status_index
+@auto1 = AutoIndexCustomer.new(custid: 'auto_001', name: 'AutoAlice', status: 'active', tier: 'premium')
+@auto1.save
+AutoIndexCustomer.status_index_for('active').members.include?('auto_001')
+#=> true
+
+## Auto-indexing works for tier_index too (explicit within: :class)
+AutoIndexCustomer.tier_index_for('premium').members.include?('auto_001')
+#=> true
+
+## Second object saved - joins same status index
+@auto2 = AutoIndexCustomer.new(custid: 'auto_002', name: 'AutoBob', status: 'active', tier: 'standard')
+@auto2.save
+AutoIndexCustomer.status_index_for('active').members.sort
+#=> ["auto_001", "auto_002"]
+
+## Different tier index is separate
+AutoIndexCustomer.tier_index_for('standard').members
+#=> ["auto_002"]
+
+## Object with different status creates new index entry
+@auto3 = AutoIndexCustomer.new(custid: 'auto_003', name: 'AutoCharlie', status: 'pending', tier: 'basic')
+@auto3.save
+AutoIndexCustomer.status_index_for('pending').members
+#=> ["auto_003"]
+
+## Active status index unchanged by new pending customer
+AutoIndexCustomer.status_index_for('active').size
+#=> 2
+
+# =============================================
+# 2. Query After Auto-Indexing
+# =============================================
+
+## find_all_by_status returns auto-indexed customers
+active_customers = AutoIndexCustomer.find_all_by_status('active')
+active_customers.map(&:custid).sort
+#=> ["auto_001", "auto_002"]
+
+## sample_from_status works with auto-indexed data
+sample = AutoIndexCustomer.sample_from_status('active', 1)
+['auto_001', 'auto_002'].include?(sample.first&.custid)
+#=> true
+
+## find_all_by_tier returns correct customers
+premium_customers = AutoIndexCustomer.find_all_by_tier('premium')
+premium_customers.map(&:custid)
+#=> ["auto_001"]
+
+# =============================================
+# 3. Field Change and Index Update
+# =============================================
+
+## Change status field and save - verify old index is NOT automatically updated
+# Note: auto_update_class_indexes calls add_to_class_*, which is idempotent
+# but does NOT remove from old index. Manual update is needed for field changes.
+@old_status = @auto1.status
+@auto1.status = 'inactive'
+@auto1.save
+
+# After save, customer is added to new index
+AutoIndexCustomer.status_index_for('inactive').members.include?('auto_001')
+#=> true
+
+## Old index still contains the entry (save doesn't auto-remove from old)
+# This is expected behavior - save is idempotent add, not update
+AutoIndexCustomer.status_index_for('active').members.include?('auto_001')
+#=> true
+
+## Use update_in_class_status_index to properly move between indexes
+@auto1.update_in_class_status_index(@old_status)
+AutoIndexCustomer.status_index_for('active').members.include?('auto_001')
+#=> false
+
+## Customer now only in inactive index
+AutoIndexCustomer.status_index_for('inactive').members
+#=> ["auto_001"]
+
+# =============================================
+# 4. Helper Methods - update_all_indexes
+# =============================================
+
+## update_all_indexes method exists
+@auto2.respond_to?(:update_all_indexes)
+#=> true
+
+## update_all_indexes updates both status and tier indexes
+@old_values = { status: @auto2.status, tier: @auto2.tier }
+@auto2.status = 'pending'
+@auto2.tier = 'premium'
+@auto2.update_all_indexes(@old_values)
+
+# Check status index updated
+AutoIndexCustomer.status_index_for('active').members.include?('auto_002')
+#=> false
+
+## New status index contains customer
+AutoIndexCustomer.status_index_for('pending').members.include?('auto_002')
+#=> true
+
+## Old tier index no longer contains customer
+AutoIndexCustomer.tier_index_for('standard').members.include?('auto_002')
+#=> false
+
+## New tier index contains customer
+AutoIndexCustomer.tier_index_for('premium').members.include?('auto_002')
+#=> true
+
+# =============================================
+# 5. Helper Methods - remove_from_all_indexes
+# =============================================
+
+## remove_from_all_indexes method exists
+@auto3.respond_to?(:remove_from_all_indexes)
+#=> true
+
+## Verify customer is in indexes before removal
+[
+  AutoIndexCustomer.status_index_for('pending').members.include?('auto_003'),
+  AutoIndexCustomer.tier_index_for('basic').members.include?('auto_003')
+]
+#=> [true, true]
+
+## remove_from_all_indexes removes from all class-level indexes
+@auto3.remove_from_all_indexes
+[
+  AutoIndexCustomer.status_index_for('pending').members.include?('auto_003'),
+  AutoIndexCustomer.tier_index_for('basic').members.include?('auto_003')
+]
+#=> [false, false]
+
+# =============================================
+# 6. Helper Methods - current_indexings
+# =============================================
+
+## current_indexings method exists
+@auto1.respond_to?(:current_indexings)
+#=> true
+
+## Re-add auto1 to indexes for testing current_indexings
+@auto1.add_to_class_status_index
+@auto1.add_to_class_tier_index
+@indexings = @auto1.current_indexings
+@indexings.length
+#=> 2
+
+## current_indexings returns correct info for status_index
+@status_indexing = @indexings.find { |i| i[:index_name] == :status_index }
+[@status_indexing[:field], @status_indexing[:cardinality], @status_indexing[:type]]
+#=> [:status, :multi, "multi_index"]
+
+## current_indexings returns correct info for tier_index
+@tier_indexing = @indexings.find { |i| i[:index_name] == :tier_index }
+[@tier_indexing[:field], @tier_indexing[:cardinality], @tier_indexing[:type]]
+#=> [:tier, :multi, "multi_index"]
+
+## current_indexings shows scope_class for class-level indexes
+@status_indexing[:scope_class]
+#=> "class"
+
+# =============================================
+# 7. Helper Methods - indexed_in?
+# =============================================
+
+## indexed_in? method exists
+@auto1.respond_to?(:indexed_in?)
+#=> true
+
+## indexed_in? returns true for indexes where customer is present
+@auto1.indexed_in?(:status_index)
+#=> true
+
+## indexed_in? returns true for tier_index too
+@auto1.indexed_in?(:tier_index)
+#=> true
+
+## indexed_in? returns false for non-existent index
+@auto1.indexed_in?(:nonexistent_index)
+#=> false
+
+## After removal, indexed_in? returns false
+@auto1.remove_from_class_status_index
+@auto1.indexed_in?(:status_index)
+#=> false
+
+# =============================================
+# 8. Delete and Index Cleanup
+# =============================================
+
+## Create a new customer for delete testing
+@auto4 = AutoIndexCustomer.new(custid: 'auto_004', name: 'AutoDiana', status: 'active', tier: 'standard')
+@auto4.save
+AutoIndexCustomer.status_index_for('active').members.include?('auto_004')
+#=> true
+
+## Delete does NOT automatically remove from indexes (by design)
+# Applications should call remove_from_all_indexes before delete if needed
+@auto4.delete!
+AutoIndexCustomer.status_index_for('active').members.include?('auto_004')
+#=> true
+
+## Manual cleanup required after delete
+# Note: This tests that stale entries exist until explicitly cleaned
+# The find_by methods handle stale entries gracefully
+stale_customer = AutoIndexCustomer.find_by_identifier('auto_004')
+stale_customer
+#=> nil
+
+# =============================================
+# 9. Edge Cases
+# =============================================
+
+## Nil field value - should not be indexed
+@auto_nil = AutoIndexCustomer.new(custid: 'auto_nil', name: 'NilStatus', status: nil, tier: 'basic')
+@auto_nil.save
+# Should not create an entry in the nil index (empty string key)
+AutoIndexCustomer.status_index_for('').members.include?('auto_nil')
+#=> false
+
+## Empty string field value - should not be indexed
+@auto_empty = AutoIndexCustomer.new(custid: 'auto_empty', name: 'EmptyStatus', status: '', tier: 'basic')
+@auto_empty.save
+AutoIndexCustomer.status_index_for('').members.include?('auto_empty')
+#=> false
+
+## Whitespace-only field value - should not be indexed
+@auto_ws = AutoIndexCustomer.new(custid: 'auto_ws', name: 'WSStatus', status: '   ', tier: 'basic')
+@auto_ws.save
+AutoIndexCustomer.status_index_for('   ').members.include?('auto_ws')
+#=> false
+
+# =============================================
+# 10. Idempotent Save Behavior
+# =============================================
+
+## Saving same object multiple times doesn't duplicate index entries
+@auto2.save
+@auto2.save
+@auto2.save
+# Should still only have one entry
+AutoIndexCustomer.status_index_for(@auto2.status).members.count { |m| m == 'auto_002' }
+#=> 1
+
+## UnsortedSet inherently prevents duplicates
+AutoIndexCustomer.status_index_for('pending').size
+#=> 1
+
+# Teardown
+# Clean up test objects
+[@auto1, @auto2, @auto3, @auto_nil, @auto_empty, @auto_ws].compact.each do |obj|
+  obj.delete! if obj.respond_to?(:exists?) && obj.exists?
+end
+
+# Clean up index keys
+%w[active pending inactive premium standard basic].each do |value|
+  AutoIndexCustomer.dbclient.del(AutoIndexCustomer.status_index_for(value).dbkey)
+  AutoIndexCustomer.dbclient.del(AutoIndexCustomer.tier_index_for(value).dbkey)
+end
+
+# Clean up edge case indexes
+['', '   '].each do |value|
+  AutoIndexCustomer.dbclient.del(AutoIndexCustomer.status_index_for(value).dbkey)
+end
+
+# Clean up instances collection
+AutoIndexCustomer.instances.clear if AutoIndexCustomer.respond_to?(:instances)