familia 2.0.0.pre8 → 2.0.0.pre12

data/examples/relationships.rb

@@ -0,0 +1,205 @@
+#!/usr/bin/env ruby
+
+# Basic Relationships Example
+# This example demonstrates the core features of Familia's relationships system
+
+require 'familia'
+
+# Configure Familia for the example
+# Note: Individual models can specify logical_database if needed
+Familia.configure do |config|
+  config.uri = 'redis://localhost:6379/'
+end
+
+puts '=== Familia Relationships Basic Example ==='
+puts
+
+# Define our model classes
+class Customer < Familia::Horreum
+  logical_database 15 # Use test database
+  feature :relationships
+
+  identifier_field :custid
+  field :custid
+  field :name
+  field :email
+  field :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 (using class_ prefix for class-level)
+  class_indexed_by :email, :email_lookup # i.e. Customer.email_lookup
+  class_indexed_by :plan, :plan_lookup # i.e. Customer.plan_lookup
+
+  # Track in class-level collections (using class_ prefix for class-level)
+  class_tracked_in :all_customers, score: :created_at # i.e. Customer.all_customers
+end
+
+class Domain < Familia::Horreum
+  logical_database 15 # Use test database
+  feature :relationships
+
+  identifier_field :domain_id
+  field :domain_id
+  field :name
+  field :dns_zone
+  field :status
+
+  # Declare membership in customer collections
+  member_of Customer, :domains # , type: :set
+
+  # Track domains by status (using class_ prefix for class-level)
+  class_tracked_in :active_domains,
+                   score: -> { status == 'active' ? Time.now.to_i : 0 }
+end
+
+class Project < Familia::Horreum
+  logical_database 15 # Use test database
+  feature :relationships
+
+  identifier_field :project_id
+  field :project_id
+  field :name
+  field :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 ==='
+
+# Save objects to automatically update indexes and class-level tracking
+customer.save # Automatically adds to email_lookup, plan_lookup, and all_customers
+puts '✓ Customer automatically added to indexes and tracking on save'
+
+# Establish member_of relationships using clean << operator syntax
+customer.domains << domain1   # Clean Ruby-like syntax
+customer.domains << domain2   # Same as domain1.add_to_customer_domains(customer)
+customer.projects << project  # Same as project.add_to_customer_projects(customer)
+
+puts '✓ Established domain ownership relationships using << operator'
+puts '✓ Established project ownership relationships using << operator'
+
+# Save domains to automatically add them to class-level tracking
+domain1.save  # Automatically adds to active_domains if status == 'active'
+domain2.save  # Automatically adds to active_domains if status == 'active'
+puts '✓ Domains automatically added to status tracking on save'
+puts
+
+puts '=== 3. Querying Relationships ==='
+
+record = Customer.get_by_email('admin@acme.com')
+puts "Email lookup: #{record&.custid || 'not found'}"
+
+Customer.get_by_plan('enterprise') # raises MoreThanOne
+
+results = Customer.find_by_email('admin@acme.com')
+puts "Email lookup: #{results&.size} found"
+
+results = Customer.find_by_plan('enterprise')
+puts "Enterprise lookup: #{results&.size} found"
+puts
+
+# Test membership queries
+puts "\nDomain membership checks:"
+puts "  #{domain1.name} belongs to customer? #{domain1.in_customer_domains?(customer)}"
+puts "  #{domain2.name} belongs to customer? #{domain2.in_customer_domains?(customer)}"
+
+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.values.size
+puts "\nClass-level 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 * 3600)).to_i # 24 hours ago
+recent_customers = Customer.values.rangebyscore(yesterday, '+inf')
+puts "Recent customers (last 24h): #{recent_customers.size}"
+
+# Get all active domains by score
+active_domain_scores = Domain.active_domains.rangebyscore(1, '+inf', with_scores: true)
+puts 'Active domains with timestamps:'
+active_domain_scores.each_slice(2) do |domain_id, timestamp|
+  puts "  #{domain_id}: active since #{Time.at(timestamp.to_i)} #{timestamp.inspect}"
+end
+puts
+
+puts '=== 6. Relationship Cleanup ==='
+
+# Remove relationships
+puts 'Cleaning up relationships...'
+
+# Remove from member_of relationships
+domain1.remove_from_customer_domains(customer)
+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 '=== Example Complete! ==='
+puts
+puts 'Key takeaways:'
+puts '• class_tracked_in: Automatic class-level collections updated on save'
+puts '• class_indexed_by: Automatic class-level indexes updated on save'
+puts '• member_of: Use << operator for clean Ruby-like collection syntax'
+puts '• indexed_by with parent:: Use for relationship-scoped indexes'
+puts '• Save operations: Automatically update indexes and class-level tracking'
+puts '• << operator: Works naturally with all collection types (sets, lists, sorted sets)'
+puts
+puts 'See docs/wiki/Relationships-Guide.md for comprehensive documentation'

data/examples/safe_dump.rb

@@ -0,0 +1,281 @@
+#!/usr/bin/env ruby
+
+# examples/safe_dump.rb
+#
+# Demonstrates the SafeDump feature with the new DSL methods.
+# SafeDump allows you to control which fields are exposed when
+# serializing objects, preventing accidental exposure of sensitive data.
+
+$LOAD_PATH.unshift File.expand_path('../lib', __dir__)
+require 'familia'
+
+# Configure connection
+Familia.uri = 'redis://localhost:6379/15'
+
+puts '=== SafeDump Feature Examples ==='
+puts
+
+# Example 1: Basic SafeDump with simple fields
+class User < Familia::Horreum
+  feature :safe_dump
+
+  identifier_field :email
+  field :email
+  field :first_name
+  field :last_name
+  field :password_hash # Sensitive - not included in safe dump
+  field :ssn # Sensitive - not included in safe dump
+  field :created_at
+
+  # Define safe dump fields using the new DSL
+  safe_dump_field :email
+  safe_dump_field :first_name
+  safe_dump_field :last_name
+  safe_dump_field :created_at
+end
+
+puts 'Example 1: Basic SafeDump'
+user = User.new(
+  email: 'alice@example.com',
+  first_name: 'Alice',
+  last_name: 'Smith',
+  password_hash: 'secret123',
+  ssn: '123-45-6789',
+  created_at: Time.now.to_i
+)
+
+puts "Full object data: #{user.to_h}"
+puts "Safe dump: #{user.safe_dump}"
+puts 'Notice: password_hash and ssn are excluded'
+puts
+
+# Example 2: SafeDump with computed fields using callables
+class Product < Familia::Horreum
+  feature :safe_dump
+
+  identifier_field :sku
+  field :sku
+  field :name
+  field :price_cents      # Store price in cents internally
+  field :cost_cents       # Sensitive - don't expose
+  field :inventory_count
+  field :category
+  field :created_at
+
+  # Mix simple fields with computed fields
+  safe_dump_field :sku
+  safe_dump_field :name
+  safe_dump_field :category
+  safe_dump_field :created_at
+
+  # Computed fields using callables
+  safe_dump_field :price, ->(product) { "$#{format('%.2f', product.price_cents.to_i / 100.0)}" }
+  safe_dump_field :in_stock, ->(product) { product.inventory_count.to_i > 0 }
+  safe_dump_field :display_name, ->(product) { "#{product.name} (#{product.sku})" }
+end
+
+puts 'Example 2: SafeDump with computed fields'
+product = Product.new(
+  sku: 'WIDGET-001',
+  name: 'Super Widget',
+  price_cents: 1599,     # $15.99
+  cost_cents: 800,       # $8.00 - sensitive, not exposed
+  inventory_count: 25,
+  category: 'widgets',
+  created_at: Time.now.to_i
+)
+
+puts "Full object data: #{product.to_h}"
+puts "Safe dump: #{product.safe_dump}"
+puts 'Notice: price converted to dollars, in_stock computed, cost_cents hidden'
+puts
+
+# Example 3: SafeDump with multiple field definition styles
+class Order < Familia::Horreum
+  feature :safe_dump
+
+  identifier_field :order_id
+  field :order_id
+  field :customer_email
+  field :status
+  field :total_cents
+  field :payment_method
+  field :credit_card_number  # Very sensitive!
+  field :processing_notes    # Internal only
+  field :created_at
+  field :shipped_at
+
+  # Mix of individual fields and batch definitions
+  safe_dump_field :order_id
+  safe_dump_field :customer_email
+  safe_dump_field :status
+
+  # Define multiple fields at once
+  safe_dump_fields :created_at, :shipped_at
+
+  # Computed fields using hash syntax
+  safe_dump_fields(
+    { total: ->(order) { "$#{format('%.2f', order.total_cents.to_i / 100.0)}" } },
+    { payment_type: ->(order) { order.payment_method&.split('_')&.first&.capitalize } }
+  )
+
+  def customer_obscured_email
+    email = customer_email.to_s
+    return email if email.length < 3
+
+    local, domain = email.split('@', 2)
+    return email unless domain
+
+    obscured_local = local[0] + ('*' * [local.length - 2, 0].max) + local[-1]
+    "#{obscured_local}@#{domain}"
+  end
+end
+
+puts 'Example 3: Multiple definition styles'
+order = Order.new(
+  order_id: 'ORD-2024-001',
+  customer_email: 'customer@example.com',
+  status: 'shipped',
+  total_cents: 2499, # $24.99
+  payment_method: 'credit_card',
+  credit_card_number: '4111-1111-1111-1111', # Never expose this!
+  processing_notes: 'Rush order - expedite shipping',
+  created_at: Time.now.to_i - 86_400, # Yesterday
+  shipped_at: Time.now.to_i - 3600 # 1 hour ago
+)
+
+puts "Full object data: #{order.to_h}"
+puts "Safe dump: #{order.safe_dump}"
+puts 'Notice: credit card and internal notes excluded, computed fields included'
+puts
+
+# Example 4: SafeDump with nested objects
+class Address < Familia::Horreum
+  feature :safe_dump
+
+  identifier_field :id
+  field :id
+  field :street
+  field :city
+  field :state
+  field :zip_code
+  field :country
+
+  # Simple address fields
+  safe_dump_fields :street, :city, :state, :zip_code, :country
+end
+
+class Customer < Familia::Horreum
+  feature :safe_dump
+
+  identifier_field :id
+  field :id
+  field :name
+  field :email
+  field :phone
+  field :billing_address_id
+  field :shipping_address_id
+  field :account_balance_cents
+  field :credit_limit_cents   # Sensitive
+  field :internal_notes       # Internal only
+
+  safe_dump_field :id
+  safe_dump_field :name
+  safe_dump_field :email
+  safe_dump_field :phone
+
+  # Nested object handling - load and safe_dump related addresses
+  safe_dump_field :billing_address, lambda { |customer|
+    addr_id = customer.billing_address_id
+    addr_id ? Address.load(addr_id)&.safe_dump : nil
+  }
+
+  safe_dump_field :shipping_address, lambda { |customer|
+    addr_id = customer.shipping_address_id
+    addr_id ? Address.load(addr_id)&.safe_dump : nil
+  }
+
+  safe_dump_field :account_balance, lambda { |customer|
+    "$#{format('%.2f', customer.account_balance_cents.to_i / 100.0)}"
+  }
+end
+
+puts 'Example 4: SafeDump with nested objects'
+
+# Create addresses first
+billing = Address.new(
+  id: 'addr_1',
+  street: '123 Main St',
+  city: 'Anytown',
+  state: 'CA',
+  zip_code: '90210',
+  country: 'USA'
+)
+billing.save
+
+shipping = Address.new(
+  id: 'addr_2',
+  street: '456 Oak Ave',
+  city: 'Somewhere',
+  state: 'NY',
+  zip_code: '10001',
+  country: 'USA'
+)
+shipping.save
+
+customer = Customer.new(
+  id: 'cust_123',
+  name: 'Bob Johnson',
+  email: 'bob@example.com',
+  phone: '555-1234',
+  billing_address_id: 'addr_1',
+  shipping_address_id: 'addr_2',
+  account_balance_cents: 15_000,  # $150.00
+  credit_limit_cents: 100_000,    # $1000.00 - sensitive!
+  internal_notes: 'VIP customer - handle with care'
+)
+
+puts 'Customer safe dump:'
+puts JSON.pretty_generate(customer.safe_dump)
+puts 'Notice: Nested addresses included, sensitive credit limit excluded'
+puts
+
+# Example 5: Introspection methods
+puts 'Example 5: SafeDump introspection'
+puts "User safe dump field names: #{User.safe_dump_field_names}"
+puts "Product safe dump field names: #{Product.safe_dump_field_names}"
+puts "Order safe dump field names: #{Order.safe_dump_field_names}"
+puts
+
+puts "User safe dump field map keys: #{User.safe_dump_field_map.keys}"
+puts "All Product safe dump fields are callable: #{Product.safe_dump_field_map.values.all? do |v|
+  v.respond_to?(:call)
+end}"
+puts
+
+# Example 6: Legacy compatibility methods
+puts 'Example 6: Legacy compatibility'
+puts "Using legacy safe_dump_fields getter: #{User.safe_dump_fields}"
+puts 'Setting fields with set_safe_dump_fields:'
+
+class LegacyModel < Familia::Horreum
+  feature :safe_dump
+  identifier_field :id
+  field :id
+  field :name
+  field :value
+end
+
+LegacyModel.set_safe_dump_fields(:id, :name)
+puts "LegacyModel fields after set_safe_dump_fields: #{LegacyModel.safe_dump_fields}"
+
+# Clean up
+puts
+puts '=== Cleaning up test data ==='
+[User, Product, Order, Address, Customer, LegacyModel].each do |klass|
+  klass.redis.del(klass.redis.keys("#{klass.name.downcase}:*"))
+rescue StandardError => e
+  puts "Error cleaning #{klass}: #{e.message}"
+end
+
+puts 'SafeDump examples completed!'

data/familia.gemspec

@@ -19,10 +19,10 @@ Gem::Specification.new do |spec|
 
   spec.required_ruby_version = Gem::Requirement.new('>= 3.4')
 
-  spec.add_dependency 'benchmark'
-  spec.add_dependency 'connection_pool'
-  spec.add_dependency 'csv'
-  spec.add_dependency 'logger'
+  spec.add_dependency 'benchmark', '~> 0.4'
+  spec.add_dependency 'connection_pool', '~> 2.5'
+  spec.add_dependency 'csv', '~> 3.3'
+  spec.add_dependency 'logger', '~> 1.7'
   spec.add_dependency 'redis', '>= 4.8.1', '< 6.0'
   spec.add_dependency 'stringio', '~> 3.1.1'
   spec.add_dependency 'uri-valkey', '~> 1.4'

data/lib/familia/base.rb

@@ -19,6 +19,38 @@ module Familia
     @dump_method = :to_json
     @load_method = :from_json
 
+    def self.included(base)
+      # Ensure the including class gets its own feature registry
+      base.extend(ClassMethods)
+    end
+
+    module ClassMethods
+      attr_reader :features_available, :feature_definitions
+      attr_accessor :dump_method, :load_method
+
+      def add_feature(klass, feature_name, depends_on: [])
+        @features_available ||= {}
+        Familia.trace :ADD_FEATURE, klass, feature_name, caller(1..1) if Familia.debug?
+
+        # Create field definition object
+        feature_def = FeatureDefinition.new(
+          name: feature_name,
+          depends_on: depends_on,
+        )
+
+        # Track field definitions after defining field methods
+        @feature_definitions ||= {}
+        @feature_definitions[feature_name] = feature_def
+
+        features_available[feature_name] = klass
+      end
+
+      # Find a feature by name, traversing this class's ancestry chain
+      def find_feature(feature_name)
+        Familia::Base.find_feature(feature_name, self)
+      end
+    end
+
     # Returns a string representation of the object. Implementing classes
     # are welcome to override this method to provide a more meaningful
     # representation. Using this as a default via super is recommended.
@@ -29,6 +61,7 @@ module Familia
       "#<#{self.class}:0x#{object_id.to_s(16)}>"
     end
 
+    # Module-level methods for Familia::Base itself
     class << self
       attr_reader :features_available, :feature_definitions
       attr_accessor :dump_method, :load_method
@@ -49,6 +82,25 @@ module Familia
 
         features_available[feature_name] = klass
       end
+
+      # Find a feature by name, traversing the ancestry chain of classes
+      # that include Familia::Base
+      def find_feature(feature_name, starting_class = self)
+        # Convert to symbol for consistent lookup
+        feature_name = feature_name.to_sym
+
+        # Walk up the ancestry chain, checking each class that includes Familia::Base
+        starting_class.ancestors.each do |ancestor|
+          next unless ancestor.respond_to?(:features_available)
+          next unless ancestor.features_available
+
+          if ancestor.features_available.key?(feature_name)
+            return ancestor.features_available[feature_name]
+          end
+        end
+
+        nil
+      end
     end
 
     def generate_id

data/lib/familia/connection.rb

@@ -57,7 +57,6 @@ module Familia
     #   Familia.connect('redis://localhost:6379')
     def connect(uri = nil)
       parsed_uri = normalize_uri(uri)
-      serverid = parsed_uri.serverid
 
       if Familia.enable_database_logging
         DatabaseLogger.logger = Familia.logger
@@ -70,14 +69,7 @@ module Familia
         RedisClient.register(DatabaseCommandCounter)
       end
 
-      dbclient = Redis.new(parsed_uri.conf)
-
-      if @database_clients.key?(serverid)
-        msg = "Overriding existing connection for #{serverid}"
-        Familia.warn(msg)
-      end
-
-      @database_clients[serverid] = dbclient
+      Redis.new(parsed_uri.conf)
     end
 
     def reconnect(uri = nil)
@@ -86,6 +78,7 @@ module Familia
 
       # Close the existing connection if it exists
       @database_clients[serverid].close if @database_clients.key?(serverid)
+      @database_clients.delete(serverid)
 
       connect(parsed_uri)
     end
@@ -126,19 +119,9 @@ module Familia
 
       # Legacy behavior: create connection
       parsed_uri = normalize_uri(uri)
+      serverid = parsed_uri.serverid
 
-      # Only cache when no specific URI/DB is requested to avoid DB conflicts
-      if uri.nil?
-        @dbclient ||= connect(parsed_uri)
-        @dbclient.select(parsed_uri.db) if parsed_uri.db
-        @dbclient
-      else
-        # When a specific DB is requested, create a new connection
-        # to avoid conflicts with cached connections
-        connection = connect(parsed_uri)
-        connection.select(parsed_uri.db) if parsed_uri.db
-        connection
-      end
+      @database_clients[serverid] ||= connect(parsed_uri)
     end
 
     # Executes Database commands atomically within a transaction (MULTI/EXEC).

data/lib/familia/{encryption_request_cache.rb → encryption/request_cache.rb}

@@ -1,4 +1,4 @@
-# lib/familia/encryption_request_cache.rb
+# lib/familia/encryption/request_cache.rb
 #
 # Request-scoped caching for encryption keys (if needed for performance)
 # This should ONLY be enabled if performance testing shows it's necessary

data/lib/familia/errors.rb

@@ -5,6 +5,8 @@ module Familia
   class NoIdentifier < Problem; end
   class NonUniqueKey < Problem; end
 
+  class FieldTypeError < Problem; end
+
   class HighRiskFactor < Problem
     attr_reader :value
 

data/lib/familia/features/autoloader.rb

@@ -0,0 +1,57 @@
+# lib/familia/features/autoloader.rb
+
+module Familia
+  module Features
+    # Autoloader is a mixin that automatically loads feature files from a 'features'
+    # subdirectory when included. This provides a standardized way to organize and
+    # auto-load project-specific features.
+    #
+    # When included in a module, it automatically:
+    # 1. Determines the directory containing the module file
+    # 2. Looks for a 'features' subdirectory in that location
+    # 3. Loads all *.rb files from that features directory
+    #
+    # Example usage:
+    #
+    #   # apps/api/v2/models/customer/features.rb
+    #   module V2
+    #     class Customer < Familia::Horreum
+    #       module Features
+    #         include Familia::Features::Autoloader
+    #         # Automatically loads all files from customer/features/
+    #       end
+    #     end
+    #   end
+    #
+    # This would automatically load:
+    #   - apps/api/v2/models/customer/features/deprecated_fields.rb
+    #   - apps/api/v2/models/customer/features/legacy_support.rb
+    #   - etc.
+    #
+    module Autoloader
+      def self.included(_base)
+        # Get the file path of the module that's including us.
+        # `caller_locations(1, 1).first` gives us the location where `include` was called.
+        # This is a robust way to find the file path, especially for anonymous modules.
+        calling_location = caller_locations(1, 1)&.first
+        return unless calling_location
+
+        including_file = calling_location.path
+
+        # Find the features directory relative to the including file
+        features_dir = File.join(File.dirname(including_file), 'features')
+
+        Familia.ld "[DEBUG] Autoloader: Looking for features in #{features_dir}"
+
+        if Dir.exist?(features_dir)
+          Dir.glob(File.join(features_dir, '*.rb')).each do |feature_file|
+            Familia.ld "[DEBUG] Autoloader: Loading feature #{feature_file}"
+            require feature_file
+          end
+        else
+          Familia.ld "[DEBUG] Autoloader: No features directory found at #{features_dir}"
+        end
+      end
+    end
+  end
+end