walruz 0.0.3 → 0.0.4

data/README.rdoc

@@ -10,7 +10,7 @@ Walruz facilitates the separation between the authorization process on the busin
 
 == Walruz Architecture 
 
-Walruz provides modules and classes that helps on the implementation of the concepts given previously, this are:
+Walruz provides modules and classes that help on the implementation of the concepts given previously, this are:
   
   - Walruz::Subject 
     Module that provides the interface to associate policies to an action in the subject
@@ -26,76 +26,77 @@ Walruz provides modules and classes that helps on the implementation of the conc
 
 Subject classes may specify a set of actions that can be performed to them using the check_authorization method
 
-  class ASubject
+  class User
     include Walruz::Subject
     
-    check_authorization :show => Policy1,
-                        :edit => Policy2
+    check_authorization :read => UserReadPolicy,
+                        :update => UserUpdatePolicy
   end
 
 If there is just one policy to every possible action performed to the subject, you may specify the :default action, or just specify the Policy class.
 
 Example:
 
-  class ASubject
+  class User
     include Walruz::Subject
   
-    check_authorization PolicyClazz
+    check_authorization UserPolicy
   end
 
 or
 
-  class AnotherSubject
+  class User
     include Walruz::Subject
   
-    check_authorization :default => PolicyClazz
+    check_authorization :default => UserPolicy
   end
   
 You can also specify other flags with the default flag.
 
-  class ASubject
+  class User
     include Walruz::Subject
 
-    check_authorization :show => Policy1,
-                        :edit => Policy2,
-                        :default => DefaultPolicy
+    check_authorization :read => UserReadPolicy,
+                        :update => UserUpdatePolicy,
+                        :default => UserPolicy
   end
 
 == Actors verify if they are able to perform an action on a subject
 
-Actor classes can use several methods to check if the actor instance can perform the given action on the subject. This are:
+Actor classes can use several methods to check if the actor instance can perform the given action on a subject. This are:
 
 - `can?(action, subject)`
-  Returns boolean that says if the actor can execute or not the action on the subject, if a block is given, this will be executed when the authorization is true, and a parameters hash from the policy will be passed to the block.
+  Returns boolean that says if the actor can execute or not the action on the subject.
 
-- `can!(action, subject)`
+- `authorize(action, subject)`
   In case the actor can execute the action on the subject, it returns the parameters hash from the policy, otherwise it will raise a Walruz::NotAuthorized.
 
-- `satisfies?(policy_class, subject)`
-  It behaves just like the `can?` method, but instead of giving an action to be executed to the subject, it gives a policy
+- `satisfies?(policy_label, subject)`
+  It behaves just like the `can?` method, but instead of giving an action to be executed to the subject, it receives a policy label.
 
-In case the given action is not assigned to any policy, a default Policy will be executed (if given), if no default policy is given then a Walruz::FlagNotFound exception will be raised.
+In case the given action is not assigned to any policy, a default Policy will be executed (if given), if no default policy is given then a Walruz::ActionNotFound exception will be raised.
 
 Examples:
   
-  current_user.can?(:read, friends_profile) do |policy_params|
-    # code to be executed if current user can read a friends profile
-  end
+  current_user.can?(:read, friends_profile)
   
-  current_user.satisfies?(ActorIsAdmin, nil) do
+  current_user.satisfies?(:actor_is_admin, nil) do
     # execute some admin logic
   end
   
-  policy_params = current_user.can!(:read, friends_profile)
+  policy_params = current_user.authorize(:read, friends_profile)
   # all the code executed bellow will be executed when the actor is authorized
 
 == Implementing Policies
 
-To implement a Policy, its necessary that the Policy class inherits from the Walruz::Policy class. This class provides a method called `authorized?` that return either a Boolean, or an Array of two items, the first one being a Boolean, and the second being a Hash of parameters returned from the Policy.
+To implement a policy, it is necessary to inherit from the Walruz::Policy class. This class provides a method called `authorized?` that return either a Boolean, or an Array of two items, the first one being a Boolean, and the second being a Hash of parameters returned from the Policy.
+
+Every Policy Class also has a label associated to it, by default the label will be the name of the class in underscore case; if you want to have a custom label for a Policy Class, you can invoke the `set_policy_label` method on the class context and specify the label that you want for it. This label is used on the `satisfies?` method.
 
 Examples:
   
   class ActorIsAdmin < Walruz::Policy
+    set_policy_label :is_admin
   
     def authorized?(actor, _)
       actor.is_admin?
@@ -118,29 +119,35 @@ Examples:
   
   end
 
+
 == Composing basic policies to create complex ones
 
-Sometimes policies can turn really messy, specially when you have a complex business model. The good news is that, normally this complex policies are a composition of more simple policies (eg. ActorCanSeeUserPictures). Instead of creating this new classes that replicates the same logic of basic policies, we could merge them together in the following way:
+Sometimes policies can turn really messy, specially when you have a complex business model. The good news is that normally this complex policies are a composition of more simple policies (e.g. ActorCanSeeUserPictures). Instead of creating this new classes that replicates the same logic of basic policies, we could merge them together in the following way:
 
-ActorCanSeeUserPictures = Walruz::Utils.andP(UserIsFriend, UserAllowsDisclosureOfPictures)
+ActorCanSeeUserPictures = Walruz::Utils.all(UserIsFriend, UserAllowsDisclosureOfPictures)
 
-There is also the utility methods `orP` and `notP`, to create combinations of policies. 
+There is also the utility methods `any` and `not`, to create combinations of policies. 
 
-If your policy returns a parameters hash, and you are using the `andP` method, the parameters will be merged on each policy invocation, if you are using the `orP` method, the parameters of the first policy that returns true will be returned.
+If your policy returns a parameters hash, and you are using the `all` method, the parameters of each policy will be merged together, if you are using the `any` method, the parameters of the first policy that returns true will be returned.
 
-One other thing that the utility methods do for you is leave its track on the returned policy parameters, when you invoke a composite policy, every policy will leave a symbol with the name of the policy underscored and a question mark at the end, that way you can know which policies were successful or not. 
+One other thing that the utility methods does for you is that it leaves its track on the returned policy parameters, when you invoke a composite policy, every policy will leave in the parameters hash the policy_label with a question mark at the end, that way you can know which policies were successful or not. 
 
 Example:
   
   class ActorIsAdmin < Walruz::Policy 
-    # code from above here ...
+    set_policy_label :is_admin
+
+    def authorized?(actor, _)
+      actor.is_admin?
+    end
+
   end
   
   class ActorIsSubject < Walruz::Policy
     def authorized?(actor, subject); actor == subject; end
   end
   
-  UserReadPolicy = orP(ActorIsSubject, ActorIsAdmin)
+  UserReadPolicy = any(ActorIsSubject, ActorIsAdmin)
   
   class User < AbstractORM
     include Walruz::Subject
@@ -148,19 +155,22 @@ Example:
     check_authorizations :read => UserReadPolicy
   end
   
-  current_user.can?(:read, other_user) do |policy_params|
-    if policy_params[:actor_is_subject?]
-      # do logic of the user interacting with herself
-    elsif policy_params[:actor_is_admin?]
-      # do logic of the admin user interacting with other user
-    else
-      # do other logic here...
+  class UsersController < Framework::Controller
+    def show
+      policy_params = current_user.authorize(:read, other_user)
+      if policy_params[:actor_is_subject?]
+        # do logic of the user interacting with herself
+      elsif policy_params[:is_admin?]
+        # do logic of the admin user interacting with other user
+      else
+        # do other logic here...
+      end
     end
   end
 
 == Dependencies between Policies
 
-Sometimes you would like to have a Policy that strictly depends in other ones, on the previous example `UserAllowsDisclosureOfPictures` could have a dependency that says that only the User allows the disclosure of pictures if and only if there is a friend relationship, so we could re-implement this policy as:
+Sometimes you would like to have a Policy that strictly depends in other policies, on the previous example `UserAllowsDisclosureOfPictures` could have a dependency that says that only the User allows the disclosure of pictures if and only if there is a friend relationship, so we could re-implement this policy as:
 
 Example:
 
@@ -169,7 +179,7 @@ Example:
     # ...
   end
 
-Suppose you need the parameters returned by the previous Policy, you can have them with the params method, it works just like a request.params from any Web Framework in Ruby.
+Suppose you need the parameters returned by the previous Policy, you can have them with the `params` method.
 
 Example:
 
@@ -182,7 +192,7 @@ Example:
     
   end
   
-== Policy combinators, Lifting to the rescue! 
+== Policy combinators
 
 Sometimes you would like to execute policies that are not directly related to a subject, but to the association of a subject. Given the example above of the friendship relationship and the disclosure of pictures, sometimes you would like to check if a user can see a picture directly on the picture model.
 
@@ -194,7 +204,7 @@ Suppose we have the following model in our system:
 
 and we would like to check if the current_user can see (read) the picture using:
 
-  current_user.can(:read, picture_instance)
+  current_user.can?(:read, picture_instance)
   
 If you may recall, we already implemented the logic that checks that authorization in UserAllowsDisclosureOfPictures, but that policy only works when the subject is of class User; given that you have a subject of class Picture you can not re-use this policy.
 
@@ -208,9 +218,9 @@ You could solve this issue doing the following:
     
   end
 
-But as you may see, we are just creating new policies to handle old ones, we are not combining the policies effectively. To avoid this caveat, you can use the `lift_subject` method:
+But as you may see, we are just creating new policies to handle old ones, we are not combining the policies effectively. To avoid this caveat, you can use the `PolicyClass.for_subject` method:
 
-  PictureReadPolicy = lift_subject(:owner, UserAllowsDisclosureOfPictures)
+  PictureReadPolicy = UserAllowsDisclosureOfPictures.for_subject(:owner)
   
   class Picture < AbstractORM
     include Walruz::Subject
@@ -219,7 +229,7 @@ But as you may see, we are just creating new policies to handle old ones, we are
     check_authorizations :read => PictureReadPolicy
   end
   
-The first parameter of `lift_subject` is the name of the method that will return a new subject, this new subject is then passed through the policy specified on the second parameter and then executes the Policy checking. Pretty neat eh?
+The parameter of `but_for` is the name of the subject's method that will return a new subject, this new subject is then passed through the policy. Pretty neat eh?
 
 == Returning custom errors
 
@@ -245,14 +255,14 @@ You'll notice that once you start implementing policies for your system, you'll
 - The first name of the policy should be the Subject class (e.g. UserIsFriend)
 - If the policy only applies to the actor, the policy class name should start with the Actor word (e.g. ActorIsAdmin)
 - You should always have the compositions of policies in just one place in your library folder (e.g. in policies.rb file).
-- The result of policy compositions should finish with the word Policy (e.g `UserDeletePolicy = orP(ActorIsSubject, ActorIsAdmin`))
-- Use `lift_subject` when you are combining the lifted policy with other policies, if you are not doing this, consider checking authorizations on parents of the subject instead of the subject (e.g. current_user.can?(:see_pictures_of, picture.owner))
+- The result of policy compositions should finish with the word Policy (e.g `UserDeletePolicy = any(ActorIsSubject, ActorIsAdmin`))
+- Use `PolicyClass.but_for` when you are combining the PolicyClass with other policies, if you are not doing this, consider checking authorizations on parents of the subject instead of the subject (e.g. current_user.can?(:see_pictures_of, picture.owner))
 
 If you follow this rules, it will be much easier for you to merge policies together in an efficient way.
 
 == Rails Integration
 
-See the "walruz-rails":http://github.com/noomii/walruz-rails gem
+See "walruz-rails":http://walruz-rails.rubyforge.com gem
 
 == More examples
 

data/Rakefile

@@ -7,7 +7,7 @@ begin
     gem.name = "walruz"
     gem.summary = %Q{Walruz is a gem that provides an easy but powerful way to implement authorization policies in a system, relying on the composition of simple policies to create more complex ones.}
     gem.email = "roman@noomi.com"
-    gem.homepage = "http://github.com/roman/walruz"
+    gem.homepage = "http://github.com/noomii/walruz"
     gem.authors = ["Roman Gonzalez"]
     gem.rubyforge_project = "walruz"
   

data/VERSION.yml

@@ -1,4 +1,4 @@
 --- 
 :major: 0
 :minor: 0
-:patch: 3
+:patch: 4

data/lib/walruz/actor.rb

@@ -63,7 +63,7 @@ module Walruz
     # Raises: 
     #   Walruz::NotAuthorized error if the actor can't interact with the subject
     #    
-    def can!(label, subject)
+    def authorize(label, subject)
       result = subject.can_be?(label, self)
       if result[0]
         cached_values_for_can[[label, subject]] = result[0]

data/lib/walruz/policy.rb

@@ -12,6 +12,7 @@ module Walruz
     attr_reader :params
     
     # @private
+    # :nodoc:
     def self.inherited(child)
       @policies ||= {}
       unless child.policy_label.nil?
@@ -20,12 +21,37 @@ module Walruz
     end
     
     #
-    # See Walruz.policies
+    # See +Walruz.policies+.
     #
     def self.policies
       @policies || {}
     end
     
+    # Creates a new policy class based on an existing one, this method is used 
+    # when you want to reuse a Policy class for a subject association
+    # 
+    # See the "Policy Combinators" section on the README for more info
+    #
+    def self.for_subject(key, &block)
+      # :nodoc:
+      clazz = Class.new(Walruz::Policy) do
+        extend Walruz::Utils::PolicyCompositionHelper
+        
+        # :nodoc:
+        def authorized?(actor, subject)
+          params = self.class.params
+          new_subject = subject.send(params[:key])
+          result = self.class.policy.new.safe_authorized?(actor, new_subject)
+          params[:callback].call(result[0], result[1], actor, subject) if params[:callback]
+          result
+        end
+        
+      end
+      clazz.policy = self
+      clazz.set_params(:key => key, :callback => block)
+      clazz
+    end
+    
     #
     # Returns a Proc with a curried actor, making it easier
     # to perform validations of a policy in an Array of subjects
@@ -65,28 +91,32 @@ module Walruz
     
     # Utility for depends_on macro
     # @private
+    # :nodoc:
     def self.policy_dependencies=(dependencies)
       @_policy_dependencies = dependencies
     end
     
     # Utility for depends_on macro
     # @private
+    # :nodoc:
     def self.policy_dependencies
       @_policy_dependencies
     end
     
     # Utility for depends_on macro
     # @private
+    # :nodoc:
     def self.return_policy
       if policy_dependencies.nil?
         self
       else
-        andP(*policy_dependencies)
+        all(*policy_dependencies)
       end
     end
     
     # Utility method (copied from ActiveSupport)
     # @private
+    # :nodoc:
     def self.underscore(camel_cased_word)
       if camel_cased_word.empty?
         camel_cased_word
@@ -129,6 +159,9 @@ module Walruz
       
     end
     
+    #
+    # Returns the label assigned to the policy
+    #
     def self.policy_label
       @policy_label ||= (self.name.empty? ? nil : :"#{self.underscore(self.name)}")
     end
@@ -144,6 +177,7 @@ module Walruz
     end
     
     # @private
+    # :nodoc:
     def safe_authorized?(actor, subject)
       result = Array(authorized?(actor, subject))
       result[1] ||= {}
@@ -152,6 +186,7 @@ module Walruz
     end
     
     # @private
+    # :nodoc:
     def set_params(params)
       @params = params
     end    

data/lib/walruz/subject.rb

@@ -17,6 +17,7 @@ module Walruz
     end
     
     # @private
+    # :nodoc:
     def can_be?(action, actor)
       check_authorization_actions_are_setted(action)
       action = if self.class._walruz_policies.key?(:default)
@@ -39,6 +40,7 @@ module Walruz
     end
     
     # @private
+    # :nodoc:
     def check_authorization_actions_are_setted(action)
       if self.class._walruz_policies.nil?
         message =<<BEGIN

data/lib/walruz/utils.rb

@@ -32,10 +32,12 @@ module Walruz
       
     end
     
-    def orP(*policies)
+    def any(*policies)
+      # :nodoc:
       clazz = Class.new(Walruz::Policy) do
         extend PolicyCompositionHelper
         
+        # :nodoc:
         def authorized?(actor, subject)
           result = nil
           self.class.policies.detect do |policy|
@@ -50,10 +52,12 @@ module Walruz
       clazz
     end
     
-    def andP(*policies)
+    def all(*policies)
+      # :nodoc:
       clazz = Class.new(Walruz::Policy) do
         extend PolicyCompositionHelper
         
+        # :nodoc:
         def authorized?(actor, subject)
           acum = [true, {}]
           self.class.policies.each do |policy|
@@ -67,6 +71,7 @@ module Walruz
           acum[0] ? acum : acum[0]
         end
         
+        # :nodoc:
         def self.policy_keyword
           (self.policies.map { |p| p.policy_keyword.to_s[0..-2] }.join('_and_') + "?").to_sym
         end
@@ -76,15 +81,18 @@ module Walruz
       clazz
     end
     
-    def notP(policy)
+    def negate(policy)
+      # :nodoc:
       clazz = Class.new(Walruz::Policy) do
         extend PolicyCompositionHelper
         
+        # :nodoc:
         def authorized?(actor, subject)
           result = self.class.policy.new.safe_authorized?(actor, subject)
           !result[0]
         end
         
+        # :nodoc:
         def self.policy_keyword
           keyword = self.policy.policy_keyword.to_s[0..-2]
           :"not(#{keyword})?"
@@ -95,25 +103,7 @@ module Walruz
       clazz
     end
     
-    def lift_subject(key, policy, &block)
-      clazz = Class.new(Walruz::Policy) do
-        extend PolicyCompositionHelper
-        
-        def authorized?(actor, subject)
-          params = self.class.params
-          new_subject = subject.send(params[:key])
-          result = self.class.policy.new.safe_authorized?(actor, new_subject)
-          params[:callback].call(result[0], result[1], actor, subject) if params[:callback]
-          result
-        end
-        
-      end
-      clazz.policy = policy
-      clazz.set_params(:key => key, :callback => block)
-      clazz
-    end
-    
-    module_function(:orP, :andP, :notP, :lift_subject)
+    module_function(:any, :all, :negate)
     
   end
 end

data/spec/scenario.rb

@@ -13,7 +13,7 @@ class Beatle
   end
   
   def sing_the_song(song)
-    response = can!(:sing, song)
+    response = authorize(:sing, song)
     case response[:owner]
     when Colaboration
       authors = response[:owner].authors.dup
@@ -26,7 +26,7 @@ class Beatle
   end
   
   def sing_with_john(song)
-    can!(:sing_with_john, song)
+    authorize(:sing_with_john, song)
     "Ok John, Let's Play '%s'" % song.name
   end
 
@@ -75,7 +75,7 @@ end
 #   
 # end
 
-AuthorPolicy = Walruz::Utils.lift_subject(:author, SubjectIsActorPolicy) do |authorized, params, actor, subject|
+AuthorPolicy = SubjectIsActorPolicy.for_subject(:author) do |authorized, params, actor, subject|
   params.merge!(:owner => actor) if authorized
 end
 
@@ -105,8 +105,8 @@ class Song
   include Walruz::Subject
   extend Walruz::Utils
 
-  check_authorizations :sing => orP(AuthorPolicy, AuthorInColaborationPolicy),
-                       :sell => andP(AuthorPolicy, notP(AuthorInColaborationPolicy)),
+  check_authorizations :sing => any(AuthorPolicy, AuthorInColaborationPolicy),
+                       :sell => all(AuthorPolicy, negate(AuthorInColaborationPolicy)),
                        :sing_with_john => ColaboratingWithJohnPolicy
   attr_accessor :name
   attr_accessor :colaboration

data/spec/walruz/actor_spec.rb

@@ -2,8 +2,8 @@ require File.dirname(__FILE__) + '/../spec_helper'
 
 describe 'Walruz::Actor' do
   
-  it "should add an instance method `can!` to included classes" do
-    Beatle::JOHN.should respond_to(:can!)
+  it "should add an instance method `authorize` to included classes" do
+    Beatle::JOHN.should respond_to(:authorize)
   end
   
   it "should add an instance method `can?` to included classes" do
@@ -15,7 +15,7 @@ describe 'Walruz::Actor' do
   end
   
   
-  describe "can!" do
+  describe "#authorize" do
     
     it "should raise a Walruz::NotAuthorized error when the actor is not authorized" do
       lambda do
@@ -45,7 +45,7 @@ describe 'Walruz::Actor' do
     end
     
     # @deprecated functionality
-    # WHY: When you execute `can?` you should probably have already executed `can!`
+    # WHY: When you execute `can?` you should probably have already executed `authorize`
     # it "should execute a given block if the condition is true" do
     #   proc_called = lambda { raise "Is being called" }
     #   lambda do

data/spec/walruz/policy_spec.rb

@@ -7,7 +7,7 @@ describe Walruz::Policy do
   end
   
   it "should generate an indicator that the policy was executed after authorization queries" do
-    policy = Beatle::PAUL.can!(:sing, Song::YESTERDAY)
+    policy = Beatle::PAUL.authorize(:sing, Song::YESTERDAY)
     policy[:author_policy?].should be_true
   end
   
@@ -23,7 +23,7 @@ describe Walruz::Policy do
   
   it "should raise an Walruz::ActionNotFound exception when the action is not specified, and there is no default one"  do
     lambda do
-      Beatle::RINGO.can!(:sing_drunk, Song::TAXMAN)
+      Beatle::RINGO.authorize(:sing_drunk, Song::TAXMAN)
     end.should raise_error(Walruz::ActionNotFound)
   end
   

data/spec/walruz/utils_spec.rb

@@ -4,17 +4,17 @@ describe Walruz::Utils do
   
   def check_actor_can_on_subject(label, actor, subject)
     lambda do
-      actor.can!(label, subject)
+      actor.authorize(label, subject)
     end.should_not raise_error(Walruz::NotAuthorized)
   end
   
   def check_actor_can_not_on_subject(label, actor, subject)
     lambda do
-      actor.can!(label, subject)
+      actor.authorize(label, subject)
     end.should raise_error(Walruz::NotAuthorized)
   end
   
-  describe "when using combinators `orP`, `andP` or `notP`" do
+  describe "when using combinators `any`, `all` or `negate`" do
     
     it "should work properly" do
       check_actor_can_not_on_subject(:sell, Beatle::JOHN, Song::A_DAY_IN_LIFE)
@@ -23,7 +23,7 @@ describe Walruz::Utils do
     
   end
   
-  describe "when using andP" do
+  describe "#all" do
 
     it "should return as policy keyword, the name of the original policies keywords concatenated with `_and_`" do
       Beatle::JOHN.can?(:sell, Song::ALL_YOU_NEED_IS_LOVE) do |policy_params|
@@ -33,7 +33,7 @@ describe Walruz::Utils do
     
   end
   
-  describe "when using notP" do
+  describe "#negate" do
     
     it "should return as policy keyword, the name of the original policy keyword with a `not()` around" do
       Beatle::JOHN.can?(:sell, Song::ALL_YOU_NEED_IS_LOVE) do |policy_params|

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: walruz
 version: !ruby/object:Gem::Version 
-  version: 0.0.3
+  version: 0.0.4
 platform: ruby
 authors: 
 - Roman Gonzalez
@@ -9,7 +9,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2009-06-30 00:00:00 -07:00
+date: 2009-07-02 00:00:00 -07:00
 default_executable: 
 dependencies: []
 
@@ -41,7 +41,7 @@ files:
 - spec/walruz/utils_spec.rb
 - spec/walruz/walruz_spec.rb
 has_rdoc: true
-homepage: http://github.com/roman/walruz
+homepage: http://github.com/noomii/walruz
 licenses: []
 
 post_install_message: