familia 2.0.0.pre18 → 2.0.0.pre19

data/try/unit/horreum/automatic_index_validation_try.rb

@@ -0,0 +1,253 @@
+# try/unit/horreum/automatic_index_validation_try.rb
+
+#
+# Automatic index validation tests
+# Tests that unique index validation happens automatically when adding to indexes
+#
+
+require_relative '../../support/helpers/test_helpers'
+
+# Test classes for automatic validation
+class ::AutoValidCompany < Familia::Horreum
+  feature :relationships
+
+  identifier_field :company_id
+  field :company_id
+  field :name
+end
+
+class ::AutoValidEmployee < Familia::Horreum
+  feature :relationships
+
+  identifier_field :emp_id
+  field :emp_id
+  field :badge_number
+  field :email
+
+  # Instance-scoped unique index (should auto-validate in add_to_* methods)
+  unique_index :badge_number, :badge_index, within: AutoValidCompany
+
+  # Class-level unique index (auto-validates in save)
+  unique_index :email, :email_index
+end
+
+class ::AutoValidUser < Familia::Horreum
+  feature :relationships
+
+  identifier_field :user_id
+  field :user_id
+  field :email
+
+  unique_index :email, :email_index
+end
+
+# Setup
+@company_id = "comp_#{rand(1000000)}"
+@company = AutoValidCompany.new(company_id: @company_id, name: 'Test Corp')
+@company.save
+
+@emp1_id = "emp_#{rand(1000000)}"
+@emp2_id = "emp_#{rand(1000000)}"
+
+# =============================================
+# 1. Automatic Validation in add_to_* Methods
+# =============================================
+
+## First employee can add badge to company index
+@emp1 = AutoValidEmployee.new(emp_id: @emp1_id, badge_number: 'BADGE123', email: 'emp1@example.com')
+@emp1.save  # Save first to establish class-level email index
+@emp1.add_to_auto_valid_company_badge_index(@company)
+@company.badge_index.has_key?('BADGE123')
+#=> true
+
+## Duplicate badge is automatically rejected without manual guard call
+@emp2 = AutoValidEmployee.new(emp_id: @emp2_id, badge_number: 'BADGE123', email: 'emp2@example.com')
+begin
+  @emp2.add_to_auto_valid_company_badge_index(@company)
+  false
+rescue Familia::RecordExistsError => e
+  e.message.include?('AutoValidEmployee exists in AutoValidCompany with badge_number=BADGE123')
+end
+#=> true
+
+## Badge was not added after validation failure
+@company.badge_index.get('BADGE123')
+#=> @emp1_id
+
+## Different badge number works fine
+@emp2.badge_number = 'BADGE456'
+@emp2.add_to_auto_valid_company_badge_index(@company)
+@company.badge_index.has_key?('BADGE456')
+#=> true
+
+## Same employee can re-add (idempotent)
+@emp1.add_to_auto_valid_company_badge_index(@company)
+@company.badge_index.get('BADGE123')
+#=> @emp1_id
+
+## Different company allows same badge (scoped uniqueness)
+@company2_id = "comp_#{rand(1000000)}"
+@company2 = AutoValidCompany.new(company_id: @company2_id, name: 'Other Corp')
+@company2.save
+@emp3_id = "emp_#{rand(1000000)}"
+@emp3 = AutoValidEmployee.new(emp_id: @emp3_id, badge_number: 'BADGE123', email: 'emp3@example.com')
+@emp3.add_to_auto_valid_company_badge_index(@company2)
+@company2.badge_index.has_key?('BADGE123')
+#=> true
+
+## Nil badge_number handled gracefully (no validation or addition)
+@emp_nil = AutoValidEmployee.new(emp_id: "emp_nil_#{rand(1000000)}", badge_number: nil, email: 'empnil@example.com')
+@emp_nil.add_to_auto_valid_company_badge_index(@company)
+#=> nil
+
+## Nil parent handled gracefully (no validation or addition)
+@emp4 = AutoValidEmployee.new(emp_id: "emp4_#{rand(1000000)}", badge_number: 'BADGE789', email: 'emp4@example.com')
+@emp4.add_to_auto_valid_company_badge_index(nil)
+#=> nil
+
+# =============================================
+# 2. Transaction Detection in save()
+# =============================================
+
+## Normal save works outside transaction
+@user1_id = "user_#{rand(1000000)}"
+@user1 = AutoValidUser.new(user_id: @user1_id, email: 'user1@example.com')
+@user1.save
+#=> true
+
+## save() raises error when called within transaction
+@user2_id = "user_#{rand(1000000)}"
+begin
+  AutoValidUser.transaction do
+    @user2 = AutoValidUser.new(user_id: @user2_id, email: 'user2@example.com')
+    @user2.save
+  end
+  false
+rescue Familia::OperationModeError => e
+  e.message.include?('Cannot call save within a transaction')
+end
+#=> true
+
+## Object was not saved due to transaction error
+AutoValidUser.find_by_email('user2@example.com')
+#=> nil
+
+## Transaction with explicit field updates works (bypass save)
+@user3_id = "user_#{rand(1000000)}"
+@user3 = AutoValidUser.new(user_id: @user3_id, email: 'user3@example.com')
+AutoValidUser.transaction do |_tx|
+  @user3.hmset(@user3.to_h_for_storage)
+end
+@user3.exists?
+#=> true
+
+## save() works after transaction completes
+@user4_id = "user_#{rand(1000000)}"
+AutoValidUser.transaction do
+  # Do something else in transaction
+end
+@user4 = AutoValidUser.new(user_id: @user4_id, email: 'user4@example.com')
+@user4.save
+#=> true
+
+# =============================================
+# 3. Combined Automatic Validation Scenarios
+# =============================================
+
+## Employee with duplicate class-level email caught in save
+@emp5_id = "emp_#{rand(1000000)}"
+@emp5 = AutoValidEmployee.new(emp_id: @emp5_id, badge_number: 'BADGE999', email: 'emp1@example.com')
+begin
+  @emp5.save
+  false
+rescue Familia::RecordExistsError => e
+  e.message.include?('AutoValidEmployee exists email=emp1@example.com')
+end
+#=> true
+
+## Employee can save with unique email
+@emp1.save
+AutoValidEmployee.find_by_email('emp1@example.com')&.emp_id
+#=> @emp1_id
+
+## After save, duplicate instance-scoped index still caught automatically
+@emp6_id = "emp_#{rand(1000000)}"
+@emp6 = AutoValidEmployee.new(emp_id: @emp6_id, badge_number: 'BADGE123', email: 'emp6@example.com')
+@emp6.save  # Class-level index is fine
+begin
+  @emp6.add_to_auto_valid_company_badge_index(@company)  # Instance-scoped duplicate
+  false
+rescue Familia::RecordExistsError => e
+  e.message.include?('badge_number=BADGE123')
+end
+#=> true
+
+# =============================================
+# 4. Error Message Quality
+# =============================================
+
+## Instance-scoped validation error includes both class names
+begin
+  @emp2.badge_number = 'BADGE123'  # Reset to duplicate
+  @emp2.add_to_auto_valid_company_badge_index(@company)
+rescue Familia::RecordExistsError => e
+  [e.message.include?('AutoValidEmployee'), e.message.include?('AutoValidCompany')]
+end
+#=> [true, true]
+
+## Instance-scoped validation error includes field name and value
+begin
+  @emp2.add_to_auto_valid_company_badge_index(@company)
+rescue Familia::RecordExistsError => e
+  [e.message.include?('badge_number'), e.message.include?('BADGE123')]
+end
+#=> [true, true]
+
+## Error type is RecordExistsError
+begin
+  @emp2.add_to_auto_valid_company_badge_index(@company)
+rescue => e
+  e.class
+end
+#=> Familia::RecordExistsError
+
+# =============================================
+# 5. Performance - No Double Validation
+# =============================================
+
+## Manual guard call before add_to_* is redundant but harmless
+@emp7_id = "emp_#{rand(1000000)}"
+@emp7 = AutoValidEmployee.new(emp_id: @emp7_id, badge_number: 'BADGE777', email: 'emp7@example.com')
+@emp7.guard_unique_auto_valid_company_badge_index!(@company)
+@emp7.add_to_auto_valid_company_badge_index(@company)
+@company.badge_index.has_key?('BADGE777')
+#=> true
+
+## Manual guard call detects duplicate
+@emp8_id = "emp_#{rand(1000000)}"
+@emp8 = AutoValidEmployee.new(emp_id: @emp8_id, badge_number: 'BADGE777', email: 'emp8@example.com')
+begin
+  @emp8.guard_unique_auto_valid_company_badge_index!(@company)  # Should fail - duplicate badge
+  false
+rescue Familia::RecordExistsError
+  true
+end
+#=> true
+
+# Teardown - clean up test objects
+[@emp1, @emp2, @emp3, @emp_nil, @emp4, @emp5, @emp6, @emp7, @emp8].compact.each do |obj|
+  obj.destroy! if obj.respond_to?(:destroy!) && obj.respond_to?(:exists?) && obj.exists?
+end
+
+[@user1, @user3, @user4].compact.each do |obj|
+  obj.destroy! if obj.respond_to?(:destroy!) && obj.respond_to?(:exists?) && obj.exists?
+end
+
+[@company, @company2].each do |obj|
+  obj.destroy! if obj.respond_to?(:destroy!) && obj.respond_to?(:exists?) && obj.exists?
+end
+
+# Clean up class-level indexes
+[AutoValidEmployee.email_index, AutoValidUser.email_index].each do |index|
+  index.delete! if index.respond_to?(:delete!) && index.respond_to?(:exists?) && index.exists?
+end

data/try/unit/horreum/base_try.rb

@@ -41,7 +41,7 @@ Familia.debug = false
 
 ## Remove the key
 @hashkey.delete!
-#=> true
+#=> 1
 
 ## Horreum objects can update and save their fields (1 of 2)
 @customer.name = 'John Doe'

data/try/unit/horreum/class_methods_try.rb

@@ -16,9 +16,9 @@ module AnotherModuleName
   end
 end
 
-## create factory method with existence checking
+## create! factory method with existence checking
 TestUser
-#==> _.respond_to?(:create)
+#==> _.respond_to?(:create!)
 #==> _.respond_to?(:exists?)
 
 ## multiget method is available

data/try/unit/horreum/initialization_try.rb

@@ -101,7 +101,7 @@ Familia.debug = false
 
 ## Clean up saved test objects
 [@customer6, @complex].map(&:delete!)
-#=> [true, true]
+#=> [1, 1]
 
 ## "Cleaning up" test objects that were never saved returns true regardless
 ## b/c it takes place in a transaction and it's the transaction's success

data/try/unit/horreum/relations_try.rb

@@ -92,15 +92,15 @@ prefs = @test_user.preferences
 @test_user.preferences.size
 #=> 2
 
-## Clearing a counter returns false when not set yet
+## Clearing a counter returns 0 when not set yet
 @test_product.views.clear
 @test_product.views.clear
-#=> false
+#=> 0
 
-## Clearing a counter returns true when it is set
+## Clearing a counter returns 1 when it is set
 @test_product.views.increment
 @test_product.views.clear
-#=> true
+#=> 1
 
 ## Counter Database type works
 @test_product.views.increment

data/try/unit/horreum/serialization_try.rb

@@ -20,10 +20,10 @@ Familia.dbclient.set('debug:starting_save_if_not_exists_tests', Familia.now.to_s
 @new_customer.save_if_not_exists
 #=> true
 
-## save_if_not_exists raises error when customer already exists
+## save_if_not_exists! raises error when customer already exists
 @duplicate_customer = Customer.new "new-customer-#{@test_id}@test.com"
 @duplicate_customer.name = 'Duplicate Customer'
-@duplicate_customer.save_if_not_exists
+@duplicate_customer.save_if_not_exists!
 #=!> Familia::RecordExistsError
 #==> error.message.include?("Key already exists")
 

data/try/unit/horreum/unique_index_edge_cases_try.rb

@@ -0,0 +1,376 @@
+# Testing edge cases for unique index validation
+# lib/familia/features/relationships/indexing/unique_index_generators.rb
+# lib/familia/horreum/persistence.rb
+
+require_relative '../../../lib/familia'
+
+Familia.debug = false
+
+# ========================================
+# Setup: Define test models
+# ========================================
+
+class EdgeCaseCompany < Familia::Horreum
+  feature :relationships
+
+  identifier_field :company_id
+  field :company_id
+  field :company_name
+
+  # init receives no arguments - fields already set from new()
+  # Use ||= to apply defaults if needed
+  def init
+    # No defaults needed for this class
+    # Could add: @company_name ||= 'Unknown Company'
+  end
+end
+
+class EdgeCaseEmployee < Familia::Horreum
+  feature :relationships
+
+  identifier_field :emp_id
+  field :emp_id
+  field :email
+  field :badge_number
+  field :department
+  field :status
+
+  # Class-level unique index for email (auto-populates on save)
+  unique_index :email, :email_index
+
+  # Instance-scoped unique index for badge_number within Company
+  unique_index :badge_number, :badge_index, within: EdgeCaseCompany
+
+  # Multi-index for department (1:many) within Company
+  multi_index :department, :dept_index, within: EdgeCaseCompany
+
+  # init receives no arguments - fields already set from new()
+  # Use ||= to apply defaults if needed
+  def init
+    @status ||= 'active'  # Apply default status if not provided
+  end
+end
+
+class EdgeCaseProduct < Familia::Horreum
+  feature :relationships
+
+  identifier_field :product_id
+  field :product_id
+  field :sku
+
+  # Allow empty strings in unique index
+  unique_index :sku, :sku_index
+
+  # init receives no arguments - fields already set from new()
+  # Use ||= to apply defaults if needed
+  def init
+    # No defaults needed for this class
+  end
+end
+
+# Clear all indexes before starting
+EdgeCaseEmployee.email_index.clear
+EdgeCaseProduct.sku_index.clear
+
+# ========================================
+# Test 1: Duplicate instance-scoped index values
+# ========================================
+
+## Setup companies and employees
+@company1 = EdgeCaseCompany.new(company_id: 'c1', company_name: 'Acme Corp')
+@company2 = EdgeCaseCompany.new(company_id: 'c2', company_name: 'Tech Inc')
+@company1.save
+@company2.save
+#=> true
+
+## Create employee with badge_number in company1
+@emp1 = EdgeCaseEmployee.new(emp_id: 'e1', email: 'john@test.com', badge_number: 'B12345')
+@emp1.save  # This auto-populates email index
+@emp1.add_to_edge_case_company_badge_index(@company1)  # Manual for instance-scoped
+@company1.find_by_badge_number('B12345')&.emp_id
+#=> 'e1'
+
+## Create another employee with same badge_number - guard should detect duplicate
+@emp2 = EdgeCaseEmployee.new(emp_id: 'e2', email: 'jane@test.com', badge_number: 'B12345')
+@emp2.save  # Different email is OK
+begin
+  @emp2.guard_unique_edge_case_company_badge_index!(@company1)
+  false
+rescue Familia::RecordExistsError
+  true
+end
+#=> true
+
+## Same badge_number should work in different company (different scope)
+@emp2.add_to_edge_case_company_badge_index(@company2)
+@company2.find_by_badge_number('B12345')&.emp_id
+#=> 'e2'
+
+## Verify badge exists in both companies with different employees
+[@company1.find_by_badge_number('B12345')&.emp_id, @company2.find_by_badge_number('B12345')&.emp_id]
+#=> ['e1', 'e2']
+
+## Cleanup for next test
+EdgeCaseEmployee.email_index.clear
+@company1.badge_index.clear
+@company2.badge_index.clear
+#=> 1
+
+# ========================================
+# Test 2: Field updates with auto-index cleanup
+# ========================================
+
+## Create employee with email (save auto-populates index)
+@emp3 = EdgeCaseEmployee.new(emp_id: 'e3', email: 'original@test.com')
+@emp3.save
+EdgeCaseEmployee.find_by_email('original@test.com')&.emp_id
+#=> 'e3'
+
+## Update email - must manually update index (no automatic cleanup on field change)
+old_email = @emp3.email
+@emp3.email = 'updated@test.com'
+@emp3.update_in_class_email_index(old_email)  # Manual update required
+EdgeCaseEmployee.find_by_email('original@test.com')
+#=> nil
+
+## New email should resolve to employee
+EdgeCaseEmployee.find_by_email('updated@test.com')&.emp_id
+#=> 'e3'
+
+## Update instance-scoped index
+@emp3.badge_number = 'B99999'
+@emp3.add_to_edge_case_company_badge_index(@company1)
+@company1.find_by_badge_number('B99999')&.emp_id
+#=> 'e3'
+
+## Change badge and update index
+old_badge = @emp3.badge_number
+@emp3.badge_number = 'B11111'
+@emp3.update_in_edge_case_company_badge_index(@company1, old_badge)
+@company1.find_by_badge_number('B99999')
+#=> nil
+
+## New badge should work
+@company1.find_by_badge_number('B11111')&.emp_id
+#=> 'e3'
+
+## Cleanup
+EdgeCaseEmployee.email_index.clear
+@company1.badge_index.clear
+#=> 1
+
+# ========================================
+# Test 3: Save within explicit transactions (validation bypass)
+# ========================================
+
+## Create first employee successfully
+@emp4 = EdgeCaseEmployee.new(emp_id: 'e4', email: 'txn@test.com')
+@emp4.save
+EdgeCaseEmployee.find_by_email('txn@test.com')&.emp_id
+#=> 'e4'
+
+## Save cannot be called inside transaction - it raises OperationModeError
+@emp5 = EdgeCaseEmployee.new(emp_id: 'e5', email: 'txn@test.com')
+error_raised = false
+begin
+  EdgeCaseEmployee.transaction do |tx|
+    @emp5.save  # This will raise
+  end
+rescue Familia::OperationModeError => e
+  error_raised = e.message.include?("Cannot call save within a transaction")
+end
+error_raised
+#=> true
+
+## However, we can bypass validation by manually adding to index inside transaction
+result = EdgeCaseEmployee.transaction do |tx|
+  # Manually add without validation (dangerous!)
+  EdgeCaseEmployee.email_index['txn_bypass@test.com'] = 'e5'
+  'manual_bypass'
+end
+result.successful?
+#=> true
+
+## After transaction, the manual entry exists (no validation occurred)
+EdgeCaseEmployee.email_index['txn_bypass@test.com']
+#=> 'e5'
+
+## After transaction, the manual entry exists (no validation occurred)
+EdgeCaseEmployee.email_index['txn_bypass@test.com']
+#=> 'e5'
+
+## Cleanup
+EdgeCaseEmployee.email_index.clear
+#=> 1
+
+# ========================================
+# Test 4: Multiple empty string values in same index
+# ========================================
+
+## Create product with empty SKU
+@prod1 = EdgeCaseProduct.new(product_id: 'p1', sku: '')
+@prod1.save
+EdgeCaseProduct.find_by_sku('')&.product_id
+#=> 'p1'
+
+## Try to create another product with empty SKU - should fail
+@prod2 = EdgeCaseProduct.new(product_id: 'p2', sku: '')
+begin
+  @prod2.save
+  false
+rescue Familia::RecordExistsError => e
+  e.message.include?('sku=')
+end
+#=> true
+
+## nil values should be skipped (not indexed)
+@prod3 = EdgeCaseProduct.new(product_id: 'p3', sku: nil)
+@prod3.save  # Should succeed - nil values aren't indexed
+@prod3.identifier
+#=> 'p3'
+
+## Verify nil doesn't exist in index (empty string != nil)
+EdgeCaseProduct.sku_index['']  # Empty string key
+#=> 'p1'
+
+## nil is not indexed
+EdgeCaseProduct.sku_index.keys.include?(nil)
+#=> false
+
+## Cleanup
+EdgeCaseProduct.sku_index.clear
+#=> 1
+
+# ========================================
+# Test 5: Concurrent saves with same unique value
+# ========================================
+
+## Setup fresh index
+EdgeCaseEmployee.email_index.clear
+#=> 0
+
+## Create two employees with same email (simulating race condition)
+@emp6 = EdgeCaseEmployee.new(emp_id: 'e6', email: 'race@test.com')
+@emp7 = EdgeCaseEmployee.new(emp_id: 'e7', email: 'race@test.com')
+@emp7.emp_id
+#=> 'e7'
+
+## First save succeeds
+@emp6.save
+EdgeCaseEmployee.find_by_email('race@test.com')&.emp_id
+#=> 'e6'
+
+## Second save fails due to validation
+begin
+  @emp7.save
+  false
+rescue Familia::RecordExistsError
+  true
+end
+#=> true
+
+## Simulate race condition: both check validation, then both write
+EdgeCaseEmployee.email_index.clear
+@emp8 = EdgeCaseEmployee.new(emp_id: 'e8', email: 'race2@test.com')
+@emp9 = EdgeCaseEmployee.new(emp_id: 'e9', email: 'race2@test.com')
+[@emp8.emp_id, @emp9.emp_id]
+#=> ['e8', 'e9']
+
+## Both pass validation check (index is empty)
+begin
+  @emp8.guard_unique_email_index!
+  @emp9.guard_unique_email_index!
+  true
+rescue
+  false
+end
+#=> true
+
+## Both write to index (last write wins in Redis)
+@emp8.add_to_class_email_index
+@emp9.add_to_class_email_index
+# Verify the index contains the identifier (orphaned entry - wastes space but harmless)
+EdgeCaseEmployee.email_index['race2@test.com']
+#=> 'e9'
+
+## find_by returns nil for orphaned index entries (object never saved)
+# This is correct behavior - orphaned entries degrade gracefully to nil
+EdgeCaseEmployee.find_by_email('race2@test.com')
+#=> nil
+
+## To properly handle concurrent saves, check existence inside transaction
+# Note: Can't read inside MULTI block, so need WATCH/MULTI pattern
+result = nil
+EdgeCaseEmployee.dbclient.watch('edge_case_employee:email_index') do
+  if EdgeCaseEmployee.email_index['race3@test.com'].nil?
+    EdgeCaseEmployee.transaction do |tx|
+      EdgeCaseEmployee.email_index['race3@test.com'] = 'e10'
+      result = 'success'
+    end
+  else
+    result = 'duplicate'
+  end
+end
+result
+#=> 'success'
+
+## Cleanup
+EdgeCaseEmployee.email_index.clear
+#=> 1
+
+# ========================================
+# Edge Case: Update with validation in compound operation
+# ========================================
+
+## Test compound index updates in transaction
+@company3 = EdgeCaseCompany.new(company_id: 'c3', company_name: 'Test Corp')
+@company3.save
+#=> true
+
+## Create employee
+@emp11 = EdgeCaseEmployee.new(emp_id: 'e11', email: 'compound@test.com', badge_number: 'B555')
+@emp11.save
+@emp11.add_to_edge_case_company_badge_index(@company3)
+@emp11.emp_id
+#=> 'e11'
+
+## Update multiple indexed fields atomically
+@emp11 = EdgeCaseEmployee.new(emp_id: 'e11', email: 'compound@test.com', badge_number: 'B555')
+@emp11.save
+@emp11.add_to_edge_case_company_badge_index(@company3)
+
+old_email = @emp11.email
+old_badge = @emp11.badge_number
+@emp11.email = 'compound_new@test.com'
+@emp11.badge_number = 'B666'
+
+# Update both indexes in single transaction
+result = EdgeCaseEmployee.transaction do |tx|
+  @emp11.update_in_class_email_index(old_email)
+  @emp11.update_in_edge_case_company_badge_index(@company3, old_badge)
+  'updated'
+end
+result.successful?
+#=> true
+
+## Verify updates succeeded
+[EdgeCaseEmployee.find_by_email('compound_new@test.com')&.emp_id, @company3.find_by_badge_number('B666')&.emp_id]
+#=> ['e11', 'e11']
+
+## Old values should be gone
+[EdgeCaseEmployee.find_by_email('compound@test.com'), @company3.find_by_badge_number('B555')]
+#=> [nil, nil]
+
+
+# Final cleanup
+EdgeCaseEmployee.email_index.clear
+if @company3&.respond_to?(:badge_index) && @company3.badge_index.respond_to?(:clear)
+  @company3.badge_index.clear
+end
+
+# Clean up test objects - check if they still exist before destroying
+[@company1, @company2, @company3].compact.each do |obj|
+  obj.destroy! if obj.respond_to?(:destroy!) && obj.respond_to?(:exists?) && obj.exists?
+end
+
+puts "All edge case tests completed"