the_role 1.7.0 → 2.0.0

data/.travis.yml

@@ -0,0 +1,5 @@
+language: ruby
+rvm:
+  - 1.9.3
+gemfile: spec/the_role_on_devise/Gemfile
+script: "cd spec/the_role_on_devise && bin/rake db:drop RAILS_ENV=test && bin/rake db:create RAILS_ENV=test && bin/rake db:migrate RAILS_ENV=test && bundle exec rspec"

data/README.md

@@ -1,98 +1,68 @@
-# gem 'the_role'
+## TheRole - Authorization Gem for Ruby on Rails with administrative interface.
 
-| Bye bye CanCan, I got The Role! | Description |
-|:------------- |:-------------|
-| ![Bye bye CanCan, I got The Role!](https://github.com/the-teacher/the_role/raw/master/Bye_bye_CanCan_I_got_the_Role.png) | TheRole is an authorization library for Ruby on Rails which restricts what resources a given user is allowed to access. All permissions are defined in with 2-level-hash, and store in database with JSON.<br><br>TheRole - Semantic, lightweight role system with an administrative interface.<br><br>Role is a two-level hash, consisting of the **sections** and nested **rules**.<br><br>**Section** may be associated with **controller** name.<br><br>**Rule** may be associated with **action** name.<br><br>Section can have many rules.<br><br>Rule can have **true** or **false** value<br><br>**Sections** and nested **Rules** provide **ACL** (**Access Control List**)<br><br>Role **stored in the database as JSON** string.<br><br>Using of hashes, makes role system extremely easy to configure and use.<br> |
+[rubygems](http://rubygems.org/gems/the_role) | [ruby-toolbox](https://www.ruby-toolbox.com/categories/rails_authorization) | [![Build Status](https://travis-ci.org/the-teacher/the_role.png?branch=master)](https://travis-ci.org/the-teacher/the_role)
 
-### GUI
-
-No more dependencies of Bootstrap, Less, Coffee. Just pure JS and CSS for admin section.
-
-| TheRole management web interface => localhost:3000/admin/roles |
-|:-------------:|
-|![TheRole](https://github.com/the-teacher/the_role/raw/master/pic.png)|
-
-### rubygems page
-
-http://rubygems.org/gems/the_role
-
-### TheRole and Devise 2
-
-[Integration with Devise2](https://github.com/the-teacher/the_role/wiki/Integration-with-Devise2)
-
-### TheRole and Sorcery
+### Semantic, Flexible, Lightweight
 
-[Integration with Sorcery](https://github.com/the-teacher/the_role/wiki/Integration-with-Sorcery)
+<table>
+<tr>
+<th align="left">Bye bye CanCan, I got The Role!</th>
+<th align="left">Description</th>
+</tr>
+<tr>
+<td><img src="https://github.com/the-teacher/the_role/raw/master/Bye_bye_CanCan_I_got_the_Role.png" alt="Bye bye CanCan, I got The Role!"></td>
+<td>TheRole is an authorization library for Ruby on Rails which restricts what resources a given user is allowed to access. All permissions are defined in with 2-level-hash, and store in database with JSON.<br><br>TheRole - Semantic, lightweight role system with an administrative interface.<br><br>Role is a two-level hash, consisting of the <b>sections</b> and nested <b>rules</b>.<br><br><b>Section</b> may be associated with <b>controller</b> name.<br><br><b>Rule</b> may be associated with <b>action</b> name.<br><br>Section can have many rules.<br><br>Rule can have <b>true</b> or <b>false</b> value<br><br><b>Sections</b> and nested <b>Rules</b> provide <b>ACL</b> (<b>Access Control List</b>)<br><br>Role <b>stored in the database as JSON</b> string.<br><br>Using of hashes, makes role system extremely easy to configure and use.<br></td>
+</tr>
+</table>  
 
-## Want to help or improve this gem?
+### Stabile versions
 
-* Help me to create locale file for your language
-* Don't say to Ryan Bates about this project :) <3
-* Say to your friends about this project
-* I need for your feedback and issues
-* [How to start development process](https://github.com/the-teacher/the_role/wiki/Want-to-improve-this-gem%3F)
+**Rails 4**
 
-### Rspec for TheRole
+Stabile, tested, configurable. I like it ;)
 
-[Specs with Devise 2](https://github.com/the-teacher/devise2_on_the_role/tree/master/spec)
-
-Read **How to start development process** manual for running specs
-
-## What does it mean semantic?
+```
+gem "the_role", "~> 2.0.0"
+```
 
-Semantic - the science of meaning. Human should fast to understand what is happening in a role system.
+**Rails 3**
 
-Look at next Role hash. If you can understand access rules - this authorization system is semantically.
+First prototype. Not recommended for use.
 
-``` ruby
-role = {
-  'pages' => {
-    'index'   => true,
-    'show'    => true,
-    'new'     => false,
-    'edit'    => false,
-    'update'  => false,
-    'destroy' => false
-  },
-  'articles' => {
-    'index'  => true,
-    'show'   => true
-  },
-  'twitter'  => {
-    'button' => true,
-    'follow' => false
-  }
-}
+```
+gem "the_role", "~> 1.7.0"
 ```
 
-### Virtual sections and rules
+### TheRole instead CanCan?
 
-Usually, we use real names of controllers and actions for names of sections and rules:
+I think, **CanCan** it's classic solution **for programmers**. It's great for many projects! But...
 
-``` ruby
-current_user.has_role?(:pages, :show)
-```
+For endpoint users (moderators, admins) CanCan is useless, because it's hasn't default simple User Interface for role management.
 
-But, also, you can use virtual names of sections, and virtual names of section's rules.
+**TheRole** oriented **to people**. TheRole inspired by Rails **MVC** structure. If you need simple, powerful and flexible authorization system - TheRole can be useful for you.
 
-``` ruby
-current_user.has_role?(:twitter, :button)
-current_user.has_role?(:facebook, :like)
-```
+### GUI
 
-And you can use them as well as other access rules.
+<table>
+<tr>
+  <td>TheRole management web interface => localhost:3000/admin/roles</td>
+</tr>
+<tr>
+  <td><img src="https://github.com/the-teacher/the_role/raw/master/pic.png" alt="TheRole"></td>
+</tr>
+</table> 
 
-# Install
+## Install
 
 ``` ruby
-  gem 'the_role'
+gem "the_role", "~> 2.0.0"
 ```
 
 ``` ruby
-  bundle
+bundle
 ```
 
-### User Model migration
+### Change User migration
 
 Add **role_id:integer** field to your User Model
 
@@ -104,6 +74,7 @@ def self.up
     t.string :crypted_password, :default => nil
     t.string :salt,             :default => nil
 
+    # TheRole field
     t.integer :role_id,         :default => nil
 
     t.timestamps
@@ -111,60 +82,85 @@ def self.up
 end
 ```
 
-#### Generate Role Model without migration
+### Role Model
+
+Generate Role model
 
 ``` ruby
 rails g model role --migration=false
 ```
 
-#### Generate Role migration
+Change your Role model
 
-``` ruby
+```ruby
+class Role < ActiveRecord::Base
+  include RoleModel
+end
+```
+
+install TheRole migrations
+
+```ruby
 rake the_role_engine:install:migrations
 ```
 
-#### Create database and migrate
+### Invoke migration
 
-``` ruby
+```ruby
 rake db:create && rake db:migrate
 ```
 
-#### Create fake roles for test (not required)
+### Create Admin Role
+
+```
+bin/rails c
+```
 
 ``` ruby
-rake db:roles:test
+role             = Role.new
+role.name        = "admin"
+role.title       = "role for admin"
+role.description = "this user can do anything"
+role.save
+
+role.create_rule(:system, :administrator)
+role.rule_on(:system, :administrator)
+
+role.admin? # => true
 ```
 
-#### Change your ApplicationController
+### Makes any user as Admin
 
-**include TheRole::Requires** in your Application controller
+```
+User.first.update( role: Role.with_name(:admin) )
+```
+
+### Change your ApplicationController
+
+**include TheRoleController** in your Application controller
 
 Define aliases method for correctly work TheRole's controllers
 
 ``` ruby
 class ApplicationController < ActionController::Base
-  include TheRole::Requires
+  include TheRoleController
 
   protect_from_forgery
 
+  # your Access Denied processor
   def access_denied
-    render :text => 'access_denied: requires an role' and return
+    return render(text: 'access_denied: requires an role')
   end
 
-  alias_method :login_required,     :YOUR_AUTH_SYSTEM_LOGIN_REQUIRE_METHOD
+  # 1) LOGIN_REQUIRE => authenticate_user! for Devise
+  # 2) LOGIN_REQUIRE => require_login      for Sorcery
+
+  alias_method :login_required,     :LOGIN_REQUIRE
   alias_method :role_access_denied, :access_denied
 end
 ```
 
-**access_denied** or any other method for processing access denied situation
-
-#### YOUR_AUTH_SYSTEM_LOGIN_REQUIRE_METHOD!
-
-* **authenticate_user!** - method for Devise 2
-* **require_login** - method for Sorcery
-* **some_method** - from your Auth system
-
-#### Using with any controller
+### Using with any controller
 
 ``` ruby
 class PagesController < ApplicationController
@@ -178,16 +174,16 @@ class PagesController < ApplicationController
 
   def find_page
     @page = Page.find params[:id]
-    @ownership_checking_object = @page
+
+    # TheRole: You should define OWNER CHECK OBJECT
+    # When editable object was found
+    # You should to define @owner_check_object before invoke of **owner_required** method
+    @owner_check_object = @page
   end
 end
 ```
 
-### Ownership checking
-
-**owner_required** method require **@ownership_checking_object** variable, with cheked object.
-
-You should to define **@ownership_checking_object** before invoke of **owner_required** method.
+## Understanding 
 
 ### Using with Views
 
@@ -195,24 +191,10 @@ You should to define **@ownership_checking_object** before invoke of **owner_req
 <% if @user.has_role?(:twitter, :button) %>
   Twitter Button is Here
 <% else %>
-  Access Denied
+  Nothing here :(
 <% end %>
 ```
 
-### Way to set default role for new User
-
-```ruby
-class User
-  before_create :set_default_role
-
-  private
-
-  def set_default_role
-    self.role = Role.where(:name => :user).first
-  end
-end
-```
-
 ### Who is Administrator?
 
 Administrator it's a user who can access any section and the rules of your application.
@@ -258,6 +240,50 @@ Moderator of pages is owner of any page.
 
 User is owner of object, when **Object#user_id == User#id**.
 
+## What does it mean semantic?
+
+Semantic - the science of meaning. Human should fast to understand what is happening in a role system.
+
+Look at next Role hash. If you can understand access rules - this authorization system is semantically.
+
+``` ruby
+role = {
+  'pages' => {
+    'index'   => true,
+    'show'    => true,
+    'new'     => false,
+    'edit'    => false,
+    'update'  => false,
+    'destroy' => false
+  },
+  'articles' => {
+    'index'  => true,
+    'show'   => true
+  },
+  'twitter'  => {
+    'button' => true,
+    'follow' => false
+  }
+}
+```
+
+### Virtual sections and rules
+
+Usually, we use real names of controllers and actions for names of sections and rules:
+
+``` ruby
+current_user.has_role?(:pages, :show)
+```
+
+But, also, you can use virtual names of sections, and virtual names of section's rules.
+
+``` ruby
+current_user.has_role?(:twitter, :button)
+current_user.has_role?(:facebook, :like)
+```
+
+And you can use them as well as other access rules.
+
 # User Model methods
 
 Has a user an access to **rule** of **section** (action of controller)?
@@ -378,6 +404,7 @@ new_role_hash = {
 
 ### Changelog
 
+* 2.0.0 - Rails 4 ready, configurable, tests
 * 1.7.0 - mass assignment for User#role_id, doc, locales, changes in test app
 * 1.6.9 - assets precompile addon
 * 1.6.8 - doc, re dependencies
@@ -396,8 +423,6 @@ new_role_hash = {
 
 **zh_CN** by @doabit & @linjunpop
 
-... waiting for contributors
-
 ### MIT-LICENSE
 
 ##### Copyright (c) 2012 [Ilya N.Zykin]

data/app/assets/stylesheets/the_role.css.scss

@@ -0,0 +1,47 @@
+.dropdown-menu{
+  min-width: 130px;
+  left: -35px;
+}
+
+.section{
+  position: relative;
+  margin-bottom: 15px;
+  padding-bottom: 15px;
+  border-bottom: 1px solid Gray;
+
+  h3 {
+    color: #222222;
+    padding: 10px;
+    border-radius: 3px;
+    background: #a7dded;
+  }
+  .delete {
+    position: absolute;
+    top: 8px;
+    right: 5px;
+  }
+  .rule {
+    background: red;
+    position: relative;
+    padding: 7px;
+    border-radius: 3px;
+    margin-bottom: 10px;
+    background: #f9f9f9;
+
+    &:hover {
+      cursor: pointer;
+      background: #efefef;
+    }
+
+    h4 {
+      margin: 0;
+      padding: 0;
+    }
+
+    .controls {
+      position: absolute;
+      top: 2px;
+      right: 0px;
+    }
+  }
+}

data/app/controllers/admin/role_sections_controller.rb

@@ -1,13 +1,12 @@
 class Admin::RoleSectionsController < ApplicationController
-  include TheRole::Requires
-
-  layout 'the_role'
+  include TheRoleController
+  layout TheRole.config.layout.to_s
 
   before_filter :login_required
   before_filter :role_required
 
-  before_filter :role_find,           :only => [:create, :create_rule, :rule_on, :rule_off, :destroy, :destroy_rule]
-  before_filter :owner_required,      :only => [:create, :create_rule, :rule_on, :rule_off, :destroy, :destroy_rule]
+  before_filter :role_find,      only: [:create, :create_rule, :rule_on, :rule_off, :destroy, :destroy_rule]
+  before_filter :owner_required, only: [:create, :create_rule, :rule_on, :rule_off, :destroy, :destroy_rule]
 
   def create
     if @role.create_section params[:section_name]
@@ -74,7 +73,10 @@ class Admin::RoleSectionsController < ApplicationController
 
   def role_find
     @role = Role.find params[:role_id]
-    @ownership_checking_object = @role
+
+    # TheRole: You should define OWNER CHECK OBJECT
+    # When editable object was found
+    @owner_check_object = @role
   end
 
   def redirect_to_edit

data/app/controllers/admin/roles_controller.rb

@@ -1,15 +1,15 @@
 class Admin::RolesController < ApplicationController
-  include TheRole::Requires
-  layout 'the_role'
+  include TheRoleController
+  layout TheRole.config.layout.to_s
 
   before_filter :login_required
   before_filter :role_required
 
-  before_filter :role_find,      :only => [:edit, :update, :destroy]
-  before_filter :owner_required, :only => [:edit, :update, :destroy]
+  before_filter :role_find,      only: [:edit, :update, :destroy]
+  before_filter :owner_required, only: [:edit, :update, :destroy]
 
   def index
-    @roles = Role.all :order => 'created_at ASC'
+    @roles = Role.all.order('created_at ASC')
   end
 
   def new
@@ -48,7 +48,10 @@ class Admin::RolesController < ApplicationController
 
   def role_find
     @role = Role.find params[:id]
-    @ownership_checking_object = @role
+
+    # TheRole: You should define OWNER CHECK OBJECT
+    # When editable object was found
+    @owner_check_object = @role
   end
 
   def redirect_to_edit

data/app/controllers/the_role_controller.rb

@@ -0,0 +1,18 @@
+module TheRoleController
+  private
+
+  def role_access_denied
+    flash[:error] = t('the_role.access_denied')
+    redirect_to '/'
+  end
+
+  def role_required
+    role_access_denied unless current_user.has_role?(controller_name, action_name)
+  end
+
+  def owner_required
+    # TheRole: You should define OWNER CHECK OBJECT
+    # When editable object was found
+    role_access_denied unless current_user.owner?(@owner_check_object)
+  end
+end

data/app/models/concerns/role_model.rb

@@ -0,0 +1,124 @@
+module RoleModel
+  extend ActiveSupport::Concern
+
+  include TheRoleBase
+
+  def role_hash; to_hash; end
+  alias_method :has?, :has_role?
+
+  def has_section? section_name
+    to_hash.key? TheRoleParam.process(section_name)
+  end
+
+  included do
+    has_many  :users
+    validates :name,        presence: true, uniqueness: true
+    validates :title,       presence: true, uniqueness: true
+    validates :description, presence: true
+
+    before_save do
+      self.name = TheRoleParam.process(name)
+
+      rules_set     = self.the_role
+      self.the_role = {}.to_json        if rules_set.blank?      # blank
+      self.the_role = rules_set.to_json if rules_set.is_a?(Hash) # Hash
+    end
+  end
+
+  module ClassMethods
+    def with_name name
+      where(name: name).first
+    end
+  end
+
+  # C
+  
+  def create_section section_name = nil
+    return false unless section_name
+    role         =  to_hash
+    section_name =  TheRoleParam.process(section_name)
+    return false if section_name.blank?
+    return true  if role[section_name]
+    role[section_name] = {}
+    update(the_role: role)
+  end
+          
+  def create_rule section_name, rule_name
+    return false if     rule_name.blank?
+    return false unless create_section(section_name)
+    role         =  to_hash
+    rule_name    =  TheRoleParam.process(rule_name)
+    section_name =  TheRoleParam.process(section_name)
+    return true  if role[section_name][rule_name]
+    role[section_name][rule_name] = false
+    update(the_role: role)
+  end
+
+  # R
+
+  def to_hash
+    begin JSON.load(the_role) rescue {} end
+  end
+
+  def to_json
+    the_role
+  end
+
+  # U
+
+  # source_hash will be reset to false
+  # except true items from new_role_hash
+  # all keys will become 'strings'
+  # look at lib/the_role/hash.rb to find definition of *underscorify_keys* method
+  def update_role new_role_hash
+    new_role_hash = new_role_hash.try(:to_hash) || {}
+    new_role      = new_role_hash.underscorify_keys
+    role          = to_hash.underscorify_keys.deep_reset(false)
+    role.deep_merge! new_role
+    update(the_role: role)
+  end
+
+  def rule_on section_name, rule_name
+    role         =  to_hash
+    rule_name    =  TheRoleParam.process(rule_name)
+    section_name =  TheRoleParam.process(section_name)
+    return false unless role[section_name]
+    return false unless role[section_name].key? rule_name
+    return true  if     role[section_name][rule_name]
+    role[section_name][rule_name] = true
+    update(the_role: role)
+  end
+
+  def rule_off section_name, rule_name
+    role         = to_hash
+    rule_name    = TheRoleParam.process(rule_name)
+    section_name = TheRoleParam.process(section_name)
+    return false unless role[section_name]
+    return false unless role[section_name].key? rule_name
+    return true  unless role[section_name][rule_name]
+    role[section_name][rule_name] = false
+    update(the_role: role)
+  end
+
+  # D
+
+  def delete_section section_name = nil
+    return false unless section_name
+    role         =  to_hash
+    section_name =  TheRoleParam.process(section_name)
+    return false if section_name.blank?
+    return false unless role[section_name]
+    role.delete  section_name
+    update(the_role: role)
+  end
+
+  def delete_rule section_name, rule_name
+    role         = to_hash
+    rule_name    = TheRoleParam.process(rule_name)
+    section_name = TheRoleParam.process(section_name)
+    return false unless role[section_name]
+    return false unless role[section_name].key? rule_name
+    role[section_name].delete rule_name
+    update(the_role: role)
+  end
+end

data/app/models/concerns/the_role_base.rb

@@ -0,0 +1,30 @@
+module TheRoleBase
+  def has_section? section_name
+    hash         =  role_hash
+    section_name =  TheRoleParam.process section_name
+    return true  if hash[section_name]
+    false
+  end
+
+  def has_role? section_name, rule_name
+    hash         =  role_hash
+    section_name =  TheRoleParam.process(section_name)
+    rule_name    =  TheRoleParam.process(rule_name)
+
+    return true  if hash.try(:[], 'system').try(:[], 'administrator')
+    return true  if hash.try(:[], 'moderator').try(:[], section_name)
+
+    return false unless hash[section_name]
+    return false unless hash[section_name].key? rule_name
+    hash[section_name][rule_name]
+  end
+
+  def moderator? section_name
+    section_name = TheRoleParam.process(section_name)
+    has_role? section_name, 'any_crazy_name'
+  end
+
+  def admin?
+    has_role? 'any_crazy_name', 'any_crazy_name'
+  end
+end