canable 0.1

data/.document

@@ -0,0 +1,5 @@
+README.rdoc
+lib/**/*.rb
+bin/*
+features/**/*.feature
+LICENSE

data/.gitignore

@@ -0,0 +1,22 @@
+## MAC OS
+.DS_Store
+
+## TEXTMATE
+*.tmproj
+tmtags
+
+## EMACS
+*~
+\#*
+.\#*
+
+## VIM
+*.swp
+
+## PROJECT::GENERAL
+coverage
+rdoc
+pkg
+
+## PROJECT::SPECIFIC
+tmp

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2009 John Nunemaker
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.rdoc

@@ -0,0 +1,122 @@
+= Canable
+
+Simple permissions that I have used on my last several projects so I figured it was time to abstract and wrap up into something more easily reusable.
+
+== Cans
+
+Whatever class you want all permissions to run through should include Canable::Cans.
+
+    class User
+      include MongoMapper::Document
+      include Canable::Cans
+    end
+
+This means that an instance of a user automatically gets can methods for the default REST actions: can_view?(resource), can_create?(resource), can_update?(resource), can_destroy?(resource).
+
+== Ables
+
+Each of the can methods simply calls the related "able" method (viewable, creatable, updatable, destroyable) for the action (view, create, update, delete). Canable comes with defaults for this methods that you can then override as makes sense for your permissions.
+
+    class Article
+      include MongoMapper::Document
+      include Canable::Ables
+    end
+
+Including Canable::Ables adds the able methods to the class including it. In this instance, article now has viewable_by?(user), creatable_by?(user), updatable_by?(user) and destroyable_by?(user).
+
+Lets say an article can be viewed and created by anyone, but only updated or destroyed by the user that created the article. To do that, you could leave viewable_by? and creatable_by? alone as they default to true and just override the other methods.
+
+    class Article
+      include MongoMapper::Document
+      include Canable::Ables
+      userstamps! # adds creator and updater
+      
+      def updatable_by?(user)
+        creator == user
+      end
+      
+      def destroyable_by?(user)
+        updatable_by?(user)
+      end
+    end
+
+Lets look at some sample code now:
+
+    john = User.create(:name => 'John')
+    steve = User.create(:name =. 'Steve')
+    
+    ruby = Article.new(:title => 'Ruby')
+    john.can_create?(ruby) # true
+    steve.can_create?(ruby) # true
+    
+    ruby.creator = john
+    ruby.save
+    
+    john.can_view?(ruby) # true
+    steve.can_view?(ruby) # true
+    
+    john.can_update?(ruby) # true
+    steve.can_update?(ruby) # false
+    
+    john.can_destroy?(ruby) # true
+    steve.can_destroy?(ruby) # false
+    
+Now we can implement our permissions for each resource and then always check whether a user can or cannot do something. This makes it all really easy to test. Next, how would you use this in the controller.
+
+== Enforcers
+
+    class ApplicationController
+      include Canable::Enforcers
+    end
+
+Including Canable::Enforcers adds an enforce permission method for each of the actions defined (by default view/create/update/destroy). It is the same thing as doing this for each Canable action:
+
+    class ApplicationController
+      include Canable::Enforcers
+
+      delegate :can_view?, :to => :current_user
+      helper_method :can_view? # so you can use it in your views
+      hide_action :can_view?
+
+      private
+        def enforce_view_permission(resource)
+          raise Canable::Transgression unless can_view?(resource)
+        end
+    end
+
+Which means you can use it like this:
+
+    class ArticlesController < ApplicationController
+      def show
+        @article = Article.find!(params[:id])
+        enforce_view_permission(@article)
+      end
+    end
+
+If the user can_view? the article, all is well. If not, a Canable::Transgression is raised which you can decide how to handle (show 404, slap them on the wrist, etc.).
+
+== Adding Your Own Actions
+
+You can add your own actions like this:
+
+    Canable.add(:publish, :publishable)
+
+The first parameter is the can method (ie: can_publish?) and the second is the able method (ie: publishable_by?). 
+
+== Review
+
+So, lets review: cans go on user model, ables go on everything, you override ables in each model where you want to enforce permissions, and enforcers go after each time you find or initialize an object in a controller. Bing, bang, boom.
+
+== Note on Patches/Pull Requests
+ 
+* Fork the project.
+* Make your feature addition or bug fix.
+* Add tests for it. This is important so I don't break it in a
+  future version unintentionally.
+* Commit, do not mess with rakefile, version, or history.
+  (if you want to have your own version, that is fine but bump version in a commit by itself I can ignore when I pull)
+* Send me a pull request. Bonus points for topic branches.
+
+== Copyright
+
+Copyright (c) 2010 John Nunemaker. See LICENSE for details.

data/Rakefile

@@ -0,0 +1,45 @@
+require 'rubygems'
+require 'rake'
+
+require File.dirname(__FILE__) + '/lib/canable'
+
+begin
+  require 'jeweler'
+  Jeweler::Tasks.new do |gem|
+    gem.name        = "canable"
+    gem.summary     = %Q{Simple permissions that I have used on my last several projects so I figured it was time to abstract and wrap up into something more easily reusable.}
+    gem.description = %Q{Simple permissions that I have used on my last several projects so I figured it was time to abstract and wrap up into something more easily reusable.}
+    gem.email       = "nunemaker@gmail.com"
+    gem.homepage    = "http://github.com/jnunemaker/canable"
+    gem.authors     = ["John Nunemaker"]
+    gem.version     = Canable::Version
+    gem.add_development_dependency "shoulda", "2.10.2"
+    gem.add_development_dependency "mongo_mapper", "0.7"
+    gem.add_development_dependency "mocha", "0.9.8"
+    gem.add_development_dependency "yard", ">= 0"
+    # gem is a Gem::Specification... see http://www.rubygems.org/read/chapter/20 for additional settings
+  end
+  Jeweler::GemcutterTasks.new
+rescue LoadError
+  puts "Jeweler (or a dependency) not available. Install it with: gem install jeweler"
+end
+
+require 'rake/testtask'
+Rake::TestTask.new(:test) do |test|
+  test.libs << 'lib' << 'test'
+  test.ruby_opts << '-rubygems'
+  test.pattern = 'test/**/test_*.rb'
+  test.verbose = true
+end
+
+task :test => :check_dependencies
+task :default => :test
+
+begin
+  require 'yard'
+  YARD::Rake::YardocTask.new
+rescue LoadError
+  task :yardoc do
+    abort "YARD is not available. In order to run yardoc, you must: sudo gem install yard"
+  end
+end

data/lib/canable.rb

@@ -0,0 +1,77 @@
+module Canable
+  Version = '0.1'
+
+  # Module that holds all the can_action? methods.
+  module Cans; end
+
+  # Module that holds all the [method]able_by? methods.
+  module Ables; end
+
+  # Module that holds all the enforce_[action]_permission methods for use in controllers.
+  module Enforcers
+    def self.included(controller)
+      controller.class_eval do
+        Canable.actions.each do |can, able|
+          delegate      "can_#{can}?", :to => :current_user
+          helper_method "can_#{can}?" if controller.respond_to?(:helper_method)
+          hide_action   "can_#{can}?" if controller.respond_to?(:hide_action)
+        end
+      end
+    end
+  end
+
+  # Exception that gets raised when permissions are broken for whatever reason.
+  class Transgression < StandardError; end
+
+  # Default actions to an empty hash.
+  @actions = {}
+
+  # Returns hash of actions that have been added.
+  #   {:view => :viewable, ...}
+  def self.actions
+    @actions
+  end
+
+  # Adds an action to actions and the correct methods to can and able modules.
+  #
+  #   @param [Symbol] can_method The name of the can_[action]? method.
+  #   @param [Symbol] resource_method The name of the [resource_method]_by? method.
+  def self.add(can, able)
+    @actions[can] = able
+    add_can_method(can, able)
+    add_able_method(able)
+    add_enforcer_method(can)
+  end
+
+  private
+    def self.add_can_method(can, able)
+      Cans.module_eval <<-EOM
+        def can_#{can}?(resource)
+          return false if resource.blank?
+          resource.#{able}_by?(self)
+        end
+      EOM
+    end
+
+    def self.add_able_method(able)
+      Ables.module_eval <<-EOM
+        def #{able}_by?(user)
+          true
+        end
+      EOM
+    end
+
+    def self.add_enforcer_method(can)
+      Enforcers.module_eval <<-EOM
+        def enforce_#{can}_permission(resource)
+          raise Canable::Transgression unless can_#{can}?(resource)
+        end
+        private :enforce_#{can}_permission
+      EOM
+    end
+end
+
+Canable.add(:view,    :viewable)
+Canable.add(:create,  :creatable)
+Canable.add(:update,  :updatable)
+Canable.add(:destroy, :destroyable)

data/specs.watchr

@@ -0,0 +1,47 @@
+def growl(title, msg, img)
+  %x{growlnotify -m #{ msg.inspect} -t #{title.inspect} --image ~/.watchr/#{img}.png}
+end
+
+def form_growl_message(str)
+  results = str.split("\n").last
+  if results =~ /[1-9]\s(failure|error)s?/
+    growl "Test Results", "#{results}", "fail"
+  elsif results != ""
+    growl "Test Results", "#{results}", "pass"
+  end
+end
+
+def run(cmd)
+  puts(cmd)
+  output = ""
+  IO.popen(cmd) do |com|
+    com.each_char do |c|
+      print c
+      output << c
+      $stdout.flush
+    end
+  end
+  form_growl_message output
+end
+
+def run_test_file(file)
+  run %Q(ruby -I"lib:test" -rubygems #{file})
+end
+
+def run_all_tests
+  run "rake test"
+end
+
+watch('test/helper\.rb') { system('clear'); run_all_tests }
+watch('test/test_.*\.rb') { |m| system('clear'); run_test_file(m[0]) }
+watch('lib/.*') { |m| system('clear'); run_all_tests }
+
+# Ctrl-\
+Signal.trap('QUIT') do
+  puts " --- Running all tests ---\n\n"
+  run_all_tests
+end
+
+# Ctrl-C
+Signal.trap('INT') { abort("\n") }
+

data/test/helper.rb

@@ -0,0 +1,38 @@
+require 'test/unit'
+
+gem 'mocha', '0.9.8'
+gem 'shoulda', '2.10.2'
+gem 'mongo_mapper', '0.7'
+
+require 'mocha'
+require 'shoulda'
+require 'mongo_mapper'
+
+$LOAD_PATH.unshift(File.join(File.dirname(__FILE__), '..', 'lib'))
+$LOAD_PATH.unshift(File.dirname(__FILE__))
+require 'canable'
+
+class Test::Unit::TestCase
+end
+
+def Doc(name=nil, &block)
+  klass = Class.new do
+    include MongoMapper::Document
+    set_collection_name "test#{rand(20)}"
+
+    if name
+      class_eval "def self.name; '#{name}' end"
+      class_eval "def self.to_s; '#{name}' end"
+    end
+  end
+
+  klass.class_eval(&block) if block_given?
+  klass.collection.remove
+  klass
+end
+
+test_dir = File.expand_path(File.dirname(__FILE__) + '/../tmp')
+FileUtils.mkdir_p(test_dir) unless File.exist?(test_dir)
+
+MongoMapper.connection = Mongo::Connection.new('127.0.0.1', 27017, {:logger => Logger.new(test_dir + '/test.log')})
+MongoMapper.database = 'test'

data/test/test_ables.rb

@@ -0,0 +1,51 @@
+require 'helper'
+
+class AblesTest < Test::Unit::TestCase
+  context "Class with Canable::Ables included" do
+    setup do
+      klass = Doc do
+        include Canable::Ables
+      end
+
+      @resource = klass.new
+      @user     = mock('user')
+    end
+
+    should "default viewable_by? to true" do
+      assert @resource.viewable_by?(@user)
+    end
+
+    should "default creatable_by? to true" do
+      assert @resource.creatable_by?(@user)
+    end
+
+    should "default updatable_by? to true" do
+      assert @resource.updatable_by?(@user)
+    end
+
+    should "default destroyable_by? to true" do
+      assert @resource.destroyable_by?(@user)
+    end
+  end
+  
+  context "Class that overrides an able method" do
+    setup do
+      klass = Doc do
+        include Canable::Ables
+        
+        def viewable_by?(user)
+          user.name == 'John'
+        end
+      end
+      
+      @resource = klass.new
+      @john     = mock('user', :name => 'John')
+      @steve    = mock('user', :name => 'Steve')
+    end
+    
+    should "use the overriden method and not default to true" do
+      assert @resource.viewable_by?(@john)
+      assert ! @resource.viewable_by?(@steve)
+    end
+  end
+end

data/test/test_canable.rb

@@ -0,0 +1,26 @@
+require 'helper'
+
+class TestCanable < Test::Unit::TestCase
+  context "Canable" do
+    should "have view action by default" do
+      assert_equal :viewable, Canable.actions[:view]
+    end
+
+    should "have create action by default" do
+      assert_equal :creatable, Canable.actions[:create]
+    end
+
+    should "have update action by default" do
+      assert_equal :updatable, Canable.actions[:update]
+    end
+
+    should "have destroy action by default" do
+      assert_equal :destroyable, Canable.actions[:destroy]
+    end
+    
+    should "be able to add another action" do
+      Canable.add(:publish, :publishable)
+      assert_equal :publishable, Canable.actions[:publish]
+    end
+  end
+end

data/test/test_cans.rb

@@ -0,0 +1,81 @@
+require 'helper'
+
+class CansTest < Test::Unit::TestCase
+  context "Class with Canable::Cans included" do
+    setup do
+      klass = Doc do
+        include Canable::Cans
+      end
+      
+      @user = klass.create(:name => 'John')
+    end
+
+    context "can_view?" do
+      should "be true if resource is viewable_by?" do
+        resource = mock('resource', :viewable_by? => true)
+        assert @user.can_view?(resource)
+      end
+
+      should "be false if resource is not viewable_by?" do
+        resource = mock('resource', :viewable_by? => false)
+        assert ! @user.can_view?(resource)
+      end
+
+      should "be false if resource is blank" do
+        assert ! @user.can_view?(nil)
+        assert ! @user.can_view?('')
+      end
+    end
+
+    context "can_create?" do
+      should "be true if resource is creatable_by?" do
+        resource = mock('resource', :creatable_by? => true)
+        assert @user.can_create?(resource)
+      end
+
+      should "be false if resource is not creatable_by?" do
+        resource = mock('resource', :creatable_by? => false)
+        assert ! @user.can_create?(resource)
+      end
+
+      should "be false if resource is blank" do
+        assert ! @user.can_create?(nil)
+        assert ! @user.can_create?('')
+      end
+    end
+
+    context "can_update?" do
+      should "be true if resource is updatable_by?" do
+        resource = mock('resource', :updatable_by? => true)
+        assert @user.can_update?(resource)
+      end
+
+      should "be false if resource is not updatable_by?" do
+        resource = mock('resource', :updatable_by? => false)
+        assert ! @user.can_update?(resource)
+      end
+
+      should "be false if resource is blank" do
+        assert ! @user.can_update?(nil)
+        assert ! @user.can_update?('')
+      end
+    end
+
+    context "can_destroy?" do
+      should "be true if resource is destroyable_by?" do
+        resource = mock('resource', :destroyable_by? => true)
+        assert @user.can_destroy?(resource)
+      end
+
+      should "be false if resource is not destroyable_by?" do
+        resource = mock('resource', :destroyable_by? => false)
+        assert ! @user.can_destroy?(resource)
+      end
+
+      should "be false if resource is blank" do
+        assert ! @user.can_destroy?(nil)
+        assert ! @user.can_destroy?('')
+      end
+    end
+  end
+end

data/test/test_enforcers.rb

@@ -0,0 +1,32 @@
+require 'helper'
+
+class EnforcersTest < Test::Unit::TestCase
+  context "Including Canable::Enforcers in a class" do
+    setup do
+      klass = Class.new do
+        include Canable::Enforcers
+        attr_accessor :current_user, :article
+
+        def show
+          enforce_view_permission(article)
+        end
+      end
+
+      @article                 = mock('article')
+      @user                    = mock('user')
+      @controller              = klass.new
+      @controller.article      = @article
+      @controller.current_user = @user
+    end
+
+    should "not raise error if can" do
+      @user.expects(:can_view?).with(@article).returns(true)
+      assert_nothing_raised { @controller.show }
+    end
+
+    should "raise error if cannot" do
+      @user.expects(:can_view?).with(@article).returns(false)
+      assert_raises(Canable::Transgression) { @controller.show }
+    end
+  end
+end

metadata

@@ -0,0 +1,110 @@
+--- !ruby/object:Gem::Specification 
+name: canable
+version: !ruby/object:Gem::Version 
+  version: "0.1"
+platform: ruby
+authors: 
+- John Nunemaker
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2010-02-27 00:00:00 -05:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: shoulda
+  type: :development
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - "="
+      - !ruby/object:Gem::Version 
+        version: 2.10.2
+    version: 
+- !ruby/object:Gem::Dependency 
+  name: mongo_mapper
+  type: :development
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - "="
+      - !ruby/object:Gem::Version 
+        version: "0.7"
+    version: 
+- !ruby/object:Gem::Dependency 
+  name: mocha
+  type: :development
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - "="
+      - !ruby/object:Gem::Version 
+        version: 0.9.8
+    version: 
+- !ruby/object:Gem::Dependency 
+  name: yard
+  type: :development
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: "0"
+    version: 
+description: Simple permissions that I have used on my last several projects so I figured it was time to abstract and wrap up into something more easily reusable.
+email: nunemaker@gmail.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- LICENSE
+- README.rdoc
+files: 
+- .document
+- .gitignore
+- LICENSE
+- README.rdoc
+- Rakefile
+- lib/canable.rb
+- specs.watchr
+- test/helper.rb
+- test/test_ables.rb
+- test/test_canable.rb
+- test/test_cans.rb
+- test/test_enforcers.rb
+has_rdoc: true
+homepage: http://github.com/jnunemaker/canable
+licenses: []
+
+post_install_message: 
+rdoc_options: 
+- --charset=UTF-8
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.3.5
+signing_key: 
+specification_version: 3
+summary: Simple permissions that I have used on my last several projects so I figured it was time to abstract and wrap up into something more easily reusable.
+test_files: 
+- test/helper.rb
+- test/test_ables.rb
+- test/test_canable.rb
+- test/test_cans.rb
+- test/test_enforcers.rb