permissive 0.0.1 → 0.2.0.alpha

data/.gemspec

@@ -19,7 +19,25 @@ Gem::Specification.new do |s|
     "README.markdown"
   ]
   s.files = [
-    "VERSION"
+    ".gemspec",
+     ".gitignore",
+     "MIT-LICENSE",
+     "README.markdown",
+     "Rakefile",
+     "VERSION",
+     "generators/permissive_migration/USAGE",
+     "generators/permissive_migration/permissive_migration_generator.rb",
+     "generators/permissive_migration/templates/permissive_migration.rb",
+     "lib/permissive.rb",
+     "lib/permissive/acts_as_permissive.rb",
+     "lib/permissive/permission.rb",
+     "lib/permissive/permissions.rb",
+     "rails/init.rb",
+     "spec/acts_as_permissive_spec.rb",
+     "spec/permissions_spec.rb",
+     "spec/rcov.opts",
+     "spec/spec.opts",
+     "spec/spec_helper.rb"
   ]
   s.homepage = %q{http://github.com/flipsasser/permissive}
   s.rdoc_options = ["--charset=UTF-8"]

data/.gitignore

@@ -1,2 +1,4 @@
 *.gem
-pkg/
+coverage/
+pkg/
+**/*.log

data/README.markdown

@@ -1,8 +1,9 @@
 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
+Permissive makes it trivial to add complex permission granting and checking
+to your applications using ActiveRecord. It combines a model-based permissions
+system with bitmasking to create a flexible approach to maintaining permissions
+on your models. It supports an easy-to-use set of methods for accessing and
 determining permissions, including some fun metaprogramming.
 
 Installation
@@ -25,21 +26,30 @@ Installation
 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`".
+First, define a few permissions on an ActiveRecord::Base subclass. You define them using the following simple, block-based API:
 
-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
+	class User < ActiveRecord::Base
+		has_permissions do
+			to :manage_games, 0
+			to :control_rides, 1
+			to :punch, 2
+		end
 	end
 
+The best practice is to name them in a verb format that follows this pattern: "Object can `do_action_name`".
+
+Permission values (the second argument in `to`) need to be int values counting up from zero. We use ints because Permissive uses bit
+masking to keep permissions data compact and performant.
+
 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
+		has_permissions, :on => :companies do
+			to :manage_games, 0
+			to :control_rides, 1
+			to :punch, 2
+		end
+		validates_presence_of :first_name, :last_name
 	end
 
 	class Company < ActiveRecord::Base
@@ -59,8 +69,9 @@ Easy-peasy, right? Let's try granting a few permissions:
 	@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
+	@james.can_manage_games_in! @adventureland
+	@james.can_manage_games_in? @adventureland #=> true
+	@james.can_control_rides_in? @adventureland #=> false
 
 	# We can check for multiple permissions, too:
 	@james.can?(:manage_games, :control_rides) #=> false
@@ -69,17 +80,20 @@ Easy-peasy, right? Let's try granting a few permissions:
 
 	# Scoping can be done through any object
 	@frigo.can!(:punch, :on => @james)
-	@frigo.can_punch_on?(@james) #=> true
+	@frigo.can_punch? @james #=> true
 
 	# And the permissions aren't reciprocal
-	@james.can_punch_on?(@frigo) #=> false
+	@james.can_punch? @frigo #=> false
 
 	# Of course, we can grant global (non-scoped) permissions, too:
-	@frigo.can!(:control_rides)
+	@frigo.can_control_rides!
 	@frigo.can_control_rides? #=> true
 
+	# And we can grant permissions global to a class:
+	@frigo.can_control_rides_in! Company
+
 	# BUT! Global permissions don't override scoped permissions.
-	@frigo.can_control_rides_on?(@adventureland) #=> false
+	@frigo.can_control_rides_in?(@adventureland) #=> false
 
 	# Likewise, scoped permissions don't bubble up globally:
 	@james.can_manage_games? #=> false
@@ -90,6 +104,10 @@ Easy-peasy, right? Let's try granting a few permissions:
 	# We can revoke all permissions, in any scope, too:
 	@frigo.revoke(:all)
 
+	# And revoking does the fun meta thing, too:
+	@frigo.cannot_punch!(@james)
+	@frigo.can_punch? @james #=> flase
+
 And that's it!
 
 Scoping
@@ -128,17 +146,7 @@ which might yield something like
 	# 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:
+Let's add some OR-ing to the whole thing:
 
 	@james.can_control_rides_or_manage_games_in? @adventureland
 

data/Rakefile

@@ -15,7 +15,7 @@ namespace :spec do
   Spec::Rake::SpecTask.new(:rcov) do |t|
     t.spec_files = FileList['spec/**/*.rb']
     t.rcov = true
-    t.rcov_opts = ['--exclude', 'examples']
+    t.rcov_opts = ['--exclude', 'spec/*,gems/*']
   end
 end
 
@@ -30,7 +30,7 @@ begin
     determining permissions, including some fun metaprogramming.}
     gemspec.email = "flip@x451.com"
     gemspec.homepage = "http://github.com/flipsasser/permissive"
-    gemspec.authors = ["Flip Sasser", "Simon Parsons"]
+    gemspec.authors = ["Flip Sasser"]
   end
 rescue LoadError
 end

data/VERSION

@@ -1 +1 @@
-0.0.1
+0.2.0.alpha

data/generators/permissive_migration/templates/permissive_migration.rb

@@ -6,12 +6,10 @@ class InstallPermissive < ActiveRecord::Migration
       t.integer :scoped_object_id
       t.string :scoped_object_type, :limit => 32
       t.integer :mask, :default => 0
-      t.integer :grant_mask, :default => 0
     end
     add_index :permissive_permissions, [:permitted_object_id, :permitted_object_type], :name => 'permissive_permitted'
     add_index :permissive_permissions, [:scoped_object_id, :scoped_object_type], :name => 'permissive_scoped'
     add_index :permissive_permissions, :mask, :name => 'permissive_masks'
-    add_index :permissive_permissions, :grant_mask, :name => 'permissive_grant_masks'
   end
 
   def self.down

data/lib/permissive.rb

@@ -1,15 +1,17 @@
-require 'permissive/permission'
-require 'permissive/acts_as_permissive'
-require 'permissive/permissions'
+require 'permissive/errors'
+require 'permissive/has_permissions'
 
 module Permissive
-  @@strong = false
-
-  def self.strong
-    @@strong
-  end
-
-  def self.strong=(new_strong)
-    @@strong = !!new_strong
-  end
+  # @@strong = false
+  # 
+  # def self.strong
+  #   @@strong
+  # end
+  # 
+  # def self.strong=(new_strong)
+  #   @@strong = !!new_strong
+  # end
+  # 
+  autoload(:Permission, 'permissive/permission')
+  autoload(:PermissionDefinition, 'permissive/permission_definition')
 end

data/lib/permissive/errors.rb

@@ -0,0 +1,4 @@
+module Permissive
+  class PermissionError < StandardError; end;
+  class InvalidPermissionError < StandardError; end;
+end

data/lib/permissive/has_permissions.rb

@@ -0,0 +1,153 @@
+module Permissive
+  module HasPermissions
+    module ClassMethods
+      def self.extended(base)
+
+      end
+
+      def has_permissions(options = {}, &block)
+        options.assert_valid_keys(:on)
+
+        # Define a permissions method. This will track scoped or global
+        # permission levels, depending on how you define them.
+        class_eval do
+          def self.permissions
+            @permissions ||= {}
+          end
+        end unless respond_to?(:permissions)
+
+        include InstanceMethods
+
+        has_many :permissions, :class_name => 'Permissive::Permission', :as => :permitted_object do
+          def can!(*args)
+            options = args.extract_options!
+            options.assert_valid_keys(:on, :reset)
+            permission_matcher = case options[:on]
+            when ActiveRecord::Base
+              permission = proxy_owner.permissions.find_or_initialize_by_scoped_object_id_and_scoped_object_type(options[:on].id, options[:on].class.name)
+            when Class
+              permission = proxy_owner.permissions.find_or_initialize_by_scoped_object_id_and_scoped_object_type(nil, options[:on].name)
+            when String, Symbol
+              class_name = Permissive::PermissionDefinition.interpolate_scope(proxy_owner.class, options[:on])
+              permission = proxy_owner.permissions.find_or_initialize_by_scoped_object_id_and_scoped_object_type(nil, class_name)
+            else
+              permission = Permissive::Permission.find_or_initialize_by_permitted_object_id_and_permitted_object_type_and_scoped_object_id_and_scoped_object_type(proxy_owner.id, proxy_owner.class.to_s, nil, nil)
+            end
+            if options[:reset]
+              permission.mask = 0
+            end
+            bits_for(options[:on], args).each do |bit|
+              unless permission.mask & bit != 0
+                permission.mask = permission.mask | bit
+              end
+            end
+            permission.save!
+            permission
+          end
+
+          def can?(*args)
+            options = args.extract_options!
+            options.assert_valid_keys(:in, :on)
+            options[:on] ||= options.delete(:in)
+            !on(options[:on]).granted(bits_for(options[:on], args)).empty?
+          end
+
+          def revoke(*args)
+            options = args.extract_options!
+            if args.length == 1 && args.first == :all
+              on(options[:on]).destroy_all
+            else
+              bits = bits_for(options[:on], args)
+              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
+
+          def bits_for(scope, permissions)
+            on = PermissionDefinition.normalize_scope(proxy_owner.class, scope)
+            permissions.map do |permission|
+              proxy_owner.class.permissions[on].try(:permissions).try(:[], permission.to_s.underscore.gsub('/', '_').to_sym) || raise(Permissive::InvalidPermissionError.new("#{proxy_owner.class.name} does not have a#{'n' if permission.to_s[0, 1].downcase =~ /[aeiou]/} #{permission} permission#{" on #{on}" if on}"))
+            end
+          end
+          private :bits_for
+        end
+
+        delegate :can!, :can?, :revoke, :to => :permissions
+
+        permission_definition = Permissive::PermissionDefinition.define(self, options, &block)
+
+        permission_setter = options[:on].nil? || options[:on] == :global ? 'permissions=' : "#{options[:on].to_s.singularize}_permissions="
+        class_eval <<-eoc
+          def #{permission_setter}(values)
+            if values.all? {|value| value.is_a?(String) || value.is_a?(Symbol)}
+              can!(values, :reset => true, :on => #{options[:on].inspect})
+            else
+              super
+            end
+          end
+        eoc
+        
+
+        # Oh that's right, it'll return an object.
+        permission_definition
+      end
+      alias :has_permission :has_permissions
+    end
+  end
+
+  module InstanceMethods
+    def method_missing(method, *args)
+      if method.to_s =~ /^can(not){0,1}_([^\?]+)(\?|!)$/
+        revoke = $1 == "not"
+        permissions = $2
+        setter = $3 == "!"
+        options = args.extract_options!
+        options[:on] ||= args.pop
+        if permissions =~ /_(on|in)$/
+          permissions.chomp!("_#{$1}")
+        end
+        if options[:on]
+          scope = Permissive::PermissionDefinition.normalize_scope(self.class, options[:on])
+        else
+          scope = :global
+        end
+        permissions = permissions.split('_and_')
+        if permissions.all? {|permission| self.class.permissions[scope].permissions.has_key?(permission.downcase.to_sym) }
+          if revoke
+            class_eval <<-end_eval
+            def #{method}(scope = nil)
+              revoke(#{[permissions, args].flatten.join(', ').inspect}, :on => scope)
+            end
+            end_eval
+            return can!(*[permissions, options].flatten)
+          elsif setter
+            class_eval <<-end_eval
+            def #{method}(scope = nil)
+              can!(#{[permissions, args].flatten.join(', ').inspect}, :on => scope)
+            end
+            end_eval
+            return can!(*[permissions, options].flatten)
+          else
+            class_eval <<-end_eval
+            def #{method}(scope = nil)
+              can?(#{[permissions, args].flatten.join(', ').inspect}, :on => scope)
+            end
+            end_eval
+            return can?(*[permissions, options].flatten)
+          end
+        end
+      end
+      super
+    end
+  end
+end
+
+if defined?(ActiveRecord::Base)
+  ActiveRecord::Base.extend Permissive::HasPermissions::ClassMethods
+end

data/lib/permissive/permission.rb

@@ -4,40 +4,22 @@ module Permissive
     attr_writer :grant_template, :template
     belongs_to :permitted_object, :polymorphic => true
     belongs_to :scoped_object, :polymorphic => true
+    named_scope :granted, lambda {|permissions|
+      {:conditions => permissions.map{|bit| "mask & #{bit}"}.join(' AND ')}
+    }
     named_scope :on, lambda {|scoped_object|
-      if scoped_object.nil?
-        {:conditions => ['scoped_object_id IS NULL AND scoped_object_type IS NULL']}
+      case scoped_object
+      when ActiveRecord::Base
+        {:conditions => {:scoped_object_id => scoped_object.id, :scoped_object_type => scoped_object.class.to_s}}
+      when Class
+        {:conditions => {:scoped_object_id => nil, :scoped_object_type => scoped_object.name}}
+      when Symbol
+        {:conditions => {:scoped_object_id => nil, :scoped_object_type => scoped_object.to_s.classify}}
       else
-        {:conditions => ['scoped_object_id = ? AND scoped_object_type = ?', scoped_object.id, scoped_object.class.to_s]}
+        {:conditions => {:scoped_object_id => nil, :scoped_object_type => nil}}
       end
     }
     set_table_name :permissive_permissions
-    validates_presence_of :grant_mask, :mask, :permitted_object
-
-    class << self
-      # Use this anywhere!
-      def bit_for(permission)
-        Permissive::Permissions.hash[permission.to_s.downcase.to_sym] || 0
-      end
-    end
-
-    protected
-    def before_save
-      # Save permission templates or "Roles"
-      if @grant_template
-        grant_mask = @grant_template
-      end
-      if @template
-        mask = @template
-      end
-
-      # If Permissive is set to be seriously intense about who can grant what to
-      # whom, it makes sure no bits on the grant_mask exceed those of the
-      # permission mask
-      # TODO: You know ... this.
-      # if grant_mask && Permissive.strong
-      #   grant_mask = grant_mask & mask
-      # end
-    end
+    validates_presence_of :mask, :permitted_object
   end
 end

data/lib/permissive/permission_definition.rb

@@ -0,0 +1,94 @@
+# TODO: Abstract this module more later
+module Permissive
+  class PermissionDefinition
+    class << self
+      def define(model, options, &block)
+        options.assert_valid_keys(:on)
+        options = {:on => :global}.merge(options)
+
+        unless options[:on] == :global
+          options[:on] = normalize_scope(model, options[:on])
+        end
+        permission_definition = model.permissions[options[:on]] ||= Permissive::PermissionDefinition.new(model, options)
+        if block_given?
+          permission_definition.instance_eval(&block)
+        end
+        permission_definition
+      end
+
+      def interpolate_scope(model, scope)
+        attempted_scope = scope.to_s.singularize.classify
+        model_module = model.name.to_s.split('::')
+        model_module.pop
+        model_module = model_module.join('::')
+        if (model_module.blank? ? Object : Object.const_get(model_module)).const_defined?(attempted_scope)
+          [model_module, attempted_scope].join('::')
+        else
+          scope.to_s.classify
+        end
+      end
+
+      def normalize_scope(model, scope)
+        case scope
+        when Class
+          scope.name.tableize
+        when String, Symbol
+          interpolate_scope(model, scope).to_s.tableize
+        else
+          :global
+        end.to_s.gsub('/', '_').to_sym
+      end
+    end
+
+    def can(name, value = nil)
+      if value
+        to(name, value)
+      end
+      name = name.to_s.downcase.to_sym
+      roles[@role].push(name) unless roles[@role].include?(name)
+    end
+
+    def initialize(model, options = {})
+      options.assert_valid_keys(:on)
+      @options = options
+      @model = model.name
+    end
+
+    def model
+      @model.constantize
+    end
+
+    def on(class_name, &block)
+      Permissive::PermissionDefinition.define(model, @options.merge(:on => class_name), &block)
+    end
+
+    def permission(name, value)
+      unless value.is_a?(Numeric)
+        raise Permissive::PermissionError.new("Permissions must be integers or longs. Strings, symbols, and floats are not currently supported.")
+      end
+      permissions[name.to_s.downcase.to_sym] = 2 ** value
+    end
+    alias :to :permission
+
+    def permissions
+      @permissions ||= {}
+    end
+
+    def role(name, &block)
+      @role = name.to_s.to_sym
+      roles[@role] ||= []
+      instance_eval(&block)
+      unless model.instance_methods.include?('role=')
+        model.class_eval do
+          def role=(role_name)
+            self.permissions = self.class.permissions[:global].roles[role_name.to_s.downcase.to_sym]
+          end
+        end
+      end
+    end
+
+    def roles
+      @roles ||= {}
+    end
+  end
+end