rolify 2.2.2 → 3.0.0

data/.travis.yml

@@ -1,12 +1,16 @@
 rvm:
-  - 1.8.7
-  - 1.9.2
-  - 1.9.3
-  - ruby-head
-  - rbx
-  - jruby
-  - ree
+    - 1.8.7
+    - 1.9.3
+    - ruby-head
+    - rbx
+    - jruby
+    - ree
+
+env:
+    - ADAPTER=active_record
+    - ADAPTER=mongoid
 
 before_install:
   - gem update --system
   - gem --version
+  - ruby -v

data/CHANGELOG.rdoc

@@ -1,3 +1,9 @@
+= 3.0 (unreleased)
+* support for Mongoid
+* roles search on resources on instance level (e.g. <tt>Forum.first.roles</tt>) and class level (e.g. <tt>Forum.with_role("admin", user)</tt>)
+* heavy lifting and redesign of the library, code and specs refactoring
+* enhanced drastically specs coverage: 1001 examples !
+
 = 2.2.2 (Feb 17, 2012)
 * fixed another bug occurring when dynamic shortcuts is enabled
 * display now a README file after running the generator to show the next setup steps

data/README.rdoc

@@ -1,4 +1,4 @@
-= rolify {<img src="https://secure.travis-ci.org/EppO/rolify.png?branch=v3">}[http://travis-ci.org/EppO/rolify] {<img src="https://gemnasium.com/EppO/rolify.png">}[https://gemnasium.com/EppO/rolify]
+= rolify {<img src="https://secure.travis-ci.org/EppO/rolify.png?branch=master">}[http://travis-ci.org/EppO/rolify] {<img src="https://gemnasium.com/EppO/rolify.png">}[https://gemnasium.com/EppO/rolify]
 
 Very simple Roles library without any authorization enforcement supporting scope on resource object.
 
@@ -12,7 +12,7 @@ This library was intended to be used with CanCan[https://github.com/ryanb/cancan
 == Requirements
 
 * >= Rails 3.1
-* ActiveRecord ORM
+* ActiveRecord ORM <b>or</b> Mongoid
 * supports ruby 1.8/1.9, REE, JRuby and Rubinius
 
 == Installation
@@ -36,7 +36,9 @@ First, create your Role model and migration file using this generator:
 Role and User classes are the default. You can specify any Role class name you want. This is completly a new file so any name can do the job.
 For the User class name, you would probably use the one provided by your authentication solution. rolify just adds some class methods in an existing User class.
 
-=== 2. Run the migration
+If you want to use Mongoid instead of ActiveRecord, follow these instructions[https://github.com/EppO/rolify/wiki/Configuration], and skip to step #3
+
+=== 2. Run the migration (only required when using ActiveRecord)
 
 Let's migrate !
 
@@ -99,7 +101,37 @@ A global role overrides resource role request:
   user.has_role? "moderator", Forum.last
   => true
 
-Please see on {the wiki}[https://github.com/EppO/rolify/wiki/Usage] for all the available commands and the {Tutorial}[https://github.com/EppO/rolify/wiki/Tutorial] to understand how to use {rolify}[http://eppo.github.com/rolify] with {Devise}[https://github.com/plataformatec/devise] and {CanCan}[https://github.com/ryanb/cancan].
+=== 5. Resource roles querying 
+
+Starting from rolify 3.0, you can search roles on instance level or class level resources.
+
+==== Instance level
+
+  forum = Forum.first
+  forum.roles
+  # => [ list of roles that are only binded to forum instance ]
+  forum.applied_roles
+  # => [ list of roles binded to forum instance and to the Forum class ]
+
+==== Class level
+
+  Forum.with_role("admin")
+  # => [ list of Forum instances that has role "admin" binded to it ] 
+  Forum.with_role("admin", current_user)
+  # => [ list of Forum instances that has role "admin" binded to it and belongs to current_user roles ]
+  
+  Forum.find_roles
+  # => [ list of roles that binded to any Forum instance or to the Forum class ]
+  Forum.find_roles("admin")
+  # => [ list of roles that binded to any Forum instance or to the Forum class with "admin" as a role name ]
+  Forum.find_roles("admin", current_user)
+  # => [ list of roles that binded to any Forum instance or to the Forum class with "admin" as a role name and belongs to current_user roles ]
+
+== Resources
+
+* {Wiki}[https://github.com/EppO/rolify/wiki]
+* {Usage}[https://github.com/EppO/rolify/wiki/Usage]: all the available commands
+* {Tutorial}[https://github.com/EppO/rolify/wiki/Tutorial]: how to use {rolify}[http://eppo.github.com/rolify] with {Devise}[https://github.com/plataformatec/devise] and {CanCan}[https://github.com/ryanb/cancan].
 
 == Questions or Problems?
 

data/UPGRADE.rdoc

@@ -0,0 +1,22 @@
+= Upgrade instructions for Rolify library
+
+== From a previous rolify installation (1.x or 2.x)
+
+The easiest way is to re-run the generator using <tt>rails g Rolify:Role</tt> command, and overwrite the initializer file. Both the migration file and the <tt>role.rb</tt> haven't changed.
+In the <tt>config/initializers/rolify.rb</tt> file, here are the deprecated settings:
+* <tt>role_cname</tt>
+* <tt>user_cname</tt>
+By default, these settings were commented out, so you can safely remove them. 
+If you changed them, you can remove them in the initializer file too. <tt>user_cname</tt> is no longer used in 3.x, you don't need it anymore.
+Add your custom <tt>role_cname</tt> setting as argument of the rolify method you use in your User class. 
+For instance, if you use <tt>Privilege</tt> as <tt>Role</tt> class, you should add this to your whatever your <tt>User</tt> class is, let's say <tt>Client</tt> for the sake of example: 
+   class Client < ActiveRecord::Base
+     rolify :role_cname => "Privilege"
+   end
+If you use the default <tt>Role</tt> class name, you don't have to specify the <tt>:role_cname</tt> argument.
+
+If you use <i>dynamic methods</i> (<tt>user.is_admin?</tt> like methods), you should turn it on using <tt>use_dynamic_shortcuts</tt> method starting from rolify 3.0:
+   Rolify.configure do |c|
+      c.use_dynamic_shortcuts
+   end
+The old fashion way still works though, but won't work anymore if the setter method name is changed in a possible future. You've been warned :-)

data/lib/generators/rolify/role/role_generator.rb

@@ -8,22 +8,21 @@ module Rolify
       source_root File.expand_path('../templates', __FILE__)
       argument :role_cname, :type => :string, :default => "Role"
       argument :user_cname, :type => :string, :default => "User"
+      argument :orm_adapter, :type => :string, :default => "active_record"
       class_option :dynamic_shortcuts, :type => :boolean, :default => false
 
       desc "Generates a model with the given NAME and a migration file."
 
       def generate_role
-        template "role.rb", "app/models/#{role_cname.downcase}.rb"
+        template "role-#{orm_adapter}.rb", "app/models/#{role_cname.downcase}.rb"
         inject_into_class(model_path, user_cname.camelize) do
-          "  include Rolify::Roles\n" + 
-          "  #{'# ' if !options[:dynamic_shortcuts]}extend Rolify::Dynamic\n" + 
-          "  has_and_belongs_to_many :roles#{", :class_name => \"" + role_cname.camelize + "\"" if role_cname != "Role"}, :join_table => :#{user_cname.tableize + "_" + role_cname.tableize}\n"
+          "\trolify\n"
         end
       end
 
       def copy_role_file
         template "initializer.rb", "config/initializers/rolify.rb"
-        migration_template "migration.rb", "db/migrate/rolify_create_#{role_cname.tableize}"
+        migration_template "migration.rb", "db/migrate/rolify_create_#{role_cname.tableize}" if orm_adapter == "active_record"
       end
 
       def model_path
@@ -35,7 +34,7 @@ module Rolify
       end
       
       def show_readme
-        readme "README" if behavior == :invoke
+        readme "README-#{orm_adapter}" if behavior == :invoke
       end
     end
   end

data/lib/generators/rolify/role/templates/README-active_record

@@ -0,0 +1,21 @@
+===============================================================================
+
+An initializer file has been created here: config/initializers/rolify.rb, you 
+can change rolify settings to match your needs. 
+Defaults values are commented out.
+
+A Role class has been been created in app/models (with the name you gave as 
+argument otherwise the default is role.rb), you can add your own business logic 
+inside.
+
+Inside your User class (or the name you gave as argument otherwise the default 
+is user.rb), rolify method has been inserted to provide rolify methods.
+
+Now, if you just have to run the migration using rake command:
+
+   rake db:migrate
+
+and you will be able to add the resourcify method inside all models you want 
+scoped by a role.
+
+===============================================================================

data/lib/generators/rolify/role/templates/README-mongoid

@@ -0,0 +1,17 @@
+===============================================================================
+
+An initializer file has been created here: config/initializers/rolify.rb, you 
+can change rolify settings to match your needs. 
+Defaults values are commented out.
+
+A Role class has been been created in app/models (with the name you gave as 
+argument otherwise the default is role.rb), you can add your own business logic 
+inside.
+
+Inside your User class (or the name you gave as argument otherwise the default 
+is user.rb), rolify method has been inserted to provide rolify methods.
+
+Now, if you are able to add the resourcify method inside all models you want 
+scoped by a role.
+
+===============================================================================

data/lib/generators/rolify/role/templates/initializer.rb

@@ -1,8 +1,7 @@
 Rolify.configure do |c|
-  # User class to put the roles association. Default is: "User"
-  <%= "# " if user_cname == "User" %>c.user_cname = "<%= user_cname %>"
-  # Role class provided by Rolify. Default is: "Role"
-  <%= "# " if role_cname == "Role" %>c.role_cname = "<%= role_cname %>"
-  # Dynamic shortcuts for Role class (user.is_admin? like methods). Default is: false
-  <%= "# " if !options[:dynamic_shortcuts] %>c.dynamic_shortcuts = <%= options[:dynamic_shortcuts] == true ? true : false %> if defined?(Rails::Server) || defined?(Rails::Console)
+  # By default ORM adapter is ActiveRecord. uncomment to use mongoid
+  <%= "# " if orm_adapter == "active_record" %>c.use_mongoid
+  
+  # Dynamic shortcuts for User class (user.is_admin? like methods). Default is: false
+  <%= "# " if !options[:dynamic_shortcuts] %>c.use_dynamic_shortcuts
 end

data/lib/generators/rolify/role/templates/role-mongoid.rb

@@ -0,0 +1,8 @@
+class <%= role_cname.camelize %>
+  include Mongoid::Document
+  
+  has_and_belongs_to_many :<%= user_cname.tableize %>
+  belongs_to :resource, :polymorphic => true
+  
+  field :name, :type => String
+end

data/lib/rolify/adapters/active_record.rb

@@ -0,0 +1,83 @@
+require 'rolify/adapters/base'
+
+module Rolify
+  module Adapter   
+    class ActiveRecord < Adapter::Base    
+      def find(relation, role_name, resource)
+        query, values = build_query(role_name, resource)
+        relation.where(query, *values)
+      end
+
+      def where(relation, args)
+        conditions, values = build_conditions(relation, args)
+        relation.where(conditions, *values)
+      end
+
+      def find_or_create_by(role_name, resource_type = nil, resource_id = nil)
+        role_class.find_or_create_by_name_and_resource_type_and_resource_id(role_name, resource_type, resource_id)
+      end
+
+      def add(relation, role)
+        relation.role_ids |= [role.id]
+      end
+
+      def remove(relation, role_name, resource = nil)
+        role = relation.where(:name => role_name)
+        role = role.where(:resource_type => (resource.is_a?(Class) ? resource.to_s : resource.class.name)) if resource
+        role = role.where(:resource_id => resource.id) if resource && !resource.is_a?(Class)
+        relation.delete(role) if role
+      end
+
+      def resources_find(roles_table, relation, role_name)
+        resources = relation.joins("INNER JOIN \"#{roles_table}\" ON \"#{roles_table}\".\"resource_type\" = '#{relation.to_s}'")
+        resources = resources.where("#{roles_table}.name = ? AND #{roles_table}.resource_type = ?", role_name, relation.to_s)
+        resources
+      end
+
+      def in(relation, roles)
+        relation.where("#{role_class.to_s.tableize}.id IN (?) AND ((resource_id = #{relation.table_name}.id) OR (resource_id IS NULL))", roles)
+      end
+
+      def exists?(relation, column)
+        relation.where("#{column} IS NOT NULL")
+      end
+
+      private
+
+      def build_conditions(relation, args)
+        conditions = []
+        values = []
+        args.each do |arg|
+          if arg.is_a? Hash
+            a, v = build_query(arg[:name], arg[:resource])
+          elsif arg.is_a?(String) || arg.is_a?(Symbol)
+            a, v = build_query(arg.to_s)
+          else
+            raise ArgumentError, "Invalid argument type: only hash or string or a symbol allowed"
+          end
+          conditions << a
+          values += v
+        end
+        conditions = conditions.join(' OR ')
+        [ conditions, values ]
+      end
+
+      def build_query(role, resource = nil)
+        return [ "name = ?", [ role ] ] if resource == :any
+        query = "((name = ?) AND (resource_type IS NULL) AND (resource_id IS NULL))"
+        values = [ role ]
+        if resource
+          query.insert(0, "(")
+          query += " OR ((name = ?) AND (resource_type = ?) AND (resource_id IS NULL))" 
+          values << role << (resource.is_a?(Class) ? resource.to_s : resource.class.name)
+          if !resource.is_a? Class
+            query += " OR ((name = ?) AND (resource_type = ?) AND (resource_id = ?))" 
+            values << role << resource.class.name << resource.id
+          end
+          query += ")"
+        end
+        [ query, values ]
+      end
+    end
+  end
+end

data/lib/rolify/adapters/base.rb

@@ -0,0 +1,53 @@
+module Rolify
+  module Adapter
+    class Base
+      def initialize(role_cname)
+        @role_cname = role_cname
+      end
+      
+      def role_class
+        @role_cname.constantize
+      end
+      
+      def find(relation, role_name, resource)
+        raise NotImplementedError.new("You must implement find")
+      end
+      
+      def where(relation, args)
+        raise NotImplementedError.new("You must implement where")
+      end
+      
+      def find_or_create_by(role_name, resource_type = nil, resource_id = nil)
+        raise NotImplementedError.new("You must implement find_or_create_by")
+      end
+      
+      def add(relation, role_name, resource = nil)
+        raise NotImplementedError.new("You must implement add")
+      end
+      
+      def remove(relation, role_name, resource = nil)
+        raise NotImplementedError.new("You must implement delete")
+      end
+      
+      def resources_find(roles_table, relation, role_name)
+       raise NotImplementedError.new("You must implement resources_find")
+      end
+      
+      def in(resources, roles)
+        raise NotImplementedError.new("You must implement in")
+      end
+      
+      def exists?(relation, column)
+        raise NotImplementedError.new("You must implement exists?")
+      end
+      
+      def build_conditions(relation, args)
+        raise NotImplementedError.new("You must implement build_conditions")
+      end
+      
+      def build_query(role, resource = nil)
+        raise NotImplementedError.new("You must implement build_query")
+      end
+    end
+  end
+end

data/lib/rolify/adapters/mongoid.rb

@@ -0,0 +1,87 @@
+require 'rolify/adapters/base'
+
+module Rolify
+  module Adapter  
+    class Mongoid < Adapter::Base
+      def find(relation, role_name, resource)
+        query = build_query(role_name, resource)
+        query.each do |condition|
+          criteria = relation.where(condition)
+          return criteria.all if !criteria.empty?
+        end
+        []
+      end
+
+      def where(relation, args)
+        conditions = build_conditions(relation, args)
+        relation.any_of(*conditions)
+      end
+
+      def find_or_create_by(role_name, resource_type = nil, resource_id = nil)
+        self.role_class.find_or_create_by(:name => role_name, 
+                                          :resource_type => resource_type, 
+                                          :resource_id => resource_id)
+      end
+
+      def add(relation, role)
+        relation.roles << role
+      end
+
+      def remove(relation, role_name, resource = nil)
+        role = { :name => role_name }
+        role.merge!({:resource_type => (resource.is_a?(Class) ? resource.to_s : resource.class.name)}) if resource
+        role.merge!({ :resource_id => resource.id }) if resource && !resource.is_a?(Class)
+        relation.where(role).destroy_all
+      end
+
+      def resources_find(roles_table, relation, role_name)
+        roles = roles_table.classify.constantize.where(:name => role_name, :resource_type => relation.to_s)
+        resources = []
+        roles.each do |role|
+          return relation.all if role.resource_id.nil?
+          resources << role.resource
+        end
+        resources
+      end
+
+      def in(resources, roles)
+        return [] if resources.empty? || roles.empty?
+        resources.delete_if { |resource| (resource.applied_roles && roles).empty? }
+        resources
+      end
+
+      def exists?(relation, column)
+        relation.where(column.to_sym.ne => nil)
+      end
+
+      private
+
+      def build_conditions(relation, args)
+        conditions = []
+        args.each do |arg|
+          if arg.is_a? Hash
+            query = build_query(arg[:name], arg[:resource])
+          elsif arg.is_a?(String) || arg.is_a?(Symbol)
+            query = build_query(arg)
+          else
+            raise ArgumentError, "Invalid argument type: only hash or string or symbol allowed"
+          end
+          conditions += query
+        end
+        conditions
+      end
+
+      def build_query(role, resource = nil)
+        return [{ :name => role }] if resource == :any
+        query = [{ :name => role, :resource_type => nil, :resource_id => nil }]
+        if resource
+          query << { :name => role, :resource_type => (resource.is_a?(Class) ? resource.to_s : resource.class.name), :resource_id => nil }
+          if !resource.is_a? Class
+            query << { :name => role, :resource_type => resource.class.name, :resource_id => resource.id }
+          end
+        end
+        query
+      end
+    end
+  end
+end

data/lib/rolify/configure.rb

@@ -0,0 +1,40 @@
+module Rolify
+  module Configure
+    @@dynamic_shortcuts = false
+    @@orm = "active_record"
+     
+    def configure
+      yield self if block_given?
+    end
+
+    def dynamic_shortcuts
+      @@dynamic_shortcuts || false
+    end
+
+    def dynamic_shortcuts=(is_dynamic)
+      @@dynamic_shortcuts = is_dynamic
+    end
+
+    def orm
+      @@orm
+    end
+
+    def orm=(orm)
+      @@orm = orm
+    end
+
+    def use_mongoid
+      self.orm = "mongoid"
+    end
+    
+    def use_dynamic_shortcuts
+      self.dynamic_shortcuts = true #if defined?(Rails::Server) || defined?(Rails::Console)
+    end
+
+    def use_defaults
+      @@dynamic_shortcuts = false
+      @@orm = "active_record"
+      @@adapter = Rolify::Adapter::ActiveRecord.new("Role")
+    end
+  end
+end

data/lib/rolify/dynamic.rb

@@ -0,0 +1,21 @@
+module Rolify
+  module Dynamic
+    def load_dynamic_methods
+      self.role_class.all.each do |r|
+        define_dynamic_method(r.name, r.resource)
+      end
+    end
+
+    def define_dynamic_method(role_name, resource)
+      class_eval do 
+        define_method("is_#{role_name}?".to_sym) do
+          has_role?("#{role_name}")
+        end if !method_defined?("is_#{role_name}?".to_sym)
+
+        define_method("is_#{role_name}_of?".to_sym) do |arg|
+          has_role?("#{role_name}", arg)
+        end if !method_defined?("is_#{role_name}_of?".to_sym) && !!resource
+      end
+    end
+  end
+end

data/lib/rolify/railtie.rb

@@ -0,0 +1,20 @@
+require 'rolify'
+require 'rails'
+
+module Rolify
+  class Railtie < Rails::Railtie
+    initializer 'rolify.initialize' do
+      ActiveSupport.on_load(:active_record) do
+        ActiveRecord::Base.send :extend, Rolify
+      end
+      
+      config.after_initialize do
+        ::Mongoid::Document.module_eval do
+          def self.included(base)
+            base.extend Rolify
+          end
+        end
+      end if defined?(Mongoid)
+    end
+  end
+end

data/lib/rolify/resource.rb

@@ -0,0 +1,25 @@
+module Rolify
+  module Resource
+    def self.included(base)
+      base.extend ClassMethods
+    end
+
+    module ClassMethods 
+      def find_roles(role_name = nil, user = nil)
+        roles = user && (user != :any) ? user.roles : self.role_class
+        roles = roles.where(:resource_type => self.to_s)
+        roles = roles.where(:name => role_name) if role_name && (role_name != :any)
+        roles
+      end
+
+      def with_role(role_name, user = nil)
+        resources = self.adapter.resources_find(self.role_class.to_s.tableize, self, role_name)
+        user ? self.adapter.in(resources, user.roles.where(:name => role_name)) : resources
+      end
+    end
+    
+    def applied_roles
+      self.roles + self.class.role_class.where(:resource_type => self.class.to_s, :resource_id => nil)
+    end
+  end
+end