activerecord-tenanted 0.1.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9435f6bbc9033a529437eeb79812c04d0a2a4bd03fbc04b0e1598d4785ad4e9c
-  data.tar.gz: 7670007efe5ce4ce8b90583781cac20794da00e44bb7dfda48226700f937fa12
+  metadata.gz: bec774f1cd8bd92dc8d4f0db6e76f310adbe19ccc5873e599ba0d2416f6a2dcc
+  data.tar.gz: bd914d09c8e8e0e5cef89523ac59b5152fd34154c7fc64f3cf6630713ae4bf82
 SHA512:
-  metadata.gz: 99d3a88756b44268d8890dbc1185d6fc695ce7b266ed79a9cccf203ab50fb4e0b63ac15297fcc894612b89da735c1895f93cc5535f79603cb0de3e07fddd6c12
-  data.tar.gz: be0b5c90f18a1fb8d9a3ed19a6c2e10f51e0da76975a28a92eddab20b29b8a0a993c0612f76265fbe7f04e17c4ea7f224b3feae93bab1b9ffa9bf55da58f266f
+  metadata.gz: 54f36d6835c976757988eba57325ffe7a62e5bf53fad44fa6db9a463c4bbb42b1adea362d7c35d605cdd5cc016b0bd0b28426108efb27644a9e1279d9f6ccb72
+  data.tar.gz: c430f00a857613851bac9c8e81f04ae794dd90d2827e88d914c231bac218daa352b5fc0a3c21fdb82e2073e46422ebf85c310950fe4972595f4616e03374fa04

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 37signals, LLC
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -1,43 +1,68 @@
-# Activerecord::Tenanted
+# ActiveRecord::Tenanted
 
-TODO: Delete this and the text below, and describe your gem
+Enable a Rails application to host multiple isolated tenants.
 
-Welcome to your new gem! In this directory, you'll find the files you need to be able to package up your Ruby library into a gem. Put your Ruby code in the file `lib/activerecord/tenanted`. To experiment with that code, run `bin/console` for an interactive prompt.
+> [!NOTE]
+> Only the sqlite3 database adapter is fully supported right now. If you have a use case for tenanting one of the other databases supported by Rails, please reach out to the maintainers!
 
-## Installation
+## Summary
 
-TODO: Replace `UPDATE_WITH_YOUR_GEM_NAME_IMMEDIATELY_AFTER_RELEASE_TO_RUBYGEMS_ORG` with your gem name right after releasing it to RubyGems.org. Please do not do it earlier due to security reasons. Alternatively, replace this section with instructions to install your gem from git if you don't plan to release to RubyGems.org.
+### What is "multi-tenancy"?
 
-Install the gem and add to the application's Gemfile by executing:
+A "multi-tenant application" can be informally defined as:
 
-```bash
-bundle add UPDATE_WITH_YOUR_GEM_NAME_IMMEDIATELY_AFTER_RELEASE_TO_RUBYGEMS_ORG
-```
+> ... a single instance of a software application (and its underlying database and hardware)
+> serv[ing] multiple tenants (or user accounts).
+>
+> A tenant can be an individual user, but more frequently, it’s a group of users — such as a
+> customer organization — that shares common access to and privileges within the application
+> instance. Each tenant’s data is isolated from, and invisible to, the other tenants sharing the
+> application instance, ensuring data security and privacy for all tenants.
+>
+> -- [IBM.com, "What is multi-tenant?"](https://www.ibm.com/think/topics/multi-tenant)
+
+This gem's design is rooted in a few guiding principles in order to safely allow multiple tenants to share a Rails application instance:
+
+- Data "at rest" is persisted in a separate store for each tenant's data, isolated either physically or logically from other tenants.
+- Data "in transit" is only sent to users with authenticated access to the tenant instance.
+- All tenant-related code execution must happen within a well-defined isolated tenant context with controls around data access and transmission.
+
+
+### Making it dead simple.
+
+Another guiding principle, though, is:
+
+- Developing a multi-tenant Rails app should be as easy as developing a single-tenant app.
+
+Your code shouldn't have to know about tenanting! The hope is that you will rarely need to think about managing tenant isolation, and that as long as you're following Rails conventions, this gem and the framework will keep your tenants' data safe.
 
-If bundler is not being used to manage dependencies, install the gem by executing:
+This gem extends or integrates tightly with Rails to ensure that any data persisted or transmitted happens within an isolated tenant context — without developers having to think about it.
+
+
+## Installation
+
+Install the gem and add to the application's Gemfile by executing:
 
 ```bash
-gem install UPDATE_WITH_YOUR_GEM_NAME_IMMEDIATELY_AFTER_RELEASE_TO_RUBYGEMS_ORG
+bundle add activerecord-tenanted
 ```
 
+
 ## Usage
 
-TODO: Write usage instructions here
+For detailed configuration and usage, see [GUIDE.md](./GUIDE.md).
 
-## Development
 
-After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+## Contributing
 
-To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+Bug reports and pull requests are welcome on GitHub at https://github.com/basecamp/activerecord-tenanted. The tests are split between:
 
-## Contributing
+- fast unit tests run by `bin/test-unit`
+- slower integration tests run by `bin/test-integration`
+
+For a full test feedback loop, run `bin/ci`.
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/flavorjones/activerecord-tenanted. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/flavorjones/activerecord-tenanted/blob/main/CODE_OF_CONDUCT.md).
 
 ## License
 
 The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
-
-## Code of Conduct
-
-Everyone interacting in the Activerecord::Tenanted project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/flavorjones/activerecord-tenanted/blob/main/CODE_OF_CONDUCT.md).

data/Rakefile

@@ -1,10 +1,9 @@
 # frozen_string_literal: true
 
-require "bundler/gem_tasks"
-require "minitest/test_task"
-
-Minitest::TestTask.create
+require "bundler/setup"
 
-require "standard/rake"
+require "bundler/gem_tasks"
 
-task default: %i[test standard]
+task :clean do
+  FileUtils.rm_f(Dir.glob("test/dummy/log/*.log"), verbose: true)
+end

data/lib/active_record/tenanted/base.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+module ActiveRecord
+  module Tenanted
+    module Base
+      extend ActiveSupport::Concern
+
+      class_methods do
+        def initialize(...)
+          super
+
+          @tenanted_config_name = nil
+          @tenanted_subtenant_of = nil
+        end
+
+        def tenanted(config_name = "primary")
+          raise Error, "Class #{self} is already tenanted" if tenanted?
+          raise Error, "Class #{self} is not an abstract connection class" unless abstract_class?
+
+          prepend Tenant
+
+          self.connection_class = true
+          @tenanted_config_name = config_name
+
+          unless tenanted_root_config.configuration_hash[:tenanted]
+            raise Error, "The '#{tenanted_config_name}' database is not configured as tenanted."
+          end
+        end
+
+        def subtenant_of(class_name)
+          prepend Subtenant
+
+          @tenanted_subtenant_of = class_name
+        end
+
+        def tenanted?
+          false
+        end
+
+        def table_exists?
+          super
+        rescue ActiveRecord::Tenanted::NoTenantError
+          # If this exception was raised, then Rails is trying to determine if a non-tenanted
+          # table exists by accessing the tenanted primary database config, probably during eager
+          # loading.
+          #
+          # This happens for Record classes that late-bind to their database, like
+          # SolidCable::Record, SolidQueue::Record, and SolidCache::Record (all of which inherit
+          # directly from ActiveRecord::Base but call `connects_to` to set their database later,
+          # during initialization).
+          #
+          # In non-tenanted apps, this method just returns false during eager loading. So let's
+          # follow suit. Rails will figure it out later.
+          false
+        end
+      end
+
+      def tenanted?
+        false
+      end
+    end
+  end
+end

data/lib/active_record/tenanted/cable_connection.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module ActiveRecord
+  module Tenanted
+    module CableConnection # :nodoc:
+      # this module is included into ActionCable::Connection::Base
+      module Base
+        extend ActiveSupport::Concern
+
+        prepended do
+          identified_by :current_tenant
+          around_command :with_tenant
+        end
+
+        def connect
+          # If Rails had a before_connect hook, this could be moved there.
+          set_current_tenant if connection_class && tenant_resolver
+        end
+
+        private
+          def set_current_tenant
+            return unless tenant = tenant_resolver.call(request)
+
+            if connection_class.tenant_exist?(tenant)
+              self.current_tenant = tenant
+            else
+              reject_unauthorized_connection
+            end
+          end
+
+          def with_tenant(&block)
+            if current_tenant.present?
+              connection_class.with_tenant(current_tenant, &block)
+            else
+              yield
+            end
+          end
+
+          def tenant_resolver
+            @tenant_resolver ||= Rails.application.config.active_record_tenanted.tenant_resolver
+          end
+
+          def connection_class
+            # TODO: cache this / speed this up
+            Rails.application.config.active_record_tenanted.connection_class&.constantize
+          end
+      end
+    end
+  end
+end

data/lib/active_record/tenanted/connection_adapter.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module ActiveRecord
+  module Tenanted
+    module ConnectionAdapter # :nodoc:
+      extend ActiveSupport::Concern
+
+      prepended do
+        attr_accessor :tenant
+      end
+
+      def log(sql, name = "SQL", binds = [], type_casted_binds = [], async: false, allow_retry: false, &block)
+        name = [ name, "[tenant=#{tenant}]" ].compact.join(" ") if tenanted?
+        super
+      end
+
+      def tenanted?
+        tenant.present?
+      end
+    end
+  end
+end

data/lib/active_record/tenanted/console.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module ActiveRecord
+  module Tenanted
+    module Console # :nodoc:
+      module IRBConsole
+        def start
+          ActiveRecord::Tenanted::DatabaseTasks.set_current_tenant if Rails.env.local?
+          super
+        end
+      end
+
+      module ReloadHelper
+        def execute
+          tenant = if Rails.env.local? && (connection_class = ActiveRecord::Tenanted.connection_class)
+            connection_class.current_tenant
+          end
+
+          super
+        ensure
+          # We need to reload the connection class to ensure that we get the new (reloaded) class.
+          if tenant && (connection_class = ActiveRecord::Tenanted.connection_class)
+            connection_class.current_tenant = tenant
+          end
+        end
+      end
+    end
+  end
+end

data/lib/active_record/tenanted/database_configurations.rb

@@ -0,0 +1,166 @@
+# frozen_string_literal: true
+
+require "active_record/database_configurations"
+
+module ActiveRecord
+  module Tenanted
+    module DatabaseConfigurations
+      class RootConfig < ActiveRecord::DatabaseConfigurations::HashConfig
+        attr_accessor :test_worker_id
+
+        def initialize(...)
+          super
+          @test_worker_id = nil
+        end
+
+        def database_tasks?
+          false
+        end
+
+        def database_for(tenant_name)
+          tenant_name = tenant_name.to_s
+
+          validate_tenant_name(tenant_name)
+
+          path = sprintf(database, tenant: tenant_name)
+
+          if test_worker_id
+            test_worker_path(path)
+          else
+            path
+          end
+        end
+
+        def database_path_for(tenant_name)
+          coerce_path(database_for(tenant_name))
+        end
+
+        def tenants
+          glob = database_path_for("*")
+          scanner = Regexp.new(database_path_for("(.+)"))
+
+          Dir.glob(glob).map do |path|
+            result = path.scan(scanner).flatten.first
+            if result.nil?
+              warn "WARN: ActiveRecord::Tenanted: Cannot parse tenant name from filename #{path.inspect}. " \
+                   "This is a bug, please report it to https://github.com/basecamp/activerecord-tenanted/issues"
+            end
+            result
+          end
+        end
+
+        def new_tenant_config(tenant_name)
+          config_name = "#{name}_#{tenant_name}"
+          config_hash = configuration_hash.dup.tap do |hash|
+            hash[:tenant] = tenant_name
+            hash[:database] = database_for(tenant_name)
+            hash[:database_path] = database_path_for(tenant_name)
+            hash[:tenanted_config_name] = name
+          end
+          Tenanted::DatabaseConfigurations::TenantConfig.new(env_name, config_name, config_hash)
+        end
+
+        def new_connection
+          raise NoTenantError, "Cannot use an untenanted ActiveRecord::Base connection. " \
+                               "If you have a model that inherits directly from ActiveRecord::Base, " \
+                               "make sure to use 'subtenant_of'. In development, you may see this error " \
+                               "if constant reloading is not being done properly."
+        end
+
+        private
+          # A sqlite database path can be a file path or a URI (either relative or absolute).
+          # We can't parse it as a standard URI in all circumstances, though, see https://sqlite.org/uri.html
+          def coerce_path(path)
+            if path.start_with?("file:/")
+              URI.parse(path).path
+            elsif path.start_with?("file:")
+              URI.parse(path.sub(/\?.*$/, "")).opaque
+            else
+              path
+            end
+          end
+
+          def validate_tenant_name(tenant_name)
+            if tenant_name.match?(%r{[/'"`]})
+              raise BadTenantNameError, "Tenant name contains an invalid character: #{tenant_name.inspect}"
+            end
+          end
+
+          def test_worker_path(path)
+            test_worker_suffix = "_#{test_worker_id}"
+
+            if path.start_with?("file:") && path.include?("?")
+              path.sub(/(\?.*)$/, "#{test_worker_suffix}\\1")
+            else
+              path + test_worker_suffix
+            end
+          end
+      end
+
+      class TenantConfig < ActiveRecord::DatabaseConfigurations::HashConfig
+        def tenant
+          configuration_hash.fetch(:tenant)
+        end
+
+        def new_connection
+          ensure_database_directory_exists # adapter doesn't handle this if the database is a URI
+          super.tap { |conn| conn.tenant = tenant }
+        end
+
+        def tenanted_config_name
+          configuration_hash.fetch(:tenanted_config_name)
+        end
+
+        def primary?
+          ActiveRecord::Base.configurations.primary?(tenanted_config_name)
+        end
+
+        def schema_dump(format = ActiveRecord.schema_format)
+          if configuration_hash.key?(:schema_dump) || primary?
+            super
+          else
+            "#{tenanted_config_name}_#{schema_file_type(format)}"
+          end
+        end
+
+        def default_schema_cache_path(db_dir = "db")
+          if primary?
+            super
+          else
+            File.join(db_dir, "#{tenanted_config_name}_schema_cache.yml")
+          end
+        end
+
+        def database_path
+          configuration_hash[:database_path]
+        end
+
+        private
+          def ensure_database_directory_exists
+            return unless database_path
+
+            database_dir = File.dirname(database_path)
+            unless File.directory?(database_dir)
+              FileUtils.mkdir_p(database_dir)
+            end
+          end
+      end
+
+      # Invoked by the railtie
+      def self.register_db_config_handler # :nodoc:
+        ActiveRecord::DatabaseConfigurations.register_db_config_handler do |env_name, name, _, config|
+          next unless config.fetch(:tenanted, false)
+
+          ActiveRecord::Tenanted::DatabaseConfigurations::RootConfig.new(env_name, name, config)
+        end
+      end
+    end
+  end
+end
+
+# Do this here instead of the railtie so we register the handlers before Rails's rake tasks get
+# loaded. If the handler is not present, then the RootConfigs will not return false from
+# `#database_tasks?` and the database tasks will get created anyway.
+#
+# TODO: This can be moved back into the railtie if https://github.com/rails/rails/pull/54959 is merged.
+ActiveRecord::Tenanted::DatabaseConfigurations.register_db_config_handler

data/lib/active_record/tenanted/database_tasks.rb

@@ -0,0 +1,118 @@
+# frozen_string_literal: true
+
+module ActiveRecord
+  module Tenanted
+    module DatabaseTasks # :nodoc:
+      extend self
+
+      def migrate_all
+        raise ArgumentError, "Could not find a tenanted database" unless root_config = root_database_config
+
+        tenants = root_config.tenants.presence || [ get_current_tenant ].compact
+        tenants.each do |tenant|
+          tenant_config = root_config.new_tenant_config(tenant)
+          migrate(tenant_config)
+        end
+      end
+
+      def migrate_tenant(tenant_name = set_current_tenant)
+        raise ArgumentError, "Could not find a tenanted database" unless root_config = root_database_config
+
+        tenant_config = root_config.new_tenant_config(tenant_name)
+
+        migrate(tenant_config)
+      end
+
+      def drop_all
+        raise ArgumentError, "Could not find a tenanted database" unless root_config = root_database_config
+
+        root_config.tenants.each do |tenant|
+          # NOTE: This is obviously a sqlite-specific implementation.
+          # TODO: Create a `drop_database` method upstream in the sqlite3 adapter, and call it.
+          #       Then this would delegate to the adapter and become adapter-agnostic.
+          root_config.database_path_for(tenant).tap do |path|
+            FileUtils.rm(path)
+            $stdout.puts "Dropped database '#{path}'" if verbose?
+          end
+        end
+      end
+
+      def root_database_config
+        db_configs = ActiveRecord::Base.configurations.configs_for(
+          env_name: ActiveRecord::Tasks::DatabaseTasks.env,
+          include_hidden: true
+        )
+        db_configs.detect { |c| c.configuration_hash[:tenanted] }
+      end
+
+      def get_current_tenant
+        tenant = ENV["ARTENANT"]
+
+        if tenant.present?
+          $stdout.puts "Setting current tenant to #{tenant.inspect}" if verbose?
+        elsif Rails.env.local?
+          tenant = Rails.application.config.active_record_tenanted.default_tenant
+          $stdout.puts "Defaulting current tenant to #{tenant.inspect}" if verbose?
+        else
+          tenant = nil
+          $stdout.puts "Cannot determine an implicit tenant: ARTENANT not set, and Rails.env is not local." if verbose?
+        end
+
+        tenant
+      end
+
+      def set_current_tenant
+        unless (connection_class = ActiveRecord::Tenanted.connection_class)
+          raise ActiveRecord::Tenanted::IntegrationNotConfiguredError,
+                "ActiveRecord::Tenanted integration is not configured via connection_class"
+        end
+
+        if connection_class.current_tenant.nil?
+          connection_class.current_tenant = get_current_tenant
+        else
+          connection_class.current_tenant
+        end
+      end
+
+      # This is essentially a simplified implementation of ActiveRecord::Tasks::DatabaseTasks.migrate
+      def migrate(config)
+        ActiveRecord::Tasks::DatabaseTasks.with_temporary_connection(config) do |conn|
+          pool = conn.pool
+
+          # initialize_database
+          unless pool.schema_migration.table_exists?
+            schema_dump_path = ActiveRecord::Tasks::DatabaseTasks.schema_dump_path(config)
+            if schema_dump_path && File.exist?(schema_dump_path)
+              ActiveRecord::Tasks::DatabaseTasks.load_schema(config)
+            end
+            # TODO: emit a "Created database" message once we sort out implicit creation
+          end
+
+          # migrate
+          migrated = false
+          if pool.migration_context.pending_migration_versions.present?
+            pool.migration_context.migrate(nil)
+            pool.schema_cache.clear!
+            migrated = true
+          end
+
+          # dump the schema and schema cache
+          if Rails.env.development? || ENV["ARTENANT_SCHEMA_DUMP"].present?
+            if migrated
+              ActiveRecord::Tasks::DatabaseTasks.dump_schema(config)
+            end
+
+            cache_dump = ActiveRecord::Tasks::DatabaseTasks.cache_dump_filename(config)
+            if migrated || !File.exist?(cache_dump)
+              ActiveRecord::Tasks::DatabaseTasks.dump_schema_cache(pool, cache_dump)
+            end
+          end
+        end
+      end
+
+      def verbose?
+        ActiveRecord::Tasks::DatabaseTasks.send(:verbose?)
+      end
+    end
+  end
+end

data/lib/active_record/tenanted/global_id.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+require "globalid"
+
+module ActiveRecord
+  module Tenanted
+    module GlobalId
+      def tenant
+        params && params[:tenant]
+      end
+
+      class Locator
+        def locate(gid, options = {})
+          ensure_tenant_context_safety(gid)
+          gid.model_class.find(gid.model_id)
+        end
+
+        private
+          def ensure_tenant_context_safety(gid)
+            model_class = gid.model_class
+            return unless model_class.tenanted?
+
+            gid_tenant = gid.tenant
+            raise MissingTenantError, "Tenant not present in #{gid.to_s.inspect}" unless gid_tenant
+
+            current_tenant = model_class.current_tenant.presence
+            raise NoTenantError, "Cannot connect to a tenanted database while untenanted (#{gid})" unless current_tenant
+
+            if gid_tenant != current_tenant
+              raise WrongTenantError, "GlobalID #{gid.to_s.inspect} does not belong the current tenant #{current_tenant.inspect}"
+            end
+          end
+      end
+    end
+  end
+end

data/lib/active_record/tenanted/job.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module ActiveRecord
+  module Tenanted
+    module Job # :nodoc:
+      extend ActiveSupport::Concern
+
+      prepended do
+        attr_reader :tenant
+      end
+
+      def initialize(...)
+        super
+        if klass = ActiveRecord::Tenanted.connection_class
+          @tenant = klass.current_tenant
+        end
+      end
+
+      def serialize
+        super.merge!({ "tenant" => tenant })
+      end
+
+      def deserialize(job_data)
+        super
+        @tenant = job_data.fetch("tenant", nil)
+      end
+
+      def perform_now
+        if tenant.present? && (klass = ActiveRecord::Tenanted.connection_class)
+          klass.with_tenant(tenant) { super }
+        else
+          super
+        end
+      end
+    end
+  end
+end