familia 1.2.1 → 2.0.0.pre2

data/try/prototypes/atomic_saves_v2_connection_switching.rb

@@ -0,0 +1,161 @@
+# try/prototypes/atomic_saves_v2_connection_switching.rb
+
+# try -vf try/prototypes/atomic_saves_v2_connection_switching.rb
+
+require 'bundler/setup'
+require 'securerandom'
+
+require_relative '../helpers/test_helpers'
+require_relative 'lib/atomic_saves_v2_connection_switching_helpers'
+
+# Familia.debug = false
+
+## Clean database before tests
+BankAccount.dbclient.flushdb
+#=> "OK"
+
+## Test 1: Basic atomic save - create accounts
+@account1 = BankAccount.new(balance: 1000, holder_name: "Alice")
+@account2 = BankAccount.new(balance: 500, holder_name: "Bob")
+[@account1.balance, @account2.balance]
+#=> [1000.0, 500.0]
+
+## Test 1: Save initial state
+[@account1.save, @account2.save]
+#=> [true, true]
+
+## Test 1: Perform atomic transfer
+@results = Familia.atomic do
+  @account1.withdraw(200)
+  @account2.deposit(200)
+  @account1.save
+  @account2.save
+end
+@results.class
+#=> Array
+
+## Test 1: Verify transfer completed atomically
+@account1.refresh!
+@account2.refresh!
+[@account1.balance, @account2.balance]
+#=> [800.0, 700.0]
+
+## Test 2: Failed atomic operation - create accounts
+@account3 = BankAccount.new(balance: 100, holder_name: "Charlie")
+@account4 = BankAccount.new(balance: 500, holder_name: "Dave")
+[@account3.balance, @account4.balance]
+#=> [100.0, 500.0]
+
+## Test 2: Save initial state
+[@account3.save, @account4.save]
+#=> [true, true]
+
+## Test 2: Attempt atomic operation that should fail
+begin
+  Familia.atomic do
+    @account3.withdraw(200)
+    @account4.deposit(200)
+    @account3.save
+    @account4.save
+  end
+  false
+rescue => e
+  e.message
+end
+#=> "Insufficient funds"
+
+## Test 2: Verify rollback - balances unchanged
+@account3.refresh!
+@account4.refresh!
+[@account3.balance, @account4.balance]
+#=> [100.0, 500.0]
+
+## Test 3: Complex atomic operation - create accounts
+@sender = BankAccount.new(balance: 1500, holder_name: "Eve")
+@receiver = BankAccount.new(balance: 200, holder_name: "Frank")
+[@sender.save, @receiver.save]
+#=> [true, true]
+
+## Test 3: Setup transfer amount
+@transfer_amount = 750
+@transfer_amount
+#=> 750
+
+## Test 3: Perform complex atomic operation with transaction record
+@results2 = Familia.atomic do
+  @txn = TransactionRecord.new(
+    from: @sender.account_number,
+    to: @receiver.account_number,
+    amount: @transfer_amount
+  )
+
+  @sender.withdraw(@transfer_amount)
+  @receiver.deposit(@transfer_amount)
+  @txn.status = "completed"
+
+  [@sender.save, @receiver.save, @txn.save]
+end
+@results2.class
+#=> Array
+
+## Test 3: Verify all changes were applied
+@sender.refresh!
+@receiver.refresh!
+[@sender.balance, @receiver.balance]
+#=> [750.0, 950.0]
+
+## Test 3: Verify transaction record was saved
+@txn_key = @txn.dbkey
+@saved_txn = TransactionRecord.deserialize_value(@txn_key)
+@saved_txn.status
+#=> "completed"
+
+## Test 4: Nested context behavior - create account
+@account5 = BankAccount.new(balance: 1000, holder_name: "Grace")
+@account5.save
+#=> true
+
+## Test 4: Perform nested atomic operations
+@results3 = Familia.atomic do
+  @account5.deposit(100)
+  @account5.save
+
+  Familia.atomic do
+    @account5.deposit(50)
+    @account5.save
+  end
+end
+@results3.class
+#=> Array
+
+## Test 4: Verify nested operations worked transparently
+@account5.refresh!
+@account5.balance
+#=> 1150.0
+
+## Test 5: Batch update within atomic context - create account
+@account6 = BankAccount.new(balance: 500, holder_name: "Henry")
+@account6.save
+#=> true
+
+## Test 5: Perform batch update in atomic context
+@results4 = Familia.atomic do
+  @account6.batch_update(
+    balance: 600.0,
+    holder_name: "Henry Jr."
+  )
+
+  @txn2 = TransactionRecord.new(
+    from: "system",
+    to: @account6.account_number,
+    amount: 100
+  )
+  @txn2.save
+end
+@results4.class
+#=> Array
+
+## Test 5: Verify batch update and transaction creation
+@account6.refresh!
+[@account6.balance, @account6.holder_name]
+#=> [600.0, "Henry Jr."]

data/try/prototypes/atomic_saves_v3_connection_pool.rb

@@ -0,0 +1,189 @@
+# try/prototypes/atomic_saves_v3_connection_pool.rb
+
+# try -vf try/prototypes/atomic_saves_v3_connection_pool.rb
+
+# re: Test 4, calling refresh! inside of an existing transation.
+# The issue is that refresh! is being called within the transaction, but
+#  Database MULTI transactions queue commands and don't return results until
+#  EXEC. So refresh! inside the transaction isn't going to see the current
+#  state from Redis.
+#
+#  The problem is more fundamental: Database MULTI/EXEC transactions don't
+#  work the way this code expects them to. In Redis:
+#
+#  1. MULTI starts queuing commands
+#  2. All subsequent commands are queued, not executed
+#  3. EXEC executes all queued commands atomically
+#
+#  But this code is trying to:
+#  1. Call refresh! (which does a GET) inside the transaction - this won't
+#     work as expected
+#  2. Read the current balance and modify it - this won't work inside MULTI
+#
+#  The atomic operations need to be restructured to work with Redis's
+#  actual transaction model. Let me fix this:
+
+require 'bundler/setup'
+require 'securerandom'
+require 'thread'
+
+require_relative '../helpers/test_helpers'
+require_relative 'lib/atomic_saves_v3_connection_pool_helpers'
+
+# Familia.debug = false
+
+## Clean database before tests
+BankAccount.dbclient.flushdb
+#=> "OK"
+
+## Test 1: Basic atomic operation with proxy approach
+@account1 = BankAccount.new(balance: 1000, holder_name: "Alice")
+@account2 = BankAccount.new(balance: 500, holder_name: "Bob")
+[@account1.save, @account2.save]
+#=> [true, true]
+
+## Test 1: Proxy approach atomic transfer
+@proxy_results = Familia.atomic do
+  @account1.withdraw(200)
+  @account2.deposit(200)
+  @account1.save
+  @account2.save
+end
+@proxy_results.class
+#=> Array
+
+## Test 1: Verify proxy approach worked
+@account1.refresh!
+@account2.refresh!
+[@account1.balance, @account2.balance]
+#=> [800.0, 700.0]
+
+## Test 2: Explicit connection approach
+@account3 = BankAccount.new(balance: 1500, holder_name: "Charlie")
+@account4 = BankAccount.new(balance: 300, holder_name: "Dave")
+[@account3.save, @account4.save]
+#=> [true, true]
+
+## Test 2: Explicit approach atomic transfer
+@explicit_results = Familia.atomic_explicit do |conn|
+  @account3.withdraw(500)
+  @account4.deposit(500)
+  @account3.save(using: conn)
+  @account4.save(using: conn)
+end
+@explicit_results.class
+#=> Array
+
+## Test 2: Verify explicit approach worked
+@account3.refresh!
+@account4.refresh!
+[@account3.balance, @account4.balance]
+#=> [1000.0, 800.0]
+
+## Test 3: Nested transactions create separate transactions
+@account5 = BankAccount.new(balance: 2000, holder_name: "Eve")
+@account5.save
+#=> true
+
+## Test 3: Nested atomic operations (should be separate)
+@nested_results = Familia.atomic do
+  @account5.deposit(100)
+  @account5.save
+
+  # This should be a separate transaction
+  Familia.atomic do
+    @account5.deposit(200)
+    @account5.save
+  end
+end
+@nested_results.class
+#=> Array
+
+## Test 3: Verify nested operations both executed
+@account5.refresh!
+@account5.balance
+#=> 2300.0
+
+## Test 4: Concurrent operations test (thread safety)
+@shared_account = BankAccount.new(balance: 10000, holder_name: "Shared")
+@shared_account.save
+#=> true
+
+## Test 4: Run concurrent atomic operations
+@threads = []
+@results_array = []
+@mutex = Mutex.new
+
+5.times do |i|
+  @threads << Thread.new do
+    result = Familia.atomic do
+      # Each thread performs an atomic operation
+      @shared_account.refresh!
+      current_balance = @shared_account.balance
+      @shared_account.balance = current_balance.to_f - 100
+      @shared_account.save
+    end
+
+    @mutex.synchronize { @results_array << result }
+  end
+end
+
+# Wait for all threads to complete
+@threads.each(&:join)
+@results_array.size
+#=> 5
+
+## Test 4: Verify concurrent operations worked correctly
+@shared_account.refresh!
+@shared_account.balance
+#=> 9500.0
+
+## Test 5: Connection pool behavior verification
+@initial_pool_size = Familia.connection_pool.size
+@initial_pool_size
+#=> 10
+
+## Test 5: Connection pool with multiple operations
+@pool_test_results = []
+3.times do |i|
+  @pool_test_results << Familia.atomic do
+    account = BankAccount.new(balance: 1000, holder_name: "Pool#{i}")
+    account.save
+  end
+end
+@pool_test_results.size
+#=> 3
+
+## Test 6: Error handling and rollback
+@error_account = BankAccount.new(balance: 100, holder_name: "ErrorTest")
+@error_account.save
+#=> true
+
+## Test 6: Atomic operation that should fail and rollback
+begin
+  Familia.atomic do
+    @error_account.withdraw(200)  # Should fail
+    @error_account.save
+  end
+  false
+rescue => e
+  e.message
+end
+#=> "Insufficient funds"
+
+## Test 6: Verify account balance unchanged after error
+@error_account.refresh!
+@error_account.balance
+#=> 100.0
+
+## Summary: Connection Pool Integration Results
+#
+# ✅ Proxy approach works with connection pooling
+# ✅ Explicit approach provides clear transaction boundaries
+# ✅ Nested transactions create separate transactions (as intended)
+# ✅ Thread safety handled automatically by connection pool
+# ✅ Error handling and rollback work correctly
+# ✅ Connection pool manages resources efficiently
+#
+# Key Finding: Connection pool handles thread safety automatically
+# No special thread-safety code needed - just proper pool integration

data/try/prototypes/atomic_saves_v4.rb

@@ -0,0 +1,105 @@
+# try/prototypes/atomic_saves_v4.rb
+
+class BankAccount < Familia::Horreum
+  class_sorted_set :relatable_object_ids
+
+  identifier_field :account_number
+  field :account_number
+  field :balance
+  field :foreign_balance
+  field :holder_name
+
+  string :metadata  # A separate dbkey, to store JSON blog
+
+  def init
+    @account_number ||= SecureRandom.hex(8)
+    @balance = @balance.to_f if @balance
+    @foreign_balance = @foreign_balance.to_f if @foreign_balance
+    @metadata = @metadata.is_a?(String) ? JSON.parse(@metadata) : @metadata
+  end
+
+  def balance
+    @balance&.to_f
+  end
+
+  def withdraw(amount)
+    raise "Insufficient funds" if balance < amount
+    self.balance -= amount
+  end
+
+  def deposit(amount)
+    # This is PURPOSE3, for complex updates for objects that already exist.
+    self.transaction do
+      self.balance += amount
+      self.foreign_balance = balance * 1.25 # exchange rate
+    end
+  end
+
+  def an_example_that_we_do_not_want
+    # This is how multi worked in Familia before this project. This
+    # is what we are trying to avoid by not using blocks. However,
+    # it's not the block that is the issue; it's losing the object
+    # oriented `self.fieldname = value` syntax and having to manually
+    # resort to functional programming.
+    dbclient.multi do |multi|
+      multi.del(dbkey)
+      # Also remove from the class-level values, :display_domains, :owners
+      multi.zrem(V2::CustomDomain.values.dbkey, identifier)
+      multi.hdel(V2::CustomDomain.display_domains.dbkey, display_domain)
+      multi.hdel(V2::CustomDomain.owners.dbkey, display_domain)
+      multi.del(brand.dbkey)
+      multi.del(logo.dbkey)
+      multi.del(icon.dbkey)
+      unless customer.nil?
+        multi.zrem(customer.custom_domains.dbkey, display_domain)
+      end
+    end
+  end
+
+  def metadata=(value)
+    @metadata = value.is_a?(Hash) || value.is_a?(Array) ? JSON.generate(value) : value
+  end
+
+  class << self
+    def create(account_number, holder_name, metadata = {})
+
+      attrs = {
+        account_number: account_number,
+        balance: 0.0,
+        holder_name: holder_name,
+        metadata: metadata
+      }
+
+      # By convention, we would not write any code that runs on initialization
+      # that has any database operations. However if we did, they would still work
+      # the would just run immediately and not with the following transaction.
+      accnt = new attrs
+
+      Familia.transaction do
+
+        # Inside this block, `accnt.dbclient` returns the open multi connection.
+        #
+        # Anything that calls database commands, will be queues on the multi
+        # connection, like attr.metadata = {...}. So neither the main object
+        # key or the separate `metadata` string key will update unless both
+        # succeed. This is PURPOSE1.
+        accnt.save
+
+        # PROBLEM: what is returned here when we call accnt.class.dbclient? where
+        # does a class level method like `add` get its db connection from then?
+        #
+        # This is PURPOSE2, a major reason for implementing transactions. We want
+        # to prevent our relatable_object_ids index from being updated if the
+        # account save fails.
+        add accnt
+
+        # Transaction method returns the block return
+        accnt
+      end
+    end
+
+    def add(accnt)
+      relatable_object_ids.add Time.now.to_f, accnt.identifier
+    end
+  end
+end

data/try/prototypes/lib/atomic_saves_v2_connection_switching_helpers.rb

@@ -0,0 +1,124 @@
+# try/prototypes/lib/atomic_saves_v2_connection_switching_helpers.rb
+
+##
+# Atomic Save V2 Proof of Concept - Connection Switching Approach
+#
+# This implementation demonstrates atomic saves across multiple Familia
+# objects by switching which Database connection the `dbclient` method returns
+# based on transaction context.
+#
+# Key Features:
+# 1. **Connection Switching**: The `dbclient` method returns either normal
+#    connection or MULTI connection based on Thread-local context
+# 2. **Thread Safety**: Uses Thread-local storage for transaction state
+# 3. **No method_missing**: Clean implementation via method overriding
+# 4. **Database MULTI/EXEC**: Leverages Redis's native transaction support
+#
+# Design Decision: TransactionalMethods Module REMOVED
+#
+# We prefer that nested `Familia.atomic` calls create separate transactions
+# rather than being merged into the parent transaction. This provides clearer
+# transaction boundaries and more predictable behavior:
+#
+# Familia.atomic do
+#   account.save              # Transaction 1
+#
+#   Familia.atomic do
+#     account.batch_update()  # Transaction 2 (separate)
+#   end
+# end
+#
+# This approach avoids the complexity of the TransactionalMethods module
+# and makes transaction scope explicit and predictable.
+
+
+# Test models first - define before any module modifications
+class BankAccount < Familia::Horreum
+  identifier_field :account_number
+  field :account_number
+  field :balance
+  field :holder_name
+
+  def initialize(account_number: nil, balance: 0, holder_name: nil)
+    @account_number = account_number || SecureRandom.hex(8)
+    @balance = balance.to_f
+    @holder_name = holder_name
+  end
+
+  def withdraw(amount)
+    raise "Insufficient funds" if balance < amount
+    self.balance -= amount
+  end
+
+  def deposit(amount)
+    self.balance += amount
+  end
+end
+
+class TransactionRecord < Familia::Horreum
+  identifier_field :transaction_id
+  field :transaction_id
+  field :from_account
+  field :to_account
+  field :amount
+  field :status
+  field :created_at
+
+  def initialize(from: nil, to: nil, amount: 0)
+    @transaction_id = SecureRandom.hex(8)
+    @from_account = from
+    @to_account = to
+    @amount = amount.to_f
+    @status = "pending"
+    @created_at = Time.now.to_i
+  end
+end
+
+# Atomic Save V2 - Connection-switching approach
+module Familia
+  class << self
+    def current_transaction
+      Thread.current[:familia_current_transaction]
+    end
+
+    def current_transaction=(transaction)
+      Thread.current[:familia_current_transaction] = transaction
+    end
+
+    def atomic(&block)
+      if current_transaction
+        # Already in a transaction, just execute the block
+        yield
+      else
+        # Use Database multi with block form
+        dbclient.multi do |multi|
+          begin
+            self.current_transaction = multi
+            yield
+          ensure
+            self.current_transaction = nil
+          end
+        end
+      end
+    end
+  end
+
+  # Override the dbclient method in both base classes
+  module TransactionalDatabase
+    def dbclient
+      Familia.current_transaction || super
+    end
+  end
+
+  # Inject into Horreum - TransactionalMethods module removed per design decision
+  class Horreum
+    module Serialization
+      prepend TransactionalDatabase
+    end
+  end
+
+  # Inject into DataType
+  class DataType
+    prepend TransactionalDatabase
+  end
+end