ros-apartment 4.0.0.alpha14 → 4.0.0.alpha15

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2bce6584d418fcb45322b27efd6b816c8e33b603866310d9ffabf96e1078a776
-  data.tar.gz: 77d334fc612ff87fa615b2079f2263b8505c84652e966b08b94386061621fcaa
+  metadata.gz: 894a4e62959833cd9dba2797321b9199ed8269eab4d51fe6744c95d0aef68076
+  data.tar.gz: 1e2dedc54edd54b7058ac7c86c96df47b90d2d4fb3dd62c9aab0293dbb22590a
 SHA512:
-  metadata.gz: 3f73a95f17f83e8034f2a1db98938018d5d1b5e83ec7508720305269b61cdb847c356616d0aa39ea7ad65e42716838c8f243753a14eaf47539ca20fc043ec4c5
-  data.tar.gz: c7626e6a4dfad74516f56be92ee2703e9a19e0cc1b11c525d0803dcb36f918f7bce72d9c68b62c226a712d138dd18ee6e0746ac2333b6b8a05a57a6984e3ab60
+  metadata.gz: f31685d04741cef165f6bcffcf67db498c520be551ba31c03a8967d74b4c2992163dddd09047240771347cdb6f1ef0beec6311f1779f14f114f365e96600980d
+  data.tar.gz: 841a51484b694620fa04433f0ce8b2fb63afcb9f003b7750c9b9c138703d9193501adc2fe15be3d67f15b72a7bf52e383d00767719ff7014afdd47344db8e44e

data/README.md

@@ -438,18 +438,20 @@ 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?**
+v4 keys a connection pool per `"tenant:role"`, and the pool is created when a query resolves a connection — **not** when `Tenant.switch` sets the tenant. So a switch whose block never touches the tenant database costs nothing, and the question for picking a primitive is **does the block query 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 |
+| Per-tenant-schema work, every tenant | `Apartment::Tenant.each(release_connection: true) { ... }` | One pool per tenant; released between iterations |
+| Per-tenant-schema work, a **subset** | `Apartment::Tenant.each(names, release_connection: true) { ... }` | Same, over the list you pass — no need to hand-roll the `ensure` |
 | 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.
+- **Enqueueing jobs?** Pass the tenant as a job argument (`Job.perform_async(tenant: name)`) and let your worker middleware switch when the job runs — the worker needs the name anyway, and the enqueue side stays independent of tenant routing. A switch that only enqueues is *not* itself expensive: the block touches the queue, never the tenant database, so no pool is created.
 - **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.
+- **Iterating some tenants, not all?** `Tenant.each` takes the list as its first argument — `Tenant.each(Account.active.pluck(:tenant_name)) { ... }`. Reach for this instead of writing `names.each { |n| Tenant.switch(n) { ... } }`: it is the gem-native shape, and it puts `release_connection:` within reach for when the next bullet says you need it. Add that flag deliberately rather than by default — it is not a free no-op inside an outer transaction. A hand-rolled loop over such a block leaves one leased connection per visited tenant, which keeps every pool it touches un-evictable and can drive the pool count far past `max_tenant_pools` (see [Pool admission control](docs/designs/pool-admission-control.md)). A block using only modern query methods creates a pool per tenant but no lasting lease, so those pools stay idle and the reaper can trim them. The subset form and `release_connection:` are **v4 API** — v3's `Tenant.each` forwards to the adapter and accepts neither. `Tenant.with_tenants(*names) { ... }` scopes the provider instead, if you want nested calls to see the same subset.
 - **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

data/lib/apartment/CLAUDE.md

@@ -92,6 +92,8 @@ Three details are load-bearing. The map is a `SharedTypeMap < HashLookupTypeMap`
 
 Background `Concurrent::TimerTask` that evicts idle and excess tenant pools, and also serves as the pool manager's synchronous admission controller (`admit!`) when a cap is configured — evicting the LRU idle pool inline before a new one is established, applying `pool_overflow_policy` (`:evict_idle` / `:raise`) when no idle pool can be freed. A single `evict_tenant` primitive backs the timer (idle/LRU) and admission paths. Reap cadence (`interval`/`reaper_interval`) is decoupled from the idle window (`idle_timeout`/`pool_idle_timeout`). Created by `Apartment.configure`, stored as `Apartment.pool_reaper`. Deregisters evicted pools from AR's ConnectionHandler. Default tenant is never evicted.
 
+**Admission is the quadratic path, so it does not instrument per candidate.** The scan walks every pool on every cold create; the timer paths walk every pool once per reap cycle. So `protected_pool?` (per-candidate `:skip_evict`, timer only) and `protection_reason` (bare predicate, admission) are split, and admission reports one `skipped: { pinned:, in_use:, default: }` tally on `:cap_unmet` instead — three buckets, because the default tenant's own pools are refused before the protection check and would otherwise vanish from the accounting; `pinned + in_use + default` equals `current` for an *uninterrupted* scan — a candidate whose protection check raises is rescued without being tallied, and the reaper does not take `@create_mutex`, so it can evict between the scan and the count. It also reads `PoolManager#total_pools` rather than `#stats`, which materializes the full key array to answer a count. A measured breach reaching 477 pools emitted ~218k `:skip_evict` events before this. Note that `in_use` means *leased*, not *executing* — a fan-out that never releases reads as saturation while nothing is running; `docs/observability.md` documents the tell.
+
 ### adapters/abstract_adapter.rb — Base Adapter
 
 Lifecycle ops (`create`, `drop`, `migrate`, `seed`), `ActiveSupport::Callbacks` on `:create`/`:switch`, `resolve_connection_config` (abstract — subclasses override), `process_excluded_models`, `environmentify`, `base_config` (stringified `connection_config`), `rails_env` (guarded `Rails.env` access). `process_pinned_model` / `qualify_pinned_table_name` call **`Apartment::Model` class methods** (`apartment_explicit_table_name?`, `apartment_mark_processed!`, etc.); no `instance_variable_*` on arbitrary model classes. Constructor takes `connection_config` (raw AR hash, not `Apartment::Config`).

data/lib/apartment/patches/postgresql_type_map.rb

@@ -45,13 +45,26 @@ module Apartment
     #
     # RETENTION, measured rather than bounded. An entry is removed only when a
     # later publish supersedes it (see #apartment_supersede_stale_identities),
-    # so a process retains one map per database it has connected to, times the
-    # timezone variants live against it. One built map
-    # holds ~138 registrations and 88.5 KB of RSS (measured against PostgreSQL
-    # 18 on Rails 8.1). Schema-per-tenant -- the common case, and the one this
-    # patch was written for -- has exactly ONE key for the whole process. Only
-    # database-per-tenant grows, and it grows with the tenants a process
-    # actually serves rather than with time: 570 tenant databases is ~49 MB. No
+    # so a process retains one map per KEY it has built against, and the key is
+    # [[host, port, database], identity, timezone] -- not the database alone. A
+    # :reading role on a replica is a different endpoint and carries its own
+    # map for the same catalog, so multiply by distinct endpoints, usually the
+    # number of roles. (Timezone splits nothing in practice: tenant configs
+    # derive from one base config.) One built map holds ~138 registrations and
+    # 88.5 KB of RSS (measured against PostgreSQL 18 on Rails 8.1) against a
+    # catalog carrying only built-in enums, domains and ranges -- a BASELINE,
+    # not a constant. The second load query has no namespace filter, so a map
+    # holds the built-ins plus every such type in the catalog it was built
+    # against, and pg_type is per-DATABASE, so the strategy decides only how
+    # tenant-defined types distribute. Schema-per-tenant -- the common case,
+    # and the one this patch was written for -- has one key per endpoint
+    # however many tenants there are, and that single map carries every
+    # tenant's types (138 + tenants x types-per-schema). Database-per-tenant
+    # splits the same types across maps: each carries 138 + its own tenant's,
+    # so COUNT grows with tenants, cumulatively -- supersede fires only for one
+    # endpoint under a different identity, so a dropped database leaves its
+    # entry for the life of the process. 570 tenant databases is ~49 MB of
+    # baseline per endpoint, plus whatever those tenants define. See docs/designs/postgresql-type-map-sharing.md. No
     # eviction policy ships because a cap tight enough to bound that
     # meaningfully is also tight enough to thrash the nightly sweep it exists to
     # speed up, which is the deployment that has the problem in the first place.

data/lib/apartment/pool_manager.rb

@@ -124,11 +124,19 @@ module Apartment
         .map(&:first)
     end
 
+    # O(1) pool count. Separate from #stats because the admission path asks for
+    # the count on every cold create, and #stats answers by materializing the
+    # full key array — garbage proportional to the pool count, at exactly the
+    # moment the pool count is the problem.
+    def total_pools
+      @pools.size
+    end
+
     # Basic stats. Full observability (per-tenant breakdown, connection
     # counts, eviction counters) deferred to Phase 3.
     def stats
       {
-        total_pools: @pools.size,
+        total_pools: total_pools,
         tenants: @pools.keys,
       }
     end

data/lib/apartment/pool_reaper.rb

@@ -61,13 +61,18 @@ module Apartment
     def admit!(incoming_tenant_key)
       return unless @max_total
 
+      # Reset per scan: the tally that matters is the one from the pass that
+      # gave up, not a sum over passes that each evicted something.
+      skipped = nil
       loop do
-        break if @pool_manager.stats[:total_pools] < @max_total
-        break unless evict_one_for_admission(incoming_tenant_key)
+        break if @pool_manager.total_pools < @max_total
+
+        skipped = { pinned: 0, in_use: 0, default: 0 }
+        break unless evict_one_for_admission(incoming_tenant_key, skipped)
       end
-      return if @pool_manager.stats[:total_pools] < @max_total
+      return if @pool_manager.total_pools < @max_total
 
-      apply_overflow_policy
+      apply_overflow_policy(skipped)
     end
 
     def start
@@ -156,11 +161,32 @@ module Apartment
     # Evict the single LRU evictable pool to make room for an incoming one,
     # skipping the incoming key, the default tenant, and pinned/in-use pools.
     # Returns the evicted tenant key, or nil if nothing is evictable.
-    def evict_one_for_admission(incoming_tenant_key)
-      @pool_manager.lru_tenants(count: @pool_manager.stats[:total_pools]).each do |tenant|
+    #
+    # Tallies protected candidates into +skipped+ instead of emitting a
+    # per-candidate :skip_evict. This scan walks every pool and runs on every
+    # cold create, so a per-candidate event is quadratic in the pool count: a
+    # measured breach that reached 477 pools emitted ~218k of them, each one
+    # eagerly walking that pool's connection array twice to build a payload.
+    # The aggregate lands on :cap_unmet once per admission instead. The timer
+    # paths keep their per-candidate events — there the scan is once per reap
+    # cycle, and "this tenant has been skipped for N cycles" is the signal.
+    def evict_one_for_admission(incoming_tenant_key, skipped)
+      @pool_manager.lru_tenants(count: @pool_manager.total_pools).each do |tenant|
         next if tenant == incoming_tenant_key
-        next if default_tenant_pool?(tenant)
-        next if protected_pool?(tenant, eviction_reason: :admission)
+
+        # Tallied, not silently skipped: a breach caused entirely by default
+        # pools would otherwise report "nothing protected" beside a cap that
+        # could not be met. The three buckets plus the incoming key account
+        # for every candidate the scan saw.
+        if default_tenant_pool?(tenant)
+          skipped[:default] += 1
+          next
+        end
+
+        if (reason = protection_reason(@pool_manager.peek(tenant)))
+          skipped[reason] += 1
+          next
+        end
 
         evict_tenant(tenant, reason: :admission)
         return tenant
@@ -174,18 +200,20 @@ module Apartment
     # or in use). :evict_idle degrades to a soft cap — allow the new pool, surface
     # the breach via :cap_unmet. :raise fails the admission so the caller sheds
     # load. See docs/designs/pool-admission-control.md.
-    def apply_overflow_policy
-      current = @pool_manager.stats[:total_pools]
+    def apply_overflow_policy(skipped = nil)
+      current = @pool_manager.total_pools
       case @overflow_policy
       when :raise
         raise(Apartment::PoolCapacityReached.new(max_total: @max_total, current: current))
       else
-        Instrumentation.instrument(:cap_unmet, max_total: @max_total, current: current, unevicted: 1)
+        payload = { max_total: @max_total, current: current, unevicted: 1 }
+        payload[:skipped] = skipped if skipped
+        Instrumentation.instrument(:cap_unmet, payload)
       end
     end
 
     def evict_lru
-      total = @pool_manager.stats[:total_pools]
+      total = @pool_manager.total_pools
       excess = total - @max_total
       return 0 if excess <= 0
 
@@ -231,15 +259,20 @@ module Apartment
     # protected. Used as a single guard for both eviction paths.
     def protected_pool?(tenant, eviction_reason:)
       pool = @pool_manager.peek(tenant)
-      if pool_pinned?(pool)
-        instrument_skip(reason: :pinned, tenant: tenant, eviction_reason: eviction_reason, pool: pool)
-        return true
-      end
-      if pool_in_use?(pool)
-        instrument_skip(reason: :in_use, tenant: tenant, eviction_reason: eviction_reason, pool: pool)
-        return true
-      end
-      false
+      return false unless (reason = protection_reason(pool))
+
+      instrument_skip(reason: reason, tenant: tenant, eviction_reason: eviction_reason, pool: pool)
+      true
+    end
+
+    # Why this pool cannot be evicted right now (:pinned / :in_use), or nil when
+    # it can. Split out of protected_pool? so the admission scan can classify a
+    # candidate without paying for instrumentation — see evict_one_for_admission.
+    def protection_reason(pool)
+      return :pinned if pool_pinned?(pool)
+      return :in_use if pool_in_use?(pool)
+
+      nil
     end
 
     # Instance-side wrapper around the class predicate; kept for callers

data/lib/apartment/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ros-apartment
 version: !ruby/object:Gem::Version
-  version: 4.0.0.alpha14
+  version: 4.0.0.alpha15
 platform: ruby
 authors:
 - Ryan Brunner