can_do 0.1.1 → 0.1.2

data/README

@@ -0,0 +1,94 @@
+Can Do
+
+DSL-based permission rules for Rails
+
+Example:
+
+    class Permission
+      def self.define_rules
+        CanDo.setup do
+          can :index, User do
+            rule("You must be logged in.") {User.current}
+            rule("You must have an active account to do this.") {User.current.active?}
+          end
+      
+          can :show, User do
+            cascade :index          #inherit the logged in and active rules from :index
+            rule("You may not view others' accounts if they are private.") do |user| 
+              !user.private? || user == User.current || User.current.admin?
+            end
+          end
+      
+          can :update, User do
+            cascade :index          #inherit the logged in and active rules from :index
+            rule("You may not update others' accounts.") {|user| user == User.current || User.current.admin?}
+          end
+      
+          can :delete, User do
+            cascade :update
+          end
+      
+          can :create, UserInterest do
+            # You may create an interest if you have permission to update that user.
+            cascade :update, {|interest| interest.user} 
+          end
+        end
+      end
+    end
+
+application.rb: 
+    ActionDispatch::Callbacks.to_prepare do
+      Permission.define_rules       #allows rules to be reloaded when classes are reloaded
+    end
+
+users_controller.rb:
+    def index
+      require_permission! :index, User  #this will raise a CanDo::PermissionError if permission is denied
+      ...
+    end
+  
+    def show
+      @user = User.find(params[:id])
+      require_permission! :show, user   #this will raise a CanDo::PermissionError if permission is denied
+      ...
+    end
+  
+application_controller.rb:
+    rescue_from CanDo::PermissionError do |error|
+      render :text => "Permission denied: #{error.message}"
+    end
+    
+    before_filter :initialize_current_user
+    
+    def initialize_current_user
+      User.current = your_code_goes_here
+    end
+    
+user.rb
+    def self.current=(value)
+      Thread.current["User.current"] = value
+    end
+
+    def self.current
+      Thread.current["User.current"]
+    end
+
+users/index.haml
+    %ul
+      - @users.each do |user|
+        - can?(:show, user) do
+          %li
+            = link_to user.name, user_path(user)
+            - if can?(:update, user) do
+              = link_to "Edit", edit_user_path(user)
+    - can?(:create, User) do
+      = link_to "Add User", new_user_path
+
+    
+To test your permission logic, simply call CanDo.reason(:verb, object) and test that the reason is what you expect. Make sure to test all rules inherited from cascades as well. Without this, it's easy for cascades to introduce unintended consequences.
+          
+
+Special thanks to cancan, upon which Can Do is loosely based. Important differences:
+  * For large permission sets, cancan slows down dramatically. Can Do uses hash-based lookups, which dramatically reduces performance overhead.
+  * Can Do is far more expressive, allowing user-friendly explanations for failures.
+  * Can Do has explicit support for cascading rules to reduce repetition.

data/can_do.gemspec

@@ -0,0 +1,18 @@
+# -*- encoding: utf-8 -*-
+$:.push File.expand_path("../lib", __FILE__)
+
+Gem::Specification.new do |s|
+  s.name        = "can_do"
+  s.version     = "0.1.2"
+  s.platform    = Gem::Platform::RUBY
+  s.authors     = ["Ryan Fogle", "Zachary Kurmas"]
+  s.email       = "nayrelgof@gmail.com"
+  s.homepage    = "http://github.com/fogle/can_do"
+  s.summary     = "DSL-based permission rules for Rails"
+  s.description = "DSL-based permission rules for easy authorization logic in Rails"
+
+  s.files         = `git ls-files`.split("\n")
+  s.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
+  s.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
+  s.require_paths = ["lib"]
+end

data/lib/can_do.rb

@@ -0,0 +1,46 @@
+require 'can_do/dsl'
+require 'can_do/permission_error'
+
+module CanDo
+  def self.setup &block
+    @active_dsl = CanDo::Dsl.new &block
+  end
+  
+  def self.can?(verb, noun, &block)
+    raise "you must first call setup" unless @active_dsl
+    @active_dsl.can?(verb, noun, &block)
+  end
+
+  def self.reason(verb, noun)
+    raise "you must first call setup" unless @active_dsl
+    @active_dsl.reason(verb, noun)
+  end
+end
+
+module ActionController
+  class Base
+    def can?(*args, &block)
+      CanDo.can?(*args, &block)
+    end
+    
+    def require_permission!(*args)
+      reason = CanDo.reason(*args)
+      unless reason.nil?
+        Rails.logger.info "Permission Error: #{reason}"
+        deny_permission(reason, *args)
+      end
+    end
+    
+    def deny_permission(reason, *args)
+      raise CanDo::PermissionError.new(reason)
+    end
+  end
+end
+
+module ActionView
+  module Helpers
+    def can?(*args, &block)
+      CanDo.can?(*args, &block)
+    end
+  end
+end

data/lib/can_do/dsl.rb

@@ -0,0 +1,81 @@
+module CanDo
+  class Dsl
+    NIL_REASON = "Object of query does not exist."
+    def noun(object)
+      noun = object.class unless object.class == Class || object.class == String
+      noun || object
+    end
+
+    def can?(action, object)
+      can = internal_reason(action, noun(object), object).nil?
+      yield if can && block_given?
+      can
+    end
+  
+    def reason(action, object)
+      internal_reason(action, noun(object), object)
+    end
+  
+    def internal_reason(action, noun, object)
+      return NIL_REASON if object.nil?
+      rules = @can_hash[action][noun]
+      rules.each do |rule|
+        return rule.reason unless rule.call(object, noun)
+      end
+      nil
+    end
+    
+    def can(action, noun, &block)
+      @rules = []
+      yield
+      @can_hash[action] ||= {}
+      @can_hash[action][noun] = @rules
+    end
+  
+    def rule(reason=nil, &block)
+      @rules << Rule.new(reason, &block)
+    end
+  
+    def cascade(action, &block)
+      @rules << Cascade.new(action, self, &block)
+    end
+  
+    def initialize &block
+      @can_hash = {}
+      instance_eval &block
+    end
+  
+    class Rule
+      attr_reader :reason
+    
+      def initialize(reason, &block)
+        @reason = reason || "Unknown Reason"
+        @block = block
+      end
+    
+      def call(object, noun)
+        @block.call(object)
+      end
+    end
+  
+    class Cascade
+      def initialize(action, ability, &block)
+        @action = action
+        @ability = ability
+        @transformation = block
+      end
+
+      def reason
+        @reason
+      end
+    
+      def call(object, noun)
+        @reason = nil
+        object = @transformation.call(object) if @transformation
+        noun = @ability.noun(object) if @transformation
+        @reason = @ability.internal_reason(@action, noun, object)
+        @reason.nil?
+      end
+    end
+  end
+end

data/lib/can_do/permission_error.rb

@@ -0,0 +1,8 @@
+module CanDo
+  class PermissionError < Exception
+    def initialize(reason, debug_info = nil)
+      super(reason)
+      @debug_info = debug_info
+    end
+  end
+end

data/spec/dsl_spec.rb

@@ -0,0 +1,55 @@
+require 'spec_helper'
+
+describe CanDo::Dsl do
+  before do
+    @dsl = CanDo::Dsl.new
+    @dsl.instance_eval do
+      can :be_numeric, Symbol do
+        rule("couldn't convert to a number") {|symbol, noun| symbol.to_s.gsub('"', '').to_i.to_s == symbol.to_s.gsub('"', '')}
+      end
+
+      can :be_odd, Fixnum do
+        rule("wasn't odd") {|number, noun| number.odd?}
+      end
+  
+      can :be_odd, Symbol do
+        cascade(:be_numeric)
+        cascade(:be_odd) {|symbol| symbol.to_s.gsub('"', '').to_i}
+      end
+    end
+  end
+
+  it 'returns non-nil when passed a nil noun' do
+    @dsl.can?(:be_numeric, nil).should == false
+    @dsl.reason(:be_numeric, nil).should == CanDo::Dsl::NIL_REASON
+  end
+
+  it 'handles simple rules like :be_numeric, Symbol' do
+    @dsl.can?(:be_numeric, :"3").should == true
+    @dsl.can?(:be_numeric, :"3ish").should == false
+
+
+    @dsl.reason(:be_numeric, :"3").should be_nil
+    @dsl.reason(:be_numeric, :"3ish").should == "couldn't convert to a number"
+
+
+  end
+
+  it 'handles simple rules like :be_odd, Fixnum' do
+    @dsl.can?(:be_odd, 3).should == true
+    @dsl.can?(:be_odd, 2).should == false
+    @dsl.reason(:be_odd, 3).should be_nil
+    @dsl.reason(:be_odd, 2).should == "wasn't odd"
+  end
+  
+  it 'supports cascading rules' do
+    @dsl.can?(:be_odd, :"3ish").should == false
+    @dsl.reason(:be_odd, :"3ish").should == "couldn't convert to a number"
+
+    @dsl.can?(:be_odd, :"3").should == true
+    @dsl.reason(:be_odd, :"3").should be_nil
+    
+    @dsl.can?(:be_odd, :"2").should == false
+    @dsl.reason(:be_odd, :"2").should == "wasn't odd"
+  end
+end

data/spec/spec_helper.rb

@@ -0,0 +1 @@
+require 'can_do'

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification 
 name: can_do
 version: !ruby/object:Gem::Version 
-  hash: 25
+  hash: 31
   prerelease: 
   segments: 
   - 0
   - 1
-  - 1
-  version: 0.1.1
+  - 2
+  version: 0.1.2
 platform: ruby
 authors: 
 - Ryan Fogle
@@ -27,9 +27,16 @@ extensions: []
 
 extra_rdoc_files: []
 
-files: []
-
-homepage: 
+files: 
+- README
+- can_do-0.1.0.gem
+- can_do.gemspec
+- lib/can_do.rb
+- lib/can_do/dsl.rb
+- lib/can_do/permission_error.rb
+- spec/dsl_spec.rb
+- spec/spec_helper.rb
+homepage: http://github.com/fogle/can_do
 licenses: []
 
 post_install_message: 
@@ -62,5 +69,6 @@ rubygems_version: 1.7.2
 signing_key: 
 specification_version: 3
 summary: DSL-based permission rules for Rails
-test_files: []
-
+test_files: 
+- spec/dsl_spec.rb
+- spec/spec_helper.rb