acts_as_tenant 0.4.4 → 0.5.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: 9820de48ce59a3e8efae341784175dadf04820cf
-  data.tar.gz: 28cc62d3e62171c690fd9ba48bbd53c29c5efdc7
+SHA256:
+  metadata.gz: 82765cfa1d00a63aa012f3ab5de9ddd60ae2c8041df405e08ae70ef20382d7ee
+  data.tar.gz: ba1920a299f84a4e6424304539c05ca69515e3b17e73ffb1b6635fbce79ae77c
 SHA512:
-  metadata.gz: aa052469cd82efe7062999976d4782f2240718731331698ced6ceb324646aafd431e15ca66a98d55a398192ab410bf0a0620e962e9128a3daf7220dff871c4f3
-  data.tar.gz: 54d961326dedf594be8b87b9603feb063c4ee43a8bb2b8a86a973571b6f01cafd48cc4bd86127ca71771d0e91f275e61549f366c80be425a24df7af1ac1fa3cc
+  metadata.gz: 62854b28ba5293d5437f5614032e992d914bc0741be3e8b925231116802d85b19d9631fc2e0ff2a7775e3259a998e4239f0b38c7ddf97c6817a0db96fbf488c5
+  data.tar.gz: 2e6c875895dd15882ffc4454f0c0bfae4fc3e77df17deae58710835e92bf32761247ab3b60cdfe9a83b81f72e2ea698c59f0155c046dfe2af5c62450a4bd65ca

data/README.md

@@ -1,9 +1,8 @@
-Acts As Tenant
-==============
+# Acts As Tenant
 
-[![Build Status](https://travis-ci.org/ErwinM/acts_as_tenant.svg)](https://travis-ci.org/ErwinM/acts_as_tenant)
+[![Build Status](https://github.com/ErwinM/acts_as_tenant/workflows/Tests/badge.svg)](https://github.com/ErwinM/acts_as_tenant/actions) [![Gem Version](https://badge.fury.io/rb/acts_as_tenant.svg)](https://badge.fury.io/rb/acts_as_tenant)
 
-**Note**: acts_as_tenant was introduced in this [blog post](https://github.com/ErwinM/acts_as_tenant/blob/master/docs/blog_post.md).
+Row-level multitenancy for Ruby on Rails apps.
 
 This gem was born out of our own need for a fail-safe and out-of-the-way manner to add multi-tenancy to our Rails app through a shared database strategy, that integrates (near) seamless with Rails.
 
@@ -16,9 +15,27 @@ In addition, acts_as_tenant:
 * adds a method to validate uniqueness to a tenant, `validates_uniqueness_to_tenant`
 * sets up a helper method containing the current tenant
 
+**Note**: acts_as_tenant was introduced in this [blog post](https://github.com/ErwinM/acts_as_tenant/blob/master/docs/blog_post.md).
+
+**Row-level vs schema multitenancy**
+
+What's the difference?
+
+Row-level multitenancy  each model must have a tenant ID column on it. This makes it easy to filter records for each tenant using your standard database columns and indexes. ActsAsTenant uses row-level multitenancy.
+
+Schema multitenancy uses database schemas to handle multitenancy. For this approach, your database has multiple schemas and each schema contains your database tables. Schemas require migrations to be run against each tenant and generally makes it harder to scale as you add more tenants. The Apartment gem uses schema multitenancy.
+
+#### 🎬 Walkthrough
+
+Want to see how it works? Check out [the ActsAsTenant walkthrough video](https://www.youtube.com/watch?v=BIyxM9f8Jus):
+
+<a href="https://www.youtube.com/watch?v=BIyxM9f8Jus">
+<img src="https://i.imgur.com/DLRPzhv.png" width="300" height="auto" alt="ActsAsTenant Walkthrough Video">
+</a>
+
 Installation
 ------------
-acts_as_tenant will only work on Rails 3.1 and up. This is due to changes made to the handling of `default_scope`, an essential pillar of the gem.
+acts_as_tenant will only work on Rails 5.2 and up. This is due to changes made to the handling of `default_scope`, an essential pillar of the gem.
 
 To use it, add it to your Gemfile:
 
@@ -41,7 +58,8 @@ There are three ways to set the current tenant:
 2. by setting  the current tenant in the controller, and
 3. by setting the current tenant for a block.
 
-### Use the subdomain to lookup the current tenant ###
+### Looking Up Tenants
+#### By Subdomain to lookup the current tenant
 
 ```ruby
 class ApplicationController < ActionController::Base
@@ -49,11 +67,23 @@ class ApplicationController < ActionController::Base
 end
 ```
 
-This tells acts_as_tenant to use the current subdomain to identify the current tenant. In addition, it tells acts_as_tenant that tenants are represented by the Account model and this model has a column named 'subdomain' which can be used to lookup the Account using the actual subdomain. If ommitted, the parameters will default to the values used above.
+This tells acts_as_tenant to use the last subdomain to identify the current tenant. In addition, it tells acts_as_tenant that tenants are represented by the Account model and this model has a column named 'subdomain' which can be used to lookup the Account using the actual subdomain. If ommitted, the parameters will default to the values used above.
+
+By default, the *last* subdomain will be used for lookup. Pass in `subdomain_lookup: :first` to use the first subdomain instead.
+
+#### By Domain to lookup the current tenant
+
+```ruby
+class ApplicationController < ActionController::Base
+  set_current_tenant_by_subdomain_or_domain(:account, :subdomain, :domain)
+end
+```
+
+You can locate the tenant using `set_current_tenant_by_subdomain_or_domain( :account, :subdomain,  :domain )` which will check for a subdomain and fallback to domain.
 
-Alternatively, you could locate the tenant using the method `set_current_tenant_by_subdomain_or_domain( :account, :subdomain,  :domain )` which will try to match a record first by subdomain. in case it fails, by domain.
+By default, the *last* subdomain will be used for lookup. Pass in `subdomain_lookup: :first` to use the first subdomain instead.
 
-### Setting the current tenant in a controller, manually ###
+#### Manually using before_action
 
 ```ruby
 class ApplicationController < ActionController::Base
@@ -69,6 +99,21 @@ end
 
 Setting the `current_tenant` yourself, requires you to declare `set_current_tenant_through_filter` at the top of your application_controller to tell acts_as_tenant that you are going to use a before_action to setup the current tenant. Next you should actually setup that before_action to fetch the current tenant and pass it to `acts_as_tenant` by using `set_current_tenant(current_tenant)` in the before_action.
 
+If you are setting the tenant in a specific controller (except `application_controller`), it should to be included **AT THE TOP** of the file.
+
+```ruby
+class MembersController < ActionController::Base
+  set_current_tenant_through_filter
+  before_action :set_tenant
+  before_action :set_member, only: [:show, :edit, :update, :destroy]
+
+  def set_tenant
+    set_current_tenant(current_user.account)
+  end
+end
+```
+
+This allows the tenant to be set before any other code runs so everything is within the current tenant.
 
 ### Setting the current tenant for a block ###
 
@@ -151,10 +196,40 @@ All options available to Rails' own `validates_uniqueness_of` are also available
 
 ### Custom foreign_key ###
 
-You can explicitely specifiy a foreign_key for AaT to use should the key differ from the default:
+You can explicitly specifiy a foreign_key for AaT to use should the key differ from the default:
+
+```ruby
+acts_as_tenant(:account, :foreign_key => 'accountID') # by default AaT expects account_id
+```
+
+### Custom primary_key ###
+
+You can also explicitly specifiy a primary_key for AaT to use should the key differ from the default:
 
 ```ruby
-acts_as_tenant(:account, :foreign_key => 'accountID) # by default AaT expects account_id
+acts_as_tenant(:account, :primary_key => 'primaryID') # by default AaT expects id
+```
+
+
+### Has and belongs to many ###
+
+You can scope a model that is part of a HABTM relationship by using the `through` option.
+
+```ruby
+class Organisation < ActiveRecord::Base
+  has_many :organisations_users
+  has_many :users, through: :organisations_users
+end
+
+class User < ActiveRecord::Base
+  has_many :organisations_users
+  acts_as_tenant :organisation, through: :organisations_users
+end
+
+class OrganisationsUser < ActiveRecord::Base
+  belongs_to :user
+  acts_as_tenant :organisation
+end
 ```
 
 Configuration options
@@ -170,6 +245,37 @@ end
 
 * `config.require_tenant` when set to true will raise an ActsAsTenant::NoTenant error whenever a query is made without a tenant set.
 
+`config.require_tenant` can also be assigned a lambda that is evaluated at run time. For example:
+
+```ruby
+ActsAsTenant.configure do |config|
+  config.require_tenant = lambda do
+    if $request_env.present?
+      return false if $request_env["REQUEST_PATH"].start_with?("/admin/")
+    end
+  end
+end
+```
+
+`ActsAsTenant.should_require_tenant?` is used to determine if a tenant is required in the current context, either by evaluating the lambda provided, or by returning the boolean value assigned to `config.require_tenant`.
+
+belongs_to options
+---------------------
+`acts_as_tenant :account` includes the belongs_to relationship.
+So when using acts_as_tenant on a model, do not add `belongs_to :account` alongside `acts_as_tenant :account`:
+
+```ruby
+class User < ActiveRecord::Base
+  acts_as_tenant(:account) # YES
+  belongs_to :account # REDUNDANT
+end
+```
+
+You can add the following `belongs_to` options to `acts_as_tenant`:
+`:foreign_key, :class_name, :inverse_of, :optional, :primary_key, :counter_cache`
+
+Example: `acts_as_tenant(:account, counter_cache: true)`
+
 Sidekiq support
 ---------------
 
@@ -183,24 +289,42 @@ require 'acts_as_tenant/sidekiq'
 Testing
 ---------------
 
-If you set the `current_tenant` in your tests, make sure to clean up the tenant after each test by calling `ActsAsTenant.current_tenant = nil`. If you are manually setting the `current_tenant` in integration tests, please be aware that the value will not survive across multiple requests, even if they take place within the same test.
+If you set the `current_tenant` in your tests, make sure to clean up the tenant after each test by calling `ActsAsTenant.current_tenant = nil`. Integration tests are more difficult: manually setting the `current_tenant` value will not survive across multiple requests, even if they take place within the same test. This can result in undesired boilerplate to set the desired tenant. Moreover, the efficacy of the test can be compromised because the set `current_tenant` value will carry over into the request-response cycle.
 
-If you'd like to set a default tenant that will survive across multiple requests, assign a value to `default_tenant`. You might use a before hook like this:
+To address this issue, ActsAsTenant provides for a `test_tenant` value that can be set to allow for setup and post-request expectation testing. It should be used in conjunction with middleware that clears out this value while an integration test is processing. A typical Rails and RSpec setup might look like:
 
 ```ruby
-# Make the default tenant globally available to the tests
-$default_account = Account.create!
-# Specify this account as the current tenant unless overridden
-ActsAsTenant.default_tenant = $default_account
-# Stub out the method setting a tenant in a controller hook
-allow_any_instance_of(ApplicationController).to receive(:set_current_tenant)
+# test.rb
+require_dependency 'acts_as_tenant/test_tenant_middleware'
+
+Rails.application.configure do
+  config.middleware.use ActsAsTenant::TestTenantMiddleware
+end
 ```
 
-This can later be overridden by using any of the standard methods for specifying a different tenant. If you don't want this setting to apply to all of your tests, remember to clear it when you're finished by setting `ActsAsTenant.default_tenant = nil`.
+```ruby
+# spec_helper.rb
+config.before(:suite) do |example|
+  # Make the default tenant globally available to the tests
+  $default_account = Account.create!
+end
+
+config.before(:each) do |example|
+  if example.metadata[:type] == :request
+    # Set the `test_tenant` value for integration tests
+    ActsAsTenant.test_tenant = $default_account
+  else
+    # Otherwise just use current_tenant
+    ActsAsTenant.current_tenant = $default_account
+  end
+end
 
-To Do
------
-* ...
+config.after(:each) do |example|
+  # Clear any tenancy that might have been set
+  ActsAsTenant.current_tenant = nil
+  ActsAsTenant.test_tenant = nil
+end
+```
 
 Bug reports & suggested improvements
 ------------------------------------
@@ -210,13 +334,20 @@ If you have found a bug or want to suggest an improvement, please use our issue
 
 If you want to contribute, fork the project, code your improvements and make a pull request on [Github](http://github.com/ErwinM/acts_as_tenant/). When doing so, please don't forget to add tests. If your contribution is fixing a bug it would be perfect if you could also submit a failing test, illustrating the issue.
 
-Help maintain this gem
-----------------------
-I myself, do not work with RoR much anymore. As a result, I only check this repo a few time a year. If  wants to help me maintain this gem on a more regular basis, shoot me a message!
+Contributing to this gem
+------------------------
+
+We use the Appraisal gem to run tests against supported versions of Rails to test for compatibility against them all. StandardRb also helps keep code formatted cleanly.
+
+1. Fork the repo
+2. Make changes
+3. Run test suite with `bundle exec appraisal`
+4. Run `bundle exec standardrb` to standardize code formatting
+5. Submit a PR
 
 Author & Credits
 ----------------
-acts_as_tenant is written by Erwin Matthijssen.
+acts_as_tenant is written by Erwin Matthijssen & Chris Oliver.
 
 This gem was inspired by Ryan Sonnek's [Multitenant](https://github.com/wireframe/multitenant) gem and its use of default_scope.
 

data/Rakefile

@@ -1,5 +1,7 @@
-require 'bundler/gem_tasks'
+require "bundler/gem_tasks"
 
-require 'rspec/core/rake_task'
+APP_RAKEFILE = File.expand_path("spec/dummy/Rakefile", __dir__)
+
+require "rspec/core/rake_task"
 RSpec::Core::RakeTask.new(:spec)
-task :default => :spec
+task default: :spec

data/lib/acts_as_tenant/configuration.rb

@@ -1,26 +1,13 @@
 module ActsAsTenant
-  @@configuration = nil
-
-  def self.configure
-    @@configuration = Configuration.new
-
-    if block_given?
-      yield configuration
-    end
-
-    configuration
-  end
-
-  def self.configuration
-    @@configuration || configure
-  end
-
   class Configuration
-    attr_writer :require_tenant
-  
+    attr_writer :require_tenant, :pkey
+
     def require_tenant
       @require_tenant ||= false
     end
-  
+
+    def pkey
+      @pkey ||= :id
+    end
   end
 end

data/lib/acts_as_tenant/controller_extensions/filter.rb

@@ -0,0 +1,13 @@
+module ActsAsTenant
+  module ControllerExtensions
+    module Filter
+      extend ActiveSupport::Concern
+
+      private
+
+      def set_current_tenant(current_tenant_object)
+        ActsAsTenant.current_tenant = current_tenant_object
+      end
+    end
+  end
+end

data/lib/acts_as_tenant/controller_extensions/subdomain.rb

@@ -0,0 +1,20 @@
+module ActsAsTenant
+  module ControllerExtensions
+    module Subdomain
+      extend ActiveSupport::Concern
+
+      included do
+        cattr_accessor :tenant_class, :tenant_column, :subdomain_lookup
+        before_action :find_tenant_by_subdomain
+      end
+
+      private
+
+      def find_tenant_by_subdomain
+        if (subdomain = request.subdomains.send(subdomain_lookup))
+          ActsAsTenant.current_tenant = tenant_class.where(tenant_column => subdomain.downcase).first
+        end
+      end
+    end
+  end
+end

data/lib/acts_as_tenant/controller_extensions/subdomain_or_domain.rb

@@ -0,0 +1,20 @@
+module ActsAsTenant
+  module ControllerExtensions
+    module SubdomainOrDomain
+      extend ActiveSupport::Concern
+
+      included do
+        cattr_accessor :tenant_class, :tenant_primary_column, :tenant_second_column, :subdomain_lookup
+        before_action :find_tenant_by_subdomain_or_domain
+      end
+
+      private
+
+      def find_tenant_by_subdomain_or_domain
+        subdomain = request.subdomains.send(subdomain_lookup)
+        query = subdomain.present? ? {tenant_primary_column => subdomain.downcase} : {tenant_second_column => request.domain.downcase}
+        ActsAsTenant.current_tenant = tenant_class.where(query).first
+      end
+    end
+  end
+end

data/lib/acts_as_tenant/controller_extensions.rb

@@ -1,85 +1,36 @@
 module ActsAsTenant
   module ControllerExtensions
+    autoload :Filter, "acts_as_tenant/controller_extensions/filter"
+    autoload :Subdomain, "acts_as_tenant/controller_extensions/subdomain"
+    autoload :SubdomainOrDomain, "acts_as_tenant/controller_extensions/subdomain_or_domain"
 
     # this method allows setting the current_tenant by reading the subdomain and looking
     # it up in the tenant-model passed to the method. The method will look for the subdomain
     # in a column referenced by the second argument.
-    def set_current_tenant_by_subdomain(tenant = :account, column = :subdomain )
-      self.class_eval do
-        cattr_accessor :tenant_class, :tenant_column
-      end
+    def set_current_tenant_by_subdomain(tenant = :account, column = :subdomain, subdomain_lookup: :last)
+      include Subdomain
 
       self.tenant_class = tenant.to_s.camelcase.constantize
       self.tenant_column = column.to_sym
-
-      self.class_eval do
-
-        before_action :find_tenant_by_subdomain
-        helper_method :current_tenant if respond_to?(:helper_method)
-
-
-        private
-          def find_tenant_by_subdomain
-            if request.subdomains.last
-              ActsAsTenant.current_tenant = tenant_class.where(tenant_column => request.subdomains.last.downcase).first
-            end
-          end
-
-          def current_tenant
-            ActsAsTenant.current_tenant
-          end
-      end
+      self.subdomain_lookup = subdomain_lookup
     end
 
     # 01/27/2014 Christian Yerena / @preth00nker
     # this method adds the possibility of use the domain as a possible second argument to find
     # the current_tenant.
-    def set_current_tenant_by_subdomain_or_domain(tenant = :account, primary_column = :subdomain, second_column = :domain )
-      self.class_eval do
-        cattr_accessor :tenant_class, :tenant_primary_column, :tenant_second_column
-      end
+    def set_current_tenant_by_subdomain_or_domain(tenant = :account, primary_column = :subdomain, second_column = :domain, subdomain_lookup: :last)
+      include SubdomainOrDomain
 
       self.tenant_class = tenant.to_s.camelcase.constantize
       self.tenant_primary_column = primary_column.to_sym
       self.tenant_second_column = second_column.to_sym
-
-      self.class_eval do
-
-        before_action :find_tenant_by_subdomain_or_domain
-        helper_method :current_tenant if respond_to?(:helper_method)
-
-
-        private
-          def find_tenant_by_subdomain_or_domain
-            if request.subdomains.last
-              ActsAsTenant.current_tenant = tenant_class.where(tenant_primary_column => request.subdomains.last.downcase).first
-            else
-              ActsAsTenant.current_tenant = tenant_class.where(tenant_second_column => request.domain.downcase).first
-            end
-          end
-
-          def current_tenant
-            ActsAsTenant.current_tenant
-          end
-      end
+      self.subdomain_lookup = subdomain_lookup
     end
 
-
     # This method sets up a method that allows manual setting of the current_tenant. This method should
     # be used in a before_action. In addition, a helper is setup that returns the current_tenant
     def set_current_tenant_through_filter
-      self.class_eval do
-        helper_method :current_tenant if respond_to?(:helper_method)
-
-        private
-          def set_current_tenant(current_tenant_object)
-            ActsAsTenant.current_tenant = current_tenant_object
-          end
-
-          def current_tenant
-            ActsAsTenant.current_tenant
-          end
-      end
+      include Filter
     end
   end
 end

data/lib/acts_as_tenant/errors.rb

@@ -5,15 +5,11 @@ module ActsAsTenant
   module Errors
     class ModelNotScopedByTenant < ActsAsTenant::Error
     end
-    
+
     class NoTenantSet < ActsAsTenant::Error
     end
-    
-    class ModelNotScopedByTenant < ActsAsTenant::Error
-    end
-    
+
     class TenantIsImmutable < ActsAsTenant::Error
     end
-    
   end
 end