ros-apartment 3.2.0 → 3.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e7acbb6c519fef676bdf05370eb1de788bf262a30f83040fcb2455b3a950ad58
-  data.tar.gz: c078d989df4e11e7d519bcb0c30c0a99cd8f692adc995407a6a7fdecbd5d6e2a
+  metadata.gz: 22097d27933cc7eee7bf0c5e3ad5cf1b84d9243dcfc04be00d6db07a91c9857b
+  data.tar.gz: 28e20f76b32b532db8db681503753216ca2847c66ab80e902c200ea43a82b05d
 SHA512:
-  metadata.gz: 9ef24485b251bf0d68f1e2af3a6cb82312b25f457383ed4bff1eadf50ee2cacba8af21330cd03853186ee117b07e3454f9224485d81079c687b69fadc9fabbea
-  data.tar.gz: 64c3423beb74472af3f84ad21152eed840162a6bf7d567b360f0a7216314545f7e1ca5eb5af9fb20b753fd681a4d40582478da6335ab69cc8e8795812362d74a
+  metadata.gz: 5f007c6b72251b371b02380628d53b5cf1c7b62e5620fb659b596e9dec1a62e7a2fc0bf0ad1f5253d99b852f31091ddcedf073ed5e64457c5430c58c79c8aa83
+  data.tar.gz: 53ccf42974cebbcc6f874f9a631fe366a3952ff36d993127173df34563848359f409a3beeaa37596896a75e8c85cccd63a5ce4a7ec70b7d3278bf7e3b8c7e394

data/.gitignore

@@ -13,3 +13,4 @@ cookbooks
 tmp
 spec/dummy/db/*.sqlite3
 .DS_Store
+.claude/

data/.rubocop.yml

@@ -7,7 +7,7 @@ AllCops:
     - spec/dummy_engine/dummy_engine.gemspec
     - spec/schemas/**/*.rb
 
-require:
+plugins:
   - rubocop-rails
   - rubocop-performance
   - rubocop-thread_safety
@@ -22,6 +22,26 @@ Layout/MultilineMethodCallIndentation:
   EnforcedStyle: indented
 
 Metrics/BlockLength:
+  Max: 30
+  Exclude:
+    - spec/**/*.rb
+    - lib/tasks/**/*.rake
+    - Rakefile
+
+Metrics/MethodLength:
+  Max: 15
+  Exclude:
+    - spec/**/*.rb
+    - lib/apartment/tenant.rb
+
+Metrics/AbcSize:
+  Max: 20
+  Exclude:
+    - spec/**/*.rb
+    - lib/apartment/adapters/postgresql_adapter.rb
+
+Metrics/ClassLength:
+  Max: 155
   Exclude:
     - spec/**/*.rb
 
@@ -76,4 +96,75 @@ Style/CollectionMethods:
     collect!: 'map!'
     inject: 'reduce'
     detect: 'detect'
-    find_all: 'select'
+    find_all: 'select'
+
+# RSpec style preferences - disable for mature test suite
+RSpec/NamedSubject:
+  Enabled: false
+
+RSpec/MultipleExpectations:
+  Enabled: false
+
+RSpec/MessageSpies:
+  Enabled: false
+
+RSpec/NestedGroups:
+  Enabled: false
+
+RSpec/ContextWording:
+  Enabled: false
+
+RSpec/ExampleLength:
+  Enabled: false
+
+RSpec/InstanceVariable:
+  Enabled: false
+
+RSpec/SpecFilePathFormat:
+  Enabled: false
+
+RSpec/DescribeClass:
+  Enabled: false
+
+RSpec/IndexedLet:
+  Enabled: false
+
+RSpec/AnyInstance:
+  Enabled: false
+
+RSpec/BeforeAfterAll:
+  Enabled: false
+
+RSpec/LeakyConstantDeclaration:
+  Enabled: false
+
+RSpec/VerifiedDoubles:
+  Enabled: false
+
+RSpec/NoExpectationExample:
+  Enabled: false
+
+# ThreadSafety - intentional design for configuration
+ThreadSafety/ClassInstanceVariable:
+  Exclude:
+    - lib/apartment.rb
+    - lib/apartment/model.rb
+    - lib/apartment/elevators/*.rb
+    - spec/support/config.rb
+
+ThreadSafety/ClassAndModuleAttributes:
+  Exclude:
+    - lib/apartment.rb
+    - lib/apartment/active_record/postgresql_adapter.rb
+
+ThreadSafety/DirChdir:
+  Exclude:
+    - ros-apartment.gemspec
+
+ThreadSafety/NewThread:
+  Exclude:
+    - spec/tenant_spec.rb
+
+# Rake cops
+Rake/DuplicateTask:
+  Enabled: false

data/.ruby-version

@@ -1 +1 @@
-3.3.6
+3.3.10

data/Appraisals

@@ -128,3 +128,18 @@ appraise 'rails-8-0-sqlite3' do
   gem 'rails', '~> 8.0.0'
   gem 'sqlite3', '~> 2.1'
 end
+
+appraise 'rails-8-1-postgresql' do
+  gem 'rails', '~> 8.1.0'
+  gem 'pg', '~> 1.6.0'
+end
+
+appraise 'rails-8-1-mysql' do
+  gem 'rails', '~> 8.1.0'
+  gem 'mysql2', '~> 0.5'
+end
+
+appraise 'rails-8-1-sqlite3' do
+  gem 'rails', '~> 8.1.0'
+  gem 'sqlite3', '~> 2.8'
+end

data/CLAUDE.md

@@ -0,0 +1,210 @@
+# CLAUDE.md - Apartment v3 Understanding Guide
+
+**Version**: 3.x (Current Development Branch)
+**Maintained by**: CampusESP
+**Gem Name**: `ros-apartment`
+
+## What This Documentation Covers
+
+This branch contains v3 (current stable release). A v4 refactor with different architecture exists on `man/spec-restart` branch.
+
+**Goal**: Understand v3 deeply enough to maintain it and plan v4 migration.
+
+## Where to Start
+
+1. **README.md** - Installation, basic usage, configuration options
+2. **docs/architecture.md** - Core design decisions and WHY they were made
+3. **docs/adapters.md** - Database strategy trade-offs
+4. **docs/elevators.md** - Middleware design rationale
+5. **lib/apartment/CLAUDE.md** - Implementation file guide
+6. **spec/CLAUDE.md** - Test organization and patterns
+
+## Core Concepts
+
+### Multi-Tenancy via Database Isolation
+
+**Problem**: Single application needs to serve multiple customers with data completely separated.
+
+**v3 Solution**: Thread-local tenant switching. Each request/thread tracks which tenant it's serving.
+
+**Key limitation**: Not fiber-safe (fibers share thread-local storage).
+
+### Two Main Strategies
+
+**PostgreSQL (schemas)**: Multiple namespaces in single database. Fast, scales to 100+ tenants.
+
+**MySQL (databases)**: Separate database per tenant. Complete isolation, slower switching.
+
+**See**: `docs/adapters.md` for trade-offs.
+
+### Automatic Tenant Detection
+
+**Middleware ("Elevators")**: Rack middleware extracts tenant from request (subdomain, domain, header).
+
+**Critical**: Must position before session middleware to avoid data leakage.
+
+**See**: `docs/elevators.md` for design decisions.
+
+## Key Architecture Decisions
+
+### 1. Thread-Local Adapter Storage
+
+**Why**: Concurrent requests need isolated tenant contexts without global locks.
+
+**Implementation**: `Thread.current[:apartment_adapter]`
+
+**Trade-off**: Not fiber-safe, but works for 99% of Rails deployments.
+
+**See**: `Apartment::Tenant.adapter` method in `tenant.rb`, `docs/architecture.md`
+
+### 2. Block-Based Tenant Switching
+
+**Why**: Automatic cleanup even on exceptions prevents tenant context leakage.
+
+**Pattern**: `Apartment::Tenant.switch(tenant) { ... }` with ensure block
+
+**Alternative rejected**: Manual switch/reset - too error-prone.
+
+**See**: `AbstractAdapter#switch` method in `adapters/abstract_adapter.rb`
+
+### 3. Excluded Models
+
+**Why**: Some models (User, Company) exist globally across all tenants.
+
+**Implementation**: Separate connections that bypass tenant switching.
+
+**Limitation**: Can't use `has_and_belongs_to_many` - must use `has_many :through`.
+
+**See**: `AbstractAdapter#process_excluded_models` method in `adapters/abstract_adapter.rb`
+
+### 4. Adapter Pattern
+
+**Why**: PostgreSQL uses schemas, MySQL uses databases - fundamentally different.
+
+**Implementation**: Abstract base class with database-specific subclasses.
+
+**Benefit**: Unified API hides database differences.
+
+**See**: `lib/apartment/adapters/`, `docs/adapters.md`
+
+### 5. Callback System
+
+**Why**: Users need logging/notification hooks without modifying gem code.
+
+**Implementation**: ActiveSupport::Callbacks on `:create` and `:switch`.
+
+**See**: Callback definitions in `AbstractAdapter` class in `adapters/abstract_adapter.rb`
+
+## File Organization
+
+**Core logic**: `lib/apartment.rb` (configuration), `lib/apartment/tenant.rb` (public API)
+
+**Adapters**: `lib/apartment/adapters/*.rb` - Database-specific implementations
+
+**Elevators**: `lib/apartment/elevators/*.rb` - Rack middleware for auto-switching
+
+**Tests**: `spec/` - Adapter tests, elevator tests, integration tests
+
+**See folder CLAUDE.md files for details on each directory.**
+
+## Configuration Philosophy
+
+**Dynamic tenant discovery**: `tenant_names` can be callable (proc/lambda) that queries database. Why? Tenants change at runtime.
+
+**Fail-safe boot**: Rescue database errors during config loading. Why? App should start even if tenant table doesn't exist yet (pending migrations).
+
+**Environment isolation**: Optional `prepend_environment`/`append_environment` to prevent cross-environment tenant name collisions.
+
+**See**: `Apartment.extract_tenant_config` method in `lib/apartment.rb`
+
+## Common Pitfalls
+
+**Elevator positioning**: Must be before session/auth middleware. Otherwise session data leaks across tenants.
+
+**Not using blocks**: `switch!` without block requires manual cleanup. Easy to forget. Always prefer `switch` with block.
+
+**HABTM with excluded models**: Doesn't work. Must use `has_many :through` instead.
+
+**Assuming fiber safety**: v3 uses thread-local storage. Not safe for fiber-based async frameworks.
+
+**See**: `docs/architecture.md` for detailed analysis
+
+## Performance Characteristics
+
+**PostgreSQL schemas**:
+- Switch: <1ms
+- Scalability: 100+ tenants
+- Memory: Constant
+
+**MySQL databases**:
+- Switch: 10-50ms
+- Scalability: 10-50 tenants
+- Memory: Linear with active tenants
+
+**See**: `docs/adapters.md` for benchmarks and trade-offs
+
+## Testing the Gem
+
+**Spec organization**: `spec/adapters/` for database tests, `spec/unit/elevators/` for middleware tests
+
+**Database selection**: `DB=postgresql rspec` or `DB=mysql` or `DB=sqlite3`
+
+**Key test pattern**: Create test tenant, switch to it, verify isolation, cleanup
+
+**See**: `spec/CLAUDE.md` for testing patterns
+
+## Debugging Techniques
+
+**Check current tenant**: `Apartment::Tenant.current`
+
+**Inspect adapter**: `Apartment::Tenant.adapter.class`
+
+**List tenants**: `Apartment.tenant_names`
+
+**Enable logging**: `config.active_record_log = true`
+
+**PostgreSQL search path**: `SHOW search_path` in SQL console
+
+**See**: Inline code comments for context-specific debugging
+
+## Migration to v4
+
+**v4 branch**: `man/spec-restart`
+
+**Major changes**: Connection pool per tenant (vs thread-local switching), fiber-safe via CurrentAttributes, immutable connection descriptors
+
+**Why v4**: Better performance (no switching overhead), true fiber safety, simpler mental model
+
+**Migration strategy**: Understand v3 architecture first (this branch), then contrast with v4 approach
+
+## Design Principles
+
+**Open for extension**: Users can create custom adapters and elevators without modifying gem.
+
+**Closed for modification**: Core logic shouldn't need changes for new use cases.
+
+**Fail fast**: Configuration errors raise at boot. Tenant not found raises at runtime.
+
+**Graceful degradation**: If rollback fails, fall back to default tenant rather than crash.
+
+**See**: `docs/architecture.md` for rationale
+
+## Getting Help
+
+**Issues**: https://github.com/rails-on-services/apartment/issues
+
+**Discussions**: https://github.com/rails-on-services/apartment/discussions
+
+**Code**: Read the actual implementation files - they're well-commented
+
+## Documentation Philosophy
+
+**This documentation focuses on WHY, not HOW**:
+- Design decisions and trade-offs
+- Architecture rationale
+- Pitfalls and constraints
+- References to actual source files
+
+**For HOW (implementation details)**: Read the well-commented source code in `lib/`.
+
+**For WHAT (API reference)**: See README.md and RDoc comments.

data/README.md

@@ -348,7 +348,7 @@ Please note that our custom logger inherits from `ActiveRecord::LogSubscriber` s
 
 **Example log output:**
 
-<img src="documentation/images/log_example.png">
+<img src="docs/images/log_example.png">
 
 ```ruby
 Apartment.configure do |config|

data/Rakefile

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 begin
-  require 'bundler'
+  require('bundler')
 rescue StandardError
   'You must `gem install bundler` and `bundle install` to run rake tasks'
 end
@@ -26,6 +26,7 @@ namespace :spec do
   end
 end
 
+desc 'Start an interactive console with Apartment loaded'
 task :console do
   require 'pry'
   require 'apartment'
@@ -39,15 +40,15 @@ namespace :db do
   namespace :test do
     case ENV.fetch('DATABASE_ENGINE', nil)
     when 'postgresql'
-      task prepare: %w[postgres:drop_db postgres:build_db]
+      task(prepare: %w[postgres:drop_db postgres:build_db])
     when 'mysql'
-      task prepare: %w[mysql:drop_db mysql:build_db]
+      task(prepare: %w[mysql:drop_db mysql:build_db])
     when 'sqlite'
-      task :prepare do
+      task(:prepare) do
         puts 'No need to prepare sqlite3 database'
       end
     else
-      task :prepare do
+      task(:prepare) do
         puts 'No database engine specified, skipping db:test:prepare'
       end
     end

data/docs/adapters.md

@@ -0,0 +1,177 @@
+# Apartment Adapters - Design & Architecture
+
+**Key files**: `lib/apartment/adapters/*.rb`
+
+## Purpose
+
+Adapters translate abstract tenant operations into database-specific implementations. Each database has fundamentally different isolation mechanisms, requiring separate strategies.
+
+## Design Decision: Why Adapter Pattern?
+
+**Problem**: PostgreSQL uses schemas, MySQL uses databases, SQLite uses files. A unified API across these different approaches requires abstraction.
+
+**Solution**: Adapter pattern with shared base class defining lifecycle, database-specific subclasses implementing mechanics.
+
+**Trade-off**: Adds complexity but enables multi-database support without polluting core logic.
+
+## Adapter Hierarchy
+
+See `lib/apartment/adapters/` for implementations:
+- `abstract_adapter.rb` - Shared lifecycle, callbacks, error handling
+- `postgresql_adapter.rb` - Schema-based isolation (3 variants)
+- `mysql2_adapter.rb` - Database-per-tenant
+- `sqlite3_adapter.rb` - File-per-tenant
+- JDBC variants for JRuby
+
+## AbstractAdapter - Design Rationale
+
+**File**: `lib/apartment/adapters/abstract_adapter.rb`
+
+### Why Callbacks?
+
+Provides extension points for logging, notifications, analytics without modifying core adapter code. Users can hook into `:create` and `:switch` events.
+
+### Why Ensure Blocks in switch()?
+
+**Critical decision**: Always rollback to previous tenant, even if block raises. Prevents tenant context leakage across requests/jobs. If rollback fails, fall back to default tenant as last resort.
+
+**Alternative considered**: Let exceptions propagate without cleanup. Rejected because it leaves connections in wrong tenant state.
+
+### Why Query Cache Management?
+
+Rails disables query cache during connection establishment. Must explicitly preserve and restore state across tenant switches to maintain performance.
+
+### Why Separate Connection Handler?
+
+`SeparateDbConnectionHandler` prevents admin operations (CREATE/DROP DATABASE) from polluting the main application connection pool. Multi-server setups especially need this isolation.
+
+## PostgreSQL Adapters - Three Strategies
+
+**Files**: `postgresql_adapter.rb` (3 classes in one file)
+
+### 1. PostgresqlAdapter (Database-per-tenant)
+
+Rarely used. Most deployments use schemas instead.
+
+### 2. PostgresqlSchemaAdapter (Schema-based - Primary)
+
+**Why schemas?**: Single database, multiple namespaces. Fast switching via `SET search_path`. Scales to hundreds of tenants without connection overhead.
+
+**Key design decisions**:
+- **Search path ordering**: Tenant schema first, then persistent schemas, then public. Tables resolve in order.
+- **Persistent schemas**: Shared extensions (PostGIS, uuid-ossp) remain accessible across all tenants.
+- **Excluded model handling**: Explicitly qualify table names with default schema to prevent tenant-based queries.
+
+**Trade-off**: Less isolation than separate databases, but massively better performance and scalability.
+
+### 3. PostgresqlSchemaFromSqlAdapter (pg_dump-based)
+
+**Why pg_dump instead of schema.rb?**:
+- Handles PostgreSQL-specific features (extensions, custom types, constraints) that Rails schema dumper misses
+- Required for PostGIS spatial types
+- Necessary for complex production schemas
+
+**Why patch search_path in dump?**: pg_dump outputs assume specific search_path. Must rewrite SQL to target new tenant schema instead of source schema.
+
+**Why environment variable handling?**: pg_dump shell command reads PGHOST/PGUSER/etc from ENV. Must temporarily set, execute, then restore to avoid polluting global state.
+
+**Alternative considered**: Use Rails schema.rb. Rejected because it loses PostgreSQL-specific features.
+
+## MySQL Adapters - Database Isolation
+
+**Files**: `mysql2_adapter.rb`, `trilogy_adapter.rb`
+
+### Why Separate Databases?
+
+MySQL doesn't have PostgreSQL's robust schema support. Database-level isolation is the natural fit.
+
+**Implications**:
+- Each switch establishes new connection to different database
+- Connection pool per tenant (memory overhead)
+- Practical limit of 10-50 concurrent tenants before connection exhaustion
+
+### Why Trilogy Adapter?
+
+Modern MySQL driver. Identical implementation to Mysql2Adapter, just different gem.
+
+### Multi-Server Support
+
+Hash-based tenant config allows different tenants on different MySQL servers. Enables horizontal scaling and geographic distribution.
+
+## SQLite Adapter - File-Based
+
+**File**: `sqlite3_adapter.rb`
+
+### Why File-Per-Tenant?
+
+SQLite is single-file database. Natural isolation is separate files.
+
+**Use case**: Testing, development, single-user apps. **Not** production multi-tenant.
+
+## Performance Characteristics
+
+**PostgreSQL schemas**:
+- Switch latency: <1ms (SQL command)
+- Scalability: 100+ tenants easily
+- Memory: Constant (~50MB)
+
+**MySQL databases**:
+- Switch latency: 10-50ms (connection establishment)
+- Scalability: 10-50 tenants
+- Memory: ~20MB per active tenant
+
+**SQLite files**:
+- Switch latency: 5-20ms (file I/O)
+- Scalability: Not recommended for concurrent users
+- Memory: ~5MB per database
+
+## Adapter Selection Matrix
+
+| Database   | Strategy     | Speed     | Scalability | Isolation | Best For              |
+|------------|--------------|-----------|-------------|-----------|-----------------------|
+| PostgreSQL | Schemas      | Very Fast | Excellent   | Good      | 100+ tenants          |
+| MySQL      | Databases    | Moderate  | Good        | Excellent | Complete isolation    |
+| SQLite     | Files        | Moderate  | Poor        | Excellent | Testing only          |
+
+## Extension Points
+
+### Creating Custom Adapters
+
+**Why you might need this**: Supporting databases not yet implemented (Oracle, SQL Server, CockroachDB).
+
+**What to implement**:
+1. Subclass `AbstractAdapter`
+2. Define required methods: `create_tenant`, `connect_to_new`, `drop_command`, `current`
+3. Register factory method in `lib/apartment/tenant.rb`
+
+**See**: Existing adapters for patterns. PostgreSQL is most complex, SQLite is simplest.
+
+## Common Pitfalls & Design Constraints
+
+### Why Transaction Handling in create_tenant?
+
+RSpec tests run in transactions. Must detect open transactions and avoid nested BEGIN/COMMIT to prevent errors.
+
+### Why Separate rescue_from per Adapter?
+
+Different databases raise different exceptions. PostgreSQL raises `PG::Error`, MySQL raises different errors. Each adapter specifies what to rescue.
+
+### Why environmentify()?
+
+Prevents tenant name collisions across Rails environments. `development_acme` vs `production_acme`. Optional but recommended for shared infrastructure.
+
+## Thread Safety
+
+**Critical**: Adapters stored in `Thread.current[:apartment_adapter]`. Each thread gets isolated adapter instance.
+
+**Implication**: Safe for multi-threaded servers (Puma), background jobs (Sidekiq).
+
+**Limitation**: Not fiber-safe. v4 refactor addresses this.
+
+## References
+
+- AbstractAdapter implementation: `lib/apartment/adapters/abstract_adapter.rb`
+- PostgreSQL variants: `lib/apartment/adapters/postgresql_adapter.rb`
+- MySQL variants: `lib/apartment/adapters/mysql2_adapter.rb`, `trilogy_adapter.rb`
+- SQLite: `lib/apartment/adapters/sqlite3_adapter.rb`
+- PostgreSQL documentation: https://www.postgresql.org/docs/current/ddl-schemas.html