familia 2.0.0.pre.pre → 2.0.0.pre3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 92ee81bd30cdbcb84de0e72a26bde44a170efcd6578d81bdd47458aee37f52be
-  data.tar.gz: 4127847dbc955df3e6a7c7a3dd616dd3438da046f8703a59c734399697cf8903
+  metadata.gz: a5d32d5a95de13ddda788d37390fb97e7a73c5ff1b80515bf55f2db16d18a211
+  data.tar.gz: b5a97154c4f4461de329d5190b239b0db135304ce2b36e59d226f8b37ade5614
 SHA512:
-  metadata.gz: 87f8ff4b5423771ce6c1c93640cd3e83ea1e9beb023c130896878bed64fd61341ac18b365641bd7c30310fafdcf1b31569ca726dbaedf5c7ec23d308805b3305
-  data.tar.gz: d76036d625a604014380a67e5765263c2ea51bb608da09344a57fb4cf8386ae724499bb27e352c7d7133d15ae16a052dcb27ea262943cb509662666c72983d13
+  metadata.gz: e51b2929601c71ed5fc33465fc39732fdae070c44427af3352de73e4f5b1ae14af6fc075a1179b5c0c197c6fe0e699c524e251ce22a33049f353f9d385495b09
+  data.tar.gz: 3be9e23886a0c327dbbe529a683675ca2a3dc0a3c3774a1eab447f49f7949b4b9c5a82248b6fea1a0ad546eb261872e6a54f3ef6c2ebcf6df51277c0b720aeb5

data/CLAUDE.md

@@ -5,10 +5,17 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 ## Development Commands
 
 ### Testing
-- **Run tests**: `bundle exec tryouts` (uses tryouts testing framework)
-- **Run specific test file**: `bundle exec tryouts try/specific_test_try.rb`
-- **Debug mode**: `FAMILIA_DEBUG=1 bundle exec tryouts`
-- **Trace mode**: `FAMILIA_TRACE=1 bundle exec tryouts` (detailed Redis operation logging)
+
+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.
+
+- **Run tests**: `bundle exec try` (uses tryouts testing framework)
+- **Run specific test file, verbose**: `bundle exec try -v try/specific_test_try.rb`
+- **Debug mode**: `FAMILIA_DEBUG=1 bundle exec try -D`
+- **Trace mode**: `FAMILIA_TRACE=1 bundle exec try -D` (detailed Redis operation logging)
 
 ### Development Setup
 - **Install dependencies**: `bundle install`
@@ -74,7 +81,7 @@ end
 ```
 
 **Identifier Resolution**: Multiple strategies for object identification:
-- Symbol: `identifier :email`
+- Symbol: `identifier_field :email`
 - Proc: `identifier ->(user) { "user:#{user.email}" }`
 - Array: `identifier [:type, :email]`
 

data/Gemfile

@@ -6,16 +6,16 @@ gemspec
 
 group :test do
   if ENV['LOCAL_DEV']
-    gem 'tryouts', path: '../../d/tryouts'
+    gem 'tryouts', path: '../tryouts'
+    gem 'uri-valkey', path: '..//uri-valkey/gems', glob: 'uri-valkey.gemspec'
   else
-    gem 'tryouts', '~> 3.1.1', require: false
+    gem 'tryouts', '~> 3.1.2', require: false
   end
   gem 'concurrent-ruby', '~> 1.3.5', require: false
   gem 'ruby-prof'
   gem 'stackprof'
 end
 
-
 group :development, :test do
   # byebug only works with MRI
   gem 'byebug', '~> 11.0', require: false if RUBY_ENGINE == 'ruby'
@@ -25,4 +25,5 @@ group :development, :test do
   gem 'rubocop-performance', require: false
   gem 'rubocop-thread_safety', require: false
   gem 'yard', '~> 0.9', require: false
+  gem 'irb', '~> 1.15.2', require: false
 end

data/Gemfile.lock

@@ -1,14 +1,14 @@
 PATH
   remote: .
   specs:
-    familia (2.0.0.pre.pre)
+    familia (2.0.0.pre2)
       benchmark
       connection_pool
       csv
       logger
       redis (>= 4.8.1, < 6.0)
       stringio (~> 3.1.1)
-      uri-redis (~> 1.3)
+      uri-valkey (~> 1.4)
 
 GEM
   remote: https://rubygems.org/
@@ -21,8 +21,14 @@ GEM
     concurrent-ruby (1.3.5)
     connection_pool (2.5.3)
     csv (3.3.5)
+    date (3.4.1)
     diff-lcs (1.6.2)
-    drydock (0.6.9)
+    erb (5.0.2)
+    io-console (0.8.1)
+    irb (1.15.2)
+      pp (>= 0.6.0)
+      rdoc (>= 4.0.0)
+      reline (>= 0.4.2)
     json (2.13.0)
     kramdown (2.5.1)
       rexml (>= 3.3.9)
@@ -35,6 +41,9 @@ GEM
     parser (3.3.8.0)
       ast (~> 2.4.1)
       racc
+    pp (0.6.2)
+      prettyprint
+    prettyprint (0.2.0)
     prism (1.4.0)
     pry (0.14.2)
       coderay (~> 1.1)
@@ -42,13 +51,21 @@ GEM
     pry-byebug (3.10.1)
       byebug (~> 11.0)
       pry (>= 0.13, < 0.15)
+    psych (5.2.6)
+      date
+      stringio
     racc (1.8.1)
     rainbow (3.1.1)
+    rdoc (6.14.2)
+      erb
+      psych (>= 4.0.0)
     redis (5.4.1)
       redis-client (>= 0.22.0)
     redis-client (0.25.1)
       connection_pool
     regexp_parser (2.10.0)
+    reline (0.6.2)
+      io-console (~> 0.5)
     rexml (3.4.1)
     rspec (3.13.1)
       rspec-core (~> 3.13.0)
@@ -89,19 +106,14 @@ GEM
       base64
     ruby-progressbar (1.13.0)
     stackprof (0.2.27)
-    storable (0.10.0)
     stringio (3.1.7)
-    sysinfo (0.10.0)
-      drydock (< 1.0)
-      storable (~> 0.10)
-    tryouts (3.1.1)
+    tryouts (3.1.2)
       minitest (~> 5.0)
       rspec (~> 3.0)
-      sysinfo (>= 0.8, < 1.0)
     unicode-display_width (3.1.4)
       unicode-emoji (~> 4.0, >= 4.0.4)
     unicode-emoji (4.0.4)
-    uri-redis (1.3.0)
+    uri-valkey (1.4.0)
     yard (0.9.37)
 
 PLATFORMS
@@ -112,6 +124,7 @@ DEPENDENCIES
   byebug (~> 11.0)
   concurrent-ruby (~> 1.3.5)
   familia!
+  irb (~> 1.15.2)
   kramdown
   pry-byebug (~> 3.10.1)
   rubocop
@@ -119,7 +132,7 @@ DEPENDENCIES
   rubocop-thread_safety
   ruby-prof
   stackprof
-  tryouts (~> 3.1.1)
+  tryouts (~> 3.1.2)
   yard (~> 0.9)
 
 BUNDLED WITH

data/bin/irb

@@ -1,3 +1,3 @@
 #!/bin/bash
 
-irb -ruri/redis -Ilib -r familia -Itry -r helpers/test_helpers
+irb -Ilib -r familia -Itry -r helpers/test_helpers

data/docs/connection_pooling.md

@@ -1,317 +1,192 @@
 # Connection Pooling with Familia
 
-Familia uses a flexible connection provider pattern that allows you to implement connection pooling in your application. This guide shows how to configure connection pools for optimal performance with multiple logical databases.
+Familia uses a connection provider pattern for efficient connection pooling. This guide shows how to configure pools for optimal performance with multiple logical databases.
 
 ## Key Concepts
 
-1. **Connection Provider Contract**: When you provide a `connection_provider`, it MUST return connections already on the correct logical database. Familia will NOT issue SELECT commands after receiving a connection from the provider.
+- **Connection Provider Contract**: Your provider MUST return connections already on the correct logical database. Familia will NOT issue SELECT commands.
+- **URI-based Selection**: Familia passes normalized URIs (e.g., `redis://localhost:6379/2`) encoding the logical database.
+- **One Pool Per Database**: Each unique logical database requires its own connection pool.
 
-2. **URI-based Selection**: Familia passes normalized URIs (e.g., `redis://localhost:6379/2`) to your provider, encoding the logical database in the URI.
+## Basic Setup
 
-3. **One Pool Per Database**: Since Familia models can use different logical databases, you typically need one connection pool per unique database.
-
-## Basic Connection Pool Setup
-
-### Example 1: Simple Connection Pool
+### Simple Connection Pool
 
 ```ruby
 require 'connection_pool'
-require 'familia'
 
 class MyApp
-  def self.setup_familia_pools
-    @pools = {}
-    
-    Familia.connection_provider = lambda do |uri|
-      parsed = URI.parse(uri)
-      pool_key = "#{parsed.host}:#{parsed.port}/#{parsed.db || 0}"
-      
-      # Create a pool for each unique database
-      @pools[pool_key] ||= ConnectionPool.new(size: 10, timeout: 5) do
-        Redis.new(
-          host: parsed.host,
-          port: parsed.port,
-          db: parsed.db || 0  # Connection created with correct DB
-        )
-      end
-      
-      # Return a connection from the pool
-      @pools[pool_key].with { |conn| conn }
+  @pools = {}
+
+  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
+      )
     end
+
+    @pools[pool_key].with { |conn| conn }
   end
 end
 ```
 
-### Example 2: Advanced Pooling with Different Configurations
+### Multi-Database Configuration
 
 ```ruby
 class MyApp
-  # Different pool sizes based on expected traffic
   POOL_CONFIGS = {
-    0 => { size: 20, timeout: 5 },  # High-traffic main database
-    1 => { size: 5, timeout: 5 },   # Low-traffic analytics database
-    2 => { size: 10, timeout: 5 },  # Medium-traffic cache database
-    3 => { size: 5, timeout: 5 }    # Session database
-  }
-  
-  def self.setup_familia_pools
-    @pools = {}
-    
-    Familia.connection_provider = lambda do |uri|
-      parsed = URI.parse(uri)
-      db = parsed.db || 0
-      pool_key = "#{parsed.host}:#{parsed.port}/#{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)
-        end
+    0 => { size: 20 },  # Main database
+    1 => { size: 5 },   # Analytics
+    2 => { size: 10 }   # Cache
+  }.freeze
+
+  @pools = {}
+
+  Familia.connection_provider = lambda do |uri|
+    parsed = URI.parse(uri)
+    db = parsed.db || 0
+    pool_key = "#{parsed.host}:#{parsed.port}/#{db}"
+
+    @pools[pool_key] ||= begin
+      config = POOL_CONFIGS[db] || { size: 5 }
+      ConnectionPool.new(timeout: 5, **config) do
+        Redis.new(host: parsed.host, port: parsed.port, db: db)
       end
-      
-      @pools[pool_key].with { |conn| conn }
     end
+
+    @pools[pool_key].with { |conn| conn }
   end
 end
 ```
 
-### Example 3: Using with Puma/Multi-threaded Servers
+### Production Setup with Roda
 
 ```ruby
-# In config/initializers/familia.rb
+# config/familia.rb
+class FamiliaPoolManager
+  include Singleton
 
-# Global connection pools shared across threads
-$redis_pools = {}
-$pool_mutex = Mutex.new
+  def initialize
+    @pools = {}
+  end
 
-Familia.connection_provider = lambda do |uri|
-  parsed = URI.parse(uri)
-  pool_key = parsed.to_s
-  
-  # Thread-safe pool creation
-  $pool_mutex.synchronize do
-    $redis_pools[pool_key] ||= ConnectionPool.new(
-      size: ENV.fetch('RAILS_MAX_THREADS', 5).to_i,
+  def get_connection(uri)
+    parsed = URI.parse(uri)
+    pool_key = "#{parsed.host}:#{parsed.port}/#{parsed.db || 0}"
+
+    @pools[pool_key] ||= ConnectionPool.new(
+      size: pool_size_for_environment,
       timeout: 5
     ) do
       Redis.new(
         host: parsed.host,
         port: parsed.port,
         db: parsed.db || 0,
-        timeout: 1,  # Connection timeout
+        timeout: 1,
         reconnect_attempts: 3
       )
     end
-  end
-  
-  $redis_pools[pool_key].with { |conn| conn }
-end
-```
-
-### Example 4: Using with Sidekiq
-
-```ruby
-# Sidekiq has its own connection pool management
-# This example shows how to share pools between Sidekiq and web processes
 
-class RedisConnectionPools
-  include Singleton
-  
-  def initialize
-    @pools = {}
-    @mutex = Mutex.new
+    @pools[pool_key].with { |conn| conn }
   end
-  
-  def get_connection(uri)
-    parsed = URI.parse(uri)
-    pool_key = "#{parsed.host}:#{parsed.port}/#{parsed.db || 0}"
-    
-    pool = @mutex.synchronize do
-      @pools[pool_key] ||= ConnectionPool.new(
-        size: determine_pool_size,
-        timeout: 5
-      ) do
-        Redis.new(
-          host: parsed.host,
-          port: parsed.port,
-          db: parsed.db || 0
-        )
-      end
-    end
-    
-    pool.with { |conn| conn }
-  end
-  
+
   private
-  
-  def determine_pool_size
+
+  def pool_size_for_environment
     if defined?(Sidekiq)
-      # Sidekiq workers need more connections
       Sidekiq.options[:concurrency] + 2
     else
-      # Web processes need fewer connections
-      ENV.fetch('RAILS_MAX_THREADS', 5).to_i
+      ENV.fetch('WEB_CONCURRENCY', 5).to_i + 2
     end
   end
 end
 
-# Configure Familia
+# Configure at application startup
 Familia.connection_provider = lambda do |uri|
-  RedisConnectionPools.instance.get_connection(uri)
+  FamiliaPoolManager.instance.get_connection(uri)
+end
+
+# In your Roda app
+class App < Roda
+  plugin :hooks
+
+  before do
+    # Familia pools are automatically used via connection_provider
+  end
 end
 ```
 
 ## Model Configuration
 
-Models can specify different logical databases:
+Configure models to use different logical databases:
 
 ```ruby
-# Models using different logical databases
 class Customer < Familia::Horreum
   self.logical_database = 0  # Main application data
-  field :name
-  field :email
+  field :name, :email
 end
 
 class Analytics < Familia::Horreum
-  self.logical_database = 1  # Analytics data  
-  field :event_type
-  field :timestamp
+  self.logical_database = 1  # Analytics data
+  field :event_type, :timestamp
 end
 
 class Session < Familia::Horreum
   self.logical_database = 2  # Session/cache data
   feature :expiration
   default_expiration 1.hour
-  field :user_id
-  field :data
-end
-
-# Models can share the same logical database
-class Order < Familia::Horreum
-  self.logical_database = 0  # Shares DB with Customer
-  field :customer_id
-  field :total
+  field :user_id, :data
 end
 ```
 
-## Performance Optimization
-
-### Avoiding SELECT Command Overhead
-
-Without proper pooling configuration, each Redis operation might issue a SELECT command:
+## Performance Benefits
 
+Without connection pooling, each operation triggers database switches:
 ```
-# Bad: Without connection provider
 SET key value     # Connection on DB 0
 SELECT 2          # Switch to DB 2
 SET key2 value2   # Now on DB 2
 SELECT 0          # Switch back
-GET key           # Now on DB 0
 ```
 
-With the connection provider pattern:
-
+With proper pooling, connections stay on the correct database:
 ```
-# Good: With connection provider  
-SET key value     # Connection already on correct DB
-SET key2 value2   # Different connection, already on correct DB
-GET key           # Original connection, still on correct DB
+SET key value     # Connection already on DB 0
+SET key2 value2   # Different connection, already on DB 2
 ```
 
-### Pool Sizing Guidelines
-
-1. **Web Applications**: `pool_size = number_of_threads + buffer`
-   ```ruby
-   size: ENV.fetch('RAILS_MAX_THREADS', 5).to_i + 2
-   ```
+## Pool Sizing Guidelines
 
-2. **Background Jobs**: `pool_size = concurrency + buffer`
-   ```ruby
-   size: Sidekiq.options[:concurrency] + 5
-   ```
+- **Web Applications**: `threads + 2`
+- **Background Jobs**: `concurrency + 2`
+- **High Traffic DBs**: Scale up based on usage patterns
 
-3. **Mixed Workloads**: Size based on the logical database's usage pattern
-   ```ruby
-   POOL_CONFIGS = {
-     0 => { size: 20 },  # High-traffic main DB
-     1 => { size: 5 },   # Low-traffic analytics
-     2 => { size: 15 }   # Medium-traffic cache
-   }
-   ```
-
-## Testing Your Configuration
+## Testing and Debugging
 
+Enable debug mode to verify correct database selection:
 ```ruby
-# Test helper to verify pools are working correctly
-class ConnectionPoolTester
-  def self.test_pools
-    # Create test models using different databases
-    class TestModel0 < Familia::Horreum
-      self.logical_database = 0
-      field :value
-    end
-    
-    class TestModel1 < Familia::Horreum  
-      self.logical_database = 1
-      field :value
-    end
-    
-    # Test concurrent access
-    threads = 10.times.map do |i|
-      Thread.new do
-        100.times do |j|
-          # This should use the pool for DB 0
-          TestModel0.create(value: "thread-#{i}-#{j}")
-          
-          # This should use the pool for DB 1
-          TestModel1.create(value: "thread-#{i}-#{j}")
-        end
-      end
-    end
-    
-    threads.each(&:join)
-    puts "Pool test completed successfully"
-  end
-end
-```
-
-## Monitoring and Debugging
-
-Enable debug mode to verify connection providers are returning connections on the correct database:
-
-```ruby
-Familia.debug = true  # Logs warnings if provider returns wrong DB
+Familia.debug = true
 ```
 
-Monitor pool usage:
-
+Test concurrent access:
 ```ruby
-# Add monitoring to your connection provider
-Familia.connection_provider = lambda do |uri|
-  pool = get_pool_for(uri)
-  
-  # Log pool statistics
-  Rails.logger.info "Pool stats: #{pool.size} size, #{pool.available} available"
-  
-  pool.with { |conn| conn }
+threads = 10.times.map do |i|
+  Thread.new do
+    100.times { |j| MyModel.create(value: "test-#{i}-#{j}") }
+  end
 end
+threads.each(&:join)
 ```
 
-## Common Pitfalls
-
-1. **Not returning DB-ready connections**: Your provider MUST return connections already on the correct database.
-
-2. **Creating too many pools**: Ensure you're keying pools correctly to avoid creating duplicate pools for the same database.
-
-3. **Forgetting thread safety**: Pool creation should be thread-safe in multi-threaded environments.
-
-4. **Incorrect pool sizing**: Monitor your connection usage and adjust pool sizes accordingly.
-
-## Summary
+## Best Practices
 
-- Familia delegates connection management to your application via `connection_provider`
-- Providers must return connections already on the correct logical database
-- Use the `connection_pool` gem for robust pooling
-- Create one pool per unique logical database
-- Monitor and tune pool sizes based on your workload
+- Return connections already on the correct database
+- Use one pool per unique logical database
+- Implement thread-safe pool creation
+- Monitor pool usage and adjust sizes accordingly
+- Use the `connection_pool` gem for production reliability

data/familia.gemspec

@@ -25,7 +25,7 @@ Gem::Specification.new do |spec|
   spec.add_dependency 'logger'
   spec.add_dependency 'redis', '>= 4.8.1', '< 6.0'
   spec.add_dependency 'stringio', '~> 3.1.1'
-  spec.add_dependency 'uri-redis', '~> 1.3'
+  spec.add_dependency 'uri-valkey', '~> 1.4'
 
   spec.metadata['rubygems_mfa_required'] = 'true'
 end

data/lib/familia/connection.rb

@@ -107,7 +107,7 @@ module Familia
         # Provider MUST return connection already on the correct database
         parsed_uri = normalize_uri(uri)
         connection = connection_provider.call(parsed_uri.to_s)
-        
+
         # In debug mode, verify the provider honored the contract
         if Familia.debug? && connection.respond_to?(:client)
           current_db = connection.client.db
@@ -116,7 +116,7 @@ module Familia
             Familia.warn "Connection provider returned connection on DB #{current_db}, expected #{expected_db}"
           end
         end
-        
+
         return connection
       end
 
@@ -231,7 +231,7 @@ module Familia
     # Provides explicit access to a Database connection.
     #
     # This method is useful when you need direct access to a connection
-    # for operations not covered by other methods. The connection is 
+    # for operations not covered by other methods. The connection is
     # properly managed and returned to the pool (if using connection_provider).
     #
     # @yield [Redis] A Database connection

data/lib/familia/core_ext.rb

@@ -12,7 +12,7 @@ class String
   #
   # @return [Float, nil] The time in seconds, or nil if the string is invalid
   def in_seconds
-    q, u = scan(/([\d.]+)([smh])?/).flatten
+    q, u = scan(/([\d.]+)([smhyd])?/).flatten
     q &&= q.to_f and u ||= 's'
     q&.in_seconds(u)
   end
@@ -125,7 +125,7 @@ class Numeric
     size = abs.to_f
     unit = 0
 
-    while size > 1024 && unit < units.length - 1
+    while size >= 1024 && unit < units.length - 1
       size /= 1024
       unit += 1
     end

data/lib/familia/features/expiration.rb

@@ -92,7 +92,6 @@ module Familia::Features
       # a bool.
       expire(default_expiration)
     end
-
     extend ClassMethods
 
     Familia::Base.add_feature self, :expiration