required_scopes 1.0.0

data/lib/required_scopes/active_record/relation.rb

@@ -0,0 +1,121 @@
+require 'active_record'
+require 'required_scopes/errors'
+require 'required_scopes/active_record/version_compatibility'
+
+# This file simply adds a few small methods to ::ActiveRecord::Relation to allow tracking which scope categories have
+# been satisfied on a relation.
+::ActiveRecord::Relation.class_eval do
+  # Call this method inline, exactly as you would any class-defined scope, to indicate that a particular category
+  # or categories have been satisfied. It's really intended for use in a class method, but both of these will
+  # work:
+  #
+  #     class User < ActiveRecord::Base
+  #       must_scope_by :client, :deleted
+  #
+  #       class << self
+  #         def active_for_client_named(client_name)
+  #           client_id = CLIENT_MAP[client_name]
+  #           where(:client_id => client_id).where(:deleted => false).scope_categories_satisfied(:client)
+  #         end
+  #       end
+  #     end
+  #
+  #     User.active_for_client_named('foo').first
+  #     User.where(:client_id => client_id).where(:deleted => false).scope_categories_satisfied(:client, :deleted).first
+  def scope_categories_satisfied(*categories, &block)
+    categories = categories.flatten
+
+    new_scope = if categories.length == 0
+      self
+    else
+      out = clone
+      out.scope_categories_satisfied!(categories)
+      out
+    end
+
+    if block
+      new_scope.scoping(&block)
+    else
+      new_scope
+    end
+  end
+
+  # Alias for #scope_categories_satisfied.
+  def scope_category_satisfied(category, &block)
+    scope_categories_satisfied(category, &block)
+  end
+
+  # Tells this Relation that one or more categories have been satisfied.
+  def scope_categories_satisfied!(categories)
+    categories = categories.flatten
+
+    @satisfied_scope_categories ||= [ ]
+    @satisfied_scope_categories |= categories
+  end
+
+  # Tells this Relation that _all_ categories have been satisfied.
+  def all_scope_categories_satisfied!
+    scope_categories_satisfied!(required_scope_categories)
+  end
+
+  def all_scope_categories_satisfied(&block)
+    scope_categories_satisfied(required_scope_categories, &block)
+  end
+
+  # Returns the set of scope categories that have been satisfied.
+  def satisfied_scope_categories
+    @satisfied_scope_categories ||= [ ]
+  end
+
+  # Overrides #merge to merge the information about which scope categories have been satisfied, too.
+  def merge(other_relation)
+    super.scope_categories_satisfied(satisfied_scope_categories | other_relation.satisfied_scope_categories)
+  end
+
+  delegate :required_scope_categories, :to => :klass
+
+
+  private
+  # Raises an exception if there is at least one required scope category that has not yet been satisfied.
+  # +triggering_method+ is the name of the method called that triggered this check; we include this in the error
+  # we raise.
+  def ensure_categories_satisfied!(triggering_method)
+    required_categories = required_scope_categories
+    missing_categories = required_categories - satisfied_scope_categories
+
+    if missing_categories.length > 0
+      # We return a special exception for the category +:base+, because we want to give a simpler, cleaner error
+      # message for users who are just using the #base_scope_required! syntactic sugar instead of the full categories
+      # system.
+      # $stderr.puts "RAISING AT: #{caller.join("\n    ")}"
+      if missing_categories == [ :base ]
+        raise RequiredScopes::Errors::BaseScopeNotSatisfiedError.new(klass, self, triggering_method)
+      else
+        raise RequiredScopes::Errors::RequiredScopeCategoriesNotSatisfiedError.new(
+          klass, self, triggering_method, required_categories, satisfied_scope_categories)
+      end
+    end
+  end
+
+  # Override certain key methods in ActiveRecord::Relation to make sure they check for category satisfaction before
+  # running.
+  [ :exec_queries, :perform_calculation, :update_all, :delete_all, :exists?, :pluck ].each do |method_name|
+    method_base_name = method_name
+    method_suffix = ""
+
+    if method_base_name.to_s =~ /^(.*?)([\?\!])$/
+      method_base_name = $1
+      method_suffix = $2
+    end
+
+    with_name = "#{method_base_name}_with_scope_categories_check#{method_suffix}"
+    without_name = "#{method_base_name}_without_scope_categories_check#{method_suffix}"
+
+    define_method(with_name) do |*args, &block|
+      ensure_categories_satisfied!(method_name) unless RequiredScopes::ActiveRecord::VersionCompatibility.is_association_relation?(self)
+      send(without_name, *args, &block)
+    end
+
+    alias_method_chain method_name, :scope_categories_check
+  end
+end

data/lib/required_scopes/active_record/version_compatibility.rb

@@ -0,0 +1,157 @@
+module RequiredScopes
+  module ActiveRecord
+    module VersionCompatibility
+      class << self
+        delegate :is_association_relation?, :supports_references_method?, :apply_version_specific_fixes!,
+          :supports_find_by?, :relation_method_for_ignoring_scopes, :supports_load?, :supports_take?,
+          :supports_ids?, :supports_spawn?, :supports_bang_methods?, :supports_references?,
+          :supports_unscope?, :supports_none?, :supports_distinct?, :to => :impl
+
+        private
+        def impl
+          @impl ||= if ::ActiveRecord::VERSION::MAJOR == 4
+            ActiveRecord4.new
+          elsif ::ActiveRecord::VERSION::MAJOR == 3
+            ActiveRecord3.new
+          else
+            raise "RequiredScopes does not support ActiveRecord version #{ActiveRecord::VERSION::STRING} currently."
+          end
+        end
+      end
+
+      class ActiveRecord4
+        def is_association_relation?(relation)
+          relation.kind_of?(::ActiveRecord::AssociationRelation)
+        end
+
+        def supports_references_method?
+          true
+        end
+
+        def apply_version_specific_fixes!
+
+        end
+
+        def supports_find_by?
+          true
+        end
+
+        def supports_load?
+          true
+        end
+
+        def supports_take?
+          true
+        end
+
+        def supports_ids?
+          true
+        end
+
+        def supports_spawn?
+          true
+        end
+
+        def supports_bang_methods?
+          true
+        end
+
+        def supports_references?
+          true
+        end
+
+        def supports_unscope?
+          true
+        end
+
+        def supports_none?
+          true
+        end
+
+        def supports_distinct?
+          true
+        end
+
+        def relation_method_for_ignoring_scopes
+          :all
+        end
+      end
+
+      class ActiveRecord3
+        def is_association_relation?(relation)
+          false
+        end
+
+        def supports_references_method?
+          false
+        end
+
+        def apply_version_specific_fixes!
+          ::ActiveRecord::Associations::Association.class_eval do
+            def target_scope_with_required_scopes_removed
+              out = target_scope_without_required_scopes_removed
+              out.all_scope_categories_satisfied!
+              out
+            end
+
+            alias_method_chain :target_scope, :required_scopes_removed
+          end
+
+          ::ActiveRecord::Base.class_eval do
+            def destroy_with_required_scopes_removed
+              self.class.all_scope_categories_satisfied do
+                destroy_without_required_scopes_removed
+              end
+            end
+
+            alias_method_chain :destroy, :required_scopes_removed
+          end
+        end
+
+        def supports_find_by?
+          false
+        end
+
+        def supports_load?
+          false
+        end
+
+        def supports_take?
+          false
+        end
+
+        def supports_ids?
+          false
+        end
+
+        def supports_spawn?
+          false
+        end
+
+        def supports_bang_methods?
+          false
+        end
+
+        def supports_references?
+          false
+        end
+
+        def supports_unscope?
+          false
+        end
+
+        def supports_none?
+          false
+        end
+
+        def supports_distinct?
+          false
+        end
+
+        def relation_method_for_ignoring_scopes
+          :relation
+        end
+      end
+    end
+  end
+end

data/lib/required_scopes/errors.rb

@@ -0,0 +1,48 @@
+module RequiredScopes
+  module Errors
+    # The parent of all errors raised by RequiredScopes.
+    class Base < StandardError; end
+
+    # Raised if you try to execute an operation on a model or relation without having satisfied one or more
+    # scopes.
+    class RequiredScopeCategoriesNotSatisfiedError < Base
+      attr_reader :model_class, :current_relation, :triggering_method, :required_categories, :satisfied_categories, :missing_categories
+
+      def initialize(model_class, current_relation, triggering_method, required_categories, satisfied_categories)
+        @model_class = model_class
+        @current_relation = current_relation
+        @triggering_method = triggering_method
+        @required_categories = required_categories
+        @satisfied_categories = satisfied_categories
+        @missing_categories = @required_categories - @satisfied_categories
+
+        super(build_message)
+      end
+
+      private
+      def build_message
+        %{Model #{model_class.name} requires that you apply scope(s) satisfying the following
+categories before you use it: #{missing_categories.sort_by(&:to_s).join(", ")}.
+
+Satisfy these categories by including scopes in your query that are tagged with
+:satisfies => <category name>, for each of the categories.}
+      end
+    end
+
+    # Raised if you try to execute an operation on a model or relation without having satisfied the base scope.
+    # (We use this instead of RequiredScopeCategoriesNotSatisfiedError, above, simply to make the error message
+    # simpler and more comprehensible to users who only are using the "base scope" syntactic sugar.)
+    class BaseScopeNotSatisfiedError < RequiredScopeCategoriesNotSatisfiedError
+      def initialize(model_class, current_relation, triggering_method)
+        super(model_class, current_relation, triggering_method, [ :base ], [ ])
+      end
+
+      private
+      def build_message
+        %{Model #{model_class.name} requires specification of a base scope before using it in a query
+or other such operation. (Base scopes are those declared with #base_scope rather than just #scope,
+or class methods that include #base_scope_satisfied.)}
+      end
+    end
+  end
+end

data/lib/required_scopes/version.rb

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

data/required_scopes.gemspec

@@ -0,0 +1,56 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'required_scopes/version'
+
+Gem::Specification.new do |s|
+  s.name          = "required_scopes"
+  s.version       = RequiredScopes::VERSION
+  s.authors       = ["Andrew Geweke"]
+  s.email         = ["andrew@geweke.org"]
+  s.description   = %q{Don't let developers forget about critical scopes for queries.}
+  s.summary       = %q{Don't let developers forget about critical scopes for queries.}
+  s.homepage      = "https://github.com/ageweke/required_scopes"
+  s.license       = "MIT"
+
+  s.files         = `git ls-files`.split($/)
+  s.executables   = s.files.grep(%r{^bin/}) { |f| File.basename(f) }
+  s.test_files    = s.files.grep(%r{^(test|spec|features)/})
+  s.require_paths = ["lib"]
+
+  s.add_development_dependency "bundler", "~> 1.3"
+  s.add_development_dependency "rake"
+  s.add_development_dependency "rspec", "~> 2.14"
+
+  if (RUBY_VERSION =~ /^1\.9\./ || RUBY_VERSION =~ /^2\./) && ((! defined?(RUBY_ENGINE)) || (RUBY_ENGINE != 'jruby'))
+    s.add_development_dependency "pry"
+    s.add_development_dependency "pry-debugger"
+    s.add_development_dependency "pry-stack_explorer"
+  end
+
+  ar_version = ENV['REQUIRED_SCOPES_AR_TEST_VERSION']
+  ar_version = ar_version.strip if ar_version
+
+  version_spec = case ar_version
+  when nil then [ ">= 3.0", "<= 4.99.99" ]
+  when 'master' then nil
+  else [ "=#{ar_version}" ]
+  end
+
+  if version_spec
+    s.add_dependency("activerecord", *version_spec)
+  end
+
+  s.add_dependency "activesupport", ">= 3.0", "<= 4.99.99"
+
+  require File.expand_path(File.join(File.dirname(__FILE__), 'spec', 'required_scopes', 'helpers', 'database_helper'))
+  database_gem_name = RequiredScopes::Helpers::DatabaseHelper.maybe_database_gem_name
+
+  # Ugh. Later versions of the 'mysql2' gem are incompatible with AR 3.0.x; so, here, we explicitly trap that case
+  # and use an earlier version of that Gem.
+  if database_gem_name && database_gem_name == 'mysql2' && ar_version && ar_version =~ /^3\.0\./
+    s.add_development_dependency('mysql2', '~> 0.2.0')
+  else
+    s.add_development_dependency(database_gem_name)
+  end
+end

data/spec/required_scopes/helpers/database_helper.rb

@@ -0,0 +1,174 @@
+module RequiredScopes
+  module Helpers
+    class DatabaseHelper
+      class InvalidDatabaseConfigurationError < StandardError; end
+
+      class << self
+        def maybe_database_gem_name
+          begin
+            dh = new
+            dh.database_gem_name
+          rescue InvalidDatabaseConfigurationError => idce
+            nil
+          end
+        end
+      end
+
+      def initialize
+        config # make sure we raise on instantiation if configuration is invalid
+      end
+
+      def database_type
+        case database_gem_name
+        when /mysql/i then :mysql
+        when /sqlite/i then :sqlite
+        when /pg/i, /postgres/i then :postgres
+        else raise "Unknown database type for Gem name: #{database_gem_name.inspect}"
+        end
+      end
+
+      def setup_activerecord!
+        require 'active_record'
+        require config[:require]
+        ::ActiveRecord::Base.establish_connection(config[:config])
+
+        require 'logger'
+        require 'stringio'
+        @logs = StringIO.new
+        ::ActiveRecord::Base.logger = Logger.new(@logs)
+
+        if config[:config][:adapter] == 'sqlite3'
+          sqlite_version = ::ActiveRecord::Base.connection.send(:sqlite_version).instance_variable_get("@version").inspect rescue "unknown"
+        end
+      end
+
+      def table_name(name)
+        "rec_spec_#{name}"
+      end
+
+      def database_gem_name
+        config[:database_gem_name]
+      end
+
+      private
+      def config
+        config_from_config_file || travis_ci_config_from_environment || invalid_config_file!
+      end
+
+      def config_from_config_file
+        return nil unless File.exist?(config_file_path)
+        require config_file_path
+
+        return nil unless defined?(REQUIRED_SCOPES_SPEC_DATABASE_CONFIG)
+        return nil unless REQUIRED_SCOPES_SPEC_DATABASE_CONFIG.kind_of?(Hash)
+
+        return nil unless REQUIRED_SCOPES_SPEC_DATABASE_CONFIG[:require]
+        return nil unless REQUIRED_SCOPES_SPEC_DATABASE_CONFIG[:database_gem_name]
+
+        return nil unless REQUIRED_SCOPES_SPEC_DATABASE_CONFIG
+        REQUIRED_SCOPES_SPEC_DATABASE_CONFIG
+      end
+
+      def travis_ci_config_from_environment
+        dbtype = (ENV['REQUIRED_SCOPES_TRAVIS_CI_DATABASE_TYPE'] || '').strip.downcase
+        is_jruby = defined?(RUBY_ENGINE) && RUBY_ENGINE == 'jruby'
+
+        if is_jruby
+          case dbtype
+          when 'mysql'
+            {
+              :require => 'activerecord-jdbcmysql-adapter',
+              :database_gem_name => 'activerecord-jdbcmysql-adapter',
+              :config => {
+                :adapter => 'jdbcmysql',
+                :database => 'myapp_test',
+                :username => 'travis',
+                :encoding => 'utf8'
+              }
+            }
+          when 'postgres', 'postgresql'
+            {
+              :require => 'activerecord-jdbcpostgresql-adapter',
+              :database_gem_name => 'activerecord-jdbcpostgresql-adapter',
+              :config => {
+                :adapter => 'jdbcpostgresql',
+                :database => 'myapp_test',
+                :username => 'postgres'
+              }
+            }
+          when 'sqlite'
+            {
+              :require => 'activerecord-jdbcsqlite3-adapter',
+              :database_gem_name => 'activerecord-jdbcsqlite3-adapter',
+              :config => {
+                :adapter => 'jdbcsqlite3',
+                :database => ':memory:'
+              }
+            }
+          when '', nil then nil
+          else
+            raise "Unknown Travis CI database type: #{dbtype.inspect}"
+          end
+        else
+          case dbtype
+          when 'postgres', 'postgresql'
+            {
+              :require => 'pg',
+              :database_gem_name => 'pg',
+              :config => {
+                :adapter => 'postgresql',
+                :database => 'myapp_test',
+                :username => 'postgres',
+                :min_messages => 'WARNING'
+              }
+            }
+          when 'mysql'
+            {
+              :require => 'mysql2',
+              :database_gem_name => 'mysql2',
+              :config => {
+                :adapter => 'mysql2',
+                :database => 'myapp_test',
+                :username => 'travis',
+                :encoding => 'utf8'
+              }
+            }
+          when 'sqlite'
+            {
+              :require => 'sqlite3',
+              :database_gem_name => 'sqlite3',
+              :config => {
+                :adapter => 'sqlite3',
+                :database => ':memory:',
+                :timeout => 500
+              }
+            }
+          when '', nil then nil
+          else
+            raise "Unknown Travis CI database type: #{dbtype.inspect}"
+          end
+        end
+      end
+
+      def config_file_path
+        @config_file_path ||= File.expand_path(File.join(File.dirname(__FILE__), '..', '..', '..', 'spec_database_config.rb'))
+      end
+
+      def invalid_config_file!
+        raise Errno::ENOENT, %{In order to run specs for required_scopes, you need to create a file at:
+
+#{config_file_path}
+
+...that defines a top-level REQUIRED_SCOPES_SPEC_DATABASE_CONFIG hash, with members:
+
+  :require => 'name_of_adapter_to_require',
+  :database_gem_name => 'name_of_gem_for_adapter',
+  :config  => { ...whatever ActiveRecord::Base.establish_connection should be passed... }
+
+Alternatively, if you're running under Travis CI, you can set the environment variable
+REQUIRED_SCOPES_TRAVIS_CI_DATABASE_TYPE to 'postgres', 'mysql', or 'sqlite', and it will
+use the correct configuration for testing on Travis CI.}
+      end
+    end
+  end
+end