tenant_realm 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: ec5080c5a6b4e997fd094811df564e8cb6c7520030a1fb0617917a155dd05223
+  data.tar.gz: 159100e048f540997d9e9ffa33ba215c035357573bb297a65afa52bd6547d593
+SHA512:
+  metadata.gz: 789611a5e9bc41b794a65e39d4d4cb48a69ad6d37a6d1bde72cb10e6f2bf499278f6715c5f50a7ba26023360408919bf921e33e72b9b994263747582eb0e8dc8
+  data.tar.gz: a7dc2cddb27f123a9772bd53d4e4b1f3d39f9f5cad245f83de9329aa9c3bd6acebde917cb42ce84927b12b896396f8837fe715f5f22ede2cbcec365cb2d72bfc

data/.ruby-version

@@ -0,0 +1 @@
+3.2.2

data/README.md

@@ -0,0 +1,121 @@
+Tenant Realm is a lightweight gem provides some helpers to support working on multi-tenant easily using [Multiple Database with Active Record](https://guides.rubyonrails.org/active_record_multiple_databases.html).
+
+# Installation
+
+```sh
+gem 'tenant_realm'
+```
+
+# CLI
+
+- init `tenant_realm`
+
+```sh
+rails g tenant_realm
+```
+
+- run migration for all tenants
+
+```sh
+rake tenant_realm:migrate
+```
+
+# Configuration
+
+```rb
+# frozen_string_literal: true
+
+Rails.application.config.to_prepare do
+  TenantRealm.configure do |config|
+    # required
+    # identifier is extracted from `identifier_resolver`
+    config.fetch_tenant = lambda { |identifier|
+      # get tenant using identifier
+    }
+
+    # required
+    config.fetch_tenants = lambda {
+      # get tenant list
+    }
+
+    # optional
+    # default is getting from key :db_config from tenant
+    config.dig_db_config = lambda { |tenant|
+      tenant[:db_config]
+    }
+
+    # optional
+    # set this when you wanna skip the switch database
+    config.skip_resolver = lambda { |request|
+      request.env['REQUEST_PATH'].match?(/health|favicon.ico/)
+    }
+
+    # required
+    # method to extract the identifier of tenant
+    config.identifier_resolver = lambda { |request|
+      # get identifier from request
+      # tenant is retrieved using its domain
+      domain = request.referer || request.origin
+      domain ? URI(domain).host : nil
+    }
+
+    # optional
+    # extract the sharding name for multi_db
+    # default will be this proc return value -> tenant's shard_name -> slug -> id
+    config.shard_name_from_tenant = lambda { |tenant|
+      tenant[:slug]
+    }
+
+    # optional
+    # default will be TenantRealm::CurrentTenant
+    config.current_tenant = MyCurrentTenant
+
+    # optional
+    config.cache do |cache_config|
+      # using cache service
+      cache_config.service = :redis
+
+      # when will the tenant list and tenant are expired
+      cache_config.expires_in = 6.days
+
+      # list keys to cache the tenant
+      cache_config.tenant_uniq_cols = %i[slug domain]
+
+      # in case the column is not simple like above
+      # this option will override the one above
+      cache_config.tenant_keys_resolver = lambda { |tenant|
+        [
+          tenant[:slug],
+          tenant[:settings][:domain]
+        ]
+      }
+    end
+  end
+end
+```
+
+# Customize
+
+- Custom current tenant
+
+```rb
+# frozen_string_literal: true
+
+class CurrentTenant < TenantRealm::CurrentTenant
+  attribute :additional_info
+
+  def tenant=(tenant)
+    super
+
+    self.additional_info = {
+      domain: tenant[:settings][:domain]
+    }
+  end
+end
+```
+
+# TODO
+
+- [ ] support Row-Level Security (RLS)
+
+- [ ] support multi-schema

data/Rakefile

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require 'bundler/gem_tasks'
+require 'rubocop/rake_task'
+
+RuboCop::RakeTask.new
+
+task default: :rubocop

data/lib/generators/templates/tenant_realm.tt

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+Rails.application.config.to_prepare do
+  TenantRealm.configure do |config|
+    config.fetch_tenant = lambda { |identifier|
+      # get tenant using identifier
+    }
+
+    config.fetch_tenants = lambda {
+      # get tenant list
+    }
+
+    config.dig_db_config = lambda { |tenant|
+      tenant[:db_config]
+    }
+
+    config.skip_resolver = lambda { |request|
+      request.env['REQUEST_PATH'].match?(/health|favicon.ico/)
+    }
+
+    config.identifier_resolver = lambda { |request|
+      # get identifier from request
+      # domain = request.referer || request.origin
+      # domain ? URI(domain).host : nil
+    }
+
+    config.shard_name_from_tenant = lambda { |tenant|
+      tenant[:slug]
+    }
+  end
+end

data/lib/generators/tenant_realm_generator.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+class TenantRealmGenerator < Rails::Generators::Base
+  source_root File.expand_path('templates', __dir__)
+
+  def generate_tenant_realm
+    template(
+      'tenant_realm.tt',
+      'config/initializers/tenant_realm.rb'
+    )
+  end
+end

data/lib/tasks/migrate.rake

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+namespace :tenant_realm do
+  desc 'Migrate db for all tenants'
+  task migrate: :environment do
+    tenants = TenantRealm::Tenant.tenants
+
+    tenants.each do |tenant|
+      shard = TenantRealm::Utils.shard_name_from_tenant(tenant:)
+
+      puts "Migrating #{shard}"
+
+      db_config = TenantRealm::Utils.dig_db_config(tenant:)
+
+      if db_config.blank?
+        puts "Skip Migrating #{shard}"
+
+        next
+      end
+
+      db_config = TenantRealm::DbContext.root_db_config.merge(
+        database: db_config[:database]
+      )
+
+      ActiveRecord::Tasks::DatabaseTasks.with_temporary_connection(db_config) do
+        ActiveRecord::Tasks::DatabaseTasks.migrate
+      end
+    end
+  end
+end

data/lib/tenant_realm/cache/base_cache.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module TenantRealm
+  module Cache
+    class BaseCache
+      class << self
+        def cache_tenants(_tenants)
+          raise NotImplementedError
+        end
+
+        def tenants
+          raise NotImplementedError
+        end
+
+        def cache_tenant(_tenant)
+          raise NotImplementedError
+        end
+
+        def tenant(_identifier)
+          raise NotImplementedError
+        end
+
+        private
+
+        def tenant_unique_keys(tenant)
+          config = Configuration::Cache
+
+          if config.tenant_keys_resolver.present?
+            Helpers.raise_if_not_proc(config.tenant_keys_resolver, 'cache_config.tenant_keys_resolver')
+            Helpers.wrap_array(config.tenant_keys_resolver.call(tenant))
+          elsif config.tenant_uniq_cols.present?
+            cols = Helpers.wrap_array(config.tenant_uniq_cols)
+
+            cols.map do |col|
+              tenant[col]
+            end
+          else
+            [
+              tenant[:slug]
+            ]
+          end
+        end
+
+        def tenants_key
+          'tenant_realm:tenants'
+        end
+
+        def tenant_key
+          'tenant_realm:tenant'
+        end
+      end
+    end
+  end
+end

data/lib/tenant_realm/cache/kredis_cache.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+require 'redis'
+require 'kredis'
+
+require_relative 'base_cache'
+
+module TenantRealm
+  module Cache
+    class KredisCache < BaseCache
+      class << self
+        def cache_tenants(tenants)
+          return if tenants.blank?
+
+          cached_tenants = tenants_kredis
+          cached_tenants.value = tenants
+          tenants
+        end
+
+        def tenants
+          cached_tenants = tenants_kredis
+          cached_tenants.value&.map(&:deep_symbolize_keys) || []
+        end
+
+        def cache_tenant(tenant)
+          tenant_unique_keys(tenant).each do |key|
+            cached_tenant = tenant_kredis(key)
+            cached_tenant.value = tenant
+          end
+
+          tenant
+        end
+
+        def tenant(identifier)
+          cached_tenant = tenant_kredis(identifier)
+          cached_tenant.value&.deep_symbolize_keys
+        end
+
+        private
+
+        def tenants_kredis
+          Kredis.json(tenants_key, expires_in: Configuration::Cache.expires_in)
+        end
+
+        def tenant_kredis(identifier)
+          Kredis.json("#{tenant_key}:#{identifier}", expires_in: Configuration::Cache.expires_in)
+        end
+      end
+    end
+  end
+end

data/lib/tenant_realm/class_methods.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module TenantRealm
+  class << self
+    def configure
+      yield Config
+    end
+
+    def configuration
+      Config
+    end
+  end
+end

data/lib/tenant_realm/config.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module TenantRealm
+  class Config
+    class << self
+      attr_accessor(
+        :fetch_tenant,
+        :fetch_tenants,
+        :dig_db_config,
+        :skip_resolver,
+        :current_tenant,
+        :identifier_resolver,
+        :shard_name_from_tenant
+      )
+
+      def cache
+        yield Configuration::Cache
+      end
+
+      def current
+        @current ||= current_tenant || CurrentTenant
+      end
+    end
+  end
+end

data/lib/tenant_realm/configuration/cache.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module TenantRealm
+  module Configuration
+    class Cache
+      class << self
+        attr_accessor :service,
+                      :expires_in,
+                      :tenant_uniq_cols,
+                      :tenant_keys_resolver
+      end
+    end
+  end
+end

data/lib/tenant_realm/db_context.rb

@@ -0,0 +1,127 @@
+# frozen_string_literal: true
+
+require_relative 'utils'
+require_relative 'tenant'
+
+module TenantRealm
+  class DbContext
+    # to cache all tenant's connections
+    @@shards = {}
+
+    # to cache all tenant's connections already connected
+    @@connected_shards = nil
+
+    class << self
+      def root_db_config
+        @@db_config ||= ActiveRecord::Base.connection_db_config.configuration_hash.deep_dup.freeze
+      end
+
+      def init_shards
+        config = Utils.load_database_yml
+        tenants = Tenant.tenants
+
+        @@shards = config[Rails.env].keys.each_with_object({}) do |shard, shards|
+          shards[shard] = shard
+        end
+
+        tenants.each do |tenant|
+          db_config = Utils.dig_db_config(tenant:)
+          shard = Utils.shard_name_from_tenant(tenant:)
+          next if db_config.blank?
+
+          add_shard(shard:, db_config:)
+        end
+
+        ActiveRecord::Base.connects_to(shards: connected_shards)
+      end
+
+      def connected_shards
+        @@connected_shards ||= build_connected_shards
+      end
+
+      def add_shard(shard:, db_config:)
+        return if shard_exist?(shard:) || db_config.blank?
+
+        shard_name = shard.underscore
+        config = Utils.load_database_yml
+        tenant_shard_config = root_db_config.merge(database: db_config[:database])
+        config[Rails.env][shard_name] = JSON.parse(tenant_shard_config.to_json)
+        @@shards[shard_name] = shard_name
+
+        # sometimes the dynamic tenant's db_config causes connection pool checkout
+        # write tenants' db_config to database.yml
+        # to fix this problem when restart server
+        File.open('config/database.yml', 'w') do |f|
+          YAML.dump(config, f)
+        end
+
+        ActiveRecord::Base.configurations.configurations << ActiveRecord::DatabaseConfigurations::HashConfig.new(
+          Rails.env,
+          shard_name,
+          tenant_shard_config
+        )
+
+        sym_shard = shard_name.to_sym
+
+        connected_shards[sym_shard] = {
+          writing: sym_shard,
+          reading: sym_shard
+        }
+      end
+
+      def shard_exist?(shard:)
+        @@shards.key?(shard.underscore)
+      end
+
+      def switch_database(shard:, db_config: nil, &block)
+        add_shard(shard:, db_config:)
+
+        ActiveRecord::Base.connected_to(shard: shard.underscore.to_sym, &block)
+      end
+
+      def flush_connection!
+        ActiveRecord::Base.connection_handler.clear_active_connections!(:all)
+        ActiveRecord::Base.connection_handler.flush_idle_connections!(:all)
+      end
+
+      def run_migrate(db_config:)
+        ActiveRecord::Tasks::DatabaseTasks.with_temporary_connection(
+          root_db_config.merge(database: db_config[:database])
+        ) do
+          ActiveRecord::Tasks::DatabaseTasks.migrate
+        end
+
+        false
+      rescue StandardError
+        flush_connection!
+
+        true
+      end
+
+      def create_db(shard:, affix: nil)
+        database = [shard, affix].compact.join('-').underscore
+        db_config = root_db_config.merge(database:).tap do |config|
+          config[:host] ||= 'localhost'
+          config[:port] ||= 3306
+        end
+
+        ActiveRecord::Base.connection.create_database(database)
+
+        db_config
+      end
+
+      private
+
+      def build_connected_shards
+        @@shards.keys.each_with_object({}) do |shard, shards|
+          sym_shard = shard.to_sym
+
+          shards[sym_shard] = {
+            writing: sym_shard,
+            reading: sym_shard
+          }
+        end
+      end
+    end
+  end
+end

data/lib/tenant_realm/helpers.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module TenantRealm
+  class Helpers
+    class << self
+      def wrap_array(data)
+        return [] if data.blank?
+
+        data.is_a?(Array) ? data : [data]
+      end
+
+      def dev_log(message)
+        p message if Rails.env.development?
+      end
+
+      def raise_if_not_proc(source, name)
+        raise Error, "#{name} must be a Proc" unless source.is_a?(Proc)
+      end
+    end
+  end
+end

data/lib/tenant_realm/railtie.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module TenantRealm
+  class Railtie < Rails::Railtie
+    rake_tasks do
+      Dir[File.expand_path('../tasks/*.rake', __dir__)].each do |file|
+        load(file)
+      end
+    end
+  end
+end

data/lib/tenant_realm/tenant.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+require_relative 'cache/kredis_cache'
+
+module TenantRealm
+  class Tenant
+    @@cache = {
+      redis: Cache::KredisCache,
+      kredis: Cache::KredisCache
+    }
+
+    class << self
+      def tenants
+        if cache.present?
+          tenants = cache.tenants
+          return tenants if tenants.present?
+
+          tenants = Utils.fetch_tenants
+          cache.cache_tenants(tenants)
+          tenants
+        else
+          Utils.fetch_tenants
+        end
+      end
+
+      def tenant(identifier)
+        if cache.present?
+          tenant = cache.tenant(identifier)
+          return tenant if tenant.present?
+
+          tenant = Utils.fetch_tenant(identifier)
+          cache.cache_tenant(tenant)
+          tenant
+        else
+          Utils.fetch_tenant
+        end
+      end
+
+      def cache_tenants(tenants)
+        return Helpers.dev_log('Tenant Realm: Skip cache tenants because cache not configured') if cache.blank?
+
+        cache.cache_tenants(tenants)
+      end
+
+      def cache_tenant(tenant)
+        return Helpers.dev_log('Tenant Realm: Skip cache tenant because cache not configured') if cache.blank?
+
+        cache.cache_tenant(tenant)
+      end
+
+      private
+
+      def cache
+        @cache ||= @@cache[Configuration::Cache.service]
+      end
+    end
+  end
+end

data/lib/tenant_realm/utils.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module TenantRealm
+  class Utils
+    class << self
+      def load_database_yml
+        YAML.load_file('config/database.yml', aliases: true)
+      end
+
+      def fetch_tenants
+        Helpers.raise_if_not_proc(Config.fetch_tenants, 'config.fetch_tenants')
+
+        (Config.fetch_tenants.call.presence || []).map(&:deep_symbolize_keys)
+      end
+
+      def fetch_tenant(identifier)
+        Helpers.raise_if_not_proc(Config.fetch_tenant, 'config.fetch_tenant')
+
+        Config.fetch_tenant.call(identifier)&.deep_symbolize_keys
+      end
+
+      def dig_db_config(tenant:)
+        if Config.dig_db_config.is_a?(Proc)
+          Config.dig_db_config.call(tenant)
+        else
+          key = Config.dig_db_config || :db_config
+
+          tenant[key.to_sym]
+        end
+      end
+
+      def shard_name_from_tenant(tenant:)
+        shard = if Config.shard_name_from_tenant.is_a?(Proc)
+                  Config.shard_name_from_tenant.call(tenant)
+                else
+                  key = Config.shard_name_from_tenant || :shard_name
+
+                  tenant[key.to_sym] || tenant[:slug] || tenant[:id]
+                end
+
+        shard.underscore
+      end
+
+      def identifier_resolver(request)
+        raise Error, 'config.identifier_resolver must be provided' if Config.identifier_resolver.blank?
+
+        Helpers.raise_if_not_proc(Config.identifier_resolver, 'config.identifier_resolver')
+
+        Config.identifier_resolver.call(request)
+      end
+    end
+  end
+end

data/lib/tenant_realm/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module TenantRealm
+  VERSION = '1.0.0'
+end

data/lib/tenant_realm.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+require_relative 'tenant_realm/config'
+require_relative 'tenant_realm/version'
+require_relative 'tenant_realm/helpers'
+require_relative 'tenant_realm/db_context'
+require_relative 'tenant_realm/class_methods'
+require_relative 'tenant_realm/configuration/cache'
+
+module TenantRealm
+  require 'tenant_realm/railtie' if defined?(Rails)
+
+  class Error < StandardError; end
+
+  class CurrentTenant < ActiveSupport::CurrentAttributes
+    attribute :tenant
+  end
+
+  class Railtie < Rails::Railtie
+    config.before_configuration do
+      Helpers.dev_log('Tenant Realm: Init shard resolver')
+
+      config.active_record.shard_selector = { lock: false }
+      config.active_record.shard_resolver = lambda { |request|
+        skip_switch_db = if Config.skip_resolver.is_a?(Proc)
+                           Config.skip_resolver.call(request)
+                         else
+                           false
+                         end
+
+        return :primary if skip_switch_db
+
+        identifier = Utils.identifier_resolver(request)
+        tenant = Tenant.tenant(identifier)
+        db_config = Utils.dig_db_config(tenant:)
+        shard = Utils.shard_name_from_tenant(tenant:)
+
+        return :primary if db_config.blank?
+
+        Config.current.tenant = tenant
+        DbContext.add_shard(shard:, db_config:)
+        ActiveRecord::Base.connects_to(shards: DbContext.connected_shards)
+
+        shard
+      }
+    end
+
+    initializer 'active_record.setup_tenant_realm' do
+      Helpers.dev_log('Tenant Realm: Init database shards')
+
+      ActiveSupport.on_load(:active_record) do
+        ActiveRecord::Base.default_shard = :primary
+        ActiveRecord::Base.connects_to(
+          shards: {
+            primary: { writing: :primary, reading: :primary }
+          }
+        )
+
+        DbContext.init_shards
+      rescue ActiveRecord::ActiveRecordError
+        nil
+      end
+    end
+  end
+end

data/tenant_realm.gemspec

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+require_relative 'lib/tenant_realm/version'
+
+Gem::Specification.new do |spec|
+  spec.name = 'tenant_realm'
+  spec.version = TenantRealm::VERSION
+  spec.authors = ['Alpha']
+  spec.email = ['alphanolucifer@gmail.com']
+
+  spec.summary = 'Ruby on Rails gem to support multi-tenant'
+  spec.description = 'Ruby on Rails gem to support multi-tenant'
+  spec.homepage = 'https://github.com/zgid123/tenant_realm'
+  spec.license = 'MIT'
+  spec.required_ruby_version = '>= 3.1.0'
+
+  spec.metadata['homepage_uri'] = spec.homepage
+
+  spec.files = Dir.chdir(__dir__) do
+    `git ls-files -z`.split("\x0").reject do |f|
+      (File.expand_path(f) == __FILE__) ||
+        f.start_with?(
+          *%w[
+            bin/
+            test/
+            spec/
+            features/
+            .git
+            .circleci
+            appveyor
+            examples/
+            Gemfile
+            .rubocop.yml
+            .vscode/settings.json
+            LICENSE.txt
+            lefthook.yml
+          ]
+        )
+    end
+  end
+
+  spec.require_paths = ['lib']
+end

metadata

@@ -0,0 +1,63 @@
+--- !ruby/object:Gem::Specification
+name: tenant_realm
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Alpha
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2024-01-27 00:00:00.000000000 Z
+dependencies: []
+description: Ruby on Rails gem to support multi-tenant
+email:
+- alphanolucifer@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".ruby-version"
+- README.md
+- Rakefile
+- lib/generators/templates/tenant_realm.tt
+- lib/generators/tenant_realm_generator.rb
+- lib/tasks/migrate.rake
+- lib/tenant_realm.rb
+- lib/tenant_realm/cache/base_cache.rb
+- lib/tenant_realm/cache/kredis_cache.rb
+- lib/tenant_realm/class_methods.rb
+- lib/tenant_realm/config.rb
+- lib/tenant_realm/configuration/cache.rb
+- lib/tenant_realm/db_context.rb
+- lib/tenant_realm/helpers.rb
+- lib/tenant_realm/railtie.rb
+- lib/tenant_realm/tenant.rb
+- lib/tenant_realm/utils.rb
+- lib/tenant_realm/version.rb
+- tenant_realm.gemspec
+homepage: https://github.com/zgid123/tenant_realm
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/zgid123/tenant_realm
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.1.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.4.13
+signing_key:
+specification_version: 4
+summary: Ruby on Rails gem to support multi-tenant
+test_files: []