familia 2.0.0.pre5 → 2.0.0.pre6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5517961b53f3213a7d92f9bd07001291bcdae102f1ca5cf59570537020e4fc2f
-  data.tar.gz: 44610f83cf5b65d1cde483c91b9a259816bb1040da2b1ff77867061be8aeaf36
+  metadata.gz: 93cb8ea627c19daff3566c7373aa45ff04adb6d37a3346c3b3049712c18838ea
+  data.tar.gz: 9d359e2067062a4c6afe91a76985362989a569611400f10f7155e505dd55e39b
 SHA512:
-  metadata.gz: 9e02c91aa204b248bf6853637c21ffdeabc90d7b04661c5ddc2cb99260fc0ebb6cc2d4780aed0d45e6f30e64e49229e15201551073f5c804fa8c2a0add328c97
-  data.tar.gz: ef296043a9b843fa27745d15b505fa11f2df4f5baeb505189d02013fb3f02cfccb49f9d3606912b101ed95ef6b2f3967ade5b8ff79e67c6e50ebda7a81ef0e15
+  metadata.gz: e020a48703858e929eeb11188029893656ef84ce98113e4c448d41e354edb4fe77df420aa4bab33b7775f0719ad5a693fc672c8159cd0e963be7750daa12d5b9
+  data.tar.gz: c3e66800df77ccd33ccd5a6027d031173642446210309e60bf83243f59585a0416ea99002063f0080828eb24d1aa1fa50f3013e7dbf408b2299f2fea617b2fa3

data/CLAUDE.md

@@ -6,11 +6,14 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 
 ### Testing
 
-A couple rules when writing tests:
-1) Every tryouts file has three sections: setup, testcases, teardown.
-2) Every tryouts testcase also has three parts: description, code, expectations.
-3) Tryouts tests are meant to double as documentation examples; keep that in mind when considering syntax choices.
-4) There are multiple kinds of expectations: `#=>` is the default comparison, `#=:>` is a class comparison via `is_a?` or `kind_of?`, `#=!>` is an exception class which allows you to knowingly raise an exception without needing a begin/rescue.
+Tryouts framework rules:
+1) **Structure**: 3 sections - setup (optional), testcases, teardown (optional)
+2) **Test cases**: Use `##` for descriptions, Ruby code, then `#=>` expectations
+3) **Variables**: Instance variables (`@var`) persist across all sections
+4) **Expectations**: `#=>` (value), `#==>` (boolean), `#=:>` (type), `#=!>` (exception)
+5) **Comments**: Use single `#` prefix, DO NOT label sections
+6) **Philosophy**: Plain realistic code, avoid mocks/test DSL
+7) **Result**: Last expression in each test case is the result
 
 - **Run tests**: `bundle exec try` (uses tryouts testing framework)
 - **Run specific test file, verbose**: `bundle exec try -v try/specific_test_try.rb`

data/Gemfile

@@ -9,7 +9,7 @@ group :test do
     gem 'tryouts', path: '../tryouts'
     gem 'uri-valkey', path: '..//uri-valkey/gems', glob: 'uri-valkey.gemspec'
   else
-    gem 'tryouts', '~> 3.2.2', require: false
+    gem 'tryouts', '~> 3.3.2', require: false
   end
   gem 'concurrent-ruby', '~> 1.3.5', require: false
   gem 'ruby-prof'

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    familia (2.0.0.pre5)
+    familia (2.0.0.pre6)
       benchmark
       connection_pool
       csv
@@ -113,7 +113,8 @@ GEM
     ruby-progressbar (1.13.0)
     stackprof (0.2.27)
     stringio (3.1.7)
-    tryouts (3.2.2)
+    tryouts (3.3.2)
+      concurrent-ruby (~> 1.0)
       irb
       minitest (~> 5.0)
       pastel (~> 0.8)
@@ -147,7 +148,7 @@ DEPENDENCIES
   rubocop-thread_safety
   ruby-prof
   stackprof
-  tryouts (~> 3.2.2)
+  tryouts (~> 3.3.2)
   yard (~> 0.9)
 
 BUNDLED WITH

data/docs/wiki/API-Reference.md

@@ -55,9 +55,21 @@ vault.secret_data(passphrase_value: "user_passphrase")
 
 ## Familia::Encryption Module
 
+### manager
+
+Creates a manager instance with optional algorithm selection.
+
+```ruby
+# Use best available provider
+mgr = Familia::Encryption.manager
+
+# Use specific algorithm
+mgr = Familia::Encryption.manager(algorithm: 'xchacha20poly1305')
+```
+
 ### encrypt
 
-Encrypts plaintext with context-specific key.
+Encrypts plaintext using the default provider.
 
 ```ruby
 Familia::Encryption.encrypt(plaintext,
@@ -66,16 +78,20 @@ Familia::Encryption.encrypt(plaintext,
 )
 ```
 
-**Parameters:**
-- `plaintext` (String) - Data to encrypt
-- `context` (String) - Key derivation context
-- `additional_data` (String, nil) - Optional AAD for authentication
+### encrypt_with
+
+Encrypts plaintext with a specific algorithm.
 
-**Returns:** JSON string with encrypted data structure
+```ruby
+Familia::Encryption.encrypt_with('aes-256-gcm', plaintext,
+  context: "User:favorite_snack:user123",
+  additional_data: nil
+)
+```
 
 ### decrypt
 
-Decrypts ciphertext with context-specific key.
+Decrypts ciphertext (auto-detects algorithm from JSON).
 
 ```ruby
 Familia::Encryption.decrypt(encrypted_json,
@@ -84,12 +100,33 @@ Familia::Encryption.decrypt(encrypted_json,
 )
 ```
 
-**Parameters:**
-- `encrypted_json` (String) - JSON-encoded encrypted data
-- `context` (String) - Key derivation context
-- `additional_data` (String, nil) - Optional AAD for verification
+### status
 
-**Returns:** Decrypted plaintext string
+Returns current encryption configuration and available providers.
+
+```ruby
+Familia::Encryption.status
+# => {
+#   default_algorithm: "xchacha20poly1305",
+#   available_algorithms: ["xchacha20poly1305", "aes-256-gcm"],
+#   preferred_available: "Familia::Encryption::Providers::XChaCha20Poly1305Provider",
+#   using_hardware: false,
+#   key_versions: [:v1],
+#   current_version: :v1
+# }
+```
+
+### benchmark
+
+Benchmarks available providers.
+
+```ruby
+Familia::Encryption.benchmark(iterations: 1000)
+# => {
+#   "xchacha20poly1305" => { time: 0.45, ops_per_sec: 4444, priority: 100 },
+#   "aes-256-gcm" => { time: 0.52, ops_per_sec: 3846, priority: 50 }
+# }
+```
 
 ### validate_configuration!
 
@@ -100,17 +137,57 @@ Familia::Encryption.validate_configuration!
 # Raises Familia::EncryptionError if configuration invalid
 ```
 
-### with_key_cache
+### derivation_count / reset_derivation_count!
 
-Provides request-scoped key caching.
+Monitors key derivation operations (for testing and debugging).
 
 ```ruby
-Familia::Encryption.with_key_cache do
-  # Operations here share derived keys
-  users.each { |u| u.decrypt_fields }
-end
+# Check how many key derivations have occurred
+count = Familia::Encryption.derivation_count.value
+# => 42
+
+# Reset counter
+Familia::Encryption.reset_derivation_count!
 ```
 
+## Familia::Encryption::Manager
+
+Low-level manager class for direct provider control.
+
+### initialize
+
+```ruby
+# Use default provider
+manager = Familia::Encryption::Manager.new
+
+# Use specific algorithm
+manager = Familia::Encryption::Manager.new(algorithm: 'aes-256-gcm')
+```
+
+### encrypt / decrypt
+
+Same interface as module-level methods but tied to specific provider.
+
+## Familia::Encryption::Registry
+
+Provider management system.
+
+### setup!
+
+Registers all available providers.
+
+### get
+
+Returns provider instance by algorithm name.
+
+### default_provider
+
+Returns highest-priority available provider instance.
+
+### available_algorithms
+
+Returns array of available algorithm names.
+
 ## Configuration
 
 ### Familia.configure

data/docs/wiki/Connection-Pooling-Guide.md

@@ -0,0 +1,437 @@
+# Connection Pooling Guide
+
+## Overview
+
+Familia provides robust connection pooling through a provider pattern that enables efficient Redis/Valkey connection management with support for multiple logical databases, thread safety, and optimal performance.
+
+## Core Concepts
+
+### Connection Provider Contract
+
+Your connection provider **MUST** follow these rules:
+
+1. **Database Selection**: Return connections already on the correct logical database
+2. **No SELECT Commands**: Familia will NOT issue `SELECT` commands
+3. **URI-based Selection**: Accept normalized URIs (e.g., `redis://localhost:6379/2`)
+4. **Thread Safety**: Handle concurrent access safely
+
+### Connection Priority System
+
+Familia uses a three-tier connection resolution system:
+
+1. **Thread-local connections** (middleware pattern)
+2. **Connection provider** (if configured)
+3. **Fallback behavior** (legacy direct connections, if allowed)
+
+```ruby
+# Priority 1: Thread-local (set by middleware)
+Thread.current[:familia_connection] = redis_client
+
+# Priority 2: Connection provider
+Familia.connection_provider = ->(uri) { pool.checkout(uri) }
+
+# Priority 3: Fallback (can be disabled)
+Familia.connection_required = true  # Disable fallback
+```
+
+## Basic Setup
+
+### Simple Connection Pool
+
+```ruby
+require 'connection_pool'
+
+class ConnectionManager
+  @pools = {}
+
+  # Configure provider at application startup
+  def self.setup!
+    Familia.connection_provider = lambda do |uri|
+      parsed = URI.parse(uri)
+      pool_key = "#{parsed.host}:#{parsed.port}/#{parsed.db || 0}"
+
+      @pools[pool_key] ||= ConnectionPool.new(size: 10, timeout: 5) do
+        Redis.new(
+          host: parsed.host,
+          port: parsed.port,
+          db: parsed.db || 0  # CRITICAL: Set DB on connection creation
+        )
+      end
+
+      @pools[pool_key].with { |conn| conn }
+    end
+  end
+end
+
+# Initialize at app startup
+ConnectionManager.setup!
+```
+
+### Multi-Database Configuration
+
+```ruby
+class DatabasePoolManager
+  POOL_CONFIGS = {
+    0 => { size: 20, timeout: 5 },  # Main application data
+    1 => { size: 5,  timeout: 3 },  # Analytics/reporting
+    2 => { size: 10, timeout: 2 },  # Session/cache data
+    3 => { size: 15, timeout: 5 }   # Background jobs
+  }.freeze
+
+  @pools = {}
+
+  def self.setup!
+    Familia.connection_provider = lambda do |uri|
+      parsed = URI.parse(uri)
+      db = parsed.db || 0
+      server = "#{parsed.host}:#{parsed.port}"
+      pool_key = "#{server}/#{db}"
+
+      @pools[pool_key] ||= begin
+        config = POOL_CONFIGS[db] || { size: 5, timeout: 5 }
+
+        ConnectionPool.new(**config) do
+          Redis.new(
+            host: parsed.host,
+            port: parsed.port,
+            db: db,
+            timeout: 1,
+            reconnect_attempts: 3,
+            inherit_socket: false
+          )
+        end
+      end
+
+      @pools[pool_key].with { |conn| conn }
+    end
+  end
+end
+```
+
+## Advanced Patterns
+
+### Rails/Sidekiq Integration
+
+```ruby
+# config/initializers/familia_pools.rb
+class FamiliaPoolManager
+  include Singleton
+
+  def initialize
+    @pools = {}
+    setup_connection_provider
+  end
+
+  private
+
+  def setup_connection_provider
+    Familia.connection_provider = lambda do |uri|
+      get_connection(uri)
+    end
+  end
+
+  def get_connection(uri)
+    parsed = URI.parse(uri)
+    pool_key = connection_key(parsed)
+
+    @pools[pool_key] ||= create_pool(parsed)
+    @pools[pool_key].with { |conn| conn }
+  end
+
+  def connection_key(parsed_uri)
+    "#{parsed_uri.host}:#{parsed_uri.port}/#{parsed_uri.db || 0}"
+  end
+
+  def create_pool(parsed_uri)
+    db = parsed_uri.db || 0
+
+    ConnectionPool.new(
+      size: pool_size_for_database(db),
+      timeout: 5
+    ) do
+      Redis.new(
+        host: parsed_uri.host,
+        port: parsed_uri.port,
+        db: db,
+        timeout: redis_timeout,
+        reconnect_attempts: 3
+      )
+    end
+  end
+
+  def pool_size_for_database(db)
+    case db
+    when 0 then sidekiq_concurrency + web_concurrency + 2  # Main DB
+    when 1 then 5                                          # Analytics
+    when 2 then web_concurrency + 2                        # Sessions
+    else 5                                                  # Default
+    end
+  end
+
+  def sidekiq_concurrency
+    defined?(Sidekiq) ? Sidekiq.options[:concurrency] : 0
+  end
+
+  def web_concurrency
+    ENV.fetch('WEB_CONCURRENCY', 5).to_i
+  end
+
+  def redis_timeout
+    Rails.env.production? ? 1 : 5
+  end
+end
+
+# Initialize the pool manager
+FamiliaPoolManager.instance
+```
+
+### Request-Scoped Connections (Middleware)
+
+```ruby
+# Middleware for per-request connection management
+class FamiliaConnectionMiddleware
+  def initialize(app)
+    @app = app
+  end
+
+  def call(env)
+    # Provide a single connection for the entire request
+    ConnectionPool.with do |conn|
+      Thread.current[:familia_connection] = conn
+      @app.call(env)
+    end
+  ensure
+    Thread.current[:familia_connection] = nil
+  end
+end
+
+# In your Rack/Rails app
+use FamiliaConnectionMiddleware
+```
+
+## Model Database Configuration
+
+Configure models to use specific logical databases:
+
+```ruby
+class Customer < Familia::Horreum
+  self.logical_database = 0  # Primary application data
+  field :name, :email, :status
+end
+
+class AnalyticsEvent < Familia::Horreum
+  self.logical_database = 1  # Separate analytics database
+  field :event_type, :user_id, :timestamp, :properties
+end
+
+class SessionData < Familia::Horreum
+  self.logical_database = 2  # Fast cache database
+  feature :expiration
+  default_expiration 1.hour
+  field :user_id, :data, :csrf_token
+end
+
+class BackgroundJob < Familia::Horreum
+  self.logical_database = 3  # Job queue database
+  field :job_type, :payload, :status, :retry_count
+end
+```
+
+## Performance Benefits
+
+### Without Connection Pooling
+
+Each operation may trigger database switches:
+
+```ruby
+# These operations might use different connections, causing SELECT commands:
+customer = Customer.find(123)        # SELECT 0, then query
+session = SessionData.find(456)     # SELECT 2, then query
+analytics = AnalyticsEvent.find(789) # SELECT 1, then query
+```
+
+### With Connection Pooling
+
+Connections stay on the correct database:
+
+```ruby
+# Each model uses its dedicated connection pool:
+customer = Customer.find(123)        # Connection already on DB 0
+session = SessionData.find(456)     # Different connection, already on DB 2
+analytics = AnalyticsEvent.find(789) # Different connection, already on DB 1
+```
+
+## Pool Sizing Guidelines
+
+### Web Applications
+- **Formula**: `(threads_per_process * processes) + buffer`
+- **Puma**: `(threads * workers) + 2`
+- **Unicorn**: `processes + 2`
+
+### Background Jobs
+- **Sidekiq**: `concurrency + 2`
+- **DelayedJob**: `worker_processes + 2`
+
+### Database-Specific Sizing
+```ruby
+def pool_size_for_database(db)
+  base_size = web_concurrency + sidekiq_concurrency
+
+  case db
+  when 0 then base_size + 5      # Main DB: highest usage
+  when 1 then 3                  # Analytics: batch operations
+  when 2 then base_size + 2      # Sessions: per-request access
+  when 3 then sidekiq_concurrency # Jobs: worker access only
+  else 5                         # Default for new DBs
+  end
+end
+```
+
+## Monitoring and Debugging
+
+### Enable Debug Mode
+
+```ruby
+Familia.debug = true
+# Shows database selection and connection provider usage
+```
+
+### Pool Usage Monitoring
+
+```ruby
+class PoolMonitor
+  def self.stats
+    FamiliaPoolManager.instance.instance_variable_get(:@pools).map do |key, pool|
+      {
+        database: key,
+        size: pool.size,
+        available: pool.available,
+        checked_out: pool.size - pool.available
+      }
+    end
+  end
+
+  def self.health_check
+    stats.each do |stat|
+      utilization = (stat[:checked_out] / stat[:size].to_f) * 100
+      puts "DB #{stat[:database]}: #{utilization.round(1)}% utilized"
+      warn "High utilization!" if utilization > 80
+    end
+  end
+end
+```
+
+### Connection Testing
+
+```ruby
+# Test concurrent access patterns
+def test_concurrent_access
+  threads = 20.times.map do |i|
+    Thread.new do
+      50.times do |j|
+        Customer.create(name: "test-#{i}-#{j}")
+        SessionData.create(user_id: i, data: "session-#{j}")
+      end
+    end
+  end
+
+  threads.each(&:join)
+  puts "Concurrent test completed"
+end
+```
+
+## Troubleshooting
+
+### Common Issues
+
+**1. Wrong Database Connections**
+```ruby
+# Problem: Provider not setting DB correctly
+Redis.new(host: 'localhost', port: 6379)  # Missing db: parameter
+
+# Solution: Always specify database
+Redis.new(host: 'localhost', port: 6379, db: parsed_uri.db || 0)
+```
+
+**2. Pool Exhaustion**
+```ruby
+# Monitor pool usage
+ConnectionPool.stats  # If available
+# Increase pool size or reduce hold time
+```
+
+**3. Connection Leaks**
+```ruby
+# Always use .with for pool connections
+pool.with do |conn|
+  # Use connection
+end
+
+# Never checkout without returning
+conn = pool.checkout  # ❌ Can leak
+```
+
+### Error Handling
+
+```ruby
+Familia.connection_provider = lambda do |uri|
+  begin
+    get_pooled_connection(uri)
+  rescue Redis::ConnectionError => e
+    # Log error, potentially retry or fall back
+    Familia.logger.error "Connection failed: #{e.message}"
+    raise Familia::ConnectionError, "Pool connection failed"
+  end
+end
+```
+
+## Best Practices
+
+1. **Return Pre-Selected Connections**: Provider must return connections on the correct DB
+2. **One Pool Per Database**: Each logical DB needs its own pool
+3. **Thread Safety**: Use thread-safe pool creation and access
+4. **Monitor Usage**: Track pool utilization and adjust sizes
+5. **Proper Sizing**: Account for all concurrent access patterns
+6. **Error Handling**: Gracefully handle connection failures
+7. **Connection Validation**: Verify connections are healthy before use
+
+## Integration Examples
+
+### Roda Application
+
+```ruby
+class App < Roda
+  plugin :hooks
+
+  before do
+    # Connection pooling handled automatically via provider
+    # Each request gets appropriate connections per database
+  end
+
+  route do |r|
+    r.get 'customers', Integer do |id|
+      customer = Customer.find(id)        # Uses DB 0 pool
+      session = SessionData.find(r.env)  # Uses DB 2 pool
+
+      render_json(customer: customer, session: session)
+    end
+  end
+end
+```
+
+### Background Jobs
+
+```ruby
+class ProcessCustomerJob
+  include Sidekiq::Worker
+
+  def perform(customer_id)
+    # Each of these uses appropriate database pool
+    customer = Customer.find(customer_id)           # DB 0
+    SessionData.expire_for_user(customer_id)       # DB 2
+    AnalyticsEvent.track('job.completed', user: customer_id)  # DB 1
+  end
+end
+```
+
+This connection pooling system provides the foundation for scalable, performant Familia applications with proper resource management across multiple logical databases.