guardrail 2.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 737326a16630468262a493961348ecc21dd8b4f8d82c6526bfafe1c0b66c294c
+  data.tar.gz: c90574a6e50c6556e678b08acc766ef74c36be693e6d012989bb6fcb71e93c77
+SHA512:
+  metadata.gz: d9761c6d3817b19a980827c71fceca3051cc8cbaf2b86bd959bf110f954a18c271e433bd433d92352d455e6af38234a1945369bbac118b142e1bcdfe45bbd78d
+  data.tar.gz: 20aab4abcd5ea1743df249d58d7772ac186277d6e8eb25e9772dd7aed46e41fabc1ac1870a4e802c048428f27f2bb7eb38bbbeffc1c951dd22e177c5f92d54ab

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2013 Instructure, Inc.
+
+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,76 @@
+GuardRail
+==========
+
+## About
+
+GuardRail allows multiple database environments and environment overrides to
+ActiveRecord, allowing least-privilege best practices.
+
+## Installation
+
+Add `gem 'guardrail'` to your Gemfile (tested with Rails 4.x and 5.x, and also
+with the release candidate for Rails 6.0)
+
+## Usage
+
+There are two major use cases for guardrail. The first is for primary/replica(/deploy) environments.
+Using a replica is as simple as adding a replica block (underneath your main environment block) in
+database.yml, then wrapping stuff you want to query the replica in GuardRail.activate(:replica) blocks.
+You can extend this to a deploy environment so that migrations will run as a deploy user that
+permission to modify schema, while your normal app runs with lower privileges that cannot modify
+schema. This is defense-in-depth in practice, so that *if* you happen to have a SQL injection
+bug, it would be impossible to do something like dropping tables.
+
+The other major use case is more defense-in-depth. By carefully setting up your environment, you
+can default to script/console sessions for regular users to use their own database user, and the
+replica.
+
+Example database.yml file:
+
+```yaml
+production:
+  adapter: postgresql
+  username: myapp
+  database: myapp
+  host: db-primary
+  replica:
+    host: db-replica
+  deploy:
+    username: deploy
+```
+
+Using an initializer, you can achieve the default environment settings (in tandem with profile
+changes):
+
+```ruby
+if ENV['RAILS_DATABASE_ENVIRONMENT']
+  GuardRail.activate!(ENV['RAILS_DATABASE_ENVIRONMENT'].to_sym)
+end
+if ENV['RAILS_DATABASE_USER']
+  GuardRail.apply_config!(:username => ENV['RAILS_DATABASE_USER'])
+end
+```
+
+Additionally **in Ruby 2.0+** you can include GuardRail::HelperMethods and use several helpers
+to execute methods on specific environments:
+
+```ruby
+class SomeModel
+  include GuardRail::HelperMethods
+
+  def expensive_read_only
+    ...
+  end
+  guard_rail_method :expensive_read_only, environment: :replica
+
+  def self.class_level_expensive_read_only
+    ...
+  end
+  gaurd_rail_class_method :class_level_expensive_read_only, environment: :replica
+
+  # helpers for multiple methods are also available
+
+  guard_rail_methods :instance_method_foo, :instance_method_bar, environment: :replica
+  guard_rail_class_methods :class_method_foo, :class_method_bar, environment: :replica
+end
+```

data/lib/guard_rail.rb

@@ -0,0 +1,114 @@
+require 'set'
+
+module GuardRail
+  class << self
+    attr_accessor :primary_environment_name
+    GuardRail.primary_environment_name = :primary
+
+    def environment
+      Thread.current[:guard_rail_environment] ||= primary_environment_name
+    end
+
+    def global_config
+      @global_config ||= {}
+    end
+
+    def activated_environments
+      @activated_environments ||= Set.new()
+    end
+
+    # semi-private
+    def initialize!
+      require 'guard_rail/connection_handler'
+      require 'guard_rail/connection_specification'
+      require 'guard_rail/helper_methods'
+
+      activated_environments << GuardRail.environment
+
+      ActiveRecord::ConnectionAdapters::ConnectionHandler.prepend(ConnectionHandler)
+      ActiveRecord::ConnectionAdapters::ConnectionSpecification.prepend(ConnectionSpecification)
+    end
+
+    def global_config_sequence
+      @global_config_sequence ||= 1
+    end
+
+    def bump_sequence
+      @global_config_sequence ||= 1
+      @global_config_sequence += 1
+      ActiveRecord::Base::connection_handler.clear_all_connections!
+    end
+
+    # for altering other pieces of config (i.e. username)
+    # will force a disconnect
+    def apply_config!(hash)
+      global_config.merge!(hash)
+      bump_sequence
+    end
+
+    def remove_config!(key)
+      global_config.delete(key)
+      bump_sequence
+    end
+
+    def connection_handlers
+      save_handler
+      @connection_handlers
+    end
+
+    # switch environment for the duration of the block
+    # will keep the old connections around
+    def activate(environment)
+      environment ||= primary_environment_name
+      return yield if environment == self.environment
+      begin
+        old_environment = activate!(environment)
+        activated_environments << environment
+        yield
+      ensure
+        Thread.current[:guard_rail_environment] = old_environment
+        ActiveRecord::Base.connection_handler = ensure_handler unless test?
+      end
+    end
+
+    # for use from script/console ONLY
+    def activate!(environment)
+      environment ||= primary_environment_name
+      save_handler
+      old_environment = self.environment
+      Thread.current[:guard_rail_environment] = environment
+      ActiveRecord::Base.connection_handler = ensure_handler unless test?
+      old_environment
+    end
+
+    private
+
+    def test?
+      Rails.env.test?
+    end
+
+    def save_handler
+      @connection_handlers ||= {}
+      @connection_handlers[environment] ||= ActiveRecord::Base.connection_handler
+    end
+
+    def ensure_handler
+      new_handler = @connection_handlers[environment]
+      if !new_handler
+        new_handler = @connection_handlers[environment] = ActiveRecord::ConnectionAdapters::ConnectionHandler.new
+        pools = ActiveRecord::Base.connection_handler.send(:owner_to_pool)
+        pools.each_pair do |model, pool|
+          new_handler.establish_connection(pool.spec.config)
+        end
+      end
+      new_handler
+    end
+  end
+end
+
+if defined?(Rails::Railtie)
+  require "guard_rail/railtie"
+else
+  # just load everything immediately for Rails 2
+  GuardRail.initialize!
+end

data/lib/guard_rail/connection_handler.rb

@@ -0,0 +1,13 @@
+module GuardRail
+  module ConnectionHandler
+    %w{clear_active_connections clear_reloadable_connections
+       clear_all_connections verify_active_connections }.each do |method|
+      class_eval <<-RUBY, __FILE__, __LINE__ + 1
+        def #{method}!(super_method: false)
+          return super() if super_method
+          ::GuardRail.connection_handlers.values.each { |handler| handler.#{method}!(super_method: true) }
+        end
+      RUBY
+    end
+  end
+end

data/lib/guard_rail/connection_specification.rb

@@ -0,0 +1,77 @@
+require 'i18n/core_ext/hash' unless Hash.method_defined?(:deep_symbolize_keys)
+
+module GuardRail
+  module ConnectionSpecification
+    class CacheCoherentHash < Hash
+      def initialize(spec)
+        @spec = spec
+        super
+      end
+
+      def []=(key, value)
+        super
+        @spec.instance_variable_set(:@current_config, nil)
+        @spec.instance_variable_get(:@config)[key] = value
+      end
+
+      def delete(key)
+        super
+        @spec.instance_variable_set(:@current_config, nil)
+        @spec.instance_variable_get(:@config).delete(key)
+      end
+
+      def dup
+        Hash[self]
+      end
+
+      # in rails 4.2, active support tries to create a copy of the original object's class
+      # instead of making a new Hash object, so it fails since initialize expects an argument
+      def transform_keys(&block)
+        dup.transform_keys(&block)
+      end
+    end
+
+    def initialize(name, config, adapter_method)
+      super(name, config.deep_symbolize_keys, adapter_method)
+    end
+
+    def initialize_dup(original)
+      @current_config = nil
+      super
+    end
+
+    def config
+      @current_config = nil if GuardRail.environment != @current_config_environment || GuardRail.global_config_sequence != @current_config_sequence
+      return @current_config if @current_config
+
+      @current_config_environment = GuardRail.environment
+      @current_config_sequence = GuardRail.global_config_sequence
+      config = @config.dup
+      if @config.has_key?(GuardRail.environment)
+        env_config = @config[GuardRail.environment]
+        # an array of databases for this environment; for now, just choose the first non-nil element
+        if env_config.is_a?(Array)
+          env_config = env_config.detect { |individual_config| !individual_config.nil? }
+        end
+        config.merge!(env_config.symbolize_keys)
+      end
+
+      config.keys.each do |key|
+        next unless config[key].is_a?(String)
+        config[key] = config[key] % config
+      end
+
+      config.merge!(GuardRail.global_config)
+
+      @current_config = CacheCoherentHash.new(self)
+      @current_config.replace(config)
+
+      @current_config
+    end
+
+    def config=(value)
+      @config = value
+      @current_config = nil
+    end
+  end
+end

data/lib/guard_rail/helper_methods.rb

@@ -0,0 +1,38 @@
+module GuardRail
+  module HelperMethods
+    def self.included(base)
+      base.singleton_class.include(ClassMethods)
+      # call guard_rail_class_method on the class itself, which then calls guard_rail_method on the singleton_class
+      base.singleton_class.singleton_class.include(ClassMethods)
+    end
+
+    # see readme for example usage
+    module ClassMethods
+      def guard_rail_class_methods(*methods, opts)
+        methods.each { |m| guard_rail_class_method(m, opts) }
+      end
+
+      def guard_rail_class_method(method, opts)
+        self.singleton_class.guard_rail_method(method, opts)
+      end
+
+      def guard_rail_methods(*methods, opts)
+        methods.each { |m| guard_rail_method(m, opts) }
+      end
+
+      def guard_rail_method(method, opts)
+        @guard_rail_module ||= begin
+          m = Module.new
+          self.prepend m
+          m
+        end
+
+        @guard_rail_module.class_eval <<-RUBY, __FILE__, __LINE__ + 1
+         def #{method}(*args)
+           GuardRail.activate(#{opts[:environment].inspect}) { super }
+         end
+        RUBY
+      end
+    end
+  end
+end

data/lib/guard_rail/railtie.rb

@@ -0,0 +1,9 @@
+module GuardRail
+  class Railtie < Rails::Railtie
+    initializer "guard_rail.extend_ar", :before => "active_record.initialize_database" do
+      ActiveSupport.on_load(:active_record) do
+        GuardRail.initialize!
+      end
+    end
+  end
+end

data/lib/guard_rail/version.rb

@@ -0,0 +1,3 @@
+module GuardRail
+  VERSION = "2.0.0"
+end

data/lib/guardrail.rb

@@ -0,0 +1 @@
+require 'guard_rail'

data/spec/guard_rail_spec.rb

@@ -0,0 +1,167 @@
+require 'active_record'
+require 'byebug'
+require 'rails'
+require 'guard_rail'
+
+# we're not actually bringing up ActiveRecord, so we need to initialize our stuff
+GuardRail.initialize!
+
+RSpec.configure do |config|
+  config.mock_framework = :mocha
+end
+
+describe GuardRail do
+  ConnectionSpecification = ActiveRecord::ConnectionAdapters::ConnectionSpecification
+
+  def spec_args(conf, adapter)
+    ['dummy', conf, adapter]
+  end
+
+  it "should allow changing environments" do
+    conf = {
+        :adapter => 'postgresql',
+        :database => 'primary',
+        :username => 'canvas',
+        :deploy => {
+            :username => 'deploy'
+        },
+        :replica => {
+            :database => 'replica'
+        }
+    }
+    spec = ConnectionSpecification.new(*spec_args(conf, 'adapter'))
+    expect(spec.config[:username]).to eq('canvas')
+    expect(spec.config[:database]).to eq('primary')
+    GuardRail.activate(:deploy) do
+      expect(spec.config[:username]).to eq('deploy')
+      expect(spec.config[:database]).to eq('primary')
+    end
+    expect(spec.config[:username]).to eq('canvas')
+    expect(spec.config[:database]).to eq('primary')
+    GuardRail.activate(:replica) do
+      expect(spec.config[:username]).to eq('canvas')
+      expect(spec.config[:database]).to eq('replica')
+    end
+    expect(spec.config[:username]).to eq('canvas')
+    expect(spec.config[:database]).to eq('primary')
+  end
+
+  it "should allow using hash insertions" do
+    conf = {
+        :adapter => 'postgresql',
+        :database => 'primary',
+        :username => '%{schema_search_path}',
+        :schema_search_path => 'canvas',
+        :deploy => {
+            :username => 'deploy'
+        }
+    }
+    spec = ConnectionSpecification.new(*spec_args(conf, 'adapter'))
+    expect(spec.config[:username]).to eq('canvas')
+    GuardRail.activate(:deploy) do
+      expect(spec.config[:username]).to eq('deploy')
+    end
+    expect(spec.config[:username]).to eq('canvas')
+  end
+
+  it "should be cache coherent with modifying the config" do
+    conf = {
+        :adapter => 'postgresql',
+        :database => 'primary',
+        :username => '%{schema_search_path}',
+        :schema_search_path => 'canvas',
+        :deploy => {
+            :username => 'deploy'
+        }
+    }
+    spec = ConnectionSpecification.new(*spec_args(conf.dup, 'adapter'))
+    expect(spec.config[:username]).to eq('canvas')
+    spec.config[:schema_search_path] = 'bob'
+    expect(spec.config[:schema_search_path]).to eq('bob')
+    expect(spec.config[:username]).to eq('bob')
+    GuardRail.activate(:deploy) do
+      expect(spec.config[:schema_search_path]).to eq('bob')
+      expect(spec.config[:username]).to eq('deploy')
+    end
+    external_config = spec.config.dup
+    expect(external_config.class).to eq(Hash)
+    expect(external_config).to eq(spec.config)
+
+    spec.config = conf.dup
+    expect(spec.config[:username]).to eq('canvas')
+  end
+
+  it "does not share config objects when dup'ing specs" do
+    conf = {
+        :adapter => 'postgresql',
+        :database => 'primary',
+        :username => '%{schema_search_path}',
+        :schema_search_path => 'canvas',
+        :deploy => {
+            :username => 'deploy'
+        }
+    }
+    spec = ConnectionSpecification.new(*spec_args(conf.dup, 'adapter'))
+    expect(spec.config.object_id).not_to eq spec.dup.config.object_id
+  end
+
+  describe "activate" do
+    before do
+      #!!! trick it in to actually switching envs
+      Rails.env.stubs(:test?).returns(false)
+
+      # be sure to test bugs where the current env isn't yet included in this hash
+      GuardRail.connection_handlers.clear
+
+      ActiveRecord::Base.establish_connection(:adapter => 'sqlite3', :database => ':memory:')
+    end
+
+    it "should call ensure_handler when switching envs" do
+      old_handler = ActiveRecord::Base.connection_handler
+      GuardRail.expects(:ensure_handler).returns(old_handler).twice
+      GuardRail.activate(:replica) {}
+    end
+
+    it "should not close connections when switching envs" do
+      conn = ActiveRecord::Base.connection
+      replica_conn = GuardRail.activate(:replica) { ActiveRecord::Base.connection }
+      expect(conn).not_to eq(replica_conn)
+      expect(ActiveRecord::Base.connection).to eq(conn)
+    end
+
+    it "should track all activated environments" do
+      GuardRail.activate(:replica) {}
+      GuardRail.activate(:custom) {}
+      expected = Set.new([:primary, :replica, :custom])
+      expect(GuardRail.activated_environments & expected).to eq(expected)
+    end
+
+    context "non-transactional" do
+      it "should really disconnect all envs" do
+        ActiveRecord::Base.connection
+        expect(ActiveRecord::Base.connection_pool).to be_connected
+
+        GuardRail.activate(:replica) do
+          ActiveRecord::Base.connection
+          expect(ActiveRecord::Base.connection_pool).to be_connected
+        end
+
+        ActiveRecord::Base.clear_all_connections!
+        expect(ActiveRecord::Base.connection_pool).not_to be_connected
+        GuardRail.activate(:replica) do
+          expect(ActiveRecord::Base.connection_pool).not_to be_connected
+        end
+      end
+    end
+
+    it 'is thread safe' do
+      GuardRail.activate(:replica) do
+        Thread.new do
+          GuardRail.activate!(:deploy)
+          expect(GuardRail.environment).to eq :deploy
+        end.join
+        expect(GuardRail.environment).to eq :replica
+      end
+    end
+  end
+end

metadata

@@ -0,0 +1,164 @@
+--- !ruby/object:Gem::Specification
+name: guardrail
+version: !ruby/object:Gem::Version
+  version: 2.0.0
+platform: ruby
+authors:
+- Cody Cutrer
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2020-10-05 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: activerecord
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '5.1'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '6.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '5.1'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '6.1'
+- !ruby/object:Gem::Dependency
+  name: railties
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '5.1'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '6.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '5.1'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '6.1'
+- !ruby/object:Gem::Dependency
+  name: appraisal
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: byebug
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: mocha
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: sqlite3
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: Allows multiple environments in database.yml, and dynamically switching
+  them.
+email: cody@instructure.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- lib/guard_rail.rb
+- lib/guard_rail/connection_handler.rb
+- lib/guard_rail/connection_specification.rb
+- lib/guard_rail/helper_methods.rb
+- lib/guard_rail/railtie.rb
+- lib/guard_rail/version.rb
+- lib/guardrail.rb
+- spec/guard_rail_spec.rb
+homepage: http://github.com/instructure/guardrail
+licenses:
+- MIT
+metadata: {}
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '2.5'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.1.2
+signing_key:
+specification_version: 4
+summary: ActiveRecord database environment switching for secondaries and least-privilege
+test_files:
+- spec/guard_rail_spec.rb