careacademy-acl9 3.3.0

data/lib/acl9/model_extensions/for_subject.rb

@@ -0,0 +1,232 @@
+require_relative "../prepositions"
+
+module Acl9
+  module ModelExtensions
+    module ForSubject
+      include Prepositions
+
+      DEFAULT = Class.new do
+        def default?
+          true
+        end
+      end.new.freeze
+
+      ##
+      # Role check.
+      #
+      # There is a global option, +Acl9.config[:protect_global_roles]+, which governs
+      # this method behavior.
+      #
+      # If protect_global_roles is +false+, an object role is automatically counted
+      # as global role. E.g.
+      #
+      #   Acl9.config[:protect_global_roles] = false
+      #   user.has_role!(:manager, @foo)
+      #   user.has_role?(:manager, @foo)  # => true
+      #   user.has_role?(:manager)        # => true
+      #
+      # In this case manager is anyone who "manages" at least one object.
+      #
+      # However, if protect_global_roles option set to +true+, you'll need to
+      # explicitly grant global role with same name.
+      #
+      #   Acl9.config[:protect_global_roles] = true
+      #   user.has_role!(:manager, @foo)
+      #   user.has_role?(:manager)        # => false
+      #   user.has_role!(:manager)
+      #   user.has_role?(:manager)        # => true
+      #
+      # protect_global_roles option is +false+ by default as for now, but this
+      # may change in future!
+      #
+      # @return [Boolean] Whether +self+ has a role +role_name+ on +object+.
+      # @param [Symbol,String] role_name Role name
+      # @param [Object] object Object to query a role on
+      #
+      # @see Acl9::ModelExtensions::Object#accepts_role?
+      def has_role?(role_name, object = default)
+        check! object
+        role_name = normalize role_name
+        object = _by_preposition object
+
+        !! if object == default && !::Acl9.config[:protect_global_roles]
+          _role_objects.find_by_name(role_name.to_s) ||
+          _role_objects.member?(get_role(role_name, object))
+        else
+          role = get_role(role_name, object)
+          role && _role_objects.exists?(role.id)
+        end
+      end
+
+      ##
+      # Add specified role on +object+ to +self+.
+      #
+      # @param [Symbol,String] role_name Role name
+      # @param [Object] object Object to add a role for
+      # @see Acl9::ModelExtensions::Object#accepts_role!
+      def has_role!(role_name, object = default)
+        check! object
+        role_name = normalize role_name
+        object = _by_preposition object
+
+        role = get_role(role_name, object)
+
+        if role.nil?
+          role_attrs = case object
+                       when Class   then { :authorizable_type => object.to_s }
+                       when default then {}
+                       else              { :authorizable => object }
+                       end.merge({ :name => role_name.to_s })
+
+          role = _auth_role_class.create(role_attrs)
+        end
+
+        _role_objects << role if role && !_role_objects.exists?(role.id)
+      end
+
+      ##
+      # Free +self+ from a specified role on +object+.
+      #
+      # @param [Symbol,String] role_name Role name
+      # @param [Object] object Object to remove a role on
+      # @see Acl9::ModelExtensions::Object#accepts_no_role!
+      def has_no_role!(role_name, object = default)
+        check! object
+        role_name = normalize role_name
+        object = _by_preposition object
+        delete_role(get_role(role_name, object))
+      end
+
+      ##
+      # Are there any roles for +self+ on +object+?
+      #
+      # @param [Object] object Object to query roles
+      # @return [Boolean] Returns true if +self+ has any roles on +object+.
+      # @see Acl9::ModelExtensions::Object#accepts_roles_by?
+      def has_roles_for?(object)
+        check! object
+        !!_role_objects.detect(&role_selecting_lambda(object))
+      end
+
+      alias :has_role_for? :has_roles_for?
+
+      ##
+      # Which roles does +self+ have on +object+?
+      #
+      # @return [Array<Role>] Role instances, associated both with +self+ and +object+
+      # @param [Object] object Object to query roles
+      # @see Acl9::ModelExtensions::Object#accepted_roles_by
+      # @example
+      #   user = User.find(...)
+      #   product = Product.find(...)
+      #
+      #   user.roles_for(product).map(&:name).sort  #=> role names in alphabetical order
+      def roles_for(object)
+        check! object
+        _role_objects.select(&role_selecting_lambda(object))
+      end
+
+      ##
+      # Unassign any roles on +object+ from +self+.
+      #
+      # @param [Object,default] object Object to unassign roles for. Empty args means unassign global roles.
+      def has_no_roles_for!(object = default)
+        check! object
+        roles_for(object).each { |role| delete_role(role) }
+      end
+
+      ##
+      # Unassign all roles from +self+.
+      def has_no_roles!
+        # for some reason simple
+        #
+        #   roles.each { |role| delete_role(role) }
+        #
+        # doesn't work. seems like a bug in ActiveRecord
+        _role_objects.map(&:id).each do |role_id|
+          delete_role _auth_role_class.find(role_id)
+        end
+      end
+
+      private
+
+      def role_selecting_lambda(object)
+        case object
+        when Class
+          lambda { |role| role.authorizable_type == object.to_s }
+        when default
+          lambda { |role| role.authorizable.nil? }
+        else
+          lambda do |role|
+            auth_id = role.authorizable_id.kind_of?(String) ? object.id.to_s : object.id
+            role.authorizable_type == object.class.base_class.to_s && role.authorizable_id == auth_id
+          end
+        end
+      end
+
+      def get_role(role_name, object = default)
+        check! object
+        role_name = normalize role_name
+
+        cond = case object
+               when Class
+                 [ 'name = ? and authorizable_type = ? and authorizable_id IS NULL', role_name, object.to_s ]
+               when default
+                 [ 'name = ? and authorizable_type IS NULL and authorizable_id IS NULL', role_name ]
+               else
+                 [
+                   'name = ? and authorizable_type = ? and authorizable_id = ?',
+                   role_name, object.class.base_class.to_s, object.id
+                 ]
+               end
+
+        if _auth_role_class.respond_to?(:where)
+          _auth_role_class.where(cond).first
+        else
+          _auth_role_class.find(:first, :conditions => cond)
+        end
+      end
+
+      def delete_role(role)
+        if role
+          if ret = _role_objects.delete(role)
+            if role.send(_auth_subject_class_name.demodulize.tableize).empty?
+              ret &&= role.destroy unless role.respond_to?(:system?) && role.system?
+            end
+          end
+          ret
+        end
+      end
+
+      def normalize role_name
+        Acl9.config[:normalize_role_names] ? role_name.to_s.underscore.singularize : role_name.to_s
+      end
+
+      private
+
+      def check! object
+        raise NilObjectError if object.nil?
+      end
+
+      def _by_preposition object
+        object.is_a?(Hash) ? super : object
+      end
+
+      def _auth_role_class
+        self.class._auth_role_class_name.constantize
+      end
+
+      def _auth_role_assoc
+        self.class._auth_role_assoc_name
+      end
+
+      def _role_objects
+        send(_auth_role_assoc)
+      end
+
+      def default
+        DEFAULT
+      end
+    end
+  end
+end

data/lib/acl9/model_extensions.rb

@@ -0,0 +1,136 @@
+require_relative "model_extensions/for_subject"
+require_relative "model_extensions/for_object"
+
+module Acl9
+  module ModelExtensions  #:nodoc:
+    def self.included(base)
+      base.extend(ClassMethods)
+    end
+
+    module ClassMethods
+      # Add #has_role? and other role methods to the class.
+      # Makes a class a auth. subject class.
+      #
+      # @param [Hash] options the options for tuning
+      # @option options [String] :role_class_name (Acl9::config[:default_role_class_name])
+      #                           Class name of the role class (e.g. 'AccountRole')
+      # @option options [String] :join_table_name (Acl9::config[:default_join_table_name])
+      #                           Join table name (e.g. 'accounts_account_roles')
+      # @option options [String] :association_name (Acl9::config[:default_association_name])
+      #                           Association name (e.g. ':roles')
+      # @example
+      #   class User < ActiveRecord::Base
+      #     acts_as_authorization_subject
+      #   end
+      #
+      #   user = User.new
+      #   user.role_objects      #=> returns Role objects, associated with the user
+      #   user.has_role!(...)
+      #   user.has_no_role!(...)
+      #
+      #   # other functions from Acl9::ModelExtensions::Subject are made available
+      #
+      # @see Acl9::ModelExtensions::Subject
+      #
+      def acts_as_authorization_subject(options = {})
+        assoc = options[:association_name] || Acl9::config[:default_association_name]
+        role = options[:role_class_name] || Acl9::config[:default_role_class_name]
+        join_table = options[:join_table_name] || Acl9::config[:default_join_table_name] || self.table_name_prefix + [undecorated_table_name(self.to_s), undecorated_table_name(role)].sort.join("_") + self.table_name_suffix
+
+        has_and_belongs_to_many assoc.to_sym, :class_name => role, :join_table => join_table
+
+        before_destroy :has_no_roles!
+
+        cattr_accessor :_auth_role_class_name, :_auth_subject_class_name,
+                       :_auth_role_assoc_name
+
+        self._auth_role_class_name = role
+        self._auth_subject_class_name = self.to_s
+        self._auth_role_assoc_name = assoc
+
+        include Acl9::ModelExtensions::ForSubject
+      end
+
+      # Add role query and set methods to the class (making it an auth object class).
+      #
+      # @param [Hash] options the options for tuning
+      # @option options [String] :subject_class_name (Acl9::config[:default_subject_class_name])
+      #                          Subject class name (e.g. 'User', or 'Account)
+      # @option options [String] :role_class_name (Acl9::config[:default_role_class_name])
+      #                          Role class name (e.g. 'AccountRole')
+      # @example
+      #   class Product < ActiveRecord::Base
+      #     acts_as_authorization_object
+      #   end
+      #
+      #   product = Product.new
+      #   product.accepted_roles #=> returns Role objects, associated with the product
+      #   product.users          #=> returns User objects, associated with the product
+      #   product.accepts_role!(...)
+      #   product.accepts_no_role!(...)
+      #   # other functions from Acl9::ModelExtensions::Object are made available
+      #
+      # @see Acl9::ModelExtensions::Object
+      #
+      def acts_as_authorization_object(options = {})
+        subject = options[:subject_class_name] || Acl9::config[:default_subject_class_name]
+        subj_table = subject.constantize.table_name
+
+        role = options[:role_class_name] || Acl9::config[:default_role_class_name]
+
+        has_many :accepted_roles, :as => :authorizable, :class_name => role, :dependent => :destroy
+
+        subj_assoc = "assoc_#{subj_table}".to_sym
+        has_many subj_assoc, -> { distinct.readonly }, source: subj_table.to_sym, through: :accepted_roles
+
+        define_method subj_table.to_sym do |role_name=nil|
+          rel = send subj_assoc
+
+          if role_name
+            rel = rel.where role.constantize.table_name.to_sym => { name: role_name }
+          end
+          rel
+        end
+
+        include Acl9::ModelExtensions::ForObject
+      end
+
+      # Make a class an auth role class.
+      #
+      # You'll probably never create or use objects of this class directly.
+      # Various auth. subject and object methods will do that for you
+      # internally.
+      #
+      # @param [Hash] options the options for tuning
+      # @option options [String] :subject_class_name (Acl9::config[:default_subject_class_name])
+      #                          Subject class name (e.g. 'User', or 'Account)
+      # @option options [String] :join_table_name (Acl9::config[:default_join_table_name])
+      #                           Join table name (e.g. 'accounts_account_roles')
+      #
+      # @example
+      #   class Role < ActiveRecord::Base
+      #     acts_as_authorization_role
+      #   end
+      #
+      # @see Acl9::ModelExtensions::Subject#has_role!
+      # @see Acl9::ModelExtensions::Subject#has_role?
+      # @see Acl9::ModelExtensions::Subject#has_no_role!
+      # @see Acl9::ModelExtensions::Object#accepts_role!
+      # @see Acl9::ModelExtensions::Object#accepts_role?
+      # @see Acl9::ModelExtensions::Object#accepts_no_role!
+      def acts_as_authorization_role(options = {})
+        subject = options[:subject_class_name] || Acl9::config[:default_subject_class_name]
+        join_table = options[:join_table_name] || Acl9::config[:default_join_table_name] ||
+                    self.table_name_prefix + [undecorated_table_name(self.to_s), undecorated_table_name(subject)].sort.join("_") + self.table_name_suffix
+                    # comment out use deprecated API
+                    #join_table_name(undecorated_table_name(self.to_s), undecorated_table_name(subject))
+
+        has_and_belongs_to_many subject.demodulize.tableize.to_sym,
+          :class_name => subject,
+          :join_table => join_table
+
+        belongs_to :authorizable, polymorphic: true, optional: true
+      end
+    end
+  end
+end

data/lib/acl9/prepositions.rb

@@ -0,0 +1,18 @@
+module Acl9
+  module Prepositions
+    VALID_PREPOSITIONS = %i(of for in on at by).freeze unless defined? VALID_PREPOSITIONS
+
+    def _by_preposition options
+      object = nil
+
+      VALID_PREPOSITIONS.each do |prep|
+        if options[prep]
+          raise ArgumentError, "You may only use one preposition to specify object" if object
+
+          object = options[prep]
+        end
+      end
+      object
+    end
+  end
+end

data/lib/acl9/version.rb

@@ -0,0 +1,3 @@
+module Acl9
+  VERSION = "3.3.0"
+end

data/lib/acl9.rb

@@ -0,0 +1,78 @@
+require 'acl9/version'
+require 'acl9/model_extensions'
+require 'acl9/controller_extensions'
+require 'acl9/helpers'
+
+module Acl9
+  CONFIG = {
+    :default_role_class_name    => 'Role',
+    :default_subject_class_name => 'User',
+    :default_subject_method     => :current_user,
+    :default_association_name   => :role_objects,
+    :default_join_table_name    => nil,
+    :protect_global_roles       => true,
+    :normalize_role_names       => true,
+  }.freeze
+
+  class Config < Struct.new(*CONFIG.keys )
+    def [] k; send k.to_sym; end
+    def []= k, v; send "#{k}=", v; end
+    def reset!
+      Acl9::CONFIG.each do |k,v|
+        send "#{k}=", v
+      end
+    end
+
+    def merge! h
+      h.each { |k,v| self[k.to_sym] = v }
+    end
+  end
+
+  @@config = Config.new( *CONFIG.values_at(*Config.members))
+
+  mattr_reader :config
+
+  def self.configure
+    yield config
+  end
+
+  class ArgumentError < ArgumentError; end
+  class RuntimeError < RuntimeError; end
+  class NilObjectError < RuntimeError; end
+
+  ##
+  # This exception is raised whenever ACL block finds that the current user
+  # is not authorized for the controller action he wants to execute.
+  # @example How to catch this exception in ApplicationController
+  #   class ApplicationController < ActionController::Base
+  #     rescue_from 'Acl9::AccessDenied', :with => :access_denied
+  #
+  #     # ...other stuff...
+  #     private
+  #
+  #     def access_denied
+  #       if current_user
+  #         # It's presumed you have a template with words of pity and regret
+  #         # for unhappy user who is not authorized to do what he wanted
+  #         render :template => 'home/access_denied'
+  #       else
+  #         # In this case user has not even logged in. Might be OK after login.
+  #         flash[:notice] = 'Access denied. Try to log in first.'
+  #         redirect_to login_path
+  #       end
+  #     end
+  #   end
+  #
+  class AccessDenied < RuntimeError; end
+
+  ##
+  # This exception is raised when acl9 has generated invalid code for the
+  # filtering method or block. Should never happen, and it's a bug when it
+  # happens.
+  class FilterSyntaxError < ArgumentError; end
+
+end
+
+ActiveRecord::Base.send(:include, Acl9::ModelExtensions)
+AbstractController::Base.send :include, Acl9::ControllerExtensions
+Acl9Helpers = Acl9::Helpers unless defined?(Acl9Helpers)

data/lib/generators/acl9/setup/USAGE

@@ -0,0 +1,35 @@
+Description:
+    Installs the basic framework for Acl9. Creates the necessary migration for
+    your new roles table and the join table for associating roles with users.
+
+    The optional arguments are as follows:
+
+        subject:  if you want something other than 'User'
+        role:     if you want something other than 'Role'
+        objects:  space separated list of class names of objects that you can
+                  attach roles to (see the docs)
+
+Examples:
+    `rails g acl9:setup`
+
+        This will create:
+            Migration:      db/migrate/XXX_create_role_tables.rb
+            Role Model:     app/models/role.rb
+            Config:         config/initializers/acl9.rb
+
+        And it will update (or create a skeleton):
+            Subject Model:  app/models/user.rb
+
+    `rails g acl9:setup account permission school classroom department`
+
+        This will create:
+            Migration:      db/migrate/XXX_create_permission_tables.rb
+            Role Model:     app/models/permission.rb
+            Config:         config/initializers/acl9.rb
+
+        And it will update (or create a skeleton):
+            Subject Model:  app/models/account.rb
+            Object Models:  app/models/school.rb
+                            app/models/classroom.rb
+                            app/models/department.rb
+

data/lib/generators/acl9/setup/setup_generator.rb

@@ -0,0 +1,122 @@
+require "rails/generators/active_record"
+
+module Acl9
+  class SetupGenerator < Rails::Generators::Base
+    include ActiveRecord::Generators::Migration
+
+    source_root File.expand_path('../templates', __FILE__)
+
+    argument :arg_subject, type: :string, default: 'user', banner: "subject"
+    argument :arg_role, type: :string, default: 'role', banner: "role"
+    argument :arg_objects, type: :array, default: [], banner: "objects..."
+
+    def create_migration_file
+      migration_template "create_role_tables.rb", File.join(db_migrate_path, "create_#{role_name}_tables.rb")
+    end
+
+    def create_models
+      template "role.rb", "app/models/#{role_name}.rb"
+
+      objects.each do |object|
+        my_inject "app/models/#{object}.rb", object.classify, "  #{object_helper}\n"
+      end
+
+      my_inject "app/models/#{subject_name}.rb", subject_class_name, "  #{subject_helper}\n"
+    end
+
+    def create_initializer
+      initializer "acl9.rb" do
+        <<-RUBY.strip_heredoc
+        # See https://github.com/be9/acl9#configuration for details
+        #
+        # Acl9.configure do |c|
+        #   c.default_role_class_name = 'Role'
+        #   c.default_subject_class_name = 'User'
+        #   c.default_subject_method     = :current_user
+        #   c.default_association_name   = :role_objects
+        #   c.default_join_table_name    = nil
+        #   c.protect_global_roles       = true
+        #   c.normalize_role_names       = true
+        # end
+        RUBY
+      end
+    end
+
+    private
+    def role_name
+      arg_role.underscore.singularize
+    end
+
+    def role_table_name
+      role_name.tableize
+    end
+
+    def role_class_name
+      role_name.classify
+    end
+
+    def model_base_name
+      r5? ? ApplicationRecord : ActiveRecord::Base
+    end
+
+    def r5?
+      Rails.gem_version >= Gem::Version.new(5)
+    end
+
+    def habtm_table
+      Acl9.config.default_join_table_name || [ subject_name, role_name ].map(&:pluralize).sort.join('_')
+    end
+
+    def subject_helper
+      "acts_as_authorization_subject" + ( subject_options ? " #{subject_options}" : '' )
+    end
+
+    def object_helper
+      "acts_as_authorization_object" + ( object_options ? " #{object_options}" : '' )
+    end
+
+    def role_helper
+      "acts_as_authorization_role" + ( role_options ? " #{role_options}" : '' )
+    end
+
+    def my_inject file_name, class_name, string
+      inject_into_class file_name, class_name, string
+    rescue Errno::ENOENT
+      create_file file_name do
+        <<-RUBY.strip_heredoc
+        class #{class_name} < ActiveRecord::Base
+        #{string}
+        end
+        RUBY
+      end
+    end
+
+    def role_options
+      if defined?(Acl9::config) && Acl9::config[:default_subject_class_name].to_s.classify != subject_class_name
+        "subject_class_name: #{subject_class_name}"
+      end
+    end
+
+    def subject_options
+      if defined?(Acl9::config) && Acl9::config[:default_role_class_name].to_s.classify != role_class_name
+        "role_class_name: #{role_class_name}"
+      end
+    end
+
+    def object_options
+      [ role_options, subject_options ].compact.join ', '
+    end
+
+    def subject_name
+      @subject_name ||= arg_subject.underscore.singularize
+    end
+
+    def objects
+      @objects ||= arg_objects.map{|o|o.underscore.singularize}
+    end
+
+    def subject_class_name
+      subject_name.classify
+    end
+  end
+end

data/lib/generators/acl9/setup/templates/create_role_tables.rb

@@ -0,0 +1,31 @@
+class Create<%= role_class_name %>Tables < ActiveRecord::Migration[<%= ActiveRecord::Migration.current_version %>]
+  def change
+    create_table :<%= role_table_name %> do |t|
+      t.string   :name,                   null: false
+      <% if r5? %>
+      t.references :authorizable, polymorphic: true
+      <% else %>
+      t.string   :authorizable_type,      null: true
+      t.integer  :authorizable_id,        null: true
+      <% end %>
+      t.boolean  :system, default: false, null: false
+      t.timestamps                        null: false
+    end
+
+    add_index :<%= role_table_name %>, :name
+
+    <% unless r5? %>
+    add_index :<%= role_table_name %>, [:authorizable_type, :authorizable_id]
+    <% end -%>
+
+    create_table :<%= habtm_table %>, id: false do |t|
+      t.references  :<%= subject_name %>, null: false
+      t.references  :<%= role_name %>, null: false
+    end
+
+    <% unless r5? %>
+    add_index :<%= habtm_table %>, :<%= subject_name %>_id
+    add_index :<%= habtm_table %>, :<%= role_name %>_id
+    <% end %>
+  end
+end

data/lib/generators/acl9/setup/templates/role.rb

@@ -0,0 +1,3 @@
+class <%= role_class_name %> < <%= model_base_name %>
+  <%= role_helper %>
+end