familia 2.0.0.pre15 → 2.0.0.pre17

data/.rubocop_todo.yml

@@ -1,208 +0,0 @@
-# This configuration was generated by
-# `rubocop --auto-gen-config`
-# on 2025-07-20 01:49:27 UTC using RuboCop version 1.78.0.
-# The point is for the user to remove these configuration records
-# one by one as the offenses are removed from the code base.
-# Note that changes in the inspected code, or installation of new
-# versions of RuboCop, may require this file to be generated again.
-
-# Offense count: 2
-# This cop supports safe autocorrection (--autocorrect).
-# Configuration parameters: AutoCorrect, AllowBorderComment, AllowMarginComment.
-Layout/EmptyComment:
-  Exclude:
-    - "lib/familia/base.rb"
-    - "lib/familia/connection.rb"
-
-# Offense count: 1
-# This cop supports safe autocorrection (--autocorrect).
-Layout/EmptyLines:
-  Exclude:
-    - "Gemfile"
-
-# Offense count: 2
-# This cop supports safe autocorrection (--autocorrect).
-# Configuration parameters: EnforcedStyle.
-# SupportedStyles: empty_lines, empty_lines_except_namespace, empty_lines_special, no_empty_lines, beginning_only, ending_only
-Layout/EmptyLinesAroundClassBody:
-  Exclude:
-    - "lib/familia/data_type/types/list.rb"
-    - "lib/familia/data_type/types/unsorted_set.rb"
-
-# Offense count: 1
-# This cop supports safe autocorrection (--autocorrect).
-Layout/SpaceAfterComma:
-  Exclude:
-    - "lib/familia/data_type/types/hashkey.rb"
-
-# Offense count: 4
-# This cop supports safe autocorrection (--autocorrect).
-# Configuration parameters: AutoCorrect, AllowUnusedKeywordArguments, IgnoreEmptyMethods, IgnoreNotImplementedMethods, NotImplementedExceptions.
-# NotImplementedExceptions: NotImplementedError
-Lint/UnusedMethodArgument:
-  Exclude:
-    - "lib/familia/base.rb"
-    - "lib/middleware/database_middleware.rb"
-
-# Offense count: 1
-# Configuration parameters: CountComments, CountAsOne, AllowedMethods, AllowedPatterns.
-# AllowedMethods: refine
-Metrics/BlockLength:
-  Max: 28
-
-# Offense count: 2
-# Configuration parameters: AllowedMethods, AllowedPatterns.
-Metrics/PerceivedComplexity:
-  Max: 9
-
-# Offense count: 50
-# This cop supports safe autocorrection (--autocorrect).
-# Configuration parameters: EnforcedStyle, BlockForwardingName.
-# SupportedStyles: anonymous, explicit
-Naming/BlockForwarding:
-  Exclude:
-    - "lib/familia/data_type/types/list.rb"
-    - "lib/familia/data_type/types/sorted_set.rb"
-    - "lib/familia/data_type/types/unsorted_set.rb"
-    - "lib/familia/refinements/logger_trace.rb"
-
-# Offense count: 8
-# Configuration parameters: MinNameLength, AllowNamesEndingInNumbers, AllowedNames, ForbiddenNames.
-# AllowedNames: as, at, by, cc, db, id, if, in, io, ip, of, on, os, pp, to
-Naming/MethodParameterName:
-  Exclude:
-    - "lib/familia/horreum/class_methods.rb"
-    - "lib/familia/data_type/types/sorted_set.rb"
-    - "lib/familia/data_type/types/unsorted_set.rb"
-
-# Offense count: 1
-# Configuration parameters: Mode, AllowedMethods, AllowedPatterns, AllowBangMethods, WaywardPredicates.
-# AllowedMethods: call
-# WaywardPredicates: nonzero?
-Naming/PredicateMethod:
-  Exclude:
-    - "lib/familia/horreum/class_methods.rb"
-
-# Offense count: 1
-# Configuration parameters: NamePrefix, ForbiddenPrefixes, AllowedMethods, MethodDefinitionMacros, UseSorbetSigs.
-# NamePrefix: is_, has_, have_, does_
-# ForbiddenPrefixes: is_, has_, have_, does_
-# AllowedMethods: is_a?
-# MethodDefinitionMacros: define_method, define_singleton_method
-Naming/PredicatePrefix:
-  Exclude:
-    - "spec/**/*"
-    - "lib/familia/horreum/class_methods.rb"
-
-# Offense count: 54
-# This cop supports safe autocorrection (--autocorrect).
-# Configuration parameters: AllowOnlyRestArgument, UseAnonymousForwarding, RedundantRestArgumentNames, RedundantKeywordRestArgumentNames, RedundantBlockArgumentNames.
-# RedundantRestArgumentNames: args, arguments
-# RedundantKeywordRestArgumentNames: kwargs, options, opts
-# RedundantBlockArgumentNames: blk, block, proc
-Style/ArgumentsForwarding:
-  Exclude:
-    - "lib/familia/horreum/class_methods.rb"
-    - "lib/familia/data_type/types/list.rb"
-    - "lib/familia/data_type/types/sorted_set.rb"
-    - "lib/familia/data_type/types/unsorted_set.rb"
-    - "lib/familia/refinements/logger_trace.rb"
-
-# Offense count: 11
-# Configuration parameters: AllowedConstants.
-Style/Documentation:
-  Exclude:
-    - "spec/**/*"
-    - "test/**/*"
-    - "lib/familia/errors.rb"
-    - "lib/familia/horreum/class_methods.rb"
-    - "lib/familia/horreum/related_fields_management.rb"
-    - "lib/familia/data_type/types/hashkey.rb"
-    - "lib/familia/data_type/types/list.rb"
-    - "lib/familia/data_type/types/sorted_set.rb"
-    - "lib/familia/data_type/types/string.rb"
-    - "lib/familia/data_type/types/unsorted_set.rb"
-    - "lib/familia/version.rb"
-
-# Offense count: 1
-# This cop supports safe autocorrection (--autocorrect).
-# Configuration parameters: AutoCorrect, EnforcedStyle, AllowComments.
-# SupportedStyles: empty, nil, both
-
-# Offense count: 2
-# This cop supports safe autocorrection (--autocorrect).
-# Configuration parameters: MaxUnannotatedPlaceholdersAllowed, Mode, AllowedMethods, AllowedPatterns.
-# SupportedStyles: annotated, template, unannotated
-Style/FormatStringToken:
-  EnforcedStyle: unannotated
-
-# Offense count: 1
-# This cop supports unsafe autocorrection (--autocorrect-all).
-# Configuration parameters: EnforcedStyle.
-# SupportedStyles: always, always_true, never
-Style/FrozenStringLiteralComment:
-  Exclude:
-    - "**/*.arb"
-    - "lib/familia/horreum/related_fields_management.rb"
-
-# Offense count: 1
-# This cop supports unsafe autocorrection (--autocorrect-all).
-Style/HashTransformValues:
-  Exclude:
-    - "lib/familia/data_type/types/hashkey.rb"
-
-# Offense count: 1
-# This cop supports unsafe autocorrection (--autocorrect-all).
-# Configuration parameters: EnforcedStyle, Autocorrect.
-# SupportedStyles: module_function, extend_self, forbidden
-
-# Offense count: 1
-# This cop supports unsafe autocorrection (--autocorrect-all).
-# Configuration parameters: EnforcedStyle, AllowedMethods, AllowedPatterns.
-# SupportedStyles: predicate, comparison
-Style/NumericPredicate:
-  Exclude:
-    - "spec/**/*"
-    - "lib/familia/horreum/class_methods.rb"
-
-# Offense count: 1
-# This cop supports unsafe autocorrection (--autocorrect-all).
-
-# Offense count: 1
-# This cop supports safe autocorrection (--autocorrect).
-# Configuration parameters: EnforcedStyle.
-# SupportedStyles: implicit, explicit
-Style/RescueStandardError:
-  Exclude:
-    - "lib/familia/horreum.rb"
-
-# Offense count: 1
-# This cop supports unsafe autocorrection (--autocorrect-all).
-# Configuration parameters: ConvertCodeThatCanStartToReturnNil, AllowedMethods, MaxChainLength.
-# AllowedMethods: present?, blank?, presence, try, try!
-Style/SafeNavigation:
-  Exclude:
-    - "lib/familia/connection.rb"
-
-# Offense count: 4
-# Configuration parameters: ActiveSupportClassAttributeAllowed.
-ThreadSafety/ClassAndModuleAttributes:
-  Exclude:
-    - "lib/familia/base.rb"
-    - "lib/familia/horreum.rb"
-    - "lib/middleware/database_middleware.rb"
-
-# Offense count: 29
-ThreadSafety/ClassInstanceVariable:
-  Exclude:
-    - "lib/familia/base.rb"
-    - "lib/familia/horreum/class_methods.rb"
-    - "lib/familia/version.rb"
-
-# Offense count: 2
-# This cop supports unsafe autocorrection (--autocorrect-all).
-# Configuration parameters: EnforcedStyle.
-# SupportedStyles: literals, strict
-ThreadSafety/MutableClassInstanceVariable:
-  Exclude:
-    - "lib/familia/connection.rb"

data/docs/connection_pooling.md

@@ -1,192 +0,0 @@
-# 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