indulgence 0.0.1 → 0.0.2

data/README.rdoc

@@ -9,8 +9,8 @@ things:
 * Filtered a search of objects based on the those permissions
 
 It was apparent to me that if 'something' was one of the CRUD actions, it would
-cover all the use cases I could think of. So permissions were sub-divided into
-the 'abilities': create, read, update, and delete.
+cover most of the use cases I could think of. So permissions were sub-divided 
+into the 'abilities': create, read, update, and delete.
 
 The other requirement was that the permission for an object could be defined
 succinctly within a single file.
@@ -45,12 +45,10 @@ placing it in app/permissions/thing_permission.rb
 == Users and Roles
 
 Indulgence assumes that permissions will be tested against an entity object
-(e.g. User), that has a role object associated with it, and that each role can 
-be uniquely identified by a name method.
+(e.g. User). The default behaviour assumes that the entity object has a :role 
+method that returns the role object, and that the role object has a :name method. 
 
-The default behaviour assumes that the entity object has a :role method that
-returns the role object, and that the role object has a :name method. So
-typically, these objects could look like this:
+So typically, these objects could look like this:
 
     class User < ActiveRecord::Base 
       belongs_to :role
@@ -68,7 +66,7 @@ typically, these objects could look like this:
       :role_id => role.id
     ) 
 
-== indulge?
+== Compare single item: indulge?
 
 Simple true/false permission can be determined using the :indulge? method:
 
@@ -79,7 +77,7 @@ Simple true/false permission can be determined using the :indulge? method:
     thing.indulge?(user, :update) == false
     thing.indulge?(user, :delete) == false
 
-== indulgence
+== Filter many: indulgence
 
 The :indulgence method is used as a where filter:
 
@@ -128,8 +126,8 @@ _default_ rather than being defined in _emperor_, as it is already set to *all*.
 
 abilities is a hash of hashes. The lowest level, associates action names with
 ability objects. The top level associates role names to the lower level ability 
-object hashes. The construction is perhaps clearer in the abilities above was
-written like this:
+object hashes. In this simple case, construction is perhaps clearer if the 
+abilities method above was written like this:
 
     def abilities
       {
@@ -179,21 +177,27 @@ permissions. This can be done by adding this method to ThingPermission:
   def things_they_wrote
     define_ability(
       :name => :things_they_wrote,
-      :truth => lambda {|thing| thing.author_id == entity.id},
-      :where_clause => {:author_id => entity.id}
+      :compare_single => lambda {|thing, user| thing.author_id == user.id},
+      :filter_many => lambda {|things, user| things.where(:author_id => user.id)}
     )
   end
 
 This will create an Ability object with the following methods:
 
-[name]          Allows abilities of the same kind to be matched
-[truth]         Used by :indulge?
-[where_clause]  Used by :indulgence 
+[name]           Allows abilities of the same kind to be matched
+[compare_single] Used by :indulge?
+[filter_many]    Used by :indulgence 
 
-Note that Indulgence::Permission#entity returns the entity object passed to the 
-instance on creation. In this example, that will be the User.
+==== Compare single
 
-==== The where clause
+_compare_single_ should be a lambda that is passed the object being tested and
+the entity it is to be tested against. The lambda returns _true_ if permission 
+should be given. Otherwise _false_ should be returned.
+
+Alternatively, instead of a lambda, any object can be used that returns _true_
+or _false_ when it _call_ method is passed the object and the entity.
+
+==== Filter many
 
 In this example: 
 
@@ -201,14 +205,6 @@ In this example:
 
 if the :read ability is matched to *things_they_wrote*
 
-==== truth
-
-In *all* :truth is simply _true_, and in *none* :truth is _false_.
-
-For more complex abilities :truth should be a lambda that is passed the object 
-being tested, and returns _true_ if permission should be given. Otherwise _false_ 
-should be returned.
-
 Once *things_they_wrote* has been defined, we can use it to define a new set
 of abilities:
 
@@ -297,8 +293,8 @@ The method names _indulgence_ and _indulge?_ may not suit your application. If
 you wish to use alternative names, they can be aliased like this:
 
     acts_as_indulgent(
-      :truth_method => :permit?,
-      :where_method => :permitted
+      :compare_single_method => :permit?,
+      :filter_many_method => :permitted
     )
 
 With this used to define indulgence in Thing, we can do this:

data/lib/active_record/acts/indulgent.rb

@@ -11,8 +11,8 @@ module ActiveRecord
           include Indulgence::Indulgent::InstanceMethods
           extend Indulgence::Indulgent::ClassMethods
           
-          alias_method args[:truth_method], :indulge? if args[:truth_method]
-          singleton_class.send(:alias_method, args[:where_method], :indulgence) if args[:where_method]
+          alias_method args[:compare_single_method], :indulge? if args[:compare_single_method]
+          singleton_class.send(:alias_method, args[:filter_many_method], :indulgence) if args[:filter_many_method]
           self.indulgent_permission_class = args[:using]
         end
         

data/lib/indulgence/ability.rb

@@ -1,19 +1,41 @@
 
 module Indulgence
   class Ability
-    attr_reader :name, :truth, :where_clause
+    attr_reader :name, :compare_single, :filter_many
     
     def initialize(args = {})
       @name = args[:name]
-      @truth = args[:truth]
-      @where_clause = args[:where_clause]
+      @compare_single = args[:compare_single]
+      @filter_many = args[:filter_many]
+      valid?
     end
     
     def ==(another_ability)
-      [:name, :truth, :where_clause].each do |method|
+      [:name, :compare_single, :filter_many].each do |method|
         return false if send(method) != another_ability.send(method)
       end
       return true
     end
+    
+    def valid?
+      must_be_name
+      must_respond_to_call :compare_single
+      must_respond_to_call :filter_many
+    end
+    
+    private
+    def must_be_name
+      unless name
+        raise AbilityConfigurationError, "A name is required for each ability"
+      end
+    end
+    
+    def must_respond_to_call(method)
+      unless send(method).respond_to? :call
+        raise AbilityConfigurationError, "ability.#{method} must respond to call"
+      end
+    end
+    
+    
   end
 end

data/lib/indulgence/exceptions.rb

@@ -0,0 +1,5 @@
+module Indulgence 
+  class AbilityConfigurationError < StandardError; end
+  class NotFoundError < StandardError; end
+  class AbilityNotFound < StandardError; end
+end

data/lib/indulgence/indulgent.rb

@@ -4,8 +4,9 @@ module Indulgence
     module ClassMethods      
       def indulgence(entity, ability)
         permission = indulgent_permission_class.new(entity, ability)
-        raise_not_found if permission.ability == Permission.none or permission.ability.blank?
-        where(permission.where)
+        permission.filter_many(self)
+      rescue Indulgence::NotFoundError, Indulgence::AbilityNotFound
+        raise_not_found
       end
       
       private
@@ -18,7 +19,7 @@ module Indulgence
       
       def indulge?(entity, ability)
         permission = self.class.indulgent_permission_class.new(entity, ability)
-        return permission.indulge? self
+        return permission.compare_single self
       end
       
     end

data/lib/indulgence/permission.rb

@@ -1,5 +1,3 @@
-require_relative 'ability'
-
 module Indulgence
   class Permission
     attr_reader :entity, :ability
@@ -8,6 +6,7 @@ module Indulgence
       self
       @entity = entity
       @ability = abilities_for_role[ability]
+      raise AbilityNotFound, "Unable to find an ability called #{ability}" unless @ability
     end
 
     def abilities
@@ -18,12 +17,14 @@ module Indulgence
       raise 'There must always be a default'
     end
     
-    def where
-      ability.where_clause
+    def filter_many(things)
+      check_method_can_be_called(:filter_many)
+      ability.filter_many.call things, entity
     end
     
-    def indulge?(thing)
-      ability.truth.respond_to?(:call) ? ability.truth.call(thing) : ability.truth
+    def compare_single(thing)
+      check_method_can_be_called(:compare_single)
+      ability.compare_single.call thing, entity
     end
     
     @@role_method = :role
@@ -47,21 +48,24 @@ module Indulgence
     end
 
     def self.none
-      @none ||= define_ability(
+      Permission.define_ability(
         :name => :none,
-        :truth => false
+        :compare_single => lambda {|thing, entity| false},
+        :filter_many => lambda {|things, entity| raise NotFoundError}
       )
     end
 
     def self.all
-      @all ||= define_ability(
+      Permission.define_ability(
         :name => :all,
-        :truth => true
+        :compare_single => lambda {|thing, entity| true},
+        :filter_many => lambda {|things, entity| things.where(nil)}
       )
     end
     
     def self.define_ability(args)
-      Ability.new args
+      raise AbilityConfigurationError, "A name is required for each ability" unless args[:name]
+      ability_cache[args[:name].to_sym] ||= Ability.new args
     end
     
     def define_ability(args)
@@ -99,6 +103,14 @@ module Indulgence
 
     def none
       self.class.none
-    end  
+    end 
+    
+    def self.ability_cache
+      @ability_cache ||= {}
+    end
+    
+    def check_method_can_be_called(name)
+      raise AbilityConfigurationError, "#{name} method must respond to call" unless ability.send(name).respond_to? :call
+    end
   end
 end

data/lib/indulgence/version.rb

@@ -1,10 +1,28 @@
 module Indulgence
-  VERSION = "0.0.1"
+  VERSION = "0.0.2"
 end
 
 # History
 # =======
 # 
+# 0.0.2   Rebuild with lessons learnt from first usage in host app
+# 
+#         Adds automatic caching of abilites. Required a reworking of ability 
+#         lambdas, so that a particular entity id wasn't cached
+#         
+#         Renamed ability methods truth as compare_single, and where_clause as 
+#         filter_many as more descriptive.
+#         
+#         Forced Ability methods #compare_single and #filter_many to use lambdas 
+#         (or other object that responds to call). The reasons:
+#         
+#           1. To remove the special way that the none ability was handled.
+#           2. Previously, if Ability#filter_many was nil everything would be returned,
+#              which I think is counter-intuitive.
+#           3. Also if Ability#filter_many was undefined, then everything would
+#              be returned, which is just poor design for a permission tool. Now
+#              an error is raised. 
+# 
 # 0.0.1   Initial build
 #         First alpa version
 #

data/lib/indulgence.rb

@@ -1,3 +1,5 @@
+require_relative 'indulgence/exceptions'
+require_relative 'indulgence/ability'
 require_relative 'indulgence/permission'
 require_relative 'indulgence/indulgent'
 require_relative 'active_record/acts/indulgent'

data/test/lib/thing.rb

@@ -1,11 +1,14 @@
-
+require 'indulgence'
+require 'role'
+require 'user'
+require 'thing_permission'
 class Thing < ActiveRecord::Base
 
   belongs_to :owner, :class_name => 'User'
   
   acts_as_indulgent(
-    :truth_method => :permit?,
-    :where_method => :permitted
+    :compare_single_method => :permit?,
+    :filter_many_method => :permitted
   )
   
 end

data/test/lib/thing_permission.rb

@@ -36,10 +36,10 @@ class ThingPermission < Indulgence::Permission
   end
   
   def things_they_own
-    @things_they_own ||= define_ability(
+    define_ability(
       :name => :things_they_own,
-      :truth => lambda {|thing| thing.owner_id == entity.id},
-      :where_clause => {:owner_id => entity.id}
+      :compare_single => lambda {|thing, user| thing.owner_id == user.id},
+      :filter_many => lambda {|things, user| things.where(:owner_id => user.id)}
     )
   end
   

data/test/units/indulgence/ability_test.rb

@@ -1,36 +1,45 @@
 require_relative '../../test_helper'
 require 'ability'
+require 'exceptions'
 
 module Indulgence
   class AbilityTest < Test::Unit::TestCase
     
-    def test_none
-      none = Ability.new(
-        :name => :none,
-        :truth => false
-      )
-      assert_equal(:none, none.name)
-      assert_equal(false, none.truth)
-      assert_equal(nil, none.where_clause)
-    end
-    
-    def test_all
-      all = Ability.new(
-        :name => :all,
-        :truth => true
-      )
-      assert_equal(:all, all.name)
-      assert_equal(true, all.truth)
-      assert_equal(nil, all.where_clause)
+    def setup
+      @attributes = {
+        name: :foo, 
+        compare_single: lambda {|thing, entity| true},
+        filter_many: lambda {|entity| nil}
+      }
     end
     
     def test_equality
-      attributes = {:name => :same, :true => true}
-      ability = Ability.new(attributes)
-      other_ability = Ability.new(attributes)
+      ability = Ability.new(@attributes)
+      other_ability = Ability.new(@attributes)
       assert(ability == other_ability, "#{ability} == #{other_ability} should return true")
       assert_equal(ability, other_ability)
     end
     
+    def test_name_absence_raises_error
+      @attributes.delete(:name)
+      assert_initiation_raises_error
+    end
+    
+    def test_indulge_must_respond_to_call
+      @attributes[:compare_single] = true
+      assert_initiation_raises_error
+    end
+    
+    def test_indulgence_must_respond_to_call
+      @attributes[:filter_many] = true
+      assert_initiation_raises_error
+    end
+    
+    def assert_initiation_raises_error
+      assert_raise AbilityConfigurationError do
+        Ability.new(@attributes)
+      end
+    end
+    
   end
 end

data/test/units/indulgence/permission_test.rb

@@ -1,5 +1,7 @@
 require_relative '../../test_helper'
 require 'user'
+require 'permission'
+require 'ability'
 
 module Indulgence
   class PermissionTest < Test::Unit::TestCase
@@ -10,6 +12,19 @@ module Indulgence
       end
     end
     
+    def test_define_ability_uses_cache_rather_than_duplicates
+      args = {
+        name: :test_ability,
+        compare_single: lambda {|thing, entity| true},
+        filter_many: lambda {|entity| nil}
+      }
+      abilities_at_start = ObjectSpace.each_object(Ability).count
+      Permission.define_ability args
+      Permission.define_ability args
+      Permission.define_ability args
+      assert_equal((abilities_at_start + 1), ObjectSpace.each_object(Ability).count)
+      assert_equal Ability, Permission.send(:ability_cache)[:test_ability].class
+    end
 
   end
 end

data/test/units/thing_permission_test.rb

@@ -62,6 +62,12 @@ class ThingPermissionTest < Test::Unit::TestCase
     test_super_user_permissions
   end
   
+  def test_with_unspecified_ability
+    assert_raise Indulgence::AbilityNotFound do
+      ThingPermission.new(@user, :unspecified)
+    end
+  end
+  
   def teardown
     User.delete_all
     Role.delete_all

data/test/units/thing_test.rb

@@ -28,10 +28,17 @@ class ThingTest < Test::Unit::TestCase
     make_second_thing
     @owner.update_attribute(:role_id, @god.id)
     assert_equal(true, @thing.indulge?(@owner, :read))
+    @thing.indulge?(@owner, :delete)
     assert_equal(true, @thing.indulge?(@owner, :delete))
     assert_equal(true, @other_thing.indulge?(@owner, :delete))    
   end
   
+  def test_indulgence_by_god
+    make_second_thing
+    @owner.update_attribute(:role_id, @god.id)
+    assert_equal(Thing.all, Thing.indulgence(@owner, :delete))  
+  end
+  
   def test_indulge_by_demigod
     make_second_thing
     @owner.update_attribute(:role_id, @demigod.id)
@@ -57,6 +64,12 @@ class ThingTest < Test::Unit::TestCase
     end
   end
   
+  def test_indulgence_with_unspecified_ability
+    assert_raise ActiveRecord::RecordNotFound do
+      Thing.indulgence(@owner, :unspecified)
+    end    
+  end
+  
   def test_find
     make_second_thing
     @owner.update_attribute(:role_id, @demigod.id)
@@ -66,14 +79,14 @@ class ThingTest < Test::Unit::TestCase
     end
   end
   
-  def test_truth_method
+  def test_aliased_compare_single_method
     make_second_thing
     assert_equal(true, @thing.permit?(@owner, :read))
     assert_equal(false, @thing.permit?(@owner, :delete))
     assert_equal(false, @other_thing.permit?(@owner, :delete))
   end
   
-  def test_where_method
+  def test_aliased_filter_many_method
     make_second_thing
     @owner.update_attribute(:role_id, @demigod.id)
     assert_equal(Thing.order('id'), Thing.permitted(@owner, :read).order('id'))

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: indulgence
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 0.0.2
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-04-10 00:00:00.000000000 Z
+date: 2013-04-12 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activerecord
@@ -52,6 +52,7 @@ extra_rdoc_files: []
 files:
 - lib/active_record/acts/indulgent.rb
 - lib/indulgence/version.rb
+- lib/indulgence/exceptions.rb
 - lib/indulgence/indulgent.rb
 - lib/indulgence/ability.rb
 - lib/indulgence/permission.rb