ros-apartment 3.2.0 → 3.3.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/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/task_helper.rb

@@ -2,10 +2,10 @@
 
 module Apartment
   module TaskHelper
-    def self.each_tenant(&block)
+    def self.each_tenant
       Parallel.each(tenants_without_default, in_threads: Apartment.parallel_migration_threads) do |tenant|
         Rails.application.executor.wrap do
-          block.call(tenant)
+          yield(tenant)
         end
       end
     end
@@ -44,9 +44,9 @@ module Apartment
       create_tenant(tenant_name) if strategy == :create_tenant
 
       puts("Migrating #{tenant_name} tenant")
-      Apartment::Migrator.migrate tenant_name
+      Apartment::Migrator.migrate(tenant_name)
     rescue Apartment::TenantNotFound => e
-      raise e if strategy == :raise_exception
+      raise(e) if strategy == :raise_exception
 
       puts e.message
     end

data/lib/apartment/tenant.rb

@@ -32,13 +32,13 @@ module Apartment
         end
 
         begin
-          require "apartment/adapters/#{adapter_method}"
+          require("apartment/adapters/#{adapter_method}")
         rescue LoadError
-          raise "The adapter `#{adapter_method}` is not yet supported"
+          raise("The adapter `#{adapter_method}` is not yet supported")
         end
 
         unless respond_to?(adapter_method)
-          raise AdapterNotFound, "database configuration specifies nonexistent #{config[:adapter]} adapter"
+          raise(AdapterNotFound, "database configuration specifies nonexistent #{config[:adapter]} adapter")
         end
 
         send(adapter_method, config)

data/lib/apartment/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Apartment
-  VERSION = '3.2.0'
+  VERSION = '3.3.0'
 end

data/lib/apartment.rb

@@ -41,7 +41,7 @@ module Apartment
 
     # configure apartment with available options
     def configure
-      yield self if block_given?
+      yield(self) if block_given?
     end
 
     def tenant_names
@@ -57,7 +57,7 @@ module Apartment
     end
 
     def db_config_for(tenant)
-      (tenants_with_config[tenant] || connection_config)
+      tenants_with_config[tenant] || connection_config
     end
 
     # Whether or not db:migrate should also migrate tenants
@@ -68,9 +68,10 @@ module Apartment
       @db_migrate_tenants = true
     end
 
-    # How to handle tenant missing on db:migrate
-    # defaults to :rescue_exception
-    # available options: rescue_exception, raise_exception, create_tenant
+    # How to handle missing tenants during db:migrate
+    # :rescue_exception (default) - Log error, continue with other tenants
+    # :raise_exception - Stop migration immediately
+    # :create_tenant - Automatically create missing tenant and migrate
     def db_migrate_tenant_missing_strategy
       valid = %i[rescue_exception raise_exception create_tenant]
       value = @db_migrate_tenant_missing_strategy || :rescue_exception
@@ -80,7 +81,7 @@ module Apartment
       key_name  = 'config.db_migrate_tenant_missing_strategy'
       opt_names = valid.join(', ')
 
-      raise ApartmentError, "Option #{value} not valid for `#{key_name}`. Use one of #{opt_names}"
+      raise(ApartmentError, "Option #{value} not valid for `#{key_name}`. Use one of #{opt_names}")
     end
 
     # Default to empty array
@@ -126,14 +127,19 @@ module Apartment
     def extract_tenant_config
       return {} unless @tenant_names
 
+      # Execute callable (proc/lambda) to get dynamic tenant list from database
       values = @tenant_names.respond_to?(:call) ? @tenant_names.call : @tenant_names
-      unless values.is_a? Hash
-        values = values.each_with_object({}) do |tenant, hash|
-          hash[tenant] = connection_config
+
+      # Normalize arrays to hash format (tenant_name => connection_config)
+      unless values.is_a?(Hash)
+        values = values.index_with do |_tenant|
+          connection_config
         end
       end
       values.with_indifferent_access
     rescue ActiveRecord::StatementInvalid
+      # Database query failed (table doesn't exist yet, connection issue)
+      # Return empty hash to allow app to boot without tenants
       {}
     end
   end

data/lib/generators/apartment/install/install_generator.rb

@@ -5,7 +5,7 @@ module Apartment
     source_root File.expand_path('templates', __dir__)
 
     def copy_files
-      template 'apartment.rb', File.join('config', 'initializers', 'apartment.rb')
+      template('apartment.rb', File.join('config', 'initializers', 'apartment.rb'))
     end
   end
 end

data/lib/generators/apartment/install/templates/apartment.rb

@@ -50,7 +50,7 @@ Apartment.configure do |config|
   #   end
   # end
   #
-  config.tenant_names = -> { ToDo_Tenant_Or_User_Model.pluck :database }
+  config.tenant_names = -> { ToDo_Tenant_Or_User_Model.pluck(:database) }
 
   # PostgreSQL:
   #   Specifies whether to use PostgreSQL schemas or create a new database per Tenant.
@@ -111,6 +111,6 @@ end
 # }
 
 # Rails.application.config.middleware.use Apartment::Elevators::Domain
-Rails.application.config.middleware.use Apartment::Elevators::Subdomain
+Rails.application.config.middleware.use(Apartment::Elevators::Subdomain)
 # Rails.application.config.middleware.use Apartment::Elevators::FirstSubdomain
 # Rails.application.config.middleware.use Apartment::Elevators::Host