permissive 0.0.1 → 0.2.0.alpha

data/README.markdown.html

@@ -1,191 +0,0 @@
-<h1>Permissive gives your ActiveRecord models granular permission support</h1>
-
-<p>Permissive combines a model-based permissions system with bitmasking to
-create a flexible approach to maintaining permissions on your ActiveRecord
-models. It supports an easy-to-use set of methods for accessing and
-determining permissions, including some fun metaprogramming.</p>
-
-<h2>Installation</h2>
-
-<ol>
-<li><p>Get yourself some code. You can install as a gem:</p>
-
-<p><code>gem install permissive</code></p>
-
-<p>or as a plugin:</p>
-
-<p><code>script/plugin install git://github.com/flipsasser/permissive.git</code></p></li>
-<li><p>Generate a migration so you can get some sweet table action:</p>
-
-<p><code>script/generate permissive_migration</code></p>
-
-<p><code>rake db:migrate</code></p></li>
-</ol>
-
-
-<h2>Usage</h2>
-
-<p>First, define a few permissions constants. We'll define them in <code>Rails.root/config/initializers/permissive.rb</code>. The best practice is to name them in a verb format that follows this pattern: "Object can <code>DO_PERMISSION_NAME</code>".</p>
-
-<p>Permission constants need to be int values counting up from zero. We use ints because Permissive uses bit masking to keep permissions data compact and performant.</p>
-
-<pre><code>module Permissive::Permissions
-  MANAGE_GAMES = 0
-  CONTROL_RIDES = 1
-  PUNCH = 2
-end
-</code></pre>
-
-<p>And that's all it takes to configure permissions! Now that we have them, let's grant them to a model or two:</p>
-
-<pre><code>class Employee &lt; ActiveRecord::Base
-  acts_as_permissive
-  validates_presence_of :first_name, :last_name
-end
-
-class Company &lt; ActiveRecord::Base
-  validates_presence_of :name
-end
-</code></pre>
-
-<p>Easy-peasy, right? Let's try granting a few permissions:</p>
-
-<pre><code>@james = Employee.create(:first_name =&gt; 'James', :last_name =&gt; 'Brennan')
-@frigo = Employee.create(:first_name =&gt; 'Tommy', :last_name =&gt; 'Frigo')
-@adventureland = Company.create(:name =&gt; 'Adventureland')
-
-# Okay, let's do some granting. We'll start by scoping to a specific company.
-@james.can!(:manage_games, :on =&gt; @adventureland)
-
-# Now let's do some permission checking.
-@james.can?(:manage_games, :on =&gt; @adventureland) #=&gt; true
-
-# We can also use the metaprogramming syntax:
-@james.can_manage_games_on?(@adventureland) #=&gt; true
-@james.can_control_rides_on?(@adventureland) #=&gt; false
-
-# We can check for multiple permissions, too:
-@james.can?(:manage_games, :control_rides) #=&gt; false
-# OR:
-@james.can_manage_games_and_control_rides?
-
-# Scoping can be done through any object
-@frigo.can!(:punch, :on =&gt; @james)
-@frigo.can_punch_on?(@james) #=&gt; true
-
-# And the permissions aren't reciprocal
-@james.can_punch_on?(@frigo) #=&gt; false
-
-# Of course, we can grant global (non-scoped) permissions, too:
-@frigo.can!(:control_rides)
-@frigo.can_control_rides? #=&gt; true
-
-# BUT! Global permissions don't override scoped permissions.
-@frigo.can_control_rides_on?(@adventureland) #=&gt; false
-
-# Likewise, scoped permissions don't bubble up globally:
-@james.can_manage_games? #=&gt; false
-
-# And, last but not least, let's take all of those great permissions away:
-@james.revoke(:manage_games, :on =&gt; @adventureland)
-
-# We can revoke all permissions, in any scope, too:
-@frigo.revoke(:all)
-</code></pre>
-
-<p>And that's it!</p>
-
-<h2>Scoping</h2>
-
-<p>Permissive supports scoping at the class-configuration level, which adds relationships to permitted objects:</p>
-
-<pre><code>class Employee &lt; ActiveRecord::Base
-  acts_as_permissive :scope =&gt; :company
-end
-
-@frigo.permissive_companies #=&gt; [Company 1, Company 2]
-</code></pre>
-
-<h2>Replacing Permissions</h2>
-
-<p>Sometimes you want to overwrite all previous permissions in a can! method. That's pretty easy: just add :reset => true to the options.</p>
-
-<pre><code>@frigo.can!(:control_rides, :on =&gt; @adventureland, :reset =&gt; true)
-</code></pre>
-
-<h2>Next Steps</h2>
-
-<p>There's a number of things I want to add to the permissive settings. At the moment, Permissive currently support scoping at the class level, BUT all it really does is add a <code>has_many</code> relationship. <code>@employee.can!(:do_anything)</code> will still work, as will <code>@employee.can!(:do_something, :on =&gt; @something_that_isnt_a_company)</code>. That's pretty confusing to me. Adding more granular permissions might be cooler:</p>
-
-<pre><code>class Employee &lt; ActiveRecord::Base
-  has_permissions do
-    on :companies
-    on :employees
-  end
-end
-</code></pre>
-
-<p>which might yield something like</p>
-
-<pre><code>@employee.permissive_companies
-# and
-@employee.can_control_rides_in_company @adventureland
-</code></pre>
-
-<p>I'd also like to support a more intelligent grammar:</p>
-
-<pre><code>@james.can_punch? @frigo
-@frigo.can!(:control_rides, :in =&gt; @adventureland)
-</code></pre>
-
-<p>Meta-programmed methods for granting and revoking would be cool, too:</p>
-
-<pre><code>@james.can_punch! @frigo
-@frigo.cannot_control_rides_in! @adventureland
-</code></pre>
-
-<p>And while we're on the subject of metaprogramming, let's add some OR-ing to the whole thing:</p>
-
-<pre><code>@james.can_control_rides_or_manage_games_in? @adventureland
-</code></pre>
-
-<p>I'd also like to enable Permissive::Templates (pre-set permission groups, like roles):</p>
-
-<pre><code>administrator = Permissive::Template.named('Administrator')
-@james.acts_like administrator
-</code></pre>
-
-<p>Next up! I currently use a manual reset to grant permissions through a controller. It would by great to DRY this stuff up and provide some decent path for moving permissions into HTML forms. Right now, it looks something like this:</p>
-
-<pre><code>&lt;%= check_box_tag("employee[permissions][]", Permissive::Permissions::CONTROL_RIDES, @employee.can_control_rides?) %&gt; Control rides
-</code></pre>
-
-<p>.. and in the controller:</p>
-
-<pre><code>def update
-  @employee.can!(params[:employees].delete(:permissions), :revert =&gt; true)
-  respond_to do |format|
-    ...
-  end
-end
-</code></pre>
-
-<p>Finally, I'd like to use the <code>grant_mask</code> support that exists on the Permissive::Permission model to control what people can or cannot allow others to do. This would necessitate one of two things - first, a quick way of iterating over a person's granting permissions, e.g.:</p>
-
-<pre><code>&lt;% current_user.grant_permissions.each do |permission| %&gt;
-&lt;!-- Do something! --&gt;
-&lt;% end %&gt;
-</code></pre>
-
-<p>and second, write-time checking of grantor permissions. Something like this, maybe:</p>
-
-<pre><code>def update
-  current_user.grant(params[:employees][:permissions], :to =&gt; @employee)
-end
-</code></pre>
-
-<p>which would allow the Permissive::Permission model to make sure whatever <code>current_user</code> is granting to @employee, they're <strong>allowed</strong> to grant to @employee.</p>
-
-<p>And that's it! Like all of my projects, I extracted it from some live development - which means it, too, is still in development. So please feel free to contribute!</p>
-
-<p>Copyright (c) 2009 Flip Sasser, released under the MIT license</p>

data/lib/permissive/acts_as_permissive.rb

@@ -1,134 +0,0 @@
-module Permissive
-  module ActsAsPermissive
-    def self.included(base)
-      base.class_eval do
-        # This is the core of the Permissive module. It allows you to define a
-        # permissive model structure complete with :scope. This will dynamically
-        # generate scoped, polymorphic relationships across one or more models.
-        def self.acts_as_permissive(options = {})
-          options.assert_valid_keys(:scope)
-          has_many :permissions, :class_name => 'Permissive::Permission', :as => :permitted_object do
-            def can!(*args)
-              options = args.last.is_a?(Hash) ? args.pop : {}
-              options.assert_valid_keys(:on, :reset)
-              if options[:on]
-                permission = proxy_owner.permissions.find_or_initialize_by_scoped_object_id_and_scoped_object_type(options[:on].id, options[:on].class.to_s)
-              else
-                permission = Permissive::Permission.find_or_initialize_by_permitted_object_id_and_permitted_object_type(proxy_owner.id, proxy_owner.class.to_s)
-              end
-              if options[:reset]
-                permission.mask = 0
-                permission.grant_mask = 0
-              end
-              args.flatten.each do |name|
-                bit = bit_for(name)
-                unless permission.mask & bit != 0
-                  permission.mask = permission.mask | bit
-                end
-              end
-              permission.save!
-            end
-
-            def can?(*args)
-              options = args.last.is_a?(Hash) ? args.pop : {}
-              bits = args.map{|name| bit_for(name) }
-              # scope = nil
-              # if options[:on]
-              #   scope = scoped(:conditions => ['scoped_object_id = ? AND scoped_object_type = ?', options[:on].id, options[:on].class.to_s])
-              # else
-              #   scope = scoped(:conditions => ['scoped_object_id IS NULL AND scoped_object_type IS NULL'])
-              # end
-              # Skip the trip to the database if the proxy has been loaded up already...
-              # TODO: Fix this per-scope ... somehow ... probably beyond the scope of this project.
-              # if @loaded
-              #   bits.all?{|bit| self.select{|permission| permission.mask & bit != 0} }
-              # else
-              on(options[:on]).count(:conditions => [bits.map { 'permissive_permissions.mask & ?' }.join(' AND '), *bits]) > 0
-              # end
-            end
-
-            def revoke(*args)
-              options = args.last.is_a?(Hash) ? args.pop : {}
-              if args.length == 1 && args.first == :all
-                on(options[:on]).destroy_all
-              else
-                bits = args.map{|name| bit_for(name) }
-                on(options[:on]).each do |permission|
-                  bits.each do |bit|
-                    if permission.mask & bit
-                      permission.mask = permission.mask ^ bit
-                    end
-                  end
-                  permission.save!
-                end
-              end
-            end
-          end
-
-          if options[:scope]
-            scope_name = "permissive_#{options[:scope].to_s}"
-            unless reflection = reflect_on_association(scope_name)
-              # TODO: There's just no way this should be working. It's WAY too
-              # fragile. We need support for something more intelligent here,
-              # like an options hash that includes :scope_type.
-              namespace = self.to_s.split('::')
-              if namespace.length > 1
-                namespace.pop
-                class_name = namespace.join('::') 
-              else
-                class_name = ''
-              end
-              class_name << "::#{options[:scope].to_s.classify}"
-              has_many scope_name, :through => :permissions, :source => :scoped_object, :source_type => class_name
-            end
-          end
-
-          class_eval do
-            # Pass calls to the instance down to its permissions collection
-            #   e.g. current_user.can(:view_comments) will bubble to
-            #        current_user.permissions.can(:view_comments)
-            def can!(*args)
-              permissions.can!(*args)
-            end
-
-            # Pass calls to the instance down to its permissions collection
-            #   e.g. current_user.can(:view_comments) will bubble to
-            #        current_user.permissions.can(:view_comments)
-            def can?(*args)
-              permissions.can?(*args)
-            end
-
-            def revoke(*args)
-              permissions.revoke(*args)
-            end
-
-            def method_missing(method, *args)
-              if method.to_s =~ /^can_([^\?]+)\?$/
-                permissions = $1
-                options = {}
-                if permissions =~ /_on$/
-                  permissions.chomp!('_on')
-                  options[:on] = args.shift
-                end
-                permissions = permissions.split('_and_')
-                if permissions.all? {|permission| Permissive::Permissions.hash.has_key?(permission.downcase.to_sym) }
-                  class_eval <<-end_eval
-                    def #{method}#{"(scope)" if options[:on]}
-                      can?(#{[permissions, args].flatten.join(', ').inspect}#{", :on => scope" if options[:on]})
-                    end
-                  end_eval
-                  return can?(*[permissions, options].flatten)
-                end
-              end
-              super
-            end
-          end
-        end
-      end
-    end
-  end
-end
-
-if defined?(ActiveRecord::Base)
-  ActiveRecord::Base.send :include, Permissive::ActsAsPermissive
-end

data/lib/permissive/permissions.rb

@@ -1,29 +0,0 @@
-# TODO: Abstract this module more later
-module Permissive
-  class PermissionError < StandardError; end;
-
-  module Permissions
-    class << self
-      def const_set(*args)
-        @@hash = nil
-        super
-      end
-
-      def hash
-        @@hash ||= begin
-          bitwise_hash = constants.inject({}) do |hash, constant_name|
-            hash[constant_name.downcase] = 2 ** Permissive::Permissions.const_get(constant_name.to_sym)
-            hash
-          end
-          inverted_hash = bitwise_hash.invert
-          bitwise_hash.values.sort.inject(ActiveSupport::OrderedHash.new) do |hash, value|
-            hash[inverted_hash[value].to_sym] = value
-            hash
-          end
-        rescue ArgumentError
-          raise Permissive::PermissionError.new("Permissions must be integers or longs. Strings, symbols, and floats are not currently supported.")
-        end
-      end
-    end
-  end
-end

data/spec/acts_as_permissive_spec.rb

@@ -1,192 +0,0 @@
-require File.join(File.dirname(__FILE__), 'spec_helper')
-
-# Setup some basic models to test with. We'll set permissions on both,
-# and then test :scope'd permissions through both.
-class Permissive::Organization < ActiveRecord::Base
-  set_table_name :permissive_organizations
-end
-
-class Permissive::User < ActiveRecord::Base
-  set_table_name :permissive_users
-end
-
-describe Permissive::Permission do
-  before :each do
-    PermissiveSpecHelper.db_up
-  end
-
-  after :each do
-    PermissiveSpecHelper.db_down
-  end
-
-  describe "`acts_as_permissive' default class method" do
-    [Permissive::User, Permissive::Organization].each do |model|
-      before :each do
-        model.acts_as_permissive
-      end
-
-      describe model do
-        it "should create a permissions reflection" do
-          model.new.should respond_to(:permissions)
-        end
-
-        it "should create a `can?' method" do
-          model.new.should respond_to(:can?)
-        end
-
-        it "should create a `revoke' method" do
-          model.new.should respond_to(:revoke)
-        end
-      end
-    end
-  end
-
-  describe "permissions checking" do
-    before :each do
-      Permissive::User.acts_as_permissive
-      @user = Permissive::User.create
-    end
-
-    it "should allow permissions checks through the `can?' method" do
-      @user.can?(:edit_organizations).should be_false
-    end
-
-    it "should respond to the `can!' method" do
-      @user.should respond_to(:can!)
-    end
-
-    it "should allow permissions setting through the `can!' method" do
-      count = @user.permissions.count
-      @user.can!(:view_users)
-      @user.permissions.count.should == count.next
-    end
-
-    it "should return correct permissions through the `can?' method" do
-      @user.can!(:view_users)
-      @user.can?(:view_users).should be_true
-      ['FINALIZE_LAB_SELECTION_LIST', 'SEARCH_APPLICANTS', 'CREATE_BASIC_USER', 'VIEW_BUDGET_REPORT'].each do |permission|
-        @user.can?(permission).should be_false
-      end
-    end
-
-    it "should return correct permissions on multiple requests" do
-      @user.can!(:view_users)
-      @user.can!(:view_budget_report)
-      @user.can?(:view_users, :view_budget_report).should be_true
-      ['FINALIZE_LAB_SELECTION_LIST', 'SEARCH_APPLICANTS', 'CREATE_BASIC_USER'].each do |permission|
-        @user.can?(:view_users, permission).should be_false
-      end
-    end
-
-    it "should revoke the correct permissions through the `revoke' method" do
-      @user.can!(:view_users, :view_budget_report)
-      @user.can?(:view_users).should be_true
-      @user.can?(:view_budget_report).should be_true
-      @user.revoke(:view_users)
-      @user.can?(:view_users).should be_false
-      @user.can?(:view_budget_report).should be_true
-    end
-
-    it "should revoke the full permissions through the `revoke' method w/an :all argument" do
-      @user.can!(:view_users, :view_budget_report)
-      @user.can?(:view_users).should be_true
-      @user.can?(:view_budget_report).should be_true
-      @user.revoke(:all)
-      @user.can?(:view_users).should be_false
-      @user.can?(:view_budget_report).should be_false
-    end
-  end
-
-  describe "scoped permissions" do
-    before :each do
-      Permissive::User.acts_as_permissive(:scope => :organizations)
-      @user = Permissive::User.create
-      @organization = Permissive::Organization.create
-    end
-
-    it "should allow scoped permissions checks through the `can?' method" do
-      @user.can?(:view_users, :on => @organization).should be_false
-    end
-
-    it "should return correct permissions through a scoped `can?' method" do
-      @user.can!(:view_users, :on => @organization)
-      @user.can?(:view_users, :on => @organization).should be_true
-    end
-
-    it "should not respond to generic permissions on scoped permissions" do
-      @user.can!(:view_users, :on => @organization)
-      @user.can?(:view_users).should be_false
-      @user.can?(:view_users, :on => @organization).should be_true
-    end
-
-    it "should revoke the correct permissions through the `revoke' method" do
-      @user.can!(:view_users, :view_budget_report, :on => @organization)
-      @user.can?(:view_users, :on => @organization).should be_true
-      @user.can?(:view_budget_report, :on => @organization).should be_true
-      @user.revoke(:view_users, :on => @organization)
-      @user.can?(:view_users, :on => @organization).should be_false
-      @user.can?(:view_budget_report, :on => @organization).should be_true
-    end
-
-    it "should revoke the full permissions through the `revoke' method w/an :all argument" do
-      @user.can!(:create_basic_user)
-      @user.can!(:view_users, :view_budget_report, :on => @organization)
-      @user.can?(:view_users, :on => @organization).should be_true
-      @user.can?(:view_budget_report, :on => @organization).should be_true
-      @user.can?(:create_basic_user).should be_true
-      @user.revoke(:all, :on => @organization)
-      !@user.can?(:view_users, :on => @organization).should be_false
-      !@user.can?(:view_budget_report, :on => @organization).should be_false
-      @user.can?(:create_basic_user).should be_true
-    end
-
-  end
-
-  describe "automatic method creation" do
-    before :each do
-      Permissive::User.acts_as_permissive(:scope => :organizations)
-      @user = Permissive::User.create
-      @organization = Permissive::Organization.create
-      @user.can!(:finalize_lab_selection_list)
-      @user.can!(:create_basic_user)
-      @user.can!(:view_users, :on => @organization)
-    end
-  
-    it "should not respond to invalid permission methods" do
-      lambda {
-        @user.can_finalize_lab_selection_list_fu?
-      }.should raise_error(NoMethodError)
-    end
-  
-    it "should cache chained methods" do
-      @user.respond_to?(:can_finalize_lab_selection_list_and_view_users?).should be_false
-      @user.can_finalize_lab_selection_list_and_view_users?.should be_false
-      @user.should respond_to(:can_finalize_lab_selection_list_and_view_users?)
-    end
-  
-    it "should respond to valid permission methods" do
-      @user.can_finalize_lab_selection_list?.should be_true
-      @user.can_create_basic_user?.should be_true
-      ['SEARCH_APPLICANTS', 'VIEW_USERS', 'VIEW_BUDGET_REPORT'].each do |permission|
-        @user.send("can_#{permission.downcase}?").should be_false
-      end
-    end
-  
-    it "should respond to chained permission methods" do
-      @user.can_finalize_lab_selection_list_and_create_basic_user?.should be_true
-      ['SEARCH_APPLICANTS', 'VIEW_USERS', 'VIEW_BUDGET_REPORT'].each do |permission|
-        @user.send("can_finalize_lab_selection_list_and_#{permission.downcase}?").should be_false
-      end
-    end
-  
-    it "should respond to scoped permission methods" do
-      @user.can_view_users_on?(@organization).should be_true
-      ['FINALIZE_LAB_SELECTION_LIST', 'SEARCH_APPLICANTS', 'CREATE_BASIC_USER', 'VIEW_BUDGET_REPORT'].each do |permission|
-        @user.send("can_#{permission.downcase}_on?", @organization).should be_false
-      end
-    end
-  
-  end
-end
-
-PermissiveSpecHelper.clear_log