familia 2.0.0.pre5 → 2.0.0.pre7

data/examples/redis_command_validation_example.rb

@@ -0,0 +1,231 @@
+#!/usr/bin/env ruby
+
+# examples/redis_command_validation_example.rb
+#
+# Comprehensive example demonstrating Redis command validation for Familia
+# This example shows how to validate that Redis operations execute exactly
+# as expected, with particular focus on atomic operations.
+
+require_relative '../lib/familia'
+require_relative '../lib/familia/validation'
+
+# Enable database logging for visibility
+Familia.enable_database_logging = true
+Familia.enable_database_counter = true
+
+# Example models for validation demonstration
+class Account < Familia::Horreum
+  identifier_field :account_id
+  field :account_id
+  field :balance
+  field :status
+  field :last_updated
+end
+
+class TransferService
+  def self.atomic_transfer(from_account, to_account, amount)
+    # Proper atomic implementation using Familia transaction
+    from_balance = from_account.balance.to_i - amount
+    to_balance = to_account.balance.to_i + amount
+
+    Familia.transaction do |conn|
+      conn.hset(from_account.dbkey, 'balance', from_balance.to_s)
+      conn.hset(to_account.dbkey, 'balance', to_balance.to_s)
+      conn.hset(from_account.dbkey, 'last_updated', Time.now.to_i.to_s)
+      conn.hset(to_account.dbkey, 'last_updated', Time.now.to_i.to_s)
+    end
+
+    # Update local state
+    from_account.balance = from_balance.to_s
+    to_account.balance = to_balance.to_s
+  end
+
+  def self.non_atomic_transfer(from_account, to_account, amount)
+    # Non-atomic implementation (BAD - for demonstration)
+    from_account.balance = (from_account.balance.to_i - amount).to_s
+    to_account.balance = (to_account.balance.to_i + amount).to_s
+
+    from_account.save
+    to_account.save
+  end
+end
+
+puts "🧪 Redis Command Validation Framework Demo"
+puts "=" * 50
+
+# Clean up any existing test data
+cleanup_keys = Familia.dbclient.keys("account:*")
+Familia.dbclient.del(*cleanup_keys) if cleanup_keys.any?
+
+# Example 1: Basic Command Recording
+puts "\n1. Basic Command Recording"
+puts "-" * 30
+
+CommandRecorder = Familia::Validation::CommandRecorder
+CommandRecorder.start_recording
+
+account = Account.new(account_id: "acc001", balance: "1000", status: "active")
+account.save
+
+commands = CommandRecorder.stop_recording
+puts "Recorded #{commands.command_count} commands:"
+commands.commands.each { |cmd| puts "  #{cmd}" }
+
+# Example 2: Transaction Detection
+puts "\n2. Transaction Detection"
+puts "-" * 30
+
+CommandRecorder.start_recording
+
+acc1 = Account.new(account_id: "acc002", balance: "2000")
+acc2 = Account.new(account_id: "acc003", balance: "500")
+acc1.save
+acc2.save
+
+TransferService.atomic_transfer(acc1, acc2, 500)
+
+commands = CommandRecorder.stop_recording
+puts "Commands executed: #{commands.command_count}"
+puts "Transactions detected: #{commands.transaction_count}"
+
+if commands.transaction_blocks.any?
+  tx = commands.transaction_blocks.first
+  puts "Transaction commands: #{tx.command_count}"
+  tx.commands.each { |cmd| puts "  [TX] #{cmd}" }
+end
+
+# Example 3: Validation with Expectations DSL
+puts "\n3. Command Validation with Expectations"
+puts "-" * 30
+
+begin
+  validator = Familia::Validation::Validator.new
+
+  # This should pass - we expect the exact Redis commands
+  result = validator.validate do |expect|
+    expect.transaction do |tx|
+      tx.hset("account:acc004:object", "balance", "1500")
+        .hset("account:acc005:object", "balance", "1000")
+        .hset("account:acc004:object", "last_updated", Familia::Validation::ArgumentMatcher.new(:any_string))
+        .hset("account:acc005:object", "last_updated", Familia::Validation::ArgumentMatcher.new(:any_string))
+    end
+
+    # Execute the operation
+    acc4 = Account.new(account_id: "acc004", balance: "2000")
+    acc5 = Account.new(account_id: "acc005", balance: "500")
+    acc4.save
+    acc5.save
+
+    TransferService.atomic_transfer(acc4, acc5, 500)
+  end
+
+  puts "Validation result: #{result.valid? ? 'PASS ✅' : 'FAIL ❌'}"
+  puts "Summary: #{result.summary}"
+
+rescue => e
+  puts "Validation demo encountered error: #{e.message}"
+  puts "This is expected as the framework needs Redis middleware integration"
+end
+
+# Example 4: Performance Analysis
+puts "\n4. Performance Analysis"
+puts "-" * 30
+
+begin
+  commands = Familia::Validation.capture_commands do
+    # Create multiple accounts
+    accounts = []
+    (1..5).each do |i|
+      account = Account.new(account_id: "perf#{i}", balance: "1000")
+      account.save
+      accounts << account
+    end
+
+    # Perform operations
+    accounts[0].balance = "1100"
+    accounts[0].save
+  end
+
+  analyzer = Familia::Validation::PerformanceAnalyzer.new(commands)
+  analysis = analyzer.analyze
+
+  puts "Performance Analysis:"
+  puts "  Total Commands: #{analysis[:total_commands]}"
+  puts "  Command Types: #{analysis[:command_type_breakdown].keys.join(', ')}"
+  puts "  Efficiency Score: #{analysis[:efficiency_score]}/100"
+
+rescue => e
+  puts "Performance analysis encountered error: #{e.message}"
+end
+
+# Example 5: Atomicity Validation
+puts "\n5. Atomicity Validation"
+puts "-" * 30
+
+begin
+  # Test atomic vs non-atomic operations
+  acc6 = Account.new(account_id: "acc006", balance: "3000")
+  acc7 = Account.new(account_id: "acc007", balance: "1000")
+  acc6.save
+  acc7.save
+
+  # This should detect that atomic operations are properly used
+  validator = Familia::Validation::Validator.new(strict_atomicity: true)
+
+  commands = validator.capture_redis_commands do
+    TransferService.atomic_transfer(acc6, acc7, 1000)
+  end
+
+  atomicity_validator = Familia::Validation::AtomicityValidator.new(commands)
+  result = atomicity_validator.validate
+
+  puts "Atomicity validation: #{result.valid? ? 'PASS ✅' : 'FAIL ❌'}"
+
+rescue => e
+  puts "Atomicity validation encountered error: #{e.message}"
+end
+
+puts "\n6. Framework Architecture Overview"
+puts "-" * 30
+puts "
+The Redis Command Validation Framework provides:
+
+🔍 Command Recording
+  - Captures all Redis commands with full context
+  - Tracks transaction boundaries (MULTI/EXEC)
+  - Records timing and performance metrics
+
+📝 Expectations DSL
+  - Fluent API for defining expected command sequences
+  - Support for pattern matching and flexible ordering
+  - Transaction and pipeline validation
+
+✅ Validation Engine
+  - Compares actual vs expected commands
+  - Validates atomicity of operations
+  - Provides detailed mismatch reports
+
+🧪 Test Helpers
+  - Integration with tryouts framework
+  - Methods like assert_redis_commands, assert_atomic_operation
+  - Automatic setup and cleanup
+
+⚡ Performance Analysis
+  - Command efficiency scoring
+  - N+1 pattern detection
+  - Transaction overhead analysis
+
+Key Benefits:
+• Brass-tacks Redis command validation
+• Atomic operation verification
+• Performance optimization insights
+• Clear diagnostic messages
+• Thread-safe operation
+"
+
+# Cleanup
+cleanup_keys = Familia.dbclient.keys("account:*")
+Familia.dbclient.del(*cleanup_keys) if cleanup_keys.any?
+
+puts "\n🎉 Demo complete! The validation framework is ready for use."
+puts "    See try/validation/ for comprehensive test examples."

data/examples/relationships_basic.rb

@@ -0,0 +1,273 @@
+#!/usr/bin/env ruby
+
+# Basic Relationships Example
+# This example demonstrates the core features of Familia's relationships system
+
+require_relative '../lib/familia'
+
+# Configure Familia for the example
+Familia.configure do |config|
+  config.redis_uri = ENV.fetch('REDIS_URI', 'redis://localhost:6379/15')
+end
+
+puts "=== Familia Relationships Basic Example ==="
+puts
+
+# Define our model classes
+class Customer < Familia::Horreum
+  feature :relationships
+
+  identifier_field :custid
+  field :custid, :name, :email, :plan
+
+  # Define collections for tracking relationships
+  set :domains           # Simple set of domain IDs
+  list :projects         # Ordered list of project IDs
+  sorted_set :activity   # Activity feed with timestamps
+
+  # Create indexes for fast lookups
+  indexed_by :email_lookup, field: :email
+  indexed_by :plan_lookup, field: :plan
+
+  # Track in global collections
+  tracked_in :all_customers, type: :sorted_set, score: :created_at
+
+  def created_at
+    Time.now.to_i
+  end
+end
+
+class Domain < Familia::Horreum
+  feature :relationships
+
+  identifier_field :domain_id
+  field :domain_id, :name, :dns_zone, :status
+
+  # Declare membership in customer collections
+  member_of Customer, :domains, type: :set
+
+  # Track domains by status
+  tracked_in :active_domains, type: :sorted_set,
+    score: ->(domain) { domain.status == 'active' ? Time.now.to_i : 0 }
+end
+
+class Project < Familia::Horreum
+  feature :relationships
+
+  identifier_field :project_id
+  field :project_id, :name, :priority
+
+  # Member of customer projects list (ordered)
+  member_of Customer, :projects, type: :list
+end
+
+puts "=== 1. Basic Object Creation ==="
+
+# Create some sample objects
+customer = Customer.new(
+  custid: "cust_#{SecureRandom.hex(4)}",
+  name: "Acme Corporation",
+  email: "admin@acme.com",
+  plan: "enterprise"
+)
+
+domain1 = Domain.new(
+  domain_id: "dom_#{SecureRandom.hex(4)}",
+  name: "acme.com",
+  dns_zone: "acme.com.",
+  status: "active"
+)
+
+domain2 = Domain.new(
+  domain_id: "dom_#{SecureRandom.hex(4)}",
+  name: "staging.acme.com",
+  dns_zone: "staging.acme.com.",
+  status: "active"
+)
+
+project = Project.new(
+  project_id: "proj_#{SecureRandom.hex(4)}",
+  name: "Website Redesign",
+  priority: "high"
+)
+
+puts "✓ Created customer: #{customer.name} (#{customer.custid})"
+puts "✓ Created domains: #{domain1.name}, #{domain2.name}"
+puts "✓ Created project: #{project.name}"
+puts
+
+puts "=== 2. Establishing Relationships ==="
+
+# Add objects to indexed lookups
+Customer.add_to_email_lookup(customer)
+Customer.add_to_plan_lookup(customer)
+puts "✓ Added customer to email and plan indexes"
+
+# Add customer to global tracking
+Customer.add_to_all_customers(customer)
+puts "✓ Added customer to global customer tracking"
+
+# Establish member_of relationships (bidirectional)
+domain1.add_to_customer_domains(customer.custid)
+customer.domains.add(domain1.identifier)
+
+domain2.add_to_customer_domains(customer.custid)
+customer.domains.add(domain2.identifier)
+
+project.add_to_customer_projects(customer.custid)
+customer.projects.add(project.identifier)
+
+puts "✓ Established domain ownership relationships"
+puts "✓ Established project ownership relationships"
+
+# Track domains in status collections
+Domain.add_to_active_domains(domain1)
+Domain.add_to_active_domains(domain2)
+puts "✓ Added domains to active tracking"
+puts
+
+puts "=== 3. Querying Relationships ==="
+
+# Test indexed lookups
+found_customer_id = Customer.email_lookup.get(customer.email)
+puts "Email lookup for #{customer.email}: #{found_customer_id}"
+
+enterprise_customers = Customer.plan_lookup.get("enterprise")
+puts "Enterprise customer found: #{enterprise_customers}"
+
+# Test membership queries
+puts "\nDomain membership checks:"
+puts "  #{domain1.name} belongs to customer? #{domain1.in_customer_domains?(customer.custid)}"
+puts "  #{domain2.name} belongs to customer? #{domain2.in_customer_domains?(customer.custid)}"
+
+puts "\nCustomer collections:"
+puts "  Customer has #{customer.domains.size} domains"
+puts "  Customer has #{customer.projects.size} projects"
+puts "  Domain IDs: #{customer.domains.members}"
+puts "  Project IDs: #{customer.projects.members}"
+
+# Test tracked_in collections
+all_customers_count = Customer.all_customers.size
+puts "\nGlobal tracking:"
+puts "  Total customers in system: #{all_customers_count}"
+
+active_domains_count = Domain.active_domains.size
+puts "  Active domains in system: #{active_domains_count}"
+puts
+
+puts "=== 4. Range Queries ==="
+
+# Get recent customers (last 24 hours)
+yesterday = (Time.now - 24.hours).to_i
+recent_customers = Customer.all_customers.range_by_score(yesterday, '+inf')
+puts "Recent customers (last 24h): #{recent_customers.size}"
+
+# Get all active domains by score
+active_domain_scores = Domain.active_domains.range_by_score(1, '+inf', with_scores: true)
+puts "Active domains with timestamps:"
+active_domain_scores.each do |domain_id, timestamp|
+  puts "  #{domain_id}: active since #{Time.at(timestamp.to_i)}"
+end
+puts
+
+puts "=== 5. Batch Operations ==="
+
+# Create additional test data
+additional_customers = []
+3.times do |i|
+  cust = Customer.new(
+    custid: "batch_cust_#{i}",
+    name: "Customer #{i}",
+    email: "customer#{i}@example.com",
+    plan: i.even? ? "basic" : "premium"
+  )
+  additional_customers << cust
+
+  # Add to indexes and tracking
+  Customer.add_to_email_lookup(cust)
+  Customer.add_to_plan_lookup(cust)
+  Customer.add_to_all_customers(cust)
+end
+
+puts "✓ Created and indexed #{additional_customers.size} additional customers"
+
+# Query by plan
+basic_customers = Customer.plan_lookup.get("basic")
+premium_customers = Customer.plan_lookup.get("premium")
+enterprise_customers = Customer.plan_lookup.get("enterprise")
+
+puts "\nCustomer distribution by plan:"
+puts "  Basic: #{basic_customers ? 1 : 0} customers"
+puts "  Premium: #{premium_customers ? 1 : 0} customers"
+puts "  Enterprise: #{enterprise_customers ? 1 : 0} customers"
+puts
+
+puts "=== 6. Relationship Cleanup ==="
+
+# Remove relationships
+puts "Cleaning up relationships..."
+
+# Remove from member_of relationships
+domain1.remove_from_customer_domains(customer.custid)
+customer.domains.remove(domain1.identifier)
+puts "✓ Removed #{domain1.name} from customer domains"
+
+# Remove from tracking collections
+Domain.active_domains.remove(domain2.identifier)
+puts "✓ Removed #{domain2.name} from active domains"
+
+# Verify cleanup
+puts "\nAfter cleanup:"
+puts "  Customer domains: #{customer.domains.size}"
+puts "  Active domains: #{Domain.active_domains.size}"
+puts
+
+puts "=== 7. Advanced Usage - Permission Encoding ==="
+
+# Demonstrate basic score encoding for permissions
+class DocumentAccess
+  # Permission flags (powers of 2)
+  READ = 1
+  WRITE = 2
+  DELETE = 4
+  ADMIN = 8
+
+  def self.encode_permissions(timestamp, permissions)
+    "#{timestamp}.#{permissions}".to_f
+  end
+
+  def self.decode_permissions(score)
+    parts = score.to_s.split('.')
+    timestamp = parts[0].to_i
+    permissions = parts[1] ? parts[1].to_i : 0
+    [timestamp, permissions]
+  end
+end
+
+# Example permission encoding
+now = Time.now.to_i
+read_write_permissions = DocumentAccess::READ | DocumentAccess::WRITE  # 3
+admin_permissions = DocumentAccess::ADMIN  # 8
+
+encoded_score = DocumentAccess.encode_permissions(now, read_write_permissions)
+timestamp, permissions = DocumentAccess.decode_permissions(encoded_score)
+
+puts "Permission encoding example:"
+puts "  Original: timestamp=#{now}, permissions=#{read_write_permissions}"
+puts "  Encoded score: #{encoded_score}"
+puts "  Decoded: timestamp=#{timestamp}, permissions=#{permissions}"
+puts "  Has read access: #{(permissions & DocumentAccess::READ) != 0}"
+puts "  Has write access: #{(permissions & DocumentAccess::WRITE) != 0}"
+puts "  Has delete access: #{(permissions & DocumentAccess::DELETE) != 0}"
+puts
+
+puts "=== Example Complete! ==="
+puts
+puts "Key takeaways:"
+puts "• tracked_in: Use for activity feeds, leaderboards, time-series data"
+puts "• indexed_by: Use for fast O(1) lookups by field values"
+puts "• member_of: Use for bidirectional ownership/membership"
+puts "• Score encoding: Combine timestamps with metadata for rich queries"
+puts "• Batch operations: Use Redis pipelines for efficiency"
+puts
+puts "See docs/wiki/Relationships-Guide.md for comprehensive documentation"

data/lib/familia/base.rb

@@ -35,7 +35,7 @@ module Familia
 
       def add_feature(klass, feature_name, depends_on: [])
         @features_available ||= {}
-        Familia.ld "[#{self}] Adding feature #{klass} as #{feature_name.inspect}"
+        Familia.trace :ADD_FEATURE, klass, feature_name, caller(1..1) if Familia.debug?
 
         # Create field definition object
         feature_def = FeatureDefinition.new(

data/lib/familia/connection.rb

@@ -171,7 +171,7 @@ module Familia
       result = dbclient.multi do |conn|
         Fiber[:familia_transaction] = conn
         begin
-          block_result = yield(conn) # rubocop:disable Lint/UselessAssignment
+          block_result = yield(conn)
         ensure
           Fiber[:familia_transaction] = nil # cleanup reference
         end
@@ -220,7 +220,7 @@ module Familia
       result = dbclient.pipelined do |conn|
         Fiber[:familia_pipeline] = conn
         begin
-          block_result = yield(conn) # rubocop:disable Lint/UselessAssignment
+          block_result = yield(conn)
         ensure
           Fiber[:familia_pipeline] = nil # cleanup reference
         end
@@ -244,7 +244,7 @@ module Familia
     #     conn.expire("custom_key", 3600)
     #   end
     #
-    def with_connection(&block)
+    def with_connection(&)
       yield dbclient
     end
 

data/lib/familia/data_type/types/counter.rb

@@ -0,0 +1,38 @@
+# lib/familia/data_type/types/counter.rb
+
+module Familia
+  class Counter < String
+    def initialize(*args)
+      super
+      @opts[:default] ||= 0
+    end
+
+    # Enhanced counter semantics
+    def reset(val = 0)
+      set(val).to_s.eql?('OK')
+    end
+
+    def increment_if_less_than(threshold, amount = 1)
+      current = to_i
+      return false if current >= threshold
+
+      incrementby(amount)
+      true
+    end
+
+    def atomic_increment_and_get(amount = 1)
+      incrementby(amount)
+    end
+
+    # Override to ensure integer serialization
+    def value=(val)
+      super(val.to_i)
+    end
+
+    def value
+      super.to_i
+    end
+  end
+end
+
+Familia::DataType.register Familia::Counter, :counter

data/lib/familia/data_type/types/hashkey.rb

@@ -61,6 +61,24 @@ module Familia
     end
     alias all hgetall
 
+    # Sets field in the hash stored at key to value, only if field does not yet exist.
+    # If field already exists, this operation has no effect.
+    # @param field [String] The field name
+    # @param val [Object] The value to set
+    # @return [Integer] 1 if field is a new field and value was set, 0 if field already exists
+    def hsetnx(field, val)
+      ret = dbclient.hsetnx dbkey, field.to_s, serialize_value(val)
+      update_expiration if ret == 1
+      ret
+    rescue TypeError => e
+      Familia.le "[hsetnx] #{e.message}"
+      Familia.ld "[hsetnx] #{dbkey} #{field}=#{val}" if Familia.debug
+      echo :hsetnx, caller(1..1).first if Familia.debug # logs via echo to the db and back
+      klass = val.class
+      msg = "Cannot store #{field} => #{val.inspect} (#{klass}) in #{dbkey}"
+      raise e.class, msg
+    end
+
     def key?(field)
       dbclient.hexists dbkey, field.to_s
     end

data/lib/familia/data_type/types/lock.rb

@@ -0,0 +1,43 @@
+# lib/familia/data_type/types/lock.rb
+
+module Familia
+  class Lock < String
+    def initialize(*args)
+      super
+      @opts[:default] = nil
+    end
+
+    # Acquire a lock with optional TTL
+    # @param token [String] Unique token to identify lock holder (auto-generated if nil)
+    # @param ttl [Integer, nil] Time-to-live in seconds. nil = no expiration, <=0 rejected
+    # @return [String, false] Returns token if acquired successfully, false otherwise
+    def acquire(token = SecureRandom.uuid, ttl: 10)
+      success = setnx(token)
+      # Handle both integer (1/0) and boolean (true/false) return values
+      return false unless success == 1 || success == true
+      return del && false if ttl&.<=(0)
+      return del && false if ttl&.positive? && !expire(ttl)
+      token
+    end
+
+    def release(token)
+      # Lua script to atomically check token and delete
+      script = "if redis.call('get', KEYS[1]) == ARGV[1] then return redis.call('del', KEYS[1]) else return 0 end"
+      dbclient.eval(script, [dbkey], [token]) == 1
+    end
+
+    def locked?
+      !value.nil?
+    end
+
+    def held_by?(token)
+      value == token
+    end
+
+    def force_unlock!
+      del
+    end
+  end
+end
+
+Familia::DataType.register Familia::Lock, :lock

data/lib/familia/data_type/types/string.rb

@@ -108,12 +108,19 @@ module Familia
       ret
     end
 
+    def del
+      ret = dbclient.del dbkey
+      ret.positive?
+    end
+
     def nil?
       value.nil?
     end
 
     Familia::DataType.register self, :string
-    Familia::DataType.register self, :counter
-    Familia::DataType.register self, :lock
   end
 end
+
+# Both subclass String
+require_relative 'lock'
+require_relative 'counter'