shackles 1.0.0

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,51 @@
+Shackles
+==========
+
+## About
+
+Shackles allows multiple database environments and environment overrides to
+ActiveRecord, allowing least-privilege best practices.
+
+## Installation
+
+Add `gem 'shackles'` to your Gemfile (tested with Rails 2.3 and 3.2)
+
+## Usage
+
+There are two major use cases for shackles. The first is for master/slave(/deploy) environments.
+Using a slave is as simple as adding a slave block (underneath your main environment block) in
+database.yml, then wrapping stuff you want to query the slave in Shackles.activate(:slave) 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
+slave.
+
+Example database.yml file:
+
+```yaml
+production:
+  adapter: postgresql
+  username: myapp
+  database: myapp
+  host: db-master
+  slave:
+    host: db-slave
+  deploy:
+    username: deploy
+```
+
+Using an initializer, you can achieve the default environment settings (in tandem with profile
+changes):
+
+```ruby
+if ENV['RAILS_DATABASE_ENVIRONMENT']
+  Shackles.activate!(ENV['RAILS_DATABASE_ENVIRONMENT'].to_sym)
+end
+if ENV['RAILS_DATABASE_USER']
+  Shackles.apply_config!(:username => ENV['RAILS_DATABASE_USER'])
+end
+```

data/lib/shackles/connection_handler.rb

@@ -0,0 +1,15 @@
+module Shackles
+  module ConnectionHandler
+    def self.included(klass)
+      %w{clear_active_connections clear_reloadable_connections
+         clear_all_connections verify_active_connections }.each do |method|
+        klass.class_eval(<<EOS)
+          def #{method}_with_multiple_environments!
+            ::Shackles.connection_handlers.values.each(&:#{method}_without_multiple_environments!)
+          end
+EOS
+        klass.alias_method_chain "#{method}!".to_sym, :multiple_environments
+      end
+    end
+  end
+end

data/lib/shackles/connection_specification.rb

@@ -0,0 +1,53 @@
+module Shackles
+  module ConnectionSpecification
+    class CacheCoherentHash < Hash
+      def initialize(spec)
+        @spec = spec
+        super
+      end
+
+      def []=(key, value)
+        @spec.instance_variable_set(:@current_config, nil)
+        @spec.instance_variable_get(:@config)[key] = value
+      end
+
+      def delete(key)
+        @spec.instance_variable_set(:@current_config, nil)
+        @spec.instance_variable_get(:@config).delete(key)
+      end
+    end
+
+    def self.included(klass)
+      klass.send(:remove_method, :config)
+    end
+
+    def config
+      @current_config = nil if Shackles.environment != @current_config_environment || Shackles.global_config_sequence != @current_config_sequence
+      return @current_config if @current_config
+
+      @current_config_environment = Shackles.environment
+      @current_config_sequence = Shackles.global_config_sequence
+      config = @config.dup
+      if @config.has_key?(Shackles.environment)
+        config.merge!(@config[Shackles.environment].symbolize_keys)
+      end
+
+      config.keys.each do |key|
+        next unless config[key].is_a?(String)
+        config[key] = config[key] % config
+      end
+
+      config.merge!(Shackles.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/shackles/railtie.rb

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

data/lib/shackles/version.rb

@@ -0,0 +1,3 @@
+module Shackles
+  VERSION = "1.0.0"
+end

data/lib/shackles.rb

@@ -0,0 +1,96 @@
+module Shackles
+  class << self
+    def environment
+      @environment ||= :master
+    end
+
+    def global_config
+      @global_config ||= {}
+    end
+
+    # semi-private
+    def initialize!
+      require 'shackles/connection_handler'
+      require 'shackles/connection_specification'
+
+      ActiveRecord::ConnectionAdapters::ConnectionHandler.send(:include, Shackles::ConnectionHandler)
+      ActiveRecord::Base::ConnectionSpecification.send(:include, Shackles::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 ||= :master
+      return yield if environment == self.environment
+      begin
+        old_environment = activate!(environment)
+        yield
+      ensure
+        @environment = old_environment
+        ActiveRecord::Base.connection_handler = ensure_handler unless Rails.env.test?
+      end
+    end
+
+    # for use from script/console ONLY
+    def activate!(environment)
+      environment ||= :master
+      save_handler
+      old_environment = self.environment
+      @environment = environment
+      ActiveRecord::Base.connection_handler = ensure_handler unless Rails.env.test?
+      old_environment
+    end
+
+    private
+    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
+        variable = Rails.version < '3.0' ? :@connection_pools : :@class_to_pool
+        ActiveRecord::Base.connection_handler.instance_variable_get(variable).each do |model, pool|
+          new_handler.establish_connection(model, pool.spec)
+        end
+      end
+      new_handler
+    end
+  end
+end
+
+if defined?(Rails::Railtie)
+  require "shackles/railtie"
+else
+  # just load everything immediately for Rails 2
+  Shackles.initialize!
+end

data/spec/shackles_spec.rb

@@ -0,0 +1,125 @@
+require 'active_record'
+require 'rails'
+require 'shackles'
+
+# we're not actually bringing up ActiveRecord, so we need to initialize our stuff
+Shackles.initialize!
+
+RSpec.configure do |config|
+  config.mock_framework = :mocha
+end
+
+describe Shackles do
+  it "should allow changing environments" do
+    conf = {
+        :adapter => 'postgresql',
+        :database => 'master',
+        :username => 'canvas',
+        :deploy => {
+            :username => 'deploy'
+        },
+        :slave => {
+            :database => 'slave'
+        }
+    }
+    spec = ActiveRecord::Base::ConnectionSpecification.new(conf, 'adapter')
+    spec.config[:username].should == 'canvas'
+    spec.config[:database].should == 'master'
+    Shackles.activate(:deploy) do
+      spec.config[:username].should == 'deploy'
+      spec.config[:database].should == 'master'
+    end
+    spec.config[:username].should == 'canvas'
+    spec.config[:database].should == 'master'
+    Shackles.activate(:slave) do
+      spec.config[:username].should == 'canvas'
+      spec.config[:database].should == 'slave'
+    end
+    spec.config[:username].should == 'canvas'
+    spec.config[:database].should == 'master'
+  end
+
+  it "should allow using hash insertions" do
+    conf = {
+        :adapter => 'postgresql',
+        :database => 'master',
+        :username => '%{schema_search_path}',
+        :schema_search_path => 'canvas',
+        :deploy => {
+            :username => 'deploy'
+        }
+    }
+    spec = ActiveRecord::Base::ConnectionSpecification.new(conf, 'adapter')
+    spec.config[:username].should == 'canvas'
+    Shackles.activate(:deploy) do
+      spec.config[:username].should == 'deploy'
+    end
+    spec.config[:username].should == 'canvas'
+  end
+
+  it "should be cache coherent with modifying the config" do
+    conf = {
+        :adapter => 'postgresql',
+        :database => 'master',
+        :username => '%{schema_search_path}',
+        :schema_search_path => 'canvas',
+        :deploy => {
+            :username => 'deploy'
+        }
+    }
+    spec = ActiveRecord::Base::ConnectionSpecification.new(conf.dup, 'adapter')
+    spec.config[:username].should == 'canvas'
+    spec.config[:schema_search_path] = 'bob'
+    spec.config[:username].should == 'bob'
+    Shackles.activate(:deploy) do
+      spec.config[:schema_search_path].should == 'bob'
+      spec.config[:username].should == 'deploy'
+    end
+
+    spec.config = conf.dup
+    spec.config[:username].should == 'canvas'
+  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
+      Shackles.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
+      Shackles.expects(:ensure_handler).returns(old_handler).twice
+      Shackles.activate(:slave) {}
+    end
+
+    it "should not close connections when switching envs" do
+      conn = ActiveRecord::Base.connection
+      slave_conn = Shackles.activate(:slave) { ActiveRecord::Base.connection }
+      conn.should_not == slave_conn
+      ActiveRecord::Base.connection.should == conn
+    end
+
+    context "non-transactional" do
+      it "should really disconnect all envs" do
+        ActiveRecord::Base.connection
+        ActiveRecord::Base.connection_pool.should be_connected
+
+        Shackles.activate(:slave) do
+          ActiveRecord::Base.connection
+          ActiveRecord::Base.connection_pool.should be_connected
+        end
+
+        ActiveRecord::Base.clear_all_connections!
+        ActiveRecord::Base.connection_pool.should_not be_connected
+        Shackles.activate(:slave) do
+          ActiveRecord::Base.connection_pool.should_not be_connected
+        end
+      end
+    end
+  end
+end

metadata

@@ -0,0 +1,119 @@
+--- !ruby/object:Gem::Specification
+name: shackles
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+  prerelease: 
+platform: ruby
+authors:
+- Cody Cutrer
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2013-04-09 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: activerecord
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '2.3'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '2.3'
+- !ruby/object:Gem::Dependency
+  name: mocha
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rspec-core
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '2.13'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '2.13'
+- !ruby/object:Gem::Dependency
+  name: sqlite3
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    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:
+- lib/shackles/connection_handler.rb
+- lib/shackles/connection_specification.rb
+- lib/shackles/railtie.rb
+- lib/shackles/version.rb
+- lib/shackles.rb
+- LICENSE
+- README.md
+- spec/shackles_spec.rb
+homepage: http://github.com/instructure/shackles
+licenses: []
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 1.8.23
+signing_key: 
+specification_version: 3
+summary: ActiveRecord database environment switching for slaves and least-privilege
+test_files:
+- spec/shackles_spec.rb
+has_rdoc: