tenantify 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 8c5ba9f063bf0b429174f9c8e1c0ec83c7502bf8
+  data.tar.gz: 90a9332da5ce0b6a1ff840181ab141c45a3bf45c
+SHA512:
+  metadata.gz: fff72aa956ebf8afcd1d6129a2b6114743b0514b3d79d01036cc85c32464e239e02341d1536d1c2fa3f9b945bbd8e19e9d0655df8f02728b8b372adf1fcbec25
+  data.tar.gz: 9f18246005abc4e3d0580ec40b443cc4b591e1c306e4c13747a701ce3cdb16d49139dbb8cf5ff90e29fc20f4459dd805418ec25f3405f6ddd7eb24502416273f

data/.gitignore

@@ -0,0 +1,14 @@
+/.bundle/
+/.yardoc
+/Gemfile.lock
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/
+*.bundle
+*.so
+*.o
+*.a
+mkmf.log

data/.rspec

@@ -0,0 +1,2 @@
+--color
+--require spec_helper

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in tenantify.gemspec
+gemspec

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2015 Jaime Cabot Campins
+
+MIT License
+
+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

@@ -0,0 +1,166 @@
+# Tenantify
+
+This gem provides some tools to manage multitenancy on Ruby applications.
+
+## Synopsis
+
+Tenantify is a tool to simplify multitenancy on Ruby applications.
+It stores the current tenant in a thread variable and provides:
+
+  - A Rack middleware supporting some built-in and custom strategies to find a tenant
+    and set it as the current one for a request.
+
+  - A Resource class to encapsulate your application resources per tenant (databases,
+    external services, your own ruby instances, etc)
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'tenantify'
+```
+
+And then execute:
+
+    $ bundle
+
+## Usage
+
+### The current tenant
+
+Tenantify provides some class methods to set the current tenant for a piece of code.
+
+To execute some code for a particular tenant:
+```ruby
+Tenantify.using(:the_tenant) { # some code }
+```
+
+After that the tenant is set to its previous value.
+
+The using method returns the value returned by the block. If you want to get some data from
+a database for a particular tenant:
+```ruby
+data = Tenantify.using :the_tenant do
+  get_data_from_database
+end
+```
+
+To get the current tenant `Tenantify.current` is provided.
+
+The `#using` method is the recommended way to run code for a particular tenant, but in some cases
+may be useful to set a tenant as the current one from now on instead of just running a block of code.
+For instance, in a pry session:
+```ruby
+[1] pry(main)> Tenantify.use! :my_tenant
+[2] pry(main)> Tenantify.current
+=> :my_tenant
+```
+
+Example to show `Tenantify.using` and `Tenantify.use!` behaviour:
+```ruby
+# No tenant is set by default
+Tenantify.current # => nil
+
+Tenantify.using :tenant_1 do
+  Tenantify.current # => :tenant_1
+
+  # Nested `using` blocks allowed
+  Tenantify.using :tenant_2 do
+    Tenantify.current # => :tenant_2
+
+    Tenantify.use! :tenant_3
+    Tenantify.current # => :tenant_3
+  end
+
+  # When a block ends the tenant before the block is set again
+  # even if it has changed inside the block due a `use!` call.
+  Tenantify.current # => :tenant_1
+end
+
+Tenantify.use! :tenant_4
+
+# The current tenant is stored as a thread variable. On new threads it has to be set manually.
+Thread.new do
+  Tenantify.current # => nil
+end
+Tenantify.current # => :tenant_4
+```
+
+### Resources
+
+On your multitenant application some resources may depend on the current tenant. For instance: A Sequel database,
+a redis database, the host of an external service, etc.
+
+You could handle this situation by calling `Tenantify.current` to determine the resource you need for a tenant.
+To avoid having to deal with the current tenant within your app business logic a `Tenantify::Resource` class is
+provided.
+
+To build a tenantified resource you have to build a hash that maps the tenant name to the resource for that tenant.
+The following example shows how to configure a redis database per tenant on the same host.
+```ruby
+# when initializing your application:
+correspondence = {
+  :tenant_1 => Redis.new(:host => "localhost", :port => 6379, :db => 1),
+  :tenant_2 => Redis.new(:host => "localhost", :port => 6379, :db => 2)
+}
+
+redis_resource = Tenantify.resource(correspondence)
+Object.const_set("Redis", redis_resource)
+
+
+# at the entry point of your application
+tenant_name = find_out_current_tenant
+Tenantify.using(tenant_name) { app.run }
+
+
+# anywhere inside your app
+Redis.current # => Returns the redis instance for the current tenant
+```
+
+You can build a resource for any multitenant resource you have on your application.
+
+### The Rack middleware
+
+You can use Tenantify with any Ruby application you like and set the current tenant as soon as you know it,
+ideally outside of the boundaries of your application business logic.
+
+On a Rack application, this place is somewhere in the middleware stack. To handle this situation Tenantify
+provides a `Tenantify::Middleware`.
+
+There are several strategies you could use to choose the tenant to work with from the Rack environment.
+Tenantify has some basic built-in strategies, but you might want to implement your custom ones to handle
+more specific situations.
+
+The built-in strategies are:
+
+  * The `:header` strategy expects the tenant name to be sent in a request header.
+  * The `:host` strategy expects a hash with tenants as keys, and arrays of hosts as values.
+  * The `:default` strategy always returns the same tenant.
+
+You can configure Tenantify to use one or more strategies.
+
+The following example configures Tenantify to:
+
+  * Check the "X-Tenant" header to look for a tenant.
+  * If the header does not exist, select a tenant associated to the current host.
+  * If no tenant provided for the current host, use de tenant: `:main_tenant`
+
+```ruby
+# when initializing your application
+hosts_per_tenant = {
+  :tenant_1 => ["www.host_a.com", "www.host_b.com"],
+  :tenant_2 => ["www.host_c.com"]
+}
+
+Tenantify.configure do |config|
+  config.strategy :header, :name => "X-Tenant"
+  config.strategy :hosts, hosts_per_tenant
+  config.strategy :default, :tenant => :main_tenant
+end
+
+
+# on your config.ru
+use Tenantify::Middleware
+run MyRackApplication
+```

data/Rakefile

@@ -0,0 +1,2 @@
+require "bundler/gem_tasks"
+

data/lib/tenantify.rb

@@ -0,0 +1,57 @@
+require "tenantify/version"
+
+require "tenantify/configuration"
+require "tenantify/tenant"
+require "tenantify/resource"
+require "tenantify/middleware"
+
+module Tenantify
+  # Tenantify configuration
+  #
+  # @return [Configuration] the current configuration
+  def self.configuration
+    @configuration ||= Configuration.new
+  end
+
+  # A helper to configure Tenantify
+  #
+  # @yield [configuration] Configures tenantify
+  def self.configure
+    yield configuration
+  end
+
+  # An alias to {Tenant::using}
+  #
+  # @example Run some code on a particular tenant
+  #   Tenantify.using :a_tenant do
+  #     # some code...
+  #   end
+  # @see Tenant.using
+  def self.using tenant, &block
+    Tenant.using(tenant, &block)
+  end
+
+  # An alias to {Tenant::use!}
+  #
+  # @example Change the current tenant
+  #   Tenanfify.use! :a_tenant
+  #   # using :a_tenant from now on
+  # @see Tenant.use!
+  def self.use! tenant
+    Tenant.use!(tenant)
+  end
+
+  # An alias to {Tenant::current}
+  #
+  # @see Tenant.current
+  def self.current
+    Tenant.current
+  end
+
+  # An alias to {Resource::new}
+  #
+  # @see Resource
+  def self.resource correspondence
+    Resource.new(correspondence)
+  end
+end

data/lib/tenantify/configuration.rb

@@ -0,0 +1,25 @@
+module Tenantify
+  # It stores a configuration for {Tenantify::Middleware}.
+  class Configuration
+    # All configured strategies in order of priority.
+    #
+    # @return [Array<strategy_config>] a collection of strategy configurations.
+    attr_reader :strategies
+
+    # Constructor.
+    def initialize
+      @strategies = []
+    end
+
+    # Adds a new strategy for the Tenantify middleware. The order the strategies
+    # are added is the priority order they have to match the tenant.
+    #
+    # @param [Symbol, Class] the name of a known strategy or a custom strategy
+    #   class.
+    # @param [Hash] strategy configuration.
+    # @return [Array<strategy_config>] a collection of strategy configurations.
+    def strategy name_or_class, strategy_config = {}
+      strategies << [name_or_class, strategy_config]
+    end
+  end
+end

data/lib/tenantify/middleware.rb

@@ -0,0 +1,40 @@
+require 'tenantify/tenant'
+require 'tenantify/middleware/builder'
+
+module Tenantify
+  # Rack middleware responsible for setting the tenant during the http request.
+  #
+  # This middleware builds a set of strategies from the given configuration, and
+  # sets the tenant returned from those strategies.
+  class Middleware
+    # Constructor.
+    #
+    # @param [#call] the Rack application
+    # @param [Tenantify::Configuration] the Rack application
+    def initialize app, config = Tenantify.configuration
+      @app    = app
+      @config = config
+    end
+
+    # Calls the rack middleware.
+    #
+    # @param [rack_environment] the Rack environment
+    # @return [rack_response] the Rack response
+    def call env
+      tenant = strategies.tenant_for(env)
+
+      Tenant.using(tenant) { app.call(env) }
+    end
+
+  private
+
+    attr_reader :app, :config
+
+    def strategies
+      @strategies ||= begin
+        builder = Builder.new(config)
+        builder.call
+      end
+    end
+  end
+end

data/lib/tenantify/middleware/builder.rb

@@ -0,0 +1,63 @@
+require 'tenantify/middleware/strategies'
+
+strategies_pattern = File.join(File.dirname(__FILE__), "strategies/*.rb")
+Dir[strategies_pattern].each { |strategy_file| require strategy_file }
+
+module Tenantify
+  class Middleware
+    # This class builds all the strategies and injects them into a
+    # Strategies object.
+    class Builder
+      # Invalid strategy specification
+      UnknownStrategyError = Class.new(StandardError)
+
+      # Known strategies. They can be specified with a symbol.
+      KNOWN_STRATEGIES = {
+        :header  => Strategies::Header,
+        :host    => Strategies::Host,
+        :default => Strategies::Default
+      }
+
+      # @return [Tenantify::Configuration] given configuration.
+      attr_reader :config
+
+      # Constructor.
+      #
+      # @param [Tenantify::Configuration] the tenantify configuration.
+      # @param [Hash] a correspondence between strategy names and classes.
+      def initialize config, known_strategies: KNOWN_STRATEGIES
+        @config           = config
+        @known_strategies = known_strategies
+      end
+
+      # Builds the Strategies object.
+      #
+      # @return [Strategies] the strategies object.
+      def call
+        Strategies.new(strategies)
+      end
+
+    private
+
+      attr_reader :known_strategies
+
+      def strategies
+        strategies_config.map do |(name_or_class, strategy_config)|
+          strategy_class_for(name_or_class).new(strategy_config)
+        end
+      end
+
+      def strategy_class_for name_or_class
+        case name_or_class
+          when Class          then name_or_class
+          when Symbol, String then known_strategies.fetch(name_or_class.to_sym)
+          else raise UnknownStrategyError.new(name_or_class.inspect)
+        end
+      end
+
+      def strategies_config
+        config.strategies
+      end
+    end
+  end
+end

data/lib/tenantify/middleware/strategies.rb

@@ -0,0 +1,57 @@
+module Tenantify
+  class Middleware
+    # Responsible for finding the tenant for the given env.
+    #
+    # It iterates the strategies given to the constructor until it finds
+    # one that returns a tenant.
+    #
+    # == Default strategy
+    # When there is no matching strategy for the current environment
+    # a NotMatchingStrategyError is raised. To avoid this behaviour and
+    # use a particular tenant by default a Default strategy is provided.
+    #
+    # @example Configuring a tenant by default:
+    #   Tenantify.configure do |config|
+    #     # your strategies
+    #
+    #     config.strategy :default, :tenant => :my_default_tenant
+    #   end
+    class Strategies
+      # None strategy found a valid tenant for the given environment
+      NotMatchingStrategyError = Class.new(StandardError)
+
+      # Constructor. It receives all strategies in order of precedence.
+      #
+      # @param [<#tenant_for>] enumerable of strategies
+      def initialize strategies
+        @strategies = strategies
+      end
+
+      # Find a tenant for the current env.
+      #
+      # @param [rack_environment] current env.
+      # @return [Symbol] returns the matching tenant.
+      def tenant_for env
+        find_tenant_for(env) or raise_error(env)
+      end
+
+    private
+
+      attr_reader :strategies
+
+      def find_tenant_for env
+        lazy_strategies.
+          map { |strategy| strategy.tenant_for(env) }.
+          find { |tenant| tenant }
+      end
+
+      def lazy_strategies
+        @lazy_strategies ||= strategies.lazy
+      end
+
+      def raise_error env
+        raise NotMatchingStrategyError.new(env.inspect)
+      end
+    end
+  end
+end