ros-apartment 3.2.0 → 3.4.0

data/lib/apartment/elevators/CLAUDE.md

@@ -0,0 +1,292 @@
+# lib/apartment/elevators/ - Rack Middleware for Tenant Switching
+
+This directory contains Rack middleware components ("elevators") that automatically detect and switch to the appropriate tenant based on incoming HTTP requests.
+
+## Purpose
+
+Elevators intercept incoming requests and establish tenant context **before** the application processes the request. This eliminates the need for manual tenant switching in controllers.
+
+## Metaphor
+
+Like a physical elevator taking you to different floors, these middleware components "elevate" your request to the correct tenant context.
+
+## File Structure
+
+```
+elevators/
+├── generic.rb           # Base elevator with customizable logic
+├── subdomain.rb         # Switch based on subdomain (e.g., acme.example.com)
+├── first_subdomain.rb   # Switch based on first subdomain in chain
+├── domain.rb            # Switch based on domain (excluding www and TLD)
+├── host.rb              # Switch based on full hostname
+└── host_hash.rb         # Switch based on hostname → tenant hash mapping
+```
+
+## How Elevators Work
+
+### Rack Middleware Pattern
+
+All elevators are Rack middleware that intercept requests, extract tenant identifier, switch context, invoke next middleware, and ensure cleanup. See `generic.rb` for base implementation.
+
+### Request Lifecycle with Elevator
+
+HTTP Request → Elevator extracts tenant → Switch to tenant → Application processes → Automatic cleanup (ensure block) → HTTP Response
+
+**See**: `Generic#call` method for middleware call pattern.
+
+## Generic Elevator - Base Class
+
+**Location**: `generic.rb`
+
+### Purpose
+
+Provides base implementation and allows custom tenant resolution via Proc or subclass.
+
+### Implementation
+
+Accepts optional Proc in initializer or expects `parse_tenant_name(request)` override in subclass. See `Generic` class implementation in `generic.rb`.
+
+### Usage Patterns
+
+**With Proc**: Pass Proc to Generic that extracts tenant from Rack::Request.
+
+**Via Subclass**: Inherit from Generic and override `parse_tenant_name`.
+
+**See**: `generic.rb` and README.md for usage examples.
+
+## Subdomain Elevator
+
+**Location**: `subdomain.rb`
+
+### Strategy
+
+Extract first subdomain from hostname.
+
+### Implementation
+
+Uses `request.subdomain` and checks against `excluded_subdomains` class attribute. Returns nil for excluded subdomains. See `Subdomain#parse_tenant_name` in `subdomain.rb`.
+
+### Configuration
+
+Add to middleware stack in `application.rb` and configure `excluded_subdomains` class attribute. See README.md for examples.
+
+### Behavior
+
+| Request URL                  | Subdomain | Excluded? | Tenant      |
+|------------------------------|-----------|-----------|-------------|
+| http://acme.example.com      | acme      | No        | acme        |
+| http://widgets.example.com   | widgets   | No        | widgets     |
+| http://www.example.com       | www       | Yes       | (default)   |
+| http://api.example.com       | api       | Yes       | (default)   |
+| http://example.com           | (empty)   | N/A       | (default)   |
+
+### Why PublicSuffix Dependency?
+
+**Rationale**: International domains require proper TLD parsing. Without PublicSuffix, `example.co.uk` would incorrectly parse `.uk` as the TLD rather than `.co.uk`, causing subdomain extraction to fail.
+
+**Trade-off**: Adds gem dependency, but necessary for international domain support.
+
+## FirstSubdomain Elevator
+
+**Location**: `first_subdomain.rb`
+
+### Strategy
+
+Extract **first** subdomain from chain (for nested subdomains).
+
+### Implementation
+
+Splits subdomain on `.` and takes first part. See `FirstSubdomain#parse_tenant_name` in `first_subdomain.rb`.
+
+### Configuration
+
+Add to middleware stack and configure excluded subdomains. See README.md for configuration.
+
+### Use Case
+
+Multi-level subdomain structures where tenant is always leftmost:
+- `{tenant}.api.example.com`
+- `{tenant}.app.example.com`
+- `{tenant}.staging.example.com`
+
+### Note
+
+In current v3 implementation, `Subdomain` and `FirstSubdomain` may behave identically depending on Rails version due to how `request.subdomain` works. For true nested support, test thoroughly or use custom elevator.
+
+## Domain Elevator
+
+**Location**: `domain.rb`
+
+### Strategy
+
+Use domain name (excluding 'www' and top-level domain) as tenant.
+
+### Implementation
+
+Extracts domain name excluding TLD and 'www' prefix. See `Domain#parse_tenant_name` in `domain.rb`.
+
+### Configuration
+
+Add to middleware stack. See README.md.
+
+### Use Case
+
+When full domain (not subdomain) identifies tenant:
+- `acme-corp.com` → tenant: acme-corp
+- `widgets-inc.com` → tenant: widgets-inc
+
+## Host Elevator
+
+**Location**: `host.rb`
+
+### Strategy
+
+Use **full hostname** as tenant, optionally ignoring specified first subdomains.
+
+### Implementation
+
+Uses full hostname as tenant, optionally ignoring specified first subdomains. See `Host#parse_tenant_name` in `host.rb`.
+
+### Configuration
+
+Add to middleware stack and configure `ignored_first_subdomains`. See README.md.
+
+### Use Case
+
+When each full hostname represents a different tenant:
+- Tenants use custom domains: `acme-corp.com`, `widgets-inc.net`
+- Internal apps: `billing.internal.company.com`, `crm.internal.company.com`
+
+## HostHash Elevator
+
+**Location**: `host_hash.rb`
+
+### Strategy
+
+Direct **mapping** from hostname to tenant name via hash.
+
+### Implementation
+
+Accepts hash mapping hostnames to tenant names. See `HostHash` implementation in `host_hash.rb`.
+
+### Configuration
+
+Pass hash to HostHash initializer when adding to middleware stack. See README.md for examples.
+
+### Use Cases
+
+- **Custom domains**: Each tenant has their own domain
+- **Explicit mapping**: No parsing logic, direct control
+- **Different TLDs**: .com, .io, .net, etc.
+
+### Advantages
+
+- ✅ Explicit control
+- ✅ No parsing ambiguity
+- ✅ Works with any hostname pattern
+
+### Disadvantages
+
+- ❌ Requires manual configuration per tenant
+- ❌ Not dynamic (requires app restart for changes)
+- ❌ Doesn't scale to hundreds of tenants
+
+## Middleware Positioning
+
+### Why Position Matters
+
+**Critical constraint**: Elevators must run before session and authentication middleware.
+
+**Why this matters**: Session middleware loads user data based on session ID. If session loads before tenant is established, you get the wrong tenant's session data. This creates security vulnerabilities where User A sees User B's data.
+
+**Example failure**: Without proper positioning, `www.acme.com` might load session data from `widgets.com` tenant if session middleware runs first.
+
+**How to verify**: Run `Rails.application.middleware` and confirm elevator appears before `ActionDispatch::Session::CookieStore` and authentication middleware like `Warden::Manager`.
+
+## Creating Custom Elevators
+
+### Method 1: Using Proc with Generic
+
+Pass Proc to Generic elevator for inline tenant detection logic. See `generic.rb` and README.md.
+
+### Method 2: Subclassing Generic
+
+Create custom class inheriting from Generic, override `parse_tenant_name(request)`. Supports multi-strategy fallback logic. See `generic.rb` for base class.
+
+## Error Handling
+
+### Handling Missing Tenants
+
+Custom elevators can rescue `Apartment::TenantNotFound` and return appropriate HTTP responses (404, redirect, etc.). See `generic.rb` for base call pattern.
+
+### Custom Error Pages
+
+Override `call(env)` method to wrap `super` in rescue block and handle errors. See existing elevator implementations for patterns.
+
+## Testing Elevators
+
+### Unit Testing
+
+Use `Rack::MockRequest` to create test requests and mock `Apartment::Tenant.switch`. See `spec/unit/elevators/` for test patterns.
+
+### Integration Testing
+
+Create test tenants in before hooks, make requests to different subdomains/hosts, verify correct tenant context. See `spec/integration/` for examples.
+
+## Performance Considerations
+
+### Why Caching Matters for Custom Elevators
+
+**Problem**: If your custom elevator queries the database to resolve tenant (e.g., looking up tenant by API key), you add database latency to **every request**.
+
+**Impact**: 10-50ms per request × thousands of requests = significant overhead.
+
+**Solution**: Cache tenant name lookups. Trade-off is stale cache if tenants are renamed, but this is rare.
+
+### Why Preloaded Hash Maps Beat Database Queries
+
+**Database query approach**: SELECT tenant_name FROM tenants WHERE subdomain = ? — runs on every request.
+
+**Hash map approach**: Loaded once at boot, O(1) lookup with no I/O.
+
+**Trade-off**: Hash maps don't update without restart, but for most applications tenant-to-subdomain mapping is stable.
+
+### Why Monitor Elevator Performance
+
+**Hidden cost**: Elevator runs on every request. 10ms overhead is 10% latency penalty on a 100ms request.
+
+**Target**: Elevator should complete in <5ms. If >100ms, investigate and add logging.
+
+## Common Issues
+
+### Issue: Elevator Not Triggering
+
+**Symptoms**: Tenant always default
+
+**Causes**: Elevator not in middleware stack, `parse_tenant_name` returning nil, or incorrect middleware positioning
+
+**Debug**: Add logging to `parse_tenant_name` to inspect extracted tenant values.
+
+### Issue: TenantNotFound Errors
+
+**Symptoms**: 500 errors on some requests
+
+**Causes**: Tenant doesn't exist or subdomain not in tenant list
+
+**Solution**: Add error handling in custom elevator or validate tenant existence before switching.
+
+## Best Practices
+
+1. **Position elevators early** in middleware stack
+2. **Handle errors gracefully** (don't expose internals)
+3. **Cache lookups** if using database queries
+4. **Test thoroughly** with multiple tenants
+5. **Monitor performance** (log slow switches)
+6. **Document custom logic** for maintainability
+
+## References
+
+- Rack middleware: https://github.com/rack/rack/wiki/Middleware
+- Rack::Request: https://www.rubydoc.info/github/rack/rack/Rack/Request
+- Rails middleware: https://guides.rubyonrails.org/rails_on_rack.html
+- Generic elevator: `generic.rb`

data/lib/apartment/elevators/domain.rb

@@ -16,7 +16,7 @@ module Apartment
       def parse_tenant_name(request)
         return nil if request.host.blank?
 
-        request.host.match(/(www\.)?(?<sld>[^.]*)/)['sld']
+        request.host.match(/(?:www\.)?(?<sld>[^.]*)/)['sld']
       end
     end
   end

data/lib/apartment/elevators/generic.rb

@@ -26,7 +26,7 @@ module Apartment
       end
 
       def parse_tenant_name(_request)
-        raise 'Override'
+        raise('Override')
       end
     end
   end

data/lib/apartment/elevators/host_hash.rb

@@ -9,14 +9,14 @@ module Apartment
     #
     class HostHash < Generic
       def initialize(app, hash = {}, processor = nil)
-        super app, processor
+        super(app, processor)
         @hash = hash
       end
 
       def parse_tenant_name(request)
         unless @hash.key?(request.host)
-          raise TenantNotFound,
-                "Cannot find tenant for host #{request.host}"
+          raise(TenantNotFound,
+                "Cannot find tenant for host #{request.host}")
         end
 
         @hash[request.host]

data/lib/apartment/elevators/subdomain.rb

@@ -22,8 +22,9 @@ module Apartment
       def parse_tenant_name(request)
         request_subdomain = subdomain(request.host)
 
-        # If the domain acquired is set to be excluded, set the tenant to whatever is currently
-        # next in line in the schema search path.
+        # Excluded subdomains (www, api, admin) return nil → uses default tenant.
+        # Returning nil instead of default_tenant name allows Apartment to decide
+        # the fallback behavior.
         tenant = if self.class.excluded_subdomains.include?(request_subdomain)
                    nil
                  else
@@ -35,11 +36,11 @@ module Apartment
 
       protected
 
-      # *Almost* a direct ripoff of ActionDispatch::Request subdomain methods
+      # Subdomain extraction using PublicSuffix to handle international TLDs correctly.
+      # Examples: api.example.com → "api", www.example.co.uk → "www"
 
-      # Only care about the first subdomain for the database name
       def subdomain(host)
-        subdomains(host).first
+        subdomains(host).first # Only first subdomain matters for tenant resolution
       end
 
       def subdomains(host)
@@ -50,6 +51,7 @@ module Apartment
         !ip_host?(host) && domain_valid?(host)
       end
 
+      # Reject IP addresses (127.0.0.1, 192.168.1.1) - no subdomain concept
       def ip_host?(host)
         !/^[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}$/.match(host).nil?
       end
@@ -58,6 +60,8 @@ module Apartment
         PublicSuffix.valid?(host, ignore_private: true)
       end
 
+      # PublicSuffix.parse handles TLDs correctly: example.co.uk has TLD "co.uk"
+      # .trd (third-level domain) returns subdomain parts, excluding TLD
       def parse_host(host)
         (PublicSuffix.parse(host, ignore_private: true).trd || '').split('.')
       end

data/lib/apartment/log_subscriber.rb

@@ -14,7 +14,7 @@ module Apartment
 
     private
 
-    def debug(progname = nil, &blk)
+    def debug(progname = nil, &)
       progname = "  #{apartment_log}#{progname}" unless progname.nil?
 
       super

data/lib/apartment/migrator.rb

@@ -4,12 +4,12 @@ require 'apartment/tenant'
 
 module Apartment
   module Migrator
-    extend self
+    module_function
 
     # Migrate to latest
     def migrate(database)
       Tenant.switch(database) do
-        version = ENV['VERSION'] ? ENV['VERSION'].to_i : nil
+        version = ENV['VERSION']&.to_i
 
         migration_scope_block = ->(migration) { ENV['SCOPE'].blank? || (ENV['SCOPE'] == migration.scope) }
 

data/lib/apartment/model.rb

@@ -14,7 +14,7 @@ module Apartment
         # Modifying the cache key to have a reference to the current tenant,
         # so the cached statement is referring only to the tenant in which we've
         # executed this
-        cache_key = if key.is_a? String
+        cache_key = if key.is_a?(String)
                       "#{Apartment::Tenant.current}_#{key}"
                     else
                       # NOTE: In Rails 6.0.4 we start receiving an ActiveRecord::Reflection::BelongsToReflection

data/lib/apartment/railtie.rb

@@ -48,12 +48,12 @@ module Apartment
       # NOTE: Load the custom log subscriber if enabled
       if Apartment.active_record_log
         ActiveSupport::Notifications.notifier.listeners_for('sql.active_record').each do |listener|
-          next unless listener.instance_variable_get('@delegate').is_a?(ActiveRecord::LogSubscriber)
+          next unless listener.instance_variable_get(:@delegate).is_a?(ActiveRecord::LogSubscriber)
 
-          ActiveSupport::Notifications.unsubscribe listener
+          ActiveSupport::Notifications.unsubscribe(listener)
         end
 
-        Apartment::LogSubscriber.attach_to :active_record
+        Apartment::LogSubscriber.attach_to(:active_record)
       end
     end
 

data/lib/apartment/tasks/CLAUDE.md

@@ -0,0 +1,107 @@
+# lib/apartment/tasks/ - Rake Task Infrastructure
+
+This directory contains modules that support Apartment's rake task operations, particularly tenant migrations with optional parallelism.
+
+## Problem Context
+
+Multi-tenant PostgreSQL applications using schema-per-tenant isolation face operational challenges:
+
+1. **Migration time scales linearly**: 100 tenants × 2 seconds each = 3+ minutes blocking deploys
+2. **Rails assumes single-schema**: Built-in migration tasks don't iterate over tenant schemas
+3. **Parallel execution has pitfalls**: Database connections, advisory locks, and platform differences create subtle failure modes
+
+## Files
+
+### task_helper.rb
+
+**Purpose**: Orchestrates tenant iteration for rake tasks with optional parallel execution.
+
+**Key decisions**:
+
+- **Result-based error handling**: Operations return `Result` structs instead of raising exceptions. This allows migrations to continue for other tenants when one fails, with aggregated reporting at the end.
+
+- **Platform-aware parallelism**: macOS has documented issues with libpq after `fork()` due to GSS/Kerberos state. We auto-detect the platform and choose threads (safe everywhere) or processes (faster on Linux) accordingly. Developers can override via `parallel_strategy` config.
+
+- **Advisory lock management**: Rails uses `pg_advisory_lock` to prevent concurrent migrations. With parallel tenant migrations, all workers compete for the same lock, causing deadlocks. We disable advisory locks during parallel execution. **This shifts responsibility to the developer** to ensure migrations are parallel-safe.
+
+**When to use parallel migrations**:
+
+Use when you have many tenants and your migrations only touch tenant-specific objects. Avoid when migrations create extensions, modify shared types, or have cross-tenant dependencies.
+
+**Configuration options** (set in `config/initializers/apartment.rb`):
+
+| Option | Default | Purpose |
+|--------|---------|---------|
+| `parallel_migration_threads` | `0` | Worker count. 0 = sequential (safest) |
+| `parallel_strategy` | `:auto` | `:auto`, `:threads`, or `:processes` |
+| `manage_advisory_locks` | `true` | Disable locks during parallel execution |
+
+### schema_dumper.rb
+
+**Purpose**: Ensures schema is dumped from the public schema after tenant migrations.
+
+**Why this exists**: After `rails db:migrate`, Rails dumps the current schema. Without intervention, this could capture the last-migrated tenant's schema rather than the authoritative public schema. We switch to the default tenant before invoking the dump.
+
+**Rails convention compliance**: Respects all relevant Rails settings:
+- `dump_schema_after_migration`: Global toggle for automatic dumps
+- `schema_format`: `:ruby` produces schema.rb, `:sql` produces structure.sql
+- `database_tasks`, `replica`, `schema_dump`: Per-database settings
+
+### enhancements.rb
+
+**Purpose**: Hooks Apartment tasks into Rails' standard `db:migrate` and `db:rollback` tasks.
+
+**Design choice**: We enhance rather than replace Rails tasks. Running `rails db:migrate` automatically migrates all tenant schemas after the public schema.
+
+## Relationship to Other Components
+
+- **Apartment::Migrator** (`lib/apartment/migrator.rb`): The actual migration execution logic. TaskHelper coordinates which tenants to migrate; Migrator handles the per-tenant work.
+
+- **Rake tasks** (`lib/tasks/apartment.rake`): Define the public task interface (`apartment:migrate`, etc.). These tasks use TaskHelper for iteration.
+
+- **Configuration** (`lib/apartment.rb`): Parallel execution settings live in the main Apartment module.
+
+## Common Failure Modes
+
+### Connection pool exhaustion
+
+**Symptom**: "could not obtain a connection from the pool" errors
+
+**Cause**: `parallel_migration_threads` exceeds database pool size
+
+**Fix**: Ensure `pool` in `database.yml` > `parallel_migration_threads`
+
+### Advisory lock deadlocks
+
+**Symptom**: Migrations hang indefinitely
+
+**Cause**: Multiple workers waiting for the same advisory lock
+
+**Fix**: Ensure `manage_advisory_locks: true` (default) when using parallelism
+
+### macOS fork crashes
+
+**Symptom**: Segfaults or GSS-API errors when using process-based parallelism on macOS
+
+**Cause**: libpq doesn't support fork() cleanly on macOS
+
+**Fix**: Use `parallel_strategy: :threads` or rely on `:auto` detection
+
+### Empty tenant name errors
+
+**Symptom**: `PG::SyntaxError: zero-length delimited identifier`
+
+**Cause**: `tenant_names` proc returned empty strings or nil values
+
+**Fix**: Fixed in v3.4.0 - empty values are now filtered automatically
+
+## Testing Considerations
+
+Parallel execution paths are difficult to unit test due to process isolation and connection state. The test suite verifies:
+
+- Correct delegation between sequential/parallel paths
+- Platform detection logic
+- Advisory lock ENV management
+- Result aggregation and error capture
+
+Integration testing of actual parallel execution happens in CI across Linux (processes) and macOS (threads) runners.

data/lib/apartment/tasks/enhancements.rb

@@ -46,7 +46,7 @@ module Apartment
       end
 
       def inserted_task_name(task)
-        task.name.sub(/db:/, 'apartment:')
+        task.name.sub('db:', 'apartment:')
       end
     end
   end

data/lib/apartment/tasks/schema_dumper.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+module Apartment
+  module Tasks
+    # Handles automatic schema dumping after tenant migrations.
+    #
+    # ## Problem Context
+    #
+    # After running `rails db:migrate`, Rails dumps the schema to capture the
+    # current database structure. With Apartment, tenant migrations modify
+    # individual schemas but the canonical structure lives in the public/default
+    # schema. Without explicit handling, the schema could be dumped from the
+    # last-migrated tenant schema instead of the authoritative public schema.
+    #
+    # ## Why This Approach
+    #
+    # We switch to the default tenant before dumping to ensure the schema file
+    # reflects the public schema structure. This is correct because:
+    #
+    # 1. All tenant schemas are created from the same schema file
+    # 2. The public schema is the source of truth for structure
+    # 3. Tenant-specific data differences don't affect schema structure
+    #
+    # ## Rails Convention Compliance
+    #
+    # We respect several Rails configurations rather than inventing our own:
+    #
+    # - `config.active_record.dump_schema_after_migration`: Global toggle
+    # - `config.active_record.schema_format`: `:ruby` for schema.rb, `:sql` for structure.sql
+    # - `database_tasks: true/false`: Per-database migration responsibility
+    # - `replica: true`: Excludes read replicas from schema operations
+    # - `schema_dump: false`: Per-database schema dump toggle
+    #
+    # The `db:schema:dump` task respects `schema_format` and produces either
+    # schema.rb or structure.sql accordingly.
+    #
+    # ## Gotchas
+    #
+    # - Schema dump failures are logged but don't fail the migration. This
+    #   prevents a secondary concern from blocking critical migrations.
+    # - Multi-database setups must mark one connection with `database_tasks: true`
+    #   to indicate which database owns schema management.
+    # - Don't call `Rails.application.load_tasks` here; if invoked from a rake
+    #   task, it re-triggers apartment enhancements causing recursion.
+    module SchemaDumper
+      class << self
+        # Entry point called after successful migrations. Checks all relevant
+        # Rails settings before attempting dump.
+        def dump_if_enabled
+          return unless rails_dump_schema_enabled?
+
+          db_config = find_schema_dump_config
+          return if db_config.nil?
+
+          schema_dump_setting = db_config.configuration_hash[:schema_dump]
+          return if schema_dump_setting == false
+
+          Apartment::Tenant.switch(Apartment.default_tenant) do
+            dump_schema
+          end
+        rescue StandardError => e
+          # Log but don't fail - schema dump is secondary to migration success
+          Rails.logger.warn("[Apartment] Schema dump failed: #{e.message}")
+        end
+
+        private
+
+        # Finds the database configuration responsible for schema management.
+        # Multi-database setups use `database_tasks: true` to mark the primary
+        # migration database. Falls back to 'primary' named config.
+        def find_schema_dump_config
+          configs = ActiveRecord::Base.configurations.configs_for(env_name: Rails.env)
+
+          migration_config = configs.find { |c| c.database_tasks? && !c.replica? }
+          return migration_config if migration_config
+
+          configs.find { |c| c.name == 'primary' }
+        end
+
+        # Invokes the standard Rails schema dump task. We reenable first
+        # because Rake tasks can only run once per session by default.
+        def dump_schema
+          if task_defined?('db:schema:dump')
+            Rails.logger.info('[Apartment] Dumping schema from default tenant...')
+            Rake::Task['db:schema:dump'].reenable
+            Rake::Task['db:schema:dump'].invoke
+            Rails.logger.info('[Apartment] Schema dump completed.')
+          else
+            Rails.logger.warn('[Apartment] db:schema:dump task not found')
+          end
+        end
+
+        # Safe task existence check. Avoids load_tasks which would cause
+        # recursive enhancement loading when called from apartment rake tasks.
+        def task_defined?(task_name)
+          Rake::Task.task_defined?(task_name)
+        end
+
+        # Checks Rails' global schema dump setting. Older Rails versions
+        # may not have this method, so we default to enabled.
+        def rails_dump_schema_enabled?
+          return true unless ActiveRecord::Base.respond_to?(:dump_schema_after_migration)
+
+          ActiveRecord::Base.dump_schema_after_migration
+        end
+      end
+    end
+  end
+end