walruz 0.0.6 → 0.0.7

data/lib/walruz/policy.rb

@@ -1,42 +1,42 @@
 module Walruz
   
   #
-  # One of the cores of the framework, it's purpuse is to encapsulate
-  # some authorization logic with a given actor and subject.
-  # It's main method `authorized?(actor, subject)` verifies that 
-  # an actor is actually authorized to manage the subject. 
+  # One of the cores of the framework, its purpose is to encapsulate an authorization logic 
+  # with a given actor and subject. It's main method <tt>authorized?(actor, subject)</tt> 
+  # verifies that an actor is authorized to manage the subject.
   #
   class Policy
     extend Walruz::Utils
     
-    # @private
-    # :nodoc:
-    def self.inherited(child)
+    
+    def self.inherited(child) # :nodoc:
       @policies ||= {}
       unless child.policy_label.nil?
         @policies[child.policy_label] = child
       end
     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
+    #
+    # Creates a new policy class based on an existing one, you may use this method
+    # when you want to reuse a Policy class for a subject's association.
+    # 
+    # @param [Symbol] Name of the association that will be the subject of the policy.
+    # @return [Walruz::Policy] New generated policy that will pass the association as the subject of the original <em>policy</em>.
     # 
-    # See the "Policy Combinators" section on the README for more info
+    # @see http://github.com/noomii/walruz See the "Policy Combinators" section on the README for more info and examples.
     #
     def self.for_subject(key, &block)
-      # :nodoc:
-      clazz = Class.new(Walruz::Policy) do
+      
+      clazz = Class.new(Walruz::Policy) do # :nodoc:
         extend Walruz::Utils::PolicyCompositionHelper
         
-        # :nodoc:
-        def authorized?(actor, subject)
+        def authorized?(actor, subject) # :nodoc:
           params = self.class.params
           new_subject = subject.send(params[:key])
           result = self.class.policy.new.safe_authorized?(actor, new_subject)
@@ -51,16 +51,17 @@ module Walruz
     end
     
     #
-    # Returns a Proc with a curried actor, making it easier
-    # to perform validations of a policy in an Array of subjects
-    # Params:
-    #   - actor: The actor who checks if it is authorized
-    #
-    # Returns: (subject -> [Bool, Hash])
+    # Returns a Proc with a curried actor, making it easier to perform validations of a policy 
+    # in an Array of subjects.
     #
-    # Example:
-    #   subjects.filter(&PolicyXYZ.with_actor(some_user))
+    # @param [Walruz::Actor] The actor who checks if he is authorized.
+    # @return [Proc] A proc that receives as a parameter subject and returns what the <tt>authorized?</tt> 
+    #                method returns.
+    # 
+    # @example
+    #   subjects.select(&PolicyXYZ.with_actor(some_user))
     #
+    # @see Walruz::CoreExt::Array#only_authorized_for
     def self.with_actor(actor)
       policy_instance = self.new
       lambda do |subject|
@@ -71,13 +72,18 @@ module Walruz
     #
     # Stablish other Policy dependencies, so that they are executed
     # before the current one, giving chances to receive the previous 
-    # policies return parameters
+    # policies return parameters.
+    # 
+    # @param [Array<Walruz::Policies>] Policies in wich this policy depends on.
+    # @return self
     #
-    # Example: 
+    # @example 
     #   class FriendEditProfilePolicy
     #     depends_on FriendPolicy
     #     
     #     def authorized?(actor, subject)
+    #       # The FriendPolicy returns a hash with a key of :friend_relationship
+    #       # this will be available via the params method.
     #       params[:friend_relationship].can_edit? # for friend metadata
     #     end
     #
@@ -88,23 +94,17 @@ module Walruz
     end
     
     # Utility for depends_on macro
-    # @private
-    # :nodoc:
-    def self.policy_dependencies=(dependencies)
+    def self.policy_dependencies=(dependencies) # :nodoc:
       @_policy_dependencies = dependencies
     end
     
     # Utility for depends_on macro
-    # @private
-    # :nodoc:
-    def self.policy_dependencies
+    def self.policy_dependencies # :nodoc:
       @_policy_dependencies
     end
     
     # Utility for depends_on macro
-    # @private
-    # :nodoc:
-    def self.return_policy
+    def self.return_policy # :nodoc:
       if policy_dependencies.nil?
         self
       else
@@ -112,10 +112,8 @@ module Walruz
       end
     end
     
-    # Utility method (copied from ActiveSupport)
-    # @private
-    # :nodoc:
-    def self.underscore(camel_cased_word)
+    # Utility method (from ActiveSupport)
+    def self.underscore(camel_cased_word) # :nodoc:
       if camel_cased_word.empty?
         camel_cased_word
       else
@@ -130,11 +128,12 @@ module Walruz
     
     #
     # Verifies if the actor is authorized to interact with the subject
-    # Params:
-    #   - actor: The object who checks if it is authorized
-    #   - subject: The object that is going to be accesed
+    # @param [Walruz::Actor] The object who checks if it is authorized
+    # @param [Walruz::Subject] The object that is going to be accesed
+    # @return It may return a Boolean, or an Array with the first position being a boolean and the second
+    #          being a Hash of parameters returned from the policy.
+    #
     #
-    # Returns: [Bool, Hash]
     #
     def authorized?(actor, subject)
       raise NotImplementedError.new("You need to implement policy")
@@ -144,9 +143,8 @@ module Walruz
     # Returns the identifier of the Policy that will be setted on the 
     # policy params hash once the authorization is executed. 
     # 
-    # Returns:
-    # By default it will return a symbol with the name of the Policy class in underscore (unless the policy label
-    # was setted, in that case the policy label will be used) with an '?' appended
+    # @return [Symbol] By default it will return a symbol with the name of the Policy class in underscore (unless the policy label
+    #         was setted, in that case the policy label will be used) with an '?' appended.
     #
     def self.policy_keyword
       if self.policy_label.nil?
@@ -171,21 +169,18 @@ module Walruz
     #   - label: Symbol that represents the policy
     # 
     def self.set_policy_label(label)
+      Walruz.policies[label] = Walruz.policies.delete(self.policy_label)
       @policy_label = label
     end
     
-    # @private
-    # :nodoc:
-    def safe_authorized?(actor, subject)
+    def safe_authorized?(actor, subject) # :nodoc:
       result = Array(authorized?(actor, subject))
       result[1] ||= {}
       result[1][self.class.policy_keyword] = result[0] unless self.class.policy_keyword.nil?
       result
     end
     
-    # @private
-    # :nodoc:
-    def set_params(params)
+    def set_params(params) # :nodoc:
       @params = params
       self
     end

data/lib/walruz/subject.rb

@@ -1,7 +1,30 @@
 module Walruz
+  
+  #
+  # This module provides the methods that enable a <em>subject</em> to register 
+  # the diferent actions that can be performed to it, and associates the policies
+  # that apply to each of these actions.
+  # 
+  # == Associating policies with actions on the <em>subject</em>.
+  #
+  # To associate policies and actions related to a <em>subject</em>, we use the <tt>check_authorizations</tt>
+  # method, this will receive a Hash, where the keys are the name of the actions, and the values are the policies
+  # associated to this actions.
+  #
+  # === Example:
+  #   class Profile < ActiveRecord::Base
+  #     include Walruz::Subject
+  #     belongs_to :user
+  #     check_authorizations :read   => ProfileReadPolicy,
+  #                          :update => ProfileUpdatePolicy
+  #   end
+  #
+  # Once the actions are registered on the <em>subject</em>, you can check if an <em>actor</em> can perform
+  # an action on it, using the <tt>Walruz::Actor</tt> methods
+  #
   module Subject
     
-    def self.included(base)
+    def self.included(base) # :nodoc:
       base.class_eval do 
         
         def self._walruz_policies=(policies)
@@ -16,9 +39,7 @@ module Walruz
       end
     end
     
-    # @private
-    # :nodoc:
-    def can_be?(action, actor)
+    def can_be?(action, actor) # :nodoc:
       check_authorization_actions_are_setted(action)
       action = if self.class._walruz_policies.key?(:default)
                 self.class._walruz_policies.key?(action) ? action : :default
@@ -39,9 +60,7 @@ module Walruz
       result
     end
     
-    # @private
-    # :nodoc:
-    def check_authorization_actions_are_setted(action)
+    def check_authorization_actions_are_setted(action) # :nodoc:
       if self.class._walruz_policies.nil?
         message =<<BEGIN
 You need to invoke `check_authorizations :#{action} => Policies::SomePolicy` on the #{self.class.name} class
@@ -55,10 +74,16 @@ BEGIN
       #
       # Stablishes the actions that can be made with a subject. You may
       # specify as many actions as you like, and also you may have a default
-      # policy, that will get execute if a specified flag doesn't exist.
-      # You just have to pass the action :default, or just the policy class.
+      # policy, that will get executed if a specified flag doesn't exist.
+      # You just have to pass the action :default, or the policy class only.
       #
-      # Example:
+      # Once you stablish the authorizations policies on a subject, you can
+      # check if an actor is able to interact with it via the Walruz::Actor methods
+      #
+      # @param [Hash] Set of actions with associated policies
+      # @return self
+      #
+      # @example
       #   # Without :default key
       #   class UserProfile
       #     check_authorizations :read  => Policies::FriendPolicy,
@@ -78,13 +103,8 @@ BEGIN
       #     check_authorizations Policies::OwnerPolicy
       #   end
       #
-      #  Once you stablish the authorizations policies on a subject, you can
-      #  check if an actor is able to interact with it via the Actor#can? method
-      #
-      #  Example: current_user.can?(:read, profile)
-      #
-      #  It's recommended (but not mandatory) that a policy specified to the action 
-      #  is inherting from Walruz::Policy
+      # @example Invoking the actions from the actor
+      #   current_user.can?(:read, profile)
       #
       def check_authorizations(policy_map)
         case policy_map

data/lib/walruz/utils.rb

@@ -1,9 +1,45 @@
 module Walruz
+  #
+  # This module provides pretty handy methods to do compositions of basic policies to create
+  # more complex ones.
+  #
+  # === Using a policies file to manage complex policies
+  #
+  # It's always a good idea to keep the policy composition in one place, you may place a file in your 
+  # project where you manage all the authorization policies, and then you use them on your models.
+  #
+  # Say for example you have a <tt>lib/policies.rb</tt> in your project where you manage the composition of policies,
+  # and a <tt>lib/policies</tt> folder where you create your custom policies.
+  #
+  # The <tt>lib/policies.rb</tt> file could be something like this:
+  # 
+  #   module Policies
+  #     include Walruz::Utils 
+  #     
+  #     # Requiring basic Walruz::Policy classes
+  #     BASE = File.join(File.dirname(__FILE__), "policies") unless defined?(BASE)
+  #     require File.join(BASE, "actor_is_admin")
+  #     require File.join(BASE, "user_is_owner")
+  #     require File.join(BASE, "user_is_friend")
+  #   
+  #     #####
+  #     # User Policies
+  #     #
+  #     UserCreatePolicy  = ActorIsAdmin
+  #     UserReadPolicy    = any(UserIsOwner, UserIsFriend, ActorIsAdmin)
+  #     UserUpdatePolicy  = any(UserIsOwner, ActorIsAdmin)
+  #     UserDestroyPolicy = ActorIsAdmin
+  # 
+  #   end
+  # 
+  # Using a policies file on your project, keeps all your authorization logic just in one place
+  # that way, when you change the authorizations you just have to go to one place only.
+  #
   module Utils
     
-    module PolicyCompositionHelper
+    module PolicyCompositionHelper # :nodoc: all
       
-      # NOTE: Not using cattr_accessor to avoid dependencies with ActiveSupport
+      #-- NOTE: Not using cattr_accessor to avoid dependencies with ActiveSupport
       
       def policies=(policies)
         @policies = policies
@@ -32,13 +68,21 @@ module Walruz
       
     end
     
+    #
+    # Generates a new policy that merges together different policies by an <em>OR</em> association.
+    # As soon as one of the policies succeed, the parameters of that policy will be returned.
+    #
+    # @param [Array<Walruz::Policy>] A set of policies that will be merged by an <em>OR</em> association.
+    # @return [Walruz::Policy] A new policy class that will execute each policy until one of them succeeds.
+    #
+    # @example 
+    #   UserReadPolicy = any(UserIsOwner, UserIsAdmin)
+    #
     def any(*policies)
-      # :nodoc:
-      clazz = Class.new(Walruz::Policy) do
+      clazz = Class.new(Walruz::Policy) do # :nodoc:
         extend PolicyCompositionHelper
         
-        # :nodoc:
-        def authorized?(actor, subject)
+        def authorized?(actor, subject) # :nodoc:
           result = nil
           self.class.policies.detect do |policy|
             result = policy.new.set_params(params).safe_authorized?(actor, subject)
@@ -52,13 +96,20 @@ module Walruz
       clazz
     end
     
+    #
+    # Generates a new policy that merges together different policies by an <em>AND</em> association.
+    # This will execute every <em>policy</em> on the list, if all of them return true then the policy will
+    # succeed. This process will merge the parameters of each policy, so you may be able to use the parameters 
+    # of previous policies, and at the end it will return all the parameters from every policy.
+    #
+    # @param [Array<Walruz::Policy>] A set of policies that will be merged by an <em>AND</em> association.
+    # @return [Walruz::Policy] A new policy class that will check true for each policy.
+    #
     def all(*policies)
-      # :nodoc:
-      clazz = Class.new(Walruz::Policy) do
+      clazz = Class.new(Walruz::Policy) do # :nodoc:
         extend PolicyCompositionHelper
         
-        # :nodoc:
-        def authorized?(actor, subject)
+        def authorized?(actor, subject) # :nodoc:
           acum = [true, self.params || {}]
           self.class.policies.each do |policy|
             break unless acum[0]
@@ -69,8 +120,7 @@ module Walruz
           acum[0] ? acum : acum[0]
         end
         
-        # :nodoc:
-        def self.policy_keyword
+        def self.policy_keyword # :nodoc:
           (self.policies.map { |p| p.policy_keyword.to_s[0..-2] }.join('_and_') + "?").to_sym
         end
         
@@ -79,20 +129,24 @@ module Walruz
       clazz
     end
     
+    # 
+    # Generates a new policy that negates the result of the given policy.
+    # @param [Walruz::Policy] The policy which result is going to be negated.
+    # @param [Walruz::Policy] A new policy that will negate the result of the given policy.
+    #
     def negate(policy)
-      # :nodoc:
-      clazz = Class.new(Walruz::Policy) do
+      clazz = Class.new(Walruz::Policy) do # :nodoc:
         extend PolicyCompositionHelper
         
         # :nodoc:
         def authorized?(actor, subject)
-          self.class.policy.set_params(params)
-          result = self.class.policy.new.safe_authorized?(actor, subject)
-          !result[0]
+          result = self.class.policy.new.set_params(params).safe_authorized?(actor, subject)
+          result[0] = !result[0]
+          result
         end
         
-        # :nodoc:
-        def self.policy_keyword
+        
+        def self.policy_keyword # :nodoc:
           keyword = self.policy.policy_keyword.to_s[0..-2]
           :"not(#{keyword})?"
         end

data/lib/walruz.rb

@@ -42,15 +42,33 @@ module Walruz
   autoload :Policy,  base_path + '/walruz/policy'
   autoload :Utils,   base_path + '/walruz/utils'
   
+
   def self.setup
     config = Config.new
     yield config
   end
   
+  # Holds all the policies declared on the system
+  # @return [Hash<Symbol, Walruz::Policy>] A hash of policies, each identified by it's policy label
+  # @todo Make this thread-safe
   def self.policies
     Walruz::Policy.policies
   end
   
+  # Returns a Walruz::Policy Class represented by the specified label 
+  #
+  # @param [Symbol] policy_label The label that identifies a policy
+  # @return [Walruz::Policy] A Policy class.
+  # @raise [Walruz::ActionNotFound] if the policy label is not recognized.
+  # @example Fetching a policy with label :actor_is_admin
+  #   Walruz.fetch_policy(:actor_is_admin) # => ActorIsAdmin
+  #
+  def self.fetch_policy(policy_label)
+    policy_clz = Walruz.policies[policy_label]
+    raise ActionNotFound.new(:policy_label, :label => policy_label) if policy_clz.nil?
+    policy_clz
+  end
+  
   class Config
     
     def actors=(actors)
@@ -67,5 +85,7 @@ module Walruz
     
   end
   
+end
 
-end
+require File.dirname(__FILE__) + '/walruz/core_ext/array'
+Array.send(:include, Walruz::CoreExt::Array)

data/spec/scenario.rb

@@ -30,11 +30,12 @@ class Beatle
     "Ok John, Let's Play '%s'" % song.name
   end
 
-
-  JOHN   = self.new("John")
-  PAUL   = self.new("Paul")
-  RINGO  = self.new("Ringo")
-  GEORGE = self.new("George")
+  unless defined?(RINGO)
+    JOHN   = self.new("John")
+    PAUL   = self.new("Paul")
+    RINGO  = self.new("Ringo")
+    GEORGE = self.new("George")
+  end
 end
 
 class Colaboration
@@ -50,9 +51,12 @@ class Colaboration
     @songs = []
   end
   
-  JOHN_PAUL = self.new(Beatle::JOHN, Beatle::PAUL)
-  JOHN_PAUL_GEORGE = self.new(Beatle::JOHN, Beatle::PAUL, Beatle::GEORGE)
-  JOHN_GEORGE = self.new(Beatle::JOHN, Beatle::GEORGE)
+  unless defined?(JOHN_PAUL)
+    JOHN_PAUL = self.new(Beatle::JOHN, Beatle::PAUL)
+    JOHN_PAUL_GEORGE = self.new(Beatle::JOHN, Beatle::PAUL, Beatle::GEORGE)
+    JOHN_GEORGE = self.new(Beatle::JOHN, Beatle::GEORGE)
+  end
+  
 end
 
 class SubjectIsActorPolicy < Walruz::Policy
@@ -74,12 +78,14 @@ end
 #   end
 #   
 # end
-
-AuthorPolicy = SubjectIsActorPolicy.for_subject(:author) do |authorized, params, actor, subject|
-  params.merge!(:owner => actor) if authorized
+unless defined?(AuthorPolicy)
+  AuthorPolicy = SubjectIsActorPolicy.for_subject(:author) do |authorized, params, actor, subject|
+    params.merge!(:owner => actor) if authorized
+  end
 end
 
 class AuthorInColaborationPolicy < Walruz::Policy
+  set_policy_label :in_colaboration
   
   def authorized?(beatle, song)
     return false unless song.colaboration
@@ -123,11 +129,14 @@ class Song
     owner.songs << self
   end
   
-  A_DAY_IN_LIFE        = self.new("A Day In Life", Colaboration::JOHN_PAUL)
-  YELLOW_SUBMARINE     = self.new("Yellow Submarine", Colaboration::JOHN_PAUL)
-  TAXMAN               = self.new("Taxman", Colaboration::JOHN_GEORGE)
-  YESTERDAY            = self.new("Yesterday", Beatle::PAUL)
-  ALL_YOU_NEED_IS_LOVE = self.new("All You Need Is Love", Beatle::JOHN)
-  BLUE_JAY_WAY         = self.new("Blue Jay Way", Beatle::GEORGE)
+  unless defined?(A_DAY_IN_LIFE)
+    A_DAY_IN_LIFE        = self.new("A Day In Life", Colaboration::JOHN_PAUL)
+    YELLOW_SUBMARINE     = self.new("Yellow Submarine", Colaboration::JOHN_PAUL)
+    TAXMAN               = self.new("Taxman", Colaboration::JOHN_GEORGE)
+    YESTERDAY            = self.new("Yesterday", Beatle::PAUL)
+    ALL_YOU_NEED_IS_LOVE = self.new("All You Need Is Love", Beatle::JOHN)
+    BLUE_JAY_WAY         = self.new("Blue Jay Way", Beatle::GEORGE)
+  end
+  
 end
 

data/spec/walruz/actor_spec.rb

@@ -68,9 +68,9 @@ describe 'Walruz::Actor' do
   describe '#can?' do
     
     it "should be invoked only the first time and then return a cached solution" do
-      Song::ALL_YOU_NEED_IS_LOVE.should_receive(:can_be?).once.and_return([true, {}])
-      Beatle::JOHN.can?(:sing, Song::ALL_YOU_NEED_IS_LOVE)
-      Beatle::JOHN.can?(:sing, Song::ALL_YOU_NEED_IS_LOVE)
+      Song::YELLOW_SUBMARINE.should_receive(:can_be?).once.and_return([true, {}])
+      Beatle::JOHN.can?(:sing, Song::YELLOW_SUBMARINE, true)
+      Beatle::JOHN.can?(:sing, Song::YELLOW_SUBMARINE)
     end
     
     it "if a boolean third parameter is received it should not use the cached result" do
@@ -108,34 +108,38 @@ describe 'Walruz::Actor' do
   
   describe '#satisfies?' do
     
-    it "should work with the symbol representation of the policy" do
-      Beatle::PAUL.satisfies?(:colaborating_with_john_policy, Song::TAXMAN).should be_false
+    it "should raise a Walruz::ActionNotFound error if the policy is not found" do
+      lambda do
+        Beatle::GEORGE.satisfies?(:unknown_policy, Song::TAXMAN)
+      end.should raise_error(Walruz::ActionNotFound)
     end
     
-    it "should check only the specified policy" do
+    it "should return false if the actor and the subject dont satisfy the given policy" do
       Beatle::PAUL.satisfies?(:colaborating_with_john_policy, Song::TAXMAN).should be_false
     end
     
-    it "should raise a Walruz::ActionNotFound error if the policy is not found" do
-      lambda do
-        Beatle::GEORGE.satisfies?(:unknown_policy, Song::TAXMAN)
-      end.should raise_error(Walruz::ActionNotFound)
+    it "should return true if the actor and the subject satisfy the given policy" do
+      Beatle::GEORGE.satisfies(:colaborating_with_john_policy, Song::TAXMAN).should be_true
     end
     
-    it "should execute the block if the condition is true" do
-      proc_called = Proc.new { raise "Is being called" }
-      lambda do
-        Beatle::GEORGE.satisfies?(:colaborating_with_john_policy, Song::TAXMAN, &proc_called)
-      end.should raise_error
+  end
+  
+  describe "#satisfies" do
+    
+    it "should return nil if the actor and the subject do not satisfy the given policy" do
+      Beatle::PAUL.satisfies(:colaborating_with_john_policy, Song::TAXMAN).should be_nil
     end
     
-    it "should execute the block that receives a hash of return parameters of the policy" do
-      proc_called = lambda do |params|  
-        params.should_not be_nil
-        params.should be_kind_of(Hash)
-        params[:author_in_colaboration_policy?].should be_true
-      end
-      Beatle::GEORGE.satisfies?(:colaborating_with_john_policy, Song::TAXMAN, &proc_called)
+    it "should return the parameters from the policy if the actor and the subject satisfy the policy" do
+      policy_params = Beatle::GEORGE.satisfies(:colaborating_with_john_policy, Song::TAXMAN)
+      policy_params.should_not be_nil
+      policy_params[:in_colaboration?].should be_true
+    end
+    
+    it "should raise a Walruz::ActionNotFound error if the policy is not found" do
+      lambda do
+        Beatle::GEORGE.satisfies(:unknown_policy, Song::TAXMAN)
+      end.should raise_error(Walruz::ActionNotFound)
     end
     
   end