familia 1.2.0 → 2.0.0.pre.pre

data/try/prototypes/lib/atomic_saves_v3_connection_pool_helpers.rb

@@ -0,0 +1,192 @@
+# try/prototypes/lib/atomic_saves_v3_connection_pool_helpers.rb
+
+##
+# Atomic Save V3 Proof of Concept - Connection Pool Integration
+#
+# This implementation explores atomic saves with Database connection pooling
+# for thread safety in multi-threaded environments (like Puma).
+#
+# Key Goals:
+# 1. **Connection Pool Integration**: Use ConnectionPool gem for thread safety
+# 2. **Dual Approach Testing**: Compare proxy vs explicit connection passing
+# 3. **Thread Safety Validation**: Prove pool handles concurrent operations
+# 4. **Separate Transaction Boundaries**: Each atomic block gets own transaction
+#
+# Approaches Tested:
+# - Proxy Approach: Familia.atomic { ... } (transparent, V2 style)
+# - Explicit Approach: Familia.atomic { |conn| ... } (clear boundaries)
+
+require 'connection_pool'
+require 'json'
+
+# Test models
+class BankAccount < Familia::Horreum
+  identifier_field :account_number
+  field :account_number
+  field :balance
+  field :holder_name
+  field :metadata  # Variable-sized JSON field for workload simulation
+
+  def init
+    @account_number ||= SecureRandom.hex(8)
+    @balance = @balance.to_f if @balance
+    @metadata = @metadata.is_a?(String) ? JSON.parse(@metadata) : @metadata rescue @metadata
+  end
+
+  def balance
+    @balance&.to_f
+  end
+
+  def withdraw(amount)
+    raise "Insufficient funds" if balance < amount
+    self.balance -= amount
+  end
+
+  def deposit(amount)
+    self.balance += amount
+  end
+
+  def metadata=(value)
+    @metadata = value.is_a?(Hash) || value.is_a?(Array) ? JSON.generate(value) : value
+  end
+
+  # Add method that accepts explicit connection
+  def save(using: nil)
+    if using
+      # Use provided connection explicitly
+      original_instance = @dbclient
+      @dbclient = using
+      begin
+        super()
+      ensure
+        @dbclient = original_instance
+      end
+    else
+      # Use normal save behavior
+      super()
+    end
+  end
+end
+
+class TransactionRecord < Familia::Horreum
+  identifier_field :transaction_id
+  field :transaction_id
+  field :from_account
+  field :to_account
+  field :amount
+  field :status
+  field :created_at
+
+  def initialize(from: nil, to: nil, amount: 0)
+    @transaction_id = SecureRandom.hex(8)
+    @from_account = from
+    @to_account = to
+    @amount = amount.to_f
+    @status = "pending"
+    @created_at = Time.now.to_i
+  end
+
+  def amount
+    @amount&.to_f
+  end
+
+  def created_at
+    @created_at&.to_i
+  end
+
+  def save(using: nil)
+    if using
+      original_instance = @dbclient
+      @dbclient = using
+      begin
+        super()
+      ensure
+        @dbclient = original_instance
+      end
+    else
+      super()
+    end
+  end
+end
+
+module Familia
+  # Connection pool for Database connections
+  @@connection_pool = ConnectionPool.new(size: 10, timeout: 5) do
+    Redis.new(url: Familia.uri.to_s)
+  end
+
+  class << self
+    def connection_pool
+      @@connection_pool
+    end
+
+    def current_transaction
+      Thread.current[:familia_current_transaction_v3]
+    end
+
+    def current_transaction=(transaction)
+      Thread.current[:familia_current_transaction_v3] = transaction
+    end
+
+    # Proxy approach - transparent like V2
+    def atomic(&block)
+      if current_transaction
+        # Nested atomic - create separate transaction
+        atomic_separate(&block)
+      else
+        # Use connection pool to get connection
+        # For this prototype, we'll use a simple approach that works with Redis
+        connection_pool.with do |conn|
+          begin
+            # Store the connection for use within the block
+            self.current_transaction = conn
+            result = yield
+            result
+          ensure
+            self.current_transaction = nil
+          end
+        end
+      end
+    end
+
+    # Explicit approach - connection passed to block
+    def atomic_explicit(&block)
+      connection_pool.with do |conn|
+        # For this prototype, pass the connection directly
+        yield(conn)
+      end
+    end
+
+    # Helper for separate nested transactions
+    def atomic_separate(&block)
+      connection_pool.with do |conn|
+        begin
+          old_transaction = current_transaction
+          # Use a separate connection for nested transactions
+          self.current_transaction = conn
+          result = yield
+          result
+        ensure
+          self.current_transaction = old_transaction
+        end
+      end
+    end
+  end
+
+  # Override dbclient method for proxy approach
+  module ConnectionPoolRedis
+    def dbclient
+      Familia.current_transaction || super
+    end
+  end
+
+  # Inject into Horreum for proxy approach
+  class Horreum
+    prepend ConnectionPoolRedis
+  end
+
+  # Inject into DataType for proxy approach
+  class DataType
+    prepend ConnectionPoolRedis
+  end
+end

metadata

@@ -1,15 +1,70 @@
 --- !ruby/object:Gem::Specification
 name: familia
 version: !ruby/object:Gem::Version
-  version: 1.2.0
+  version: 2.0.0.pre.pre
 platform: ruby
 authors:
 - Delano Mandelbaum
-autorequire:
 bindir: exe
 cert_chain: []
-date: 2025-05-29 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
+- !ruby/object:Gem::Dependency
+  name: benchmark
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: connection_pool
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: csv
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: logger
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: redis
   requirement: !ruby/object:Gem::Requirement
@@ -58,28 +113,40 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '1.3'
-description: 'Familia: An ORM for Redis in Ruby.. Organize and store ruby objects
-  in Redis'
+description: 'Familia: An ORM for Valkey-compatible databases in Ruby.. Organize and
+  store ruby objects in Valkey/Redis'
 email: gems@solutious.com
 executables: []
 extensions: []
 extra_rdoc_files: []
 files:
-- ".github/workflows/ruby.yml"
+- ".github/workflows/ci.yml"
+- ".github/workflows/docs.yml"
 - ".gitignore"
 - ".pre-commit-config.yaml"
 - ".rubocop.yml"
 - ".rubocop_todo.yml"
+- ".yardopts"
+- CLAUDE.md
 - Gemfile
 - Gemfile.lock
 - LICENSE.txt
 - README.md
-- VERSION.yml
+- bin/irb
+- docs/connection_pooling.md
 - familia.gemspec
 - lib/familia.rb
 - lib/familia/base.rb
 - lib/familia/connection.rb
 - lib/familia/core_ext.rb
+- lib/familia/datatype.rb
+- lib/familia/datatype/commands.rb
+- lib/familia/datatype/serialization.rb
+- lib/familia/datatype/types/hashkey.rb
+- lib/familia/datatype/types/list.rb
+- lib/familia/datatype/types/sorted_set.rb
+- lib/familia/datatype/types/string.rb
+- lib/familia/datatype/types/unsorted_set.rb
 - lib/familia/errors.rb
 - lib/familia/features.rb
 - lib/familia/features/expiration.rb
@@ -88,51 +155,82 @@ files:
 - lib/familia/horreum.rb
 - lib/familia/horreum/class_methods.rb
 - lib/familia/horreum/commands.rb
-- lib/familia/horreum/relations_management.rb
+- lib/familia/horreum/connection.rb
+- lib/familia/horreum/related_fields_management.rb
 - lib/familia/horreum/serialization.rb
 - lib/familia/horreum/settings.rb
 - lib/familia/horreum/utils.rb
 - lib/familia/logging.rb
-- lib/familia/redistype.rb
-- lib/familia/redistype/commands.rb
-- lib/familia/redistype/serialization.rb
-- lib/familia/redistype/types/hashkey.rb
-- lib/familia/redistype/types/list.rb
-- lib/familia/redistype/types/sorted_set.rb
-- lib/familia/redistype/types/string.rb
-- lib/familia/redistype/types/unsorted_set.rb
+- lib/familia/multi_result.rb
 - lib/familia/refinements.rb
 - lib/familia/settings.rb
-- lib/familia/tools.rb
 - lib/familia/utils.rb
 - lib/familia/version.rb
-- lib/redis_middleware.rb
-- try/00_familia_try.rb
-- try/10_familia_try.rb
-- try/20_redis_type_try.rb
-- try/21_redis_type_zset_try.rb
-- try/22_redis_type_set_try.rb
-- try/23_redis_type_list_try.rb
-- try/24_redis_type_string_try.rb
-- try/25_redis_type_hash_try.rb
-- try/26_redis_bool_try.rb
-- try/27_redis_horreum_try.rb
-- try/28_redis_horreum_serialization_try.rb
-- try/29_redis_horreum_initialization_try.rb
-- try/30_familia_object_try.rb
-- try/35_feature_safedump_try.rb
-- try/40_customer_try.rb
-- try/41_customer_safedump_try.rb
-- try/91_json_bug_try.rb
-- try/92_symbolize_try.rb
-- try/93_string_coercion_try.rb
-- try/test_helpers.rb
+- lib/middleware/database_middleware.rb
+- try/configuration/scenarios_try.rb
+- try/core/connection_try.rb
+- try/core/errors_try.rb
+- try/core/extensions_try.rb
+- try/core/familia_extended_try.rb
+- try/core/familia_try.rb
+- try/core/middleware_try.rb
+- try/core/refinements_try.rb
+- try/core/settings_try.rb
+- try/core/tools_try.rb
+- try/core/utils_try.rb
+- try/datatypes/boolean_try.rb
+- try/datatypes/datatype_base_try.rb
+- try/datatypes/hash_try.rb
+- try/datatypes/list_try.rb
+- try/datatypes/set_try.rb
+- try/datatypes/sorted_set_try.rb
+- try/datatypes/string_try.rb
+- try/edge_cases/empty_identifiers_try.rb
+- try/edge_cases/hash_symbolization_try.rb
+- try/edge_cases/json_serialization_try.rb
+- try/edge_cases/race_conditions_try.rb
+- try/edge_cases/reserved_keywords_try.rb
+- try/edge_cases/string_coercion_try.rb
+- try/edge_cases/ttl_side_effects_try.rb
+- try/features/expiration_try.rb
+- try/features/quantization_try.rb
+- try/features/safe_dump_advanced_try.rb
+- try/features/safe_dump_try.rb
+- try/helpers/test_helpers.rb
+- try/horreum/base_try.rb
+- try/horreum/class_methods_try.rb
+- try/horreum/commands_try.rb
+- try/horreum/initialization_try.rb
+- try/horreum/relations_try.rb
+- try/horreum/serialization_try.rb
+- try/horreum/settings_try.rb
+- try/integration/cross_component_try.rb
+- try/models/customer_safe_dump_try.rb
+- try/models/customer_try.rb
+- try/models/datatype_base_try.rb
+- try/models/familia_object_try.rb
+- try/performance/benchmarks_try.rb
+- try/pooling/README.md
+- try/pooling/configurable_stress_test_try.rb
+- try/pooling/connection_pool_test_try.rb
+- try/pooling/lib/atomic_saves_v3_connection_pool_helpers.rb
+- try/pooling/lib/connection_pool_metrics.rb
+- try/pooling/lib/connection_pool_stress_test.rb
+- try/pooling/lib/connection_pool_threading_models.rb
+- try/pooling/lib/visualize_stress_results.rb
+- try/pooling/pool_siege_try.rb
+- try/pooling/run_stress_tests_try.rb
+- try/prototypes/atomic_saves_v1_context_proxy.rb
+- try/prototypes/atomic_saves_v2_connection_switching.rb
+- try/prototypes/atomic_saves_v3_connection_pool.rb
+- try/prototypes/atomic_saves_v4.rb
+- try/prototypes/lib/atomic_saves_v2_connection_switching_helpers.rb
+- try/prototypes/lib/atomic_saves_v3_connection_pool_helpers.rb
 homepage: https://github.com/delano/familia
 licenses:
 - MIT
 metadata:
   rubygems_mfa_required: 'true'
-post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -140,15 +238,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 2.7.8
+      version: '3.4'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.16
-signing_key:
+rubygems_version: 3.6.9
 specification_version: 4
-summary: An ORM for Redis in Ruby.
+summary: An ORM for Valkey-compatible databases in Ruby.
 test_files: []

data/.github/workflows/ruby.yml

@@ -1,71 +0,0 @@
-name: Ruby
-
-on:
-  push:
-    branches:
-      - main
-
-  pull_request:
-
-  workflow_dispatch:
-
-jobs:
-  build:
-    runs-on: ubuntu-latest
-    name: Ruby ${{ matrix.ruby }}
-    strategy:
-      matrix:
-        include:
-          - ruby: '3.3'
-            bundler: latest
-            rubygems: latest
-
-          - ruby: '3.2'
-            bundler: latest
-            rubygems: latest
-
-          - ruby: '3.1'
-            bundler: latest
-            rubygems: latest
-
-          - ruby: '3.0'
-            bundler: latest
-            rubygems: latest
-
-          - ruby: '2.7'
-            bundler: '2.4.22'
-            rubygems: '3.2.3'
-
-    services:
-      redis:
-        image: redis:bookworm@sha256:e422889e156ebea83856b6ff973bfe0c86bce867d80def228044eeecf925592b
-        # Set health checks to wait until redis has started
-        options: >-
-          --health-cmd "redis-cli ping"
-          --health-interval 10s
-          --health-timeout 3s
-          --health-retries 5
-        ports:
-          # https://docs.github.com/en/actions/using-containerized-services/creating-redis-service-containers#running-jobs-in-containers
-          # Maps port 6379 on service container to the host
-          - 6379:6379
-
-    steps:
-    - uses: actions/checkout@v4
-    - name: Set up Ruby
-      uses: ruby/setup-ruby@v1
-      with:
-        ruby-version: ${{ matrix.ruby }}
-        rubygems: ${{ matrix.rubygems }}
-        bundler: ${{ matrix.bundler }}
-        # When the following is true, also run "bundle install",
-        # and cache the result automatically. Ran into an issue
-        # with the caching and multiple ruby versions. Needs
-        # further investigation.
-        bundler-cache: false
-
-    - name: Re-run bundle install
-      run: bundle install
-
-    - name: Run the tryouts
-      run: bundle exec try -v try/*_try.rb

data/VERSION.yml

@@ -1,4 +0,0 @@
----
-:MAJOR: 1
-:MINOR: 2
-:PATCH: 0

data/lib/familia/redistype/commands.rb

@@ -1,59 +0,0 @@
-# rubocop:disable all
-
-class Familia::RedisType
-
-  # Must be included in all RedisType classes to provide Redis
-  # commands. The class must have a rediskey method.
-  module Commands
-
-    def move(db)
-      redis.move rediskey, db
-    end
-
-    def rename(newkey)
-      redis.rename rediskey, newkey
-    end
-
-    def renamenx(newkey)
-      redis.renamenx rediskey, newkey
-    end
-
-    def type
-      redis.type rediskey
-    end
-
-    # Deletes the entire Redis key
-    # @return [Boolean] true if the key was deleted, false otherwise
-    def delete!
-      Familia.trace :DELETE!, redis, redisuri, caller(1..1) if Familia.debug?
-      ret = redis.del rediskey
-      ret.positive?
-    end
-    alias clear delete!
-
-    def exists?
-      redis.exists(rediskey) && !size.zero?
-    end
-
-    def realttl
-      redis.ttl rediskey
-    end
-
-    def expire(sec)
-      redis.expire rediskey, sec.to_i
-    end
-
-    def expireat(unixtime)
-      redis.expireat rediskey, unixtime
-    end
-
-    def persist
-      redis.persist rediskey
-    end
-
-    def echo(meth, trace)
-      redis.echo "[#{self.class}\##{meth}] #{trace} (#{@opts[:class]}\#)"
-    end
-
-  end
-end