has_roles 0.0.2 → 0.3.0

data/CHANGELOG.rdoc

@@ -0,0 +1,46 @@
+== master
+
+== 0.3.0 / 2009-04-30
+
+* Improve permission lookup performance
+* Introduce RolePermission as the join model between Roles and Permissions
+* Replace acts_as_enumeration with enumerate_by
+* Add dependency on Rails 2.3
+
+== 0.2.0 / 2008-12-14
+
+* Remove the PluginAWeek namespace
+
+== 0.1.2 / 2008-10-26
+
+* Fix permissions for new roles always defaulting to empty even when it's passed in to the constructor
+* Add authorized?, authorized_required, and authorization_denied helpers
+* Moved authorized_for? helper method into the controller so that it can be used there as well as in views
+* Change how the base module is included to prevent namespacing conflicts
+
+== 0.1.1 / 2008-06-22
+
+* Remove log files from gems
+* Index permission enumerations by their path
+
+== 0.1.0 / 2008-05-05
+
+* Add use of named_scope instead of class finders
+* Moved storage of controller paths into the Permission model
+* Permission and Role are now enumerations (adding dependency on acts_as_enumeration)
+* Removed unused helper methods in Permission and Role
+* Added default permissions / roles
+* Update documentation
+
+== 0.0.2 / 2007-09-26
+
+* Fix role_assignments unique index having too long a name
+* Add workaround for old sqlite versions that can't handle :distinct => true
+
+== 0.0.1 / 2007-09-05
+
+* Add #role_ids and #role_ids=(new_ids) for models
+* Added documentation
+* Added helper methods for determining authorization within views
+* Added unit tests
+* Convert dos newlines to unix newlines

data/{MIT-LICENSE → LICENSE}

@@ -1,4 +1,4 @@
-Copyright (c) 2006-2007 Aaron Pfeifer & Neil Abraham
+Copyright (c) 2006-2009 Aaron Pfeifer
 
 Permission is hereby granted, free of charge, to any person obtaining
 a copy of this software and associated documentation files (the
@@ -17,4 +17,4 @@ 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.
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.rdoc

@@ -0,0 +1,92 @@
+= has_roles
+
++has_roles+ demonstrates a reference implementation for handling role management.
+
+== Resources
+
+API
+
+* http://api.pluginaweek.org/has_roles
+
+Bugs
+
+* http://pluginaweek.lighthouseapp.com/projects/13277-has_roles
+
+Development
+
+* http://github.com/pluginaweek/has_roles
+
+Source
+
+* git://github.com/pluginaweek/has_roles.git
+
+== Description
+
+One of the easiest and most straightforward techniques for adding role
+management and authorization to specific parts of your application is
+restricting usage on a controller/action-basis.  Each role defined in your
+system is mapped to one or more permissions.  Each permission is a combination
+of a controller and action.
+
+== Usage
+
+Note that this is a reference implementation and, most likely, should be
+modified for your own usage.
+
+=== Adding permissions
+
+To add permissions, you can create an initializer like so:
+
+config/initializers/permissions.rb:
+
+  Permission.bootstrap(
+    {:id => 1, :controller => 'application'},
+    {:id => 2, :controller => 'admin/stats'},
+    {:id => 3, :controller => 'comments', :action => 'create'},
+    ...
+  )
+
+=== Adding / Updating roles
+
+To add / update roles, you can create an initializer like so:
+
+config/initializers/roles.rb:
+
+  Role.bootstrap(
+    {:id => 1, :name => 'admin'},
+    {:id => 2, :name => 'developer'},
+    ...
+  )
+  
+  RolePermission.bootstrap(
+    {:role => 'admin', :permission => 'application/'},
+    {:role => 'admin', :permission => 'admin/states/'},
+    {:role => 'developer', :permission => 'comments/create'},
+    {:role => 'developer', :permission => 'admin/stats/'},
+    ...
+  )
+
+=== Checking a user's authorization
+
+Below is an example of checking a user's authorization for a url before
+displaying information:
+
+app/views/layouts/application.rhtml:
+
+  <% if authorized_for?(:controller => 'admin/users') %>
+  <p>Read to start administering your website?</p>
+  <% end %>
+
+== Testing
+
+Before you can run any tests, the following gem must be installed:
+* plugin_test_helper[http://github.com/pluginaweek/plugin_test_helper]
+
+To run against a specific version of Rails:
+
+  rake test RAILS_FRAMEWORK_ROOT=/path/to/rails
+
+== Dependencies
+
+* Rails 2.3 or later
+* enumerate_by[http://github.com/pluginaweek/enumerate_by]

data/Rakefile

@@ -3,45 +3,55 @@ require 'rake/rdoctask'
 require 'rake/gempackagetask'
 require 'rake/contrib/sshpublisher'
 
-PKG_NAME           = 'has_roles'
-PKG_VERSION        = '0.0.2'
-PKG_FILE_NAME      = "#{PKG_NAME}-#{PKG_VERSION}"
-RUBY_FORGE_PROJECT = 'pluginaweek'
-
-desc 'Default: run unit tests.'
+spec = Gem::Specification.new do |s|
+  s.name              = 'has_roles'
+  s.version           = '0.3.0'
+  s.platform          = Gem::Platform::RUBY
+  s.summary           = 'Demonstrates a reference implementation for handling role management'
+  
+  s.files             = FileList['{app,db,lib,test}/**/*'] + %w(CHANGELOG.rdoc init.rb LICENSE Rakefile README.rdoc) - FileList['test/app_root/{log,log/*,script,script/*}']
+  s.require_path      = 'lib'
+  s.has_rdoc          = true
+  s.test_files        = Dir['test/**/*_test.rb']
+  s.add_dependency    'enumerate_by', '>= 0.4.0'
+  
+  s.author            = 'Aaron Pfeifer'
+  s.email             = 'aaron@pluginaweek.org'
+  s.homepage          = 'http://www.pluginaweek.org'
+  s.rubyforge_project = 'pluginaweek'
+end
+  
+desc 'Default: run all tests.'
 task :default => :test
 
-desc 'Test the has_roles plugin.'
+desc "Test the #{spec.name} plugin."
 Rake::TestTask.new(:test) do |t|
   t.libs << 'lib'
-  t.pattern = 'test/**/*_test.rb'
+  t.test_files = spec.test_files
   t.verbose = true
 end
 
-desc 'Generate documentation for the has_roles plugin.'
+begin
+  require 'rcov/rcovtask'
+  namespace :test do
+    desc "Test the #{spec.name} plugin with Rcov."
+    Rcov::RcovTask.new(:rcov) do |t|
+      t.libs << 'lib'
+      t.test_files = spec.test_files
+      t.rcov_opts << '--exclude="^(?!lib/|app/)"'
+      t.verbose = true
+    end
+  end
+rescue LoadError
+end
+
+desc "Generate documentation for the #{spec.name} plugin."
 Rake::RDocTask.new(:rdoc) do |rdoc|
   rdoc.rdoc_dir = 'rdoc'
-  rdoc.title    = 'HasRoles'
+  rdoc.title    = spec.name
+  rdoc.template = '../rdoc_template.rb'
   rdoc.options << '--line-numbers' << '--inline-source'
-  rdoc.rdoc_files.include('README')
-  rdoc.rdoc_files.include('lib/**/*.rb')
-end
-
-spec = Gem::Specification.new do |s|
-  s.name            = PKG_NAME
-  s.version         = PKG_VERSION
-  s.platform        = Gem::Platform::RUBY
-  s.summary         = 'Provides simple role management based on controllers/actions'
-  
-  s.files           = FileList['{app,db,lib,test}/**/*'].to_a + %w(CHANGELOG init.rb MIT-LICENSE Rakefile README)
-  s.require_path    = 'lib'
-  s.autorequire     = 'has_roles'
-  s.has_rdoc        = true
-  s.test_files      = Dir['test/**/*_test.rb']
-  
-  s.author          = 'Aaron Pfeifer, Neil Abraham'
-  s.email           = 'info@pluginaweek.org'
-  s.homepage        = 'http://www.pluginaweek.org'
+  rdoc.rdoc_files.include('README.rdoc', 'CHANGELOG.rdoc', 'LICENSE', 'lib/**/*.rb', 'app/**/*.rb')
 end
   
 Rake::GemPackageTask.new(spec) do |p|
@@ -50,30 +60,30 @@ Rake::GemPackageTask.new(spec) do |p|
   p.need_zip = true
 end
 
-desc 'Publish the beta gem'
+desc 'Publish the beta gem.'
 task :pgem => [:package] do
-  Rake::SshFilePublisher.new('pluginaweek@pluginaweek.org', '/home/pluginaweek/gems.pluginaweek.org/gems', 'pkg', "#{PKG_FILE_NAME}.gem").upload
+  Rake::SshFilePublisher.new('aaron@pluginaweek.org', '/home/aaron/gems.pluginaweek.org/public/gems', 'pkg', "#{spec.name}-#{spec.version}.gem").upload
 end
 
-desc 'Publish the API documentation'
+desc 'Publish the API documentation.'
 task :pdoc => [:rdoc] do
-  Rake::SshDirPublisher.new('pluginaweek@pluginaweek.org', "/home/pluginaweek/api.pluginaweek.org/#{PKG_NAME}", 'rdoc').upload
+  Rake::SshDirPublisher.new('aaron@pluginaweek.org', "/home/aaron/api.pluginaweek.org/public/#{spec.name}", 'rdoc').upload
 end
 
 desc 'Publish the API docs and gem'
-task :publish => [:pdoc, :release]
+task :publish => [:pgem, :pdoc, :release]
 
 desc 'Publish the release files to RubyForge.'
 task :release => [:gem, :package] do
   require 'rubyforge'
   
-  ruby_forge = RubyForge.new
+  ruby_forge = RubyForge.new.configure
   ruby_forge.login
-
-  %w( gem tgz zip ).each do |ext|
-    file = "pkg/#{PKG_FILE_NAME}.#{ext}"
+  
+  %w(gem tgz zip).each do |ext|
+    file = "pkg/#{spec.name}-#{spec.version}.#{ext}"
     puts "Releasing #{File.basename(file)}..."
     
-    ruby_forge.add_release(RUBY_FORGE_PROJECT, PKG_NAME, PKG_VERSION, file)
+    ruby_forge.add_release(spec.rubyforge_project, spec.name, spec.version, file)
   end
 end

data/app/models/permission.rb

@@ -1,44 +1,61 @@
-# A permission defines access to a single part of an application, restricted by
-# both controller and action specifications.
+# A permission defines access to a single part of an application, restricted
+# by both controller and action specifications.
 # 
-# Permissions can be application-, controller-, or action-specific.  Permissions
-# using the +application+ controller are global.  Permissions without any +action+
-# specified are controller-specific.  Permissions with both +controller+ and
+# Permissions can be application-, controller-, or action-specific.  Those
+# using the +application+ controller are global.  Those without any +action+
+# specified are controller-specific.  Those with both +controller+ and
 # +action+ specified are action-specific.
+# 
+# == Examples
+# 
+#   Permission.bootstrap(
+#     {:id => 1, :controller => 'application'},               # Access to the whole application
+#     {:id => 2, :controller => 'users'},                     # Access to the Users controller (any action)
+#     {:id => 3, :controller => 'users', :action => 'index'}  # Access to the Users controller and index action
+#   )
 class Permission < ActiveRecord::Base
-  belongs_to              :controller
-  has_and_belongs_to_many :roles
+  enumerate_by :path
+  
+  has_many :assigned_roles, :class_name => 'RolePermission'
+  has_many :roles, :through => :assigned_roles
+  
+  validates_presence_of :controller
+  validates_length_of :action, :minimum => 1, :allow_nil => true
   
-  validates_presence_of   :controller_id
-  validates_length_of     :action,
-                            :minimum => 1,
-                            :allow_nil => true
-  validates_uniqueness_of :action,
-                            :scope => :controller_id,
-                            :allow_nil => true
+  before_validation :set_path
   
   class << self
-    # Is there a permission that exists which restricts the given url?.  See
-    # <tt>Controller#recognize_path</tt> for possible options.
+    # Is there a permission that exists which restricts the given url?  If
+    # there is no permission that restricts the path, then anyone should be
+    # allowed access to it
     def restricts?(options = '')
-      controller_path, action = Controller.recognize_path(options)
-      count(
-        :include => :controller,
-        :conditions => ['path = ? AND (action IS NULL OR action = ?)', controller_path, action],
-        :distinct => true # TODO: Workaround for old sqlite versions until Rails 1.2
-      ) > 0
+      controller, action = recognize_path(options)
+      
+      # See if a permission exists for either the controller or controller/action
+      # combination.  If it doesn't, then the path isn't restricted
+      exists?(:path => ["#{controller}/", "#{controller}/#{action}"])
     end
     
-    # Finds all permissions that are authorized for the given url.  See
-    # <tt>Controller#recognize_path</tt> for possible options.
-    def find_all_authorized_for(options = '')
-      controller_path, action = Controller.recognize_path(options)
-      controller = Controller.new(:path => controller_path)
+    # Parses the controller path and action from the given options.  Options
+    # may be in any one of the following formats:
+    # * +string+ - A relative or absolute path in the application
+    # * +hash+ - A hash include the controller/action attributes
+    def recognize_path(options = '')
+      # Grab the actual url options if the path is specified
+      options = ActionController::Routing::Routes.recognize_path(URI.parse(options).path) if options.is_a?(String)
       
-      find(:all,
-        :include => :controller,
-        :conditions => ['path IN (?) AND (action IS NULL OR action = ?)', controller.possible_path_matches, action]
-      )
+      # Only return the controller/action of the url options
+      return options[:controller], options[:action] ? options[:action].to_s : 'index'
     end
   end
+  
+  private
+    # Set full path for the controller / action
+    def set_path
+      self.path = "#{controller}/#{action}"
+    end
+  
+  bootstrap(
+    {:id => 1, :controller => 'application'}
+  )
 end

data/app/models/role.rb

@@ -1,30 +1,38 @@
 # A role defines a group of users in the system who are able to access a
-# collection of features in the application.  Examples of roles could be
-# 'Administrator', 'Developer', or 'Guest'.
+# collection of features in the application.
+# 
+# == Examples
+# 
+#   Role.bootstrap(
+#     {:id => 1, :name => 'administrator'},
+#     {:id => 2, :name => 'developer'},
+#     {:id => 3, :name => 'guest'}
+#   )
 class Role < ActiveRecord::Base
-  has_and_belongs_to_many :permissions
-  has_many                :assignments,
-                            :class_name => 'RoleAssignment',
-                            :dependent => true
+  enumerate_by :name
   
-  validates_presence_of   :name
-  validates_uniqueness_of :name,
-                            :allow_nil => true
+  has_many :assigned_permissions, :class_name => 'RolePermission'
+  has_many :permissions, :through => :assigned_permissions
+  has_many :assignments, :class_name => 'RoleAssignment'
   
-  class << self
-    # Finds all roles that are authorized for the given url
-    def find_all_authorized_for(options = '')
-      controller_path, action = Controller.recognize_path(options)
-      controller = Controller.new(:path => controller_path)
-      
-      find(:all,
-        :include => {:permissions => :controller},
-        :conditions => ['path IN (?) AND (action IS NULL OR action = ?)', controller.possible_path_matches, action]
-      )
-    end
-  end
+  # Is this role authorized for the given url?  The url can be any one of the
+  # following formats:
+  # * +string+ - A relative or absolute path in the application
+  # * +hash+ - A hash include the controller/action attributes
+  # 
+  # Using this information, the controller and action can be determined.
+  # Authorization is based on whether the role has a permission that either
+  # directly matches the path or represents a parent path (i.e. using the
+  # controller/class hierarchy)
+  named_scope :authorized_for, lambda {|*args|
+    options = args.first || ''
+    controller, action = Permission.recognize_path(options)
+    controllers = "#{controller.camelize}Controller".constantize.ancestors.select {|c| c < ActionController::Base}.map(&:controller_path)
+    
+    {:joins => :permissions, :conditions => ['permissions.controller IN (?) AND (permissions.action IS NULL OR permissions.action = ?)', controllers, action]}
+  }
   
-  def to_s #:nodoc
-    name
-  end
+  bootstrap(
+    {:id => 1, :name => 'admin'}
+  )
 end

data/app/models/role_assignment.rb

@@ -1,10 +1,9 @@
 # Represents an assignment of a role to a user (assignee) in the system
 class RoleAssignment < ActiveRecord::Base
-  belongs_to  :role
-  belongs_to  :assignee,
-                :polymorphic => true
+  belongs_to :role
+  belongs_to :assignee, :polymorphic => true
   
-  validates_presence_of :role_id,
-                        :assignee_id,
-                        :assignee_type
+  validates_presence_of :role_id, :assignee_id, :assignee_type
+  
+  attr_accessible :role
 end

data/app/models/role_permission.rb

@@ -0,0 +1,25 @@
+# Represents an assignment of a permission to a role.  The permissions for a
+# role determine what parts of the system that role has access to.
+# 
+# == Examples
+# 
+#   RolePermission.bootstrap(
+#     {:role => 'admin', :permission => 'application/'},
+#     {:role => 'developer', :permission => 'comments/create'},
+#     {:role => 'developer', :permission => 'admin/stats/'}
+#   )
+# 
+# Notice that permissions are in the form of the path defined by the
+# controller/action.
+class RolePermission < ActiveRecord::Base
+  extend EnumerateBy::Bootstrapped
+  
+  belongs_to :role
+  belongs_to :permission
+  
+  validates_presence_of :role_id, :permission_id
+  
+  bootstrap(
+    {:role => 'admin', :permission => 'application/'}
+  )
+end

data/db/migrate/{002_create_permissions.rb → 001_create_permissions.rb}

@@ -1,13 +1,12 @@
 class CreatePermissions < ActiveRecord::Migration
   def self.up
     create_table :permissions do |t|
-      t.column :controller_id, :integer, :null => false
-      t.column :action, :string
+      t.string :controller, :path, :null => false
+      t.string :action
     end
-    add_index :permissions, [:controller_id, :action], :unique => true
   end
-
+  
   def self.down
     drop_table :permissions
   end
-end
+end

data/db/migrate/{003_create_roles.rb → 002_create_roles.rb}

@@ -1,10 +1,8 @@
 class CreateRoles < ActiveRecord::Migration
   def self.up
     create_table :roles do |t|
-      t.column :name, :string, :null => false
-      t.column :description, :text
+      t.string :name, :null => false
     end
-    add_index :roles, :name, :unique => true
   end
   
   def self.down

data/db/migrate/003_create_role_permissions.rb

@@ -0,0 +1,11 @@
+class CreateRolePermissions < ActiveRecord::Migration
+  def self.up
+    create_table :role_permissions do |t|
+      t.references :role, :permission, :null => false
+    end
+  end
+  
+  def self.down
+    drop_table :role_permissions
+  end
+end

data/db/migrate/{005_create_role_assignments.rb → 004_create_role_assignments.rb}

@@ -1,9 +1,8 @@
 class CreateRoleAssignments < ActiveRecord::Migration
   def self.up
     create_table :role_assignments do |t|
-      t.column :role_id, :integer, :null => false
-      t.column :assignee_id, :integer, :null => false
-      t.column :assignee_type, :string, :null => false
+      t.references :role, :null => false
+      t.references :assignee, :polymorphic => true, :null => false
     end
     add_index :role_assignments, [:role_id, :assignee_id, :assignee_type], :unique => true, :name => 'index_role_assignments_on_role_and_assignee'
   end

data/lib/has_roles/authorization_helper.rb

@@ -1,56 +1,75 @@
-module PluginAWeek #:nodoc:
-  module Has #:nodoc:
-    module Roles
-      # Provides helper methods for determining whether users are authorized
-      # for a given url.
+module HasRoles
+  # Provides helper methods for determining whether users are authorized
+  # for a given url.
+  module AuthorizationHelper
+    def self.included(base) #:nodoc:
+      base.class_eval do
+        helper_method :authorized?
+        helper_method :authorized_for?
+      end
+    end
+    
+    protected
+      # Is the user authorized for the current url?  If there is no current
+      # user, then this will return false.  If there *is* a current user, then
+      # this will return true/false depending on whether the user is assigned
+      # a role that has permission to access the current request url.
+      def authorized?
+        authorized_for?(request.request_uri)
+      end
+      
+      # Checks if the current user is authorized for the url specified by the
+      # given options. See <tt>HasRoles::InstanceMethods#authorized_for?</tt>
+      # for a description of the possible options that can be passed in.
+      # 
+      # If there is no current user, then the authorization will fail.
+      # 
+      # == Examples
+      # 
+      #   authorized_for?(:controller => 'admin/messages')
+      #   authorized_for?(:controller => 'admin/messages', :action => 'destroy')
+      #   authorized_for?('admin/messages')
+      #   authorized_for?('http://localhost:3000/admin/messages')
+      def authorized_for?(options = {})
+        current_user && current_user.authorized_for?(options)
+      end
+      
+      # Ensures that the user is authorized for the current url.  If not
+      # authorized, then a 401 "Unauthorized" response will be sent back.
       # 
-      # In order to determine who the current user is, the helper methods
-      # assume that a +current_user+ helper has been defined.  If this method
-      # is not already defined, it will assume that the current user is stored
-      # in the session as <tt>session['user']</tt>.  If your application implements
-      # this differently, you can override it like so:
+      # This is useful for defining filters on resources that are protected
+      # based on the role of the current user.  For example,
       # 
-      #   module ApplicationHelper
-      #     def current_user
-      #       session['user_id'] ? User.find(session['user_id']) : nil
-      #     end
+      #   class PostsController < ApplicationController
+      #     before_filter :authorization_required, :only => [:destroy]
+      #     ...
       #   end
-      module AuthorizationHelper
-        def self.included(base) #:nodoc:
-          unless base.instance_methods.include?('current_user')
-            base.class_eval do
-              def current_user
-                session['user']
-              end
-            end
-          end
-        end
-        
-        # Check if the user is authorized for the url specified by the given options.
-        # See <tt>Controller#recognize_path</tt> for a description of the possible
-        # options that can be passed in.
-        def authorized_for?(options = {})
-          current_user && current_user.authorized_for?(options)
-        end
-        
-        # Only link to the url if the user is authorized to access it.  In
-        # addition to the options normally available in +link_to+, the following
-        # options can be specified:
-        # * +show_text+ - If set to true, will only display the text if the user is not authorized for the link. (Default is +false+).
-        def link_to_if_authorized(name, options = {}, html_options = {}, *parameters_for_method_reference, &block)
-          text_on_no_authorization = html_options.delete(:show_text) ? name : ''
-          
-          if authorized_for?(options)
-            link_to name, options, html_options, *parameters_for_method_reference, &block
-          else
-            text_on_no_authorization
-          end
-        end
+      # 
+      # See #authorization_denied for the response given and how to provide
+      # a custom implementation for responding to unauthorized requests.
+      def authorization_required
+        authorized? || authorization_denied
+      end
+      
+      # Renders an "unauthorized request" response to the user.  By default,
+      # this is a simple HEAD response with the status code set to 401.  This
+      # method should be overridden to provide a custom implementation for
+      # authorization denials, such as redirecting to a particular page:
+      # 
+      #   class ApplicationController < ActionController::Base
+      #     ...
+      #     protected
+      #       def authorization_denied
+      #         flash[:notice] = 'Unauthorized'
+      #         redirect_to root_url
+      #       end
+      #   end
+      def authorization_denied
+        head :unauthorized
       end
-    end
   end
 end
 
 ActionController::Base.class_eval do
-  helper PluginAWeek::Has::Roles::AuthorizationHelper
+  include HasRoles::AuthorizationHelper
 end