walruz 0.0.3

data/lib/walruz/subject.rb

@@ -0,0 +1,99 @@
+module Walruz
+  module Subject
+    
+    def self.included(base)
+      base.class_eval do 
+        
+        def self._walruz_policies=(policies)
+          @_walruz_policies = policies
+        end
+        
+        def self._walruz_policies
+          @_walruz_policies
+        end
+        
+        extend ClassMethods
+      end
+    end
+    
+    # @private
+    def can_be?(action, actor)
+      check_authorization_actions_are_setted(action)
+      action = if self.class._walruz_policies.key?(:default)
+                self.class._walruz_policies.key?(action) ? action : :default
+              else
+                if self.class._walruz_policies.key?(action) 
+                  action
+                else 
+                  raise ActionNotFound.new(:subject_action, :subject => self, 
+                                                            :action => action)
+                end
+              end
+      
+      result = self.class._walruz_policies[action].
+                          return_policy.
+                          new.
+                          safe_authorized?(actor, self)
+      
+      result
+    end
+    
+    # @private
+    def check_authorization_actions_are_setted(action)
+      if self.class._walruz_policies.nil?
+        message =<<BEGIN
+You need to invoke `check_authorizations :#{action} => Policies::SomePolicy` on the #{self.class.name} class
+BEGIN
+        raise AuthorizationActionsNotDefined.new(message)
+      end
+    end
+    
+    module ClassMethods
+      
+      #
+      # 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.
+      #
+      # Example:
+      #   # Without :default key
+      #   class UserProfile
+      #     check_authorizations :read  => Policies::FriendPolicy,
+      #                          :write => Policies::OwnerPolicy
+      #   end
+      #
+      #   # With :default key
+      #   class UserProfile
+      #     check_authorizations :read    => Policies::FriendPolicy,
+      #                          :write   => Policies::OwnerPolicy,
+      #                          :default => Policies::AdminPolicy
+      #   end
+      #
+      #   # Without any key at all
+      #   class UserProfile
+      #     # this policy is the default one
+      #     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
+      #
+      def check_authorizations(policy_map)
+        case policy_map
+        when Hash
+          self._walruz_policies = policy_map
+        else
+          self._walruz_policies = { :default => policy_map }
+        end
+      end
+      
+    end
+    
+  end
+end

data/lib/walruz/utils.rb

@@ -0,0 +1,119 @@
+module Walruz
+  module Utils
+    
+    module PolicyCompositionHelper
+      
+      # NOTE: Not using cattr_accessor to avoid dependencies with ActiveSupport
+      
+      def policies=(policies)
+        @policies = policies
+      end
+      
+      def policies
+        @policies
+      end
+      
+      def policy=(policy)
+        @policy = policy
+      end
+      
+      def policy
+        @policy
+      end
+      
+      def set_params(params = {})
+        @params ||= {}
+        @params.merge!(params)
+      end
+      
+      def params
+        @params
+      end
+      
+    end
+    
+    def orP(*policies)
+      clazz = Class.new(Walruz::Policy) do
+        extend PolicyCompositionHelper
+        
+        def authorized?(actor, subject)
+          result = nil
+          self.class.policies.detect do |policy|
+            result = policy.new.safe_authorized?(actor, subject)
+            result[0]
+          end
+          result[0] ? result : result[0]
+        end
+      
+      end
+      clazz.policies = policies
+      clazz
+    end
+    
+    def andP(*policies)
+      clazz = Class.new(Walruz::Policy) do
+        extend PolicyCompositionHelper
+        
+        def authorized?(actor, subject)
+          acum = [true, {}]
+          self.class.policies.each do |policy|
+            break unless acum[0]
+            policy_instance = policy.new
+            policy_instance.set_params(acum[1])
+            result = policy_instance.safe_authorized?(actor, subject)
+            acum[0] &&= result[0]
+            acum[1].merge!(result[1])
+          end
+          acum[0] ? acum : acum[0]
+        end
+        
+        def self.policy_keyword
+          (self.policies.map { |p| p.policy_keyword.to_s[0..-2] }.join('_and_') + "?").to_sym
+        end
+        
+      end
+      clazz.policies = policies
+      clazz
+    end
+    
+    def notP(policy)
+      clazz = Class.new(Walruz::Policy) do
+        extend PolicyCompositionHelper
+        
+        def authorized?(actor, subject)
+          result = self.class.policy.new.safe_authorized?(actor, subject)
+          !result[0]
+        end
+        
+        def self.policy_keyword
+          keyword = self.policy.policy_keyword.to_s[0..-2]
+          :"not(#{keyword})?"
+        end
+        
+      end
+      clazz.policy = policy
+      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)
+    
+  end
+end

data/lib/walruz.rb

@@ -0,0 +1,54 @@
+module Walruz
+
+  class NotAuthorized < Exception
+  end
+  
+  class AuthorizationActionsNotDefined < Exception
+  end
+  
+  class ActionNotFound < Exception
+    
+    def initialize(failure, params = {})
+      case failure
+      when :subject_action
+        super("%s class doesn't have an authorization action called :%s nor a :default policy" % [params[:subject].class.name, params[:action]])
+      when :policy_label
+        super("There is no Policy with the label %s" % params[:label])
+      end
+    end
+    
+  end
+  
+  base_path = File.dirname(__FILE__)
+  autoload :Actor,   base_path + '/walruz/actor'
+  autoload :Subject, base_path + '/walruz/subject'
+  autoload :Policy,  base_path + '/walruz/policy'
+  autoload :Utils,   base_path + '/walruz/utils'
+  
+  def self.setup
+    config = Config.new
+    yield config
+  end
+  
+  def self.policies
+    Walruz::Policy.policies
+  end
+  
+  class Config
+    
+    def actors=(actors)
+      Array(actors).each do |actor|
+        actor.send(:include, Actor)
+      end
+    end
+
+    def subjects=(subjects)
+      Array(subjects).each do |subject|
+        subject.send(:include, Subject)
+      end
+    end
+    
+  end
+  
+
+end

data/spec/scenario.rb

@@ -0,0 +1,133 @@
+class Beatle
+  include Walruz::Actor
+  include Walruz::Subject
+  
+  attr_reader :name
+  attr_accessor :songs
+  attr_accessor :colaborations
+  
+  def initialize(name)
+    @name = name
+    @songs = []
+    @colaborations = []
+  end
+  
+  def sing_the_song(song)
+    response = can!(:sing, song)
+    case response[:owner]
+    when Colaboration
+      authors = response[:owner].authors.dup
+      authors.delete(self)
+      authors.map! { |author| author.name }
+      "I need %s to play this song properly" % authors.join(', ')
+    when Beatle
+      "I just need myself, Let's Rock! \\m/"
+    end
+  end
+  
+  def sing_with_john(song)
+    can!(:sing_with_john, song)
+    "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")
+end
+
+class Colaboration
+  
+  attr_accessor :authors
+  attr_accessor :songs
+  
+  def initialize(*authors)
+    authors.each do |author|
+      author.colaborations << self
+    end
+    @authors = authors
+    @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)
+end
+
+class SubjectIsActorPolicy < Walruz::Policy
+  
+  def authorized?(actor, subject)
+    actor == subject
+  end
+  
+end
+
+# class AuthorPolicy < Walruz::Policy
+#   
+#   def authorized?(beatle, song)
+#     if song.author == beatle
+#       [true, { :owner => beatle }]
+#     else
+#       false
+#     end
+#   end
+#   
+# end
+
+AuthorPolicy = Walruz::Utils.lift_subject(:author, SubjectIsActorPolicy) do |authorized, params, actor, subject|
+  params.merge!(:owner => actor) if authorized
+end
+
+class AuthorInColaborationPolicy < Walruz::Policy
+  
+  def authorized?(beatle, song)
+    return false unless song.colaboration
+    if song.colaboration.authors.include?(beatle)
+      [true, { :owner => song.colaboration }]
+    else
+      false
+    end
+  end
+  
+end
+
+class ColaboratingWithJohnPolicy < Walruz::Policy
+  depends_on AuthorInColaborationPolicy
+  
+  def authorized?(beatle, song)
+    params[:owner].authors.include?(Beatle::JOHN)
+  end
+  
+end
+
+class Song
+  include Walruz::Subject
+  extend Walruz::Utils
+
+  check_authorizations :sing => orP(AuthorPolicy, AuthorInColaborationPolicy),
+                       :sell => andP(AuthorPolicy, notP(AuthorInColaborationPolicy)),
+                       :sing_with_john => ColaboratingWithJohnPolicy
+  attr_accessor :name
+  attr_accessor :colaboration
+  attr_accessor :author
+  
+  def initialize(name, owner)
+    @name = name
+    case owner
+    when Colaboration
+      @colaboration = owner
+    when Beatle
+      @author = owner
+    end
+    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)
+end
+

data/spec/spec.opts

@@ -0,0 +1,5 @@
+--colour
+--format specdoc
+--loadby mtime
+--reverse
+--backtrace

data/spec/spec_helper.rb

@@ -0,0 +1,11 @@
+require 'rubygems'
+require 'spec'
+require 'pp'
+
+$LOAD_PATH.unshift(File.dirname(__FILE__))
+$LOAD_PATH.unshift(File.join(File.dirname(__FILE__), '..', 'lib'))
+require 'walruz'
+require File.dirname(__FILE__) + '/scenario'
+
+Spec::Runner.configure do |config|
+end

data/spec/walruz/actor_spec.rb

@@ -0,0 +1,123 @@
+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!)
+  end
+  
+  it "should add an instance method `can?` to included classes" do
+    Beatle::JOHN.should respond_to(:can?)
+  end
+  
+  it "should add an instance method `satisfies?` to included classes" do
+    Beatle::JOHN.should respond_to(:satisfies?)
+  end
+  
+  
+  describe "can!" do
+    
+    it "should raise a Walruz::NotAuthorized error when the actor is not authorized" do
+      lambda do
+        Beatle::RINGO.sing_the_song(Song::ALL_YOU_NEED_IS_LOVE)
+      end.should raise_error(Walruz::NotAuthorized)
+    end
+    
+    it "should not raise a Walruz::NotAuthorized error when the actor is authorized" do
+      lambda do
+        Beatle::JOHN.sing_the_song(Song::ALL_YOU_NEED_IS_LOVE)
+      end.should_not raise_error(Walruz::NotAuthorized)
+    end
+    
+    it "should provide parameteres for the invokator correctly" do
+      Beatle::JOHN.sing_the_song(Song::ALL_YOU_NEED_IS_LOVE).should == "I just need myself, Let's Rock! \\m/"
+      Beatle::JOHN.sing_the_song(Song::YELLOW_SUBMARINE).should == "I need Paul to play this song properly"
+    end
+    
+  end
+  
+  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)
+    end
+    
+    # @deprecated functionality
+    # WHY: When you execute `can?` you should probably have already executed `can!`
+    # it "should execute a given block if the condition is true" do
+    #   proc_called = lambda { raise "Is being called" }
+    #   lambda do
+    #     Beatle::JOHN.can?(:sing, Song::ALL_YOU_NEED_IS_LOVE, &proc_called)
+    #   end.should raise_error
+    # end
+    
+    it "if a boolean third parameter is received it should not use the cached result" do
+      Beatle::JOHN.stub!(:can_without_caching?).and_return(true)
+      Beatle::JOHN.can?(:sing, Song::ALL_YOU_NEED_IS_LOVE).should be_true
+      
+      Beatle::JOHN.stub!(:can_without_caching?).and_return(false)
+      Beatle::JOHN.can?(:sing, Song::ALL_YOU_NEED_IS_LOVE).should be_true
+      Beatle::JOHN.can?(:sing, Song::ALL_YOU_NEED_IS_LOVE, true).should be_false
+    end
+    
+    it "should receive at least 2 parameters" do
+      lambda do
+        Beatle::JOHN.can?(:sing)
+      end.should raise_error(ArgumentError)
+    end
+    
+    it "should receive at most 3 parameters" do
+      lambda do
+        Beatle::JOHN.can?(:sing, Song::ALL_YOU_NEED_IS_LOVE, true, false)
+      end.should raise_error(ArgumentError)
+    end
+    
+    
+    it "should execute a given 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_policy?].should be_true
+      end
+      Beatle::JOHN.can?(:sing, Song::ALL_YOU_NEED_IS_LOVE, &proc_called)
+    end
+    
+  end
+  
+  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
+    end
+    
+    it "should check only the specified 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)
+    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
+    
+    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)
+    end
+    
+  end
+  
+end

data/spec/walruz/policy_spec.rb

@@ -0,0 +1,62 @@
+require File.dirname(__FILE__) + '/../spec_helper'
+
+describe Walruz::Policy do
+  
+  it "should provide the with_actor utility" do
+    AuthorPolicy.should respond_to(:with_actor)
+  end
+  
+  it "should generate an indicator that the policy was executed after authorization queries" do
+    policy = Beatle::PAUL.can!(:sing, Song::YESTERDAY)
+    policy[:author_policy?].should be_true
+  end
+  
+  it "should have a default label" do
+    AuthorPolicy.policy_label.should == :author_policy
+  end
+  
+  it "should prioritize a label that is setted over the default one" do
+    AuthorPolicy.set_policy_label :is_author
+    AuthorPolicy.policy_label.should == :is_author
+    AuthorPolicy.set_policy_label(nil)
+  end
+  
+  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)
+    end.should raise_error(Walruz::ActionNotFound)
+  end
+  
+  describe "when using the #with_actor method" do
+    
+    before(:each) do
+      @songs = [Song::A_DAY_IN_LIFE, Song::YELLOW_SUBMARINE, Song::TAXMAN,
+                Song::YESTERDAY, Song::ALL_YOU_NEED_IS_LOVE, Song::BLUE_JAY_WAY]
+    end
+    
+    it "should work properly" do
+      george_authorship_songs = @songs.select(&AuthorPolicy.with_actor(Beatle::GEORGE))
+      george_authorship_songs.should have(1).song
+      george_authorship_songs.should == [Song::BLUE_JAY_WAY]
+      
+      
+      john_and_paul_songs = @songs.select(&AuthorInColaborationPolicy.with_actor(Beatle::JOHN))
+      john_and_paul_songs.should have(3).songs
+      john_and_paul_songs.should == [Song::A_DAY_IN_LIFE, Song::YELLOW_SUBMARINE, Song::TAXMAN]
+    end
+    
+  end
+  
+  describe "when using dependence_on macro" do
+    
+    it "should work properly" do
+      lambda do
+        Beatle::PAUL.sing_with_john(Song::YESTERDAY)
+      end.should raise_error(Walruz::NotAuthorized)
+      
+      Beatle::PAUL.sing_with_john(Song::A_DAY_IN_LIFE).should == "Ok John, Let's Play 'A Day In Life'"
+    end
+  
+  end
+  
+end

data/spec/walruz/subject_spec.rb

@@ -0,0 +1,24 @@
+require File.dirname(__FILE__) + '/../spec_helper'
+
+describe Walruz::Subject do
+  
+  it "should add a can_be? method" do
+    Song::A_DAY_IN_LIFE.should respond_to(:can_be?)
+  end
+  
+  it "should add a class method called check_authorizations" do
+    Song.should respond_to(:check_authorizations)
+  end
+  
+  
+  describe "when executing validations on an invalid subject" do
+    
+    it "should raise an Walruz::AuthorizationActionsNotDefined error" do
+      lambda do
+        Beatle::JOHN.can_be?(:talk_with, Beatle::PAUL)
+      end.should raise_error(Walruz::AuthorizationActionsNotDefined)
+    end
+    
+  end
+  
+end

data/spec/walruz/utils_spec.rb

@@ -0,0 +1,46 @@
+require File.dirname(__FILE__) + '/../spec_helper'
+
+describe Walruz::Utils do
+  
+  def check_actor_can_on_subject(label, actor, subject)
+    lambda do
+      actor.can!(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)
+    end.should raise_error(Walruz::NotAuthorized)
+  end
+  
+  describe "when using combinators `orP`, `andP` or `notP`" do
+    
+    it "should work properly" do
+      check_actor_can_not_on_subject(:sell, Beatle::JOHN, Song::A_DAY_IN_LIFE)
+      check_actor_can_on_subject(:sell, Beatle::JOHN, Song::ALL_YOU_NEED_IS_LOVE)
+    end
+    
+  end
+  
+  describe "when using andP" 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|
+        policy_params[:"author_policy_and_not(author_in_colaboration_policy)?"].should be_true
+      end
+    end
+    
+  end
+  
+  describe "when using notP" 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|
+        policy_params[:"not(author_in_colaboration_policy)?"].should be_true
+      end
+    end
+    
+  end
+  
+end

data/spec/walruz/walruz_spec.rb

@@ -0,0 +1,20 @@
+require File.dirname(__FILE__) + '/../spec_helper'
+
+describe Walruz do
+
+  it "should have a policies method" do
+    Walruz.should respond_to(:policies)
+  end
+  
+  describe '#policies' do
+    
+    it "should return all the policies created that have a label" do
+      Walruz.policies.should_not be_nil
+      Walruz.policies[:author_policy].should be_nil
+      Walruz.policies[:author_in_colaboration_policy].should == AuthorInColaborationPolicy
+      Walruz.policies[:colaborating_with_john_policy].should == ColaboratingWithJohnPolicy
+    end
+    
+  end
+
+end