familia 2.0.0.pre23 → 2.0.0.pre24

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: cc6c562adc770554d50a5d8d97be46b8a924d04ed6a28e7447a765990e69d89b
-  data.tar.gz: 97812dfbbcd8b7cb2e3c9447558e7b1b6eb30181d9eed8c3ae86e0371f83cf7e
+  metadata.gz: 9b6118ccf4f7a1ed2da6b080a8e256088481ecd93d9f60378f2fca40fe5bb364
+  data.tar.gz: 1960335d0f688f6b9fb8c8a0ccfc8c4314b85ee36cf4dc56281c1e6d0642f455
 SHA512:
-  metadata.gz: 6d41492ba9f38dafacfe65a37a792c6f50ad90e406718131b0e226a6003b27008a1057851eb1d73ed1ff8baf8cf95312e684b290e23b3bbc2c9b5d453f0ba2ea
-  data.tar.gz: 2bf7cb92e0e06b623429dd0ff3b1da46686236329f5f3540e9f344195d1a51b50a209fc3b7d6538827c91e51194dd1014f9e5efd536a264c08283c505ea5044f
+  metadata.gz: 51a4ab15e2181939e0b2b43f440e2629f149b9e774c7061737812c39f8b722280b20c8468d0e41ae6045c08a1751a661865622e0277f252edbd79e12eedbd9bc
+  data.tar.gz: 3cebb9d48404ce9b3aaffc43d74d605dda64d90463fbc604c8b0ad2a53853132683bb8b39be24e905ab8b86d5d4736a36fee91dc1fe9cd57b9fc18fd10331265

data/CHANGELOG.rst

@@ -7,6 +7,40 @@ The format is based on `Keep a Changelog <https://keepachangelog.com/en/1.1.0/>`
 
    <!--scriv-insert-here-->
 
+.. _changelog-2.0.0.pre24:
+
+2.0.0.pre24 — 2026-01-07
+========================
+
+Added
+-----
+
+- Add comprehensive test coverage for ``find_by_dbkey`` race condition and lazy cleanup
+  scenarios in ``try/edge_cases/find_by_dbkey_race_condition_try.rb`` (16 new tests).
+  Tests cover empty hash handling, lazy cleanup, TTL expiration, count consistency,
+  and concurrent access patterns.
+
+Fixed
+-----
+
+- Fix race condition in ``find_by_dbkey`` where keys expiring between EXISTS and HGETALL
+  could create objects with nil identifiers, causing ``NoIdentifier`` errors on subsequent
+  operations like ``destroy!``. Now always checks for empty hash results regardless of
+  ``check_exists`` parameter value.
+
+- Add lazy cleanup of stale ``instances`` sorted set entries when ``find_by_dbkey`` detects
+  a non-existent key (via EXISTS check) or an expired key (via empty HGETALL result). This
+  prevents phantom instance counts from accumulating when objects expire via TTL without
+  explicit ``destroy!`` calls. The cleanup is performed opportunistically during load
+  attempts, requiring no background jobs or Redis keyspace notifications.
+
+AI Assistance
+-------------
+
+- Claude helped verify the race condition analysis through multi-agent investigation
+  (Explore, Code Explorer, QA Engineer agents) and implemented the fix with lazy cleanup
+  and comprehensive test coverage.
+
 .. _changelog-2.0.0.pre23:
 
 2.0.0.pre23 — 2025-12-22

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    familia (2.0.0.pre23)
+    familia (2.0.0.pre24)
       benchmark (~> 0.4)
       concurrent-ruby (~> 1.3)
       connection_pool (~> 2.5)

data/lib/familia/horreum/management.rb

@@ -156,7 +156,10 @@ module Familia
           # doesn't, we return nil. If it does, we proceed to load the object.
           # Otherwise, hgetall will return an empty hash, which will be passed to
           # the constructor, which will then be annoying to debug.
-          return unless does_exist
+          unless does_exist
+            cleanup_stale_instance_entry(objkey)
+            return nil
+          end
         else
           # Optimized mode: Skip existence check
           Familia.debug "[find_by_key] #{self} from key #{objkey} (check_exists: false)"
@@ -166,12 +169,42 @@ module Familia
         obj = dbclient.hgetall(objkey) # horreum objects are persisted as database hashes
         Familia.trace :FIND_BY_DBKEY_INSPECT, nil, "#{objkey}: #{obj.inspect}"
 
-        # If we skipped existence check and got empty hash, key doesn't exist
-        return nil if !check_exists && obj.empty?
+        # Always check for empty hash to handle race conditions where the key
+        # expires between EXISTS check and HGETALL (when check_exists: true),
+        # or simply doesn't exist (when check_exists: false).
+        if obj.empty?
+          cleanup_stale_instance_entry(objkey)
+          return nil
+        end
 
         # Create instance and deserialize fields using shared helper method
         instantiate_from_hash(obj)
       end
+
+      # Removes a stale entry from the instances sorted set.
+      # Called when find_by_dbkey detects that an object no longer exists
+      # (either EXISTS returned false, or HGETALL returned empty hash).
+      #
+      # This provides lazy cleanup of phantom instance entries that can
+      # accumulate when objects expire via TTL without explicit destroy!
+      #
+      # @param objkey [String] The full database key (prefix:identifier:suffix)
+      # @return [void]
+      # @api private
+      def cleanup_stale_instance_entry(objkey)
+        return unless respond_to?(:instances)
+
+        # Key format is prefix:identifier:suffix, so identifier is at index 1
+        parts = Familia.split(objkey)
+        return unless parts.length >= 2
+
+        identifier = parts[1]
+        return if identifier.nil? || identifier.empty?
+
+        instances.remove(identifier)
+        Familia.debug "[find_by_dbkey] Removed stale instance entry: #{identifier}"
+      end
+      private :cleanup_stale_instance_entry
       alias find_by_key find_by_dbkey
 
       # Retrieves and instantiates an object from Database using its identifier.

data/lib/familia/version.rb

@@ -4,5 +4,5 @@
 
 module Familia
   # Version information for the Familia
-  VERSION = '2.0.0.pre23'.freeze unless defined?(Familia::VERSION)
+  VERSION = '2.0.0.pre24'.freeze unless defined?(Familia::VERSION)
 end

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: familia
 version: !ruby/object:Gem::Version
-  version: 2.0.0.pre23
+  version: 2.0.0.pre24
 platform: ruby
 authors:
 - Delano Mandelbaum
@@ -317,6 +317,7 @@ files:
 - pr_agent.toml
 - pr_compliance_checklist.yaml
 - try/edge_cases/empty_identifiers_try.rb
+- try/edge_cases/find_by_dbkey_race_condition_try.rb
 - try/edge_cases/hash_symbolization_try.rb
 - try/edge_cases/json_serialization_try.rb
 - try/edge_cases/legacy_data_detection/deserialization_edge_cases_try.rb