familia 1.2.1 → 2.0.0.pre2

data/Gemfile.lock

@@ -1,84 +1,145 @@
 PATH
   remote: .
   specs:
-    familia (1.2.1)
+    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/
   specs:
-    ast (2.4.2)
+    ast (2.4.3)
+    base64 (0.3.0)
+    benchmark (0.4.1)
     byebug (11.1.3)
     coderay (1.1.3)
-    connection_pool (2.4.1)
+    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)
-    json (2.7.2)
-    language_server-protocol (3.17.0.3)
+    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)
+    language_server-protocol (3.17.0.5)
+    lint_roller (1.1.0)
+    logger (1.7.0)
     method_source (1.1.0)
-    parallel (1.25.1)
-    parser (3.3.4.0)
+    minitest (5.25.5)
+    parallel (1.27.0)
+    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)
       method_source (~> 1.0)
     pry-byebug (3.10.1)
       byebug (~> 11.0)
       pry (>= 0.13, < 0.15)
-    racc (1.8.0)
+    psych (5.2.6)
+      date
+      stringio
+    racc (1.8.1)
     rainbow (3.1.1)
-    redis (5.2.0)
+    rdoc (6.14.2)
+      erb
+      psych (>= 4.0.0)
+    redis (5.4.1)
       redis-client (>= 0.22.0)
-    redis-client (0.22.2)
+    redis-client (0.25.1)
       connection_pool
-    regexp_parser (2.9.2)
-    rexml (3.3.2)
-      strscan
-    rubocop (1.65.0)
+    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)
+      rspec-expectations (~> 3.13.0)
+      rspec-mocks (~> 3.13.0)
+    rspec-core (3.13.5)
+      rspec-support (~> 3.13.0)
+    rspec-expectations (3.13.5)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.13.0)
+    rspec-mocks (3.13.5)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.13.0)
+    rspec-support (3.13.4)
+    rubocop (1.78.0)
       json (~> 2.3)
-      language_server-protocol (>= 3.17.0)
+      language_server-protocol (~> 3.17.0.2)
+      lint_roller (~> 1.1.0)
       parallel (~> 1.10)
       parser (>= 3.3.0.2)
       rainbow (>= 2.2.2, < 4.0)
-      regexp_parser (>= 2.4, < 3.0)
-      rexml (>= 3.2.5, < 4.0)
-      rubocop-ast (>= 1.31.1, < 2.0)
+      regexp_parser (>= 2.9.3, < 3.0)
+      rubocop-ast (>= 1.45.1, < 2.0)
       ruby-progressbar (~> 1.7)
-      unicode-display_width (>= 2.4.0, < 3.0)
-    rubocop-ast (1.31.3)
-      parser (>= 3.3.1.0)
-    rubocop-performance (1.21.1)
-      rubocop (>= 1.48.1, < 2.0)
-      rubocop-ast (>= 1.31.1, < 2.0)
-    rubocop-thread_safety (0.5.1)
-      rubocop (>= 0.90.0)
+      unicode-display_width (>= 2.4.0, < 4.0)
+    rubocop-ast (1.46.0)
+      parser (>= 3.3.7.2)
+      prism (~> 1.4)
+    rubocop-performance (1.25.0)
+      lint_roller (~> 1.1)
+      rubocop (>= 1.75.0, < 2.0)
+      rubocop-ast (>= 1.38.0, < 2.0)
+    rubocop-thread_safety (0.7.3)
+      lint_roller (~> 1.1)
+      rubocop (~> 1.72, >= 1.72.1)
+      rubocop-ast (>= 1.44.0, < 2.0)
+    ruby-prof (1.7.2)
+      base64
     ruby-progressbar (1.13.0)
+    stackprof (0.2.27)
     storable (0.10.0)
-    stringio (3.1.1)
-    strscan (3.1.0)
+    stringio (3.1.7)
     sysinfo (0.10.0)
       drydock (< 1.0)
       storable (~> 0.10)
-    tryouts (2.4.1)
-      sysinfo (~> 0.10)
-    unicode-display_width (2.5.0)
-    uri-redis (1.3.0)
+    tryouts (3.1.1)
+      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-valkey (1.4.0)
+    yard (0.9.37)
 
 PLATFORMS
-  arm64-darwin-23
   arm64-darwin-24
   ruby
 
 DEPENDENCIES
   byebug (~> 11.0)
+  concurrent-ruby (~> 1.3.5)
   familia!
+  irb (~> 1.15.2)
+  kramdown
   pry-byebug (~> 3.10.1)
   rubocop
   rubocop-performance
   rubocop-thread_safety
-  tryouts (~> 2.4)
+  ruby-prof
+  stackprof
+  tryouts (~> 3.1.1)
+  yard (~> 0.9)
 
 BUNDLED WITH
-   2.5.13
+   2.6.2

data/README.md

@@ -1,8 +1,8 @@
-# Familia - 1.1.0-rc1 (November 2024)
+# Familia - 2.0.0
 
-**Organize and store Ruby objects in Redis. A powerful Ruby ORM (of sorts) for Redis.**
+**Organize and store Ruby objects in Valkey/Redis. A powerful Ruby ORM (of sorts) for Valkey/Redis.**
 
-Familia provides a flexible and feature-rich way to interact with Redis using Ruby objects. It's designed to make working with Redis as natural as working with Ruby classes, while offering advanced features for complex data management.
+Familia provides a flexible and feature-rich way to interact with Valkey using Ruby objects. It's designed to make working with Valkey as natural as working with Ruby classes, while offering advanced features for complex data management.
 
 ## Installation
 
@@ -18,11 +18,11 @@ Get it in one of the following ways:
 
 ### 1. Defining Horreum Classes
 
-Familia uses the concept of "Horreum" classes to represent Redis-backed objects:
+Familia uses the concept of "Horreum" classes to represent Valkey-compatible objects:
 
 ```ruby
 class Flower < Familia::Horreum
-  identifier :token
+  identifier_field :token
   field :name
   list :owners
   set :tags
@@ -38,20 +38,20 @@ You can define identifiers in various ways:
 
 ```ruby
 class User < Familia::Horreum
-  identifier :email
+  identifier_field :email
   # or
-  identifier -> (user) { "user:#{user.email}" }
+  identifier_field -> (user) { "user:#{user.email}" }
   # or
-  identifier [:type, :email]
+  identifier_field [:type, :email]
 
   field :email
   field :type
 end
 ```
 
-### 3. Redis Data Types
+### 3. Data Types
 
-Familia supports various Redis data types:
+Familia supports various Valkey-compatible data types:
 
 ```ruby
 class Product < Familia::Horreum
@@ -63,9 +63,9 @@ class Product < Familia::Horreum
 end
 ```
 
-### 4. Class-level Redis Types
+### 4. Class-level Valkey-compatible Types
 
-You can also define Redis types at the class level:
+You can also define Valkey-compatible types at the class level:
 
 ```ruby
 class Customer < Familia::Horreum
@@ -78,12 +78,12 @@ end
 
 ### 5. Automatic Expiration
 
-Use the expiration feature to set TTL for objects:
+Use the expiration feature to set default TTL for objects:
 
 ```ruby
 class Session < Familia::Horreum
   feature :expiration
-  ttl 180.minutes
+  default_expiration 180.minutes
 end
 ```
 
@@ -110,7 +110,7 @@ Use quantization for time-based metrics:
 ```ruby
 class DailyMetric < Familia::Horreum
   feature :quantization
-  string :counter, ttl: 1.day, quantize: [10.minutes, '%H:%M']
+  string :counter, default_expiration: 1.day, quantize: [10.minutes, '%H:%M']
 end
 ```
 
@@ -140,13 +140,6 @@ class Customer < Familia::Horreum
     verified && !reset_requested
   end
 end
-
-class Session < Familia::Horreum
-  def external_identifier
-    elements = [ipaddress || 'UNKNOWNIP', custid || 'anon']
-    @external_identifier ||= Familia.generate_sha_hash(elements)
-  end
-end
 ```
 ### 10. Open-ended Serialization
 
@@ -171,6 +164,29 @@ user.transaction do |conn|
 end
 ```
 
+### 12. Connection Management and Pooling
+
+Familia supports custom connection providers for advanced scenarios like connection pooling:
+
+```ruby
+# Using connection_pool gem for thread-safe pooling
+require 'connection_pool'
+
+# Create pools for each logical database
+pools = {
+  "redis://localhost:6379/0" => ConnectionPool.new(size: 10) { Redis.new(db: 0) },
+  "redis://localhost:6379/1" => ConnectionPool.new(size: 5) { Redis.new(db: 1) }
+}
+
+# Configure Familia to use the pools
+Familia.connection_provider = lambda do |uri|
+  pool = pools[uri] || pools["redis://localhost:6379/0"]
+  pool.with { |conn| conn }
+end
+```
+
+See the [Connection Pooling Guide](docs/connection_pooling.md) for detailed examples.
+
 
 ## Usage Examples
 
@@ -225,7 +241,7 @@ end
 
 ## Conclusion
 
-Familia provides a powerful and flexible way to work with Redis in Ruby applications. Its features like automatic expiration, safe dumping, and quantization make it suitable for a wide range of use cases, from simple key-value storage to complex time-series data management.
+Familia provides a powerful and flexible way to work with Valkey-compatible in Ruby applications. Its features like automatic expiration, safe dumping, and quantization make it suitable for a wide range of use cases, from simple key-value storage to complex time-series data management.
 
 For more information, visit:
 - [Github Repository](https://github.com/delano/familia)

data/bin/irb

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

data/docs/connection_pooling.md

@@ -0,0 +1,192 @@
+# Connection Pooling with Familia
+
+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
+
+- **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.
+
+## Basic Setup
+
+### Simple Connection Pool
+
+```ruby
+require 'connection_pool'
+
+class MyApp
+  @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
+```
+
+### Multi-Database Configuration
+
+```ruby
+class MyApp
+  POOL_CONFIGS = {
+    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
+    end
+
+    @pools[pool_key].with { |conn| conn }
+  end
+end
+```
+
+### Production Setup with Roda
+
+```ruby
+# config/familia.rb
+class FamiliaPoolManager
+  include Singleton
+
+  def initialize
+    @pools = {}
+  end
+
+  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,
+        reconnect_attempts: 3
+      )
+    end
+
+    @pools[pool_key].with { |conn| conn }
+  end
+
+  private
+
+  def pool_size_for_environment
+    if defined?(Sidekiq)
+      Sidekiq.options[:concurrency] + 2
+    else
+      ENV.fetch('WEB_CONCURRENCY', 5).to_i + 2
+    end
+  end
+end
+
+# Configure at application startup
+Familia.connection_provider = lambda do |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
+
+Configure models to use different logical databases:
+
+```ruby
+class Customer < Familia::Horreum
+  self.logical_database = 0  # Main application data
+  field :name, :email
+end
+
+class Analytics < Familia::Horreum
+  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, :data
+end
+```
+
+## Performance Benefits
+
+Without connection pooling, each operation triggers database switches:
+```
+SET key value     # Connection on DB 0
+SELECT 2          # Switch to DB 2
+SET key2 value2   # Now on DB 2
+SELECT 0          # Switch back
+```
+
+With proper pooling, connections stay on the correct database:
+```
+SET key value     # Connection already on DB 0
+SET key2 value2   # Different connection, already on DB 2
+```
+
+## Pool Sizing Guidelines
+
+- **Web Applications**: `threads + 2`
+- **Background Jobs**: `concurrency + 2`
+- **High Traffic DBs**: Scale up based on usage patterns
+
+## Testing and Debugging
+
+Enable debug mode to verify correct database selection:
+```ruby
+Familia.debug = true
+```
+
+Test concurrent access:
+```ruby
+threads = 10.times.map do |i|
+  Thread.new do
+    100.times { |j| MyModel.create(value: "test-#{i}-#{j}") }
+  end
+end
+threads.each(&:join)
+```
+
+## Best Practices
+
+- 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

@@ -1,12 +1,12 @@
-# frozen_string_literal: true
+# lib/familia/settings.rb
 
 require_relative 'lib/familia/version'
 
 Gem::Specification.new do |spec|
   spec.name        = 'familia'
-  spec.version     = Familia::VERSION.to_s
-  spec.summary     = 'An ORM for Redis in Ruby.'
-  spec.description = "Familia: #{spec.summary}. Organize and store ruby objects in Redis"
+  spec.version     = Familia::VERSION
+  spec.summary     = 'An ORM for Valkey-compatible databases in Ruby.'
+  spec.description = "Familia: #{spec.summary}. Organize and store ruby objects in Valkey/Redis"
   spec.authors     = ['Delano Mandelbaum']
   spec.email       = 'gems@solutious.com'
   spec.homepage    = 'https://github.com/delano/familia'
@@ -17,11 +17,15 @@ Gem::Specification.new do |spec|
   spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
   spec.require_paths = ['lib']
 
-  spec.required_ruby_version = Gem::Requirement.new('>= 2.7.8')
+  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 '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/base.rb

@@ -1,8 +1,8 @@
-# frozen_string_literal: true
+# lib/familia/base.rb
 
 #
 module Familia
-  # A common module for Familia::RedisType and Familia::Horreum to include.
+  # A common module for Familia::DataType and Familia::Horreum to include.
   #
   # This allows us to use a single comparison to check if a class is a
   # Familia class. e.g.
@@ -11,13 +11,23 @@ module Familia
   #     klass.ancestors.member?(Familia::Base) # => true
   #
   # @see Familia::Horreum
-  # @see Familia::RedisType
+  # @see Familia::DataType
   #
   module Base
     @features = nil
     @dump_method = :to_json
     @load_method = :from_json
 
+    # 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.
+    #
+    # @return [String] A string representation of the object. Never nil.
+    #
+    def to_s
+      "#<#{self.class}:0x#{object_id.to_s(16)}>"
+    end
+
     class << self
       attr_reader :features
       attr_accessor :dump_method, :load_method
@@ -34,23 +44,23 @@ module Familia
     # with the :expiration feature's implementation.
     #
     # This is a no-op implementation that gets overridden by features like
-    # :expiration. It accepts an optional ttl parameter to maintain interface
+    # :expiration. It accepts an optional default_expiration parameter to maintain interface
     # compatibility with the overriding implementations.
     #
-    # @param ttl [Integer, nil] Time To Live in seconds (ignored in base implementation)
+    # @param default_expiration [Integer, nil] Time To Live in seconds (ignored in base implementation)
     # @return [nil] Always returns nil
     #
     # @note This is a no-op implementation. Classes that need expiration
     #       functionality should include the :expiration feature.
     #
-    def update_expiration(ttl: nil)
-      Familia.ld "[update_expiration] Feature not enabled for #{self.class}. Key: #{rediskey} (caller: #{caller(1..1)})"
+    def update_expiration(default_expiration: nil)
+      Familia.ld "[update_expiration] Feature not enabled for #{self.class}. Key: #{dbkey} (caller: #{caller(1..1)})"
       nil
     end
 
     def generate_id
-      @key ||= Familia.generate_id
-      @key
+      @identifier ||= Familia.generate_id
+      @identifier
     end
 
     def uuid