permissive 0.0.0

data/README.markdown

@@ -0,0 +1,179 @@
+Permissive gives your ActiveRecord models granular permission support
+=
+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.
+
+Installation
+-
+
+1. Get yourself some code. You can install as a gem:
+
+	`gem install permissive`
+
+	or as a plugin:
+	
+	`script/plugin install git://github.com/flipsasser/permissive.git`
+
+2. Generate a migration so you can get some sweet table action:
+
+	`script/generate permissive_migration`
+
+	`rake db:migrate`
+
+Usage
+-
+
+First, define a few permissions constants. We'll define them in `Rails.root/config/initializers/permissive.rb`. The best practice is to name them in a verb format that follows this pattern: "Object can `DO_PERMISSION_NAME`".
+
+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.
+
+	module Permissive::Permissions
+		MANAGE_GAMES = 0
+		CONTROL_RIDES = 1
+		PUNCH = 2
+	end
+
+And that's all it takes to configure permissions! Now that we have them, let's grant them to a model or two:
+
+	class Employee < ActiveRecord::Base
+		acts_as_permissive
+		validates_presence_of :first_name, :last_name
+	end
+
+	class Company < ActiveRecord::Base
+		validates_presence_of :name
+	end
+
+Easy-peasy, right? Let's try granting a few permissions:
+
+	@james = Employee.create(:first_name => 'James', :last_name => 'Brennan')
+	@frigo = Employee.create(:first_name => 'Tommy', :last_name => 'Frigo')
+	@adventureland = Company.create(:name => 'Adventureland')
+
+	# Okay, let's do some granting. We'll start by scoping to a specific company.
+	@james.can!(:manage_games, :on => @adventureland)
+
+	# Now let's do some permission checking.
+	@james.can?(:manage_games, :on => @adventureland) #=> true
+
+	# We can also use the metaprogramming syntax:
+	@james.can_manage_games_on?(@adventureland) #=> true
+	@james.can_control_rides_on?(@adventureland) #=> false
+
+	# We can check for multiple permissions, too:
+	@james.can?(:manage_games, :control_rides) #=> false
+	# OR:
+	@james.can_manage_games_and_control_rides?
+
+	# Scoping can be done through any object
+	@frigo.can!(:punch, :on => @james)
+	@frigo.can_punch_on?(@james) #=> true
+
+	# And the permissions aren't reciprocal
+	@james.can_punch_on?(@frigo) #=> false
+
+	# Of course, we can grant global (non-scoped) permissions, too:
+	@frigo.can!(:control_rides)
+	@frigo.can_control_rides? #=> true
+
+	# BUT! Global permissions don't override scoped permissions.
+	@frigo.can_control_rides_on?(@adventureland) #=> false
+
+	# Likewise, scoped permissions don't bubble up globally:
+	@james.can_manage_games? #=> false
+
+	# And, last but not least, let's take all of those great permissions away:
+	@james.revoke(:manage_games, :on => @adventureland)
+
+	# We can revoke all permissions, in any scope, too:
+	@frigo.revoke(:all)
+
+And that's it!
+
+Scoping
+-
+
+Permissive supports scoping at the class-configuration level, which adds relationships to permitted objects:
+
+	class Employee < ActiveRecord::Base
+		acts_as_permissive :scope => :company
+	end
+
+	@frigo.permissive_companies #=> [Company 1, Company 2]
+
+Replacing Permissions
+-
+
+Sometimes you want to overwrite all previous permissions in a can! method. That's pretty easy: just add :reset => true to the options.
+
+	@frigo.can!(:control_rides, :on => @adventureland, :reset => true)
+
+Next Steps
+-
+
+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 `has_many` relationship. `@employee.can!(:do_anything)` will still work, as will `@employee.can!(:do_something, :on => @something_that_isnt_a_company)`. That's pretty confusing to me. Adding more granular permissions might be cooler:
+
+	class Employee < ActiveRecord::Base
+		has_permissions do
+			on :companies
+			on :employees
+		end
+	end
+
+which might yield something like
+
+	@employee.permissive_companies
+	# and
+	@employee.can_control_rides_in_company @adventureland
+
+I'd also like to support a more intelligent grammar:
+
+	@james.can_punch? @frigo
+	@frigo.can!(:control_rides, :in => @adventureland)
+
+Meta-programmed methods for granting and revoking would be cool, too:
+
+	@james.can_punch! @frigo
+	@frigo.cannot_control_rides_in! @adventureland
+
+And while we're on the subject of metaprogramming, let's add some OR-ing to the whole thing:
+
+	@james.can_control_rides_or_manage_games_in? @adventureland
+
+I'd also like to enable Permissive::Templates (pre-set permission groups, like roles):
+
+	administrator = Permissive::Template.named('Administrator')
+	@james.acts_like administrator
+
+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:
+
+	<%= check_box_tag("employee[permissions][]", Permissive::Permissions::CONTROL_RIDES, @employee.can_control_rides?) %> Control rides
+
+.. and in the controller:
+
+	def update
+		@employee.can!(params[:employees].delete(:permissions), :revert => true)
+		respond_to do |format|
+			...
+		end
+	end
+
+Finally, I'd like to use the `grant_mask` 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.:
+
+	<% current_user.grant_permissions.each do |permission| %>
+	<!-- Do something! -->
+	<% end %>
+
+and second, write-time checking of grantor permissions. Something like this, maybe:
+
+	def update
+		current_user.grant(params[:employees][:permissions], :to => @employee)
+	end
+
+which would allow the Permissive::Permission model to make sure whatever `current_user` is granting to @employee, they're **allowed** to grant to @employee.
+
+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!
+
+Copyright (c) 2009 Flip Sasser, released under the MIT license

data/VERSION

@@ -0,0 +1 @@
+0.0.0

data/spec/acts_as_permissive_spec.rb

@@ -0,0 +1,192 @@
+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

data/spec/permissions_spec.rb

@@ -0,0 +1,44 @@
+require File.join(File.dirname(__FILE__), 'spec_helper')
+describe Permissive::Permissions do
+  before :each do
+    PermissiveSpecHelper.db_up
+  end
+
+  after :each do
+    PermissiveSpecHelper.db_down
+  end
+
+  context "permission constants" do
+    it "should have a `hash' method" do
+      Permissive::Permissions.should respond_to(:hash)
+    end
+
+    it "should return an ordered hash when `hash' is called" do
+      Permissive::Permissions.hash.should be_instance_of(ActiveSupport::OrderedHash)
+    end
+
+    it "should have symbol keys for the permission constants" do
+      Permissive::Permissions.hash.has_key?(:finalize_lab_selection_list).should be_true
+    end
+
+    it "should convert all CONSTANT values to base-2 compatible integers" do
+      Permissive::Permissions.constants.each do |constant|
+        Permissive::Permissions.hash[constant.downcase.to_sym].should == 2 ** Permissive::Permissions.const_get(constant)
+      end
+    end
+
+    it "should explode when a constant isn't Numeric" do
+      Permissive::Permissions.const_set('FOOBAR', 'achoo')
+      lambda {
+        Permissive::Permissions.hash
+      }.should raise_error(Permissive::PermissionError)
+
+      Permissive::Permissions.const_set('FOOBAR', 5)
+      lambda {
+        Permissive::Permissions.hash
+      }.should_not raise_error(Permissive::PermissionError)
+    end
+  end
+end
+
+PermissiveSpecHelper.clear_log

data/spec/spec_helper.rb

@@ -0,0 +1,59 @@
+require 'rubygems'
+require 'activerecord'
+require 'permissive'
+
+module PermissiveSpecHelper
+  def self.clear_log
+    File.open(PermissiveSpecHelper.log_path, 'w') do |file|
+      file.puts ''
+    end
+  end
+
+  def self.db_down
+    File.unlink(db) if File.exists?(db)
+  end
+
+  def self.db_up
+    db_down
+    ActiveRecord::Base.establish_connection({:adapter => 'sqlite3', :database => db, :pool => 5, :timeout => 5000})
+    silence_stream(STDOUT) do
+      ActiveRecord::Schema.define do
+        create_table :permissive_users, :force => true do |t|
+          t.timestamps
+        end
+        create_table :permissive_organizations, :force => true do |t|
+          t.timestamps
+        end
+        create_table :permissive_permissions do |t|
+          t.integer :permitted_object_id
+          t.string :permitted_object_type, :limit => 32
+          t.integer :scoped_object_id
+          t.string :scoped_object_type, :limit => 32
+          t.integer :mask, :default => 0
+          t.integer :grant_mask, :default => 0
+        end
+      end
+    end
+  end
+
+  def self.log_path
+    File.join(File.dirname(__FILE__), 'spec.log')
+  end
+
+  private
+  def self.db
+    @@db ||= File.expand_path(File.join(File.dirname(__FILE__), 'test.sqlite3'))
+  end
+end
+
+# Setup some test permissions
+module Permissive::Permissions
+  FINALIZE_LAB_SELECTION_LIST = 0
+  SEARCH_APPLICANTS = 1
+  CREATE_BASIC_USER = 2
+  VIEW_USERS = 3
+  VIEW_BUDGET_REPORT = 4
+end
+
+# Setup the logging
+ActiveRecord::Base.logger = Logger.new(PermissiveSpecHelper.log_path)

metadata

@@ -0,0 +1,63 @@
+--- !ruby/object:Gem::Specification 
+name: permissive
+version: !ruby/object:Gem::Version 
+  version: 0.0.0
+platform: ruby
+authors: 
+- Flip Sasser
+- Simon Parsons
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2009-11-01 00:00:00 -04:00
+default_executable: 
+dependencies: []
+
+description: |-
+  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.
+email: flip@x451.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- README.markdown
+files: 
+- VERSION
+- README.markdown
+has_rdoc: true
+homepage: http://github.com/flipsasser/permissive
+licenses: []
+
+post_install_message: 
+rdoc_options: 
+- --charset=UTF-8
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.3.5
+signing_key: 
+specification_version: 3
+summary: Permissive gives your ActiveRecord models granular permission support
+test_files: 
+- spec/acts_as_permissive_spec.rb
+- spec/permissions_spec.rb
+- spec/spec_helper.rb