ros-apartment 4.0.0.alpha3 → 4.0.0.alpha5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0b2254c1f3f95622ba9fa45147fcc2f5b2036db4c5c75a2d68c3718772df6149
-  data.tar.gz: efcc9149b0aaaa6c7b614cc981848f02e999259eaa0826120b4df16b555f6caf
+  metadata.gz: c4e597c986618a8043acbecc8081ef0399493c545fd3720d8f57653da90025da
+  data.tar.gz: 9fb0d04fe5abb04e93a4ef654edc14744dfc8d86d35f6d6ef8b685d7eb6ddb29
 SHA512:
-  metadata.gz: 35b3bdeb392ed750be9a20868082f1708e2ae3c4c8449cef5bda163d3e2e911409274abf9a1f8161811678192c8aaaa21c2f4d6a177a5932a9567942172bc234
-  data.tar.gz: 3d0909cc593dcbd014f21626a2565e0e92d373cb74aa768f308b1033f689fbdea1aa48a2f886294e581d4d3954b1d719b15ab3277990a8fde216449eed40485f
+  metadata.gz: 747e6efe4c8c073368684944bbee84cccfd0b063f389d7b4a699debd97662496db9ea220e6be6f119986fa76e3586d180bb3f61ff61c4c44bc3acc37b7784f0c
+  data.tar.gz: 9ceef5927c8169dc2db2041fbbfba99b81c7106a9cf02814812550c1775cd2566398dd8383e78bd0d24e7a82a845d2c4418bc974c43cc5e0169cd25a6072eba5

data/README.md

@@ -30,7 +30,7 @@ Apartment uses **schema-per-tenant** (PostgreSQL) or **database-per-tenant** (My
 
 ## About ros-apartment
 
-This gem is a maintained fork of the original [Apartment gem](https://github.com/influitive/apartment). Maintained by [CampusESP](https://www.campusesp.com) since 2024. Same `require 'apartment'`; v4 introduces a pool-per-tenant architecture that replaces the thread-local switching of v3. Tenant context is fiber-safe via `CurrentAttributes`, and connection pools are managed per tenant rather than swapping search paths on a shared connection. See the [upgrade guide](docs/upgrading-to-v4.md) for migration steps from v3.
+This gem is a maintained fork of the original [Apartment gem](https://github.com/influitive/apartment). Maintained by [CampusESP](https://www.campusesp.com) since 2024. Same `require 'apartment'`; v4 introduces a pool-per-tenant architecture that replaces the thread-local switching of v3. Tenant context is fiber-safe via `CurrentAttributes`, and connection pools are managed per tenant rather than swapping search paths on a shared connection. For *why* v4 chose this model over the alternatives (including fully-qualified table names), see [`docs/designs/v4-connection-model-rationale.md`](docs/designs/v4-connection-model-rationale.md). See the [upgrade guide](docs/upgrading-to-v4.md) for migration steps from v3.
 
 ## Installation
 
@@ -109,6 +109,14 @@ All options are set in `config/initializers/apartment.rb` inside an `Apartment.c
 
 `pool_overflow_policy`: behavior when a new pool would breach `max_total_connections` and every existing pool is pinned or in use (no idle pool to evict). `:evict_idle` (default) — allow the new pool, emit a `cap_unmet` notification (soft cap, prioritizes availability). `:raise` — raise `Apartment::PoolCapacityReached` (hard cap, sheds load). When an idle pool *is* available it is always evicted inline regardless of policy. See `docs/designs/pool-admission-control.md`.
 
+`reap_in_test`: keep the background reaper running under `Rails.env.test?` (default `false` — the Railtie stops it in test, where fixture transactions make mid-example eviction a liability). Set `true` if a deployed process can run under test-env semantics and must keep reaping — that's cleaner than guarding `RAILS_ENV` at boot to avoid silently leaking connections. It applies to *every* `Rails.env.test?` process, including CI, so enable it only when a real deployment needs it.
+
+### Observability
+
+Apartment emits `ActiveSupport::Notifications` for the pool lifecycle and ships
+`Apartment::PoolObserver`, a sink-agnostic subscriber + sampler. See
+[docs/observability.md](docs/observability.md).
+
 ### Elevator (Request Tenant Detection)
 
 ```ruby
@@ -363,6 +371,22 @@ tenant's keyspace. Guard routed work with `Apartment::Tenant.require_tenant!`
 `require_default_tenant!`. See [Tenant-Aware Caching](docs/caching.md) for the
 routed-vs-pinned model and the two-store recipe.
 
+## Iterating across tenants
+
+v4 keys a connection pool per `"tenant:role"`, so *switching* into a tenant creates a pool. Pick the lightest primitive for the work — the question is **does the block touch per-tenant-schema data?**
+
+| Need | Use | v4 cost |
+|---|---|---|
+| Names only (enqueue a job, build a list) | `Apartment.tenant_names.each { ... }` | No switch, no pool created |
+| Per-tenant-schema work (read/write tenant tables) | `Apartment::Tenant.each(release_connection: true) { ... }` | One pool per tenant; released between iterations |
+| Global/pinned data only | Don't switch — read it in the default context | Under shared pinned connections (PG schema, MySQL default), a switch routes pinned/global models *through* the tenant pool |
+
+Rules of thumb:
+
+- **Enqueueing jobs?** Don't switch — pass the tenant as a job argument (`Job.perform_async(tenant: name)`) and let your worker middleware switch when the job runs. Switching only to enqueue spins up a pool for nothing.
+- **Only need global/pinned data?** Don't switch. Under shared pinned connections a `switch` resolves pinned and excluded models through the *current tenant's* pool, so reading global data inside a switch still creates a tenant pool.
+- **Large fan-out doing real per-tenant work?** Pass `release_connection: true` to `Tenant.each` — it releases connections after each tenant so the reaper can evict finished tenants' pools mid-run. It matters for blocks that hold a connection (raw `ActiveRecord::Base.connection`, an open transaction, a long operation); modern query methods (`create!`, `where`, …) check the connection back in themselves (Rails 7.2+), so a fan-out of only those needs no release. **It releases *every* connection leased to the current thread (`clear_active_connections!(:all)`), so don't use it inside an outer transaction or while holding a connection for non-tenant work.**
+
 ## Convenience Methods
 
 `Apartment.tenant_names` returns the current tenant list (delegates to `config.tenants_provider.call`). Preserves the v3 API so existing call sites work without changes.

data/lib/apartment/CLAUDE.md

@@ -95,6 +95,10 @@ All inherit from `AbstractAdapter`. Override `resolve_connection_config`, `creat
 
 **Shim compatibility:** `process_pinned_model` dynamically includes `Apartment::Model` on classes registered via the `excluded_models` shim that lack the concern. This is a runtime `include` on a partially-booted class — acceptable for the legacy shim path but new code should always use `include Apartment::Model` + `pin_tenant` explicitly.
 
+### pool_observer.rb — Observability (opt-in)
+
+Sink-agnostic subscriber for the pool events (`create`/`evict`/`cap_unmet`/`skip_evict`/`reaper_stopped`) + an optional `Concurrent::TimerTask` gauge sampler (`tenant_pools_live`, optional adopter `backend_count`). Normalizes each to a `Sample` and forwards to a caller `sink`; ships no transport. Error-isolated — never raises into instrumentation. See `docs/observability.md`.
+
 ### railtie.rb — v4 Rails Integration
 
 Three hooks in Rails boot order:

data/lib/apartment/config.rb

@@ -26,7 +26,7 @@ module Apartment
                   :active_record_log, :sql_query_tags,
                   :shard_key_prefix,
                   :migration_role, :app_role, :schema_cache_per_tenant, :check_pending_migrations,
-                  :force_separate_pinned_pool, :test_fixture_cleanup
+                  :force_separate_pinned_pool, :test_fixture_cleanup, :reap_in_test
 
     def initialize # rubocop:disable Metrics/AbcSize
       @tenant_strategy = nil
@@ -59,6 +59,7 @@ module Apartment
       @schema_cache_per_tenant = false
       @check_pending_migrations = true
       @force_separate_pinned_pool = false
+      @reap_in_test = false
       @test_fixture_cleanup = true
     end
 
@@ -209,6 +210,11 @@ module Apartment
               "test_fixture_cleanup must be true or false, got: #{@test_fixture_cleanup.inspect}")
       end
 
+      unless [true, false].include?(@reap_in_test)
+        raise(ConfigurationError,
+              "reap_in_test must be true or false, got: #{@reap_in_test.inspect}")
+      end
+
       unless @tenant_validator.nil? || @tenant_validator == false || @tenant_validator.respond_to?(:call)
         raise(ConfigurationError,
               'tenant_validator must be nil, false, or a callable, ' \

data/lib/apartment/pool_observer.rb

@@ -0,0 +1,131 @@
+# frozen_string_literal: true
+
+require 'concurrent'
+
+module Apartment
+  # Sink-agnostic observer for the v4 pool lifecycle. Subscribes to the gem's
+  # ActiveSupport::Notifications and forwards a normalized Sample to a caller-
+  # supplied sink; optionally samples pool gauges on an interval. Ships no
+  # transport — the adopter's sink maps Samples to CloudWatch/StatsD/logs/etc.
+  # All sink/sampler calls are error-isolated: telemetry must never raise into
+  # the gem's instrumentation or timer path. See docs/observability.md.
+  class PoolObserver
+    # name: Symbol (:evict, :tenant_pools_live, ...); kind: :counter | :gauge;
+    # value: Numeric; dimensions: Hash (curated, e.g. { reason: :idle });
+    # payload: the raw notification payload (counters) or {} (gauges).
+    Sample = Data.define(:name, :kind, :value, :dimensions, :payload)
+
+    # Pool-lifecycle events forwarded as counters (value 1 each).
+    COUNTER_EVENTS = %i[create evict cap_unmet skip_evict reaper_stopped].freeze
+
+    # Build, subscribe, and (optionally) start the gauge sampler. Returns the
+    # observer; call #stop! to tear it down. Idempotent subscription is NOT
+    # guaranteed — install once per process (e.g. an after_initialize hook).
+    def self.install!(sink:, sample_interval: nil, backend_count: nil)
+      observer = new(sink: sink, backend_count: backend_count)
+      observer.subscribe!
+      if sample_interval.nil?
+        # nil is the intentional "no gauge sampler" signal; counters still flow.
+      elsif sample_interval.positive?
+        observer.start_sampler!(interval: sample_interval)
+      else
+        # A non-nil, non-positive interval is almost always a misconfig (e.g. an
+        # empty APARTMENT_POOL_SAMPLE_INTERVAL coerced to 0). Silently skipping
+        # the sampler ships an observer whose gauges never emit; surface it.
+        warn "[Apartment::PoolObserver] sample_interval=#{sample_interval.inspect} is not " \
+             'positive; gauge sampler not started (tenant_pools_live/backend_connections ' \
+             'will not emit). Pass a positive interval, or nil to disable the sampler.'
+      end
+      observer
+    rescue StandardError
+      # Don't leak subscriptions if a later step (e.g. a bad sample_interval)
+      # raises after subscribe! has registered listeners.
+      observer&.stop!
+      raise
+    end
+
+    def initialize(sink:, backend_count: nil)
+      raise(ArgumentError, 'sink must be callable') unless sink.respond_to?(:call)
+
+      @sink = sink
+      @backend_count = backend_count
+      @subscribers = []
+      @sampler = nil
+    end
+
+    def subscribe!
+      COUNTER_EVENTS.each do |event|
+        @subscribers << ActiveSupport::Notifications.subscribe("#{event}.apartment") do |*, payload|
+          record_event(event, payload || {})
+        end
+      end
+      self
+    end
+
+    # One gauge pass: live tenant-pool count, plus the adopter's backend count
+    # when supplied. Safe to call from start_sampler! or an external scheduler.
+    def sample!
+      total = Apartment.pool_manager&.stats&.fetch(:total_pools, 0) || 0
+      emit(Sample.new(name: :tenant_pools_live, kind: :gauge, value: total, dimensions: {}, payload: {}))
+
+      return unless @backend_count
+
+      backends = @backend_count.call
+      return if backends.nil?
+
+      emit(Sample.new(name: :backend_connections, kind: :gauge, value: backends, dimensions: {}, payload: {}))
+    rescue StandardError => e
+      warn_failure('sample!', e)
+    end
+
+    def start_sampler!(interval:)
+      @sampler&.shutdown
+      @sampler = Concurrent::TimerTask.new(execution_interval: interval) { sample! }
+      @sampler.execute
+      @sampler
+    end
+
+    # Unsubscribe from all events and shut down the sampler. Safe to call twice.
+    def stop!
+      @subscribers.each { |subscriber| ActiveSupport::Notifications.unsubscribe(subscriber) }
+      @subscribers.clear
+      shutdown_sampler!
+    end
+
+    private
+
+    # shutdown stops future ticks; wait_for_termination ensures an in-flight
+    # sample! can't emit after stop! returns (mirrors PoolReaper#stop_internal).
+    def shutdown_sampler!
+      return unless @sampler
+
+      @sampler.shutdown
+      @sampler.wait_for_termination(5)
+      @sampler = nil
+    end
+
+    def record_event(event, payload)
+      # Copy the notification payload so a sink that mutates Sample#payload
+      # can't corrupt it for other subscribers of the same event.
+      payload = payload.dup
+      dimensions = payload[:reason] ? { reason: payload[:reason] } : {}
+      emit(Sample.new(name: event, kind: :counter, value: 1, dimensions: dimensions, payload: payload))
+    rescue StandardError => e
+      warn_failure("record_event(#{event})", e)
+    end
+
+    def emit(sample)
+      @sink.call(sample)
+    rescue StandardError => e
+      warn_failure("sink(#{sample.name})", e)
+    end
+
+    def warn_failure(context, error)
+      warn "[Apartment::PoolObserver] #{context} failed: #{error.class}: #{error.message}"
+    rescue StandardError
+      # The failure logger must never be the thing that raises into the gem's
+      # instrumentation path (e.g. a closed/replaced $stderr).
+      nil
+    end
+  end
+end

data/lib/apartment/railtie.rb

@@ -171,8 +171,13 @@ module Apartment
     # can call Apartment.pool_reaper.start explicitly. Emits :reaper_stopped
     # so an upgrading adopter notices the behavior change without combing
     # release notes.
+    #
+    # Opt out with `config.reap_in_test = true`: a deployment whose processes
+    # can run under Rails.env.test? semantics (and must keep reaping) then needs
+    # no boot guard around RAILS_ENV to avoid silently leaking connections.
     def self.deactivate_pool_reaper_in_test_env!
       return unless Rails.env.test?
+      return if Apartment.config&.reap_in_test
       return unless Apartment.pool_reaper
 
       Apartment.pool_reaper.stop

data/lib/apartment/tenant.rb

@@ -185,11 +185,45 @@ module Apartment
       # Accepts an optional tenant list; defaults to tenants_provider.
       # Fail-fast: raises immediately if a block raises for any tenant;
       # tenants after the failing one are not visited.
-      def each(tenants = nil)
+      #
+      # release_connection: when true, release leased connections after each
+      # tenant so the reaper can evict finished tenants' pools mid-run. v4 keys a
+      # pool per "tenant:role"; a fan-out whose block leaves a connection checked
+      # out (raw ActiveRecord::Base.connection use, an open transaction, a long-
+      # held connection) would otherwise hold one warm connection per visited
+      # tenant. Modern query methods (create!, where, ...) check the connection
+      # back in themselves (Rails 7.2+), so a fan-out of only those needs no
+      # release — but when in doubt for a large fan-out, pass it; it is a cheap
+      # no-op when there is nothing to release.
+      #
+      # WARNING: the release is handler-wide (clear_active_connections!(:all)) —
+      # it drops EVERY connection leased to the current execution context, across
+      # all pools and roles, not just the tenant pool. Do NOT use it inside an
+      # outer ActiveRecord::Base.transaction, or while holding a non-tenant
+      # connection you mean to keep. Fail-fast: a raising block still aborts the
+      # fan-out, but the failing tenant's connection is released first — the
+      # release is best-effort cleanup (in an ensure), not iteration semantics.
+      def each(tenants = nil, release_connection: false)
         raise(ArgumentError, 'Apartment::Tenant.each requires a block') unless block_given?
 
         tenants ||= Apartment.tenant_names
-        tenants.each { |tenant| switch(tenant) { yield(tenant) } }
+        tenants.each do |tenant|
+          switch(tenant) { yield(tenant) }
+        ensure
+          # Handler-wide (:all) covers writing + reading roles — the gem's
+          # established release call (see memory_stability_spec). In an ensure so
+          # a raising tenant is still released; the exception then propagates and
+          # halts the fan-out (fail-fast preserved). Best-effort: a release
+          # failure must never mask the block's exception, so it is rescued and
+          # warned rather than raised out of the ensure.
+          if release_connection
+            begin
+              ActiveRecord::Base.connection_handler.clear_active_connections!(:all)
+            rescue StandardError => e
+              warn("[Apartment::Tenant.each] connection release failed: #{e.class}: #{e.message}")
+            end
+          end
+        end
       end
 
       # Block-scoped override of the tenant resolver. For the duration of the

data/lib/apartment/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Apartment
-  VERSION = '4.0.0.alpha3'
+  VERSION = '4.0.0.alpha5'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ros-apartment
 version: !ruby/object:Gem::Version
-  version: 4.0.0.alpha3
+  version: 4.0.0.alpha5
 platform: ruby
 authors:
 - Ryan Brunner
@@ -195,6 +195,7 @@ files:
 - lib/apartment/patches/connection_handling.rb
 - lib/apartment/patches/live_tenant_propagation.rb
 - lib/apartment/pool_manager.rb
+- lib/apartment/pool_observer.rb
 - lib/apartment/pool_reaper.rb
 - lib/apartment/railtie.rb
 - lib/apartment/schema_cache.rb