cannabis 0.2.0

data/.gitignore

@@ -0,0 +1,3 @@
+pkg/*
+*.gem
+.bundle

data/Gemfile

@@ -0,0 +1,4 @@
+source :gemcutter
+
+# Specify your gem's dependencies in cannabis.gemspec
+gemspec

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2010 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,136 @@
+= Cannabis
+
+Very 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
+Cannabis::Cans.
+
+    class User
+      include MongoMapper::Document
+      include Cannabis::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). Cannabis comes with defaults for this methods
+that you can then override as makes sense for your permissions.
+
+    class Article
+      include MongoMapper::Document
+      include Cannabis::Ables
+    end
+
+Including Cannabis::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 Cannabis::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 Cannabis::Enforcers
+    end
+
+Including Cannabis::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 Cannabis action:
+
+    class ApplicationController
+      include Cannabis::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 Cannabis::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
+Cannabis::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:
+
+    Cannabis.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.
+
+== Copyright
+
+Copyright (c) 2010 John Nunemaker. See LICENSE for details.

data/Rakefile

@@ -0,0 +1,11 @@
+require 'bundler'
+Bundler::GemHelper.install_tasks
+
+require "rake/testtask"
+Rake::TestTask.new(:test) do |test|
+  test.libs << "lib" << "test"
+  test.pattern = "test/**/*_test.rb"
+  test.verbose = true
+end
+
+task :default => :test

data/cannabis.gemspec

@@ -0,0 +1,22 @@
+# -*- encoding: utf-8 -*-
+require File.expand_path("../lib/cannabis/version", __FILE__)
+
+Gem::Specification.new do |s|
+  s.name        = "cannabis"
+  s.version     = Cannabis::VERSION
+  s.platform    = Gem::Platform::RUBY
+  s.authors     = ["Jakub Kuźma"]
+  s.email       = ["qoobaa@gmail.com"]
+  s.homepage    = "http://rubygems.org/gems/cannabis"
+  s.summary     = "Simple permissions system"
+  s.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."
+
+  s.required_rubygems_version = ">= 1.3.6"
+  s.rubyforge_project         = "cannabis"
+
+  s.add_development_dependency "bundler", ">= 1.0.0"
+
+  s.files        = `git ls-files`.split("\n")
+  s.executables  = `git ls-files`.split("\n").map{|f| f =~ /^bin\/(.*)/ ? $1 : nil}.compact
+  s.require_path = 'lib'
+end

data/lib/cannabis.rb

@@ -0,0 +1,34 @@
+require "cannabis/ables"
+require "cannabis/cans"
+require "cannabis/enforcers"
+require "cannabis/exceptions"
+require "cannabis/version"
+
+module Cannabis
+  # Default actions to an empty hash.
+  @actions = {}
+
+  # Returns hash of actions that have been added.
+  #   {:view => :viewable, ...}
+  def self.actions
+    @actions
+  end
+
+  def self.cans
+    actions.keys
+  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
+    Ables.send(:define_method, "#{able}_by?") { |user| true }
+  end
+end
+
+Cannabis.add(:view, :viewable)
+Cannabis.add(:create, :creatable)
+Cannabis.add(:update, :updatable)
+Cannabis.add(:destroy, :destroyable)

data/lib/cannabis/ables.rb

@@ -0,0 +1,6 @@
+module Cannabis
+  # Module that holds all the [method]able_by? methods.
+  module Ables
+
+  end
+end

data/lib/cannabis/cans.rb

@@ -0,0 +1,10 @@
+module Cannabis
+  module Cans
+    def can?(can, resource)
+      return false if resource.nil?
+      able = Cannabis.actions[can]
+      raise Exceptions::InvalidAction if able.nil?
+      resource.send("#{able}_by?", self)
+    end
+  end
+end

data/lib/cannabis/enforcers.rb

@@ -0,0 +1,19 @@
+module Cannabis
+  module Enforcers
+    def self.included(controller)
+      controller.helper_method :can? if controller.respond_to?(:helper_method)
+      controller.hide_action :can? if controller.respond_to?(:hide_action)
+    end
+
+    # delegates the call to current_user
+    def can?(can, resource)
+      current_user.can?(can, resource)
+    end
+
+    private
+
+    def authorize!(can, resource)
+      raise Exceptions::Transgression unless can?(can, resource)
+    end
+  end
+end

data/lib/cannabis/exceptions.rb

@@ -0,0 +1,9 @@
+module Cannabis
+  module Exceptions
+    # Exception that gets raised when permissions are broken for whatever reason.
+    class Transgression < StandardError; end
+
+    # Exception that gets raised when wrong action given.
+    class InvalidAction < StandardError; end
+  end
+end

data/lib/cannabis/version.rb

@@ -0,0 +1,3 @@
+module Cannabis
+  VERSION = "0.2.0"
+end

data/test/ables_test.rb

@@ -0,0 +1,24 @@
+require "test_helper"
+
+class AblesTest < MiniTest::Unit::TestCase
+  def setup
+    @resource = Resource.new
+    @user     = MiniTest::Mock.new
+  end
+
+  def test_default_viewable_by_to_true
+    assert @resource.viewable_by?(@user)
+  end
+
+  def test_default_creatable_by_to_true
+    assert @resource.creatable_by?(@user)
+  end
+
+  def test_default_updatable_by_to_true
+    assert @resource.updatable_by?(@user)
+  end
+
+  def test_default_destroyable_by_to_true
+    assert @resource.destroyable_by?(@user)
+  end
+end

data/test/cannabis_test.rb

@@ -0,0 +1,29 @@
+require "test_helper"
+
+class CannabisTest < MiniTest::Unit::TestCase
+  def test_have_view_action_by_default
+    assert_equal :viewable, Cannabis.actions[:view]
+  end
+
+  def test_have_create_action_by_default
+    assert_equal :creatable, Cannabis.actions[:create]
+  end
+
+  def test_have_update_action_by_default
+    assert_equal :updatable, Cannabis.actions[:update]
+  end
+
+  def test_have_destroy_action_by_default
+    assert_equal :destroyable, Cannabis.actions[:destroy]
+  end
+
+  def test_be_able_to_add_another_action
+    Cannabis.add(:publish, :publishable)
+    assert_equal :publishable, Cannabis.actions[:publish]
+  end
+
+  def test_know_cans
+    Cannabis.add(:publish, :publishable)
+    assert_equal %w(create destroy publish update view), Cannabis.cans.map(&:to_s).sort
+  end
+end

data/test/cans_test.rb

@@ -0,0 +1,83 @@
+require "test_helper"
+
+class CansTest < MiniTest::Unit::TestCase
+  def setup
+    @user = User.new
+  end
+
+  # can_view?
+  def test_is_true_if_resource_is_viewable_by
+    resource = MiniTest::Mock.new
+    resource.expect(:viewable_by?, true, [@user])
+    assert @user.can?(:view, resource)
+    resource.verify
+  end
+
+  def test_is_false_if_resource_is_not_viewable_by
+    resource = MiniTest::Mock.new
+    resource.expect(:viewable_by?, false, [@user])
+    assert ! @user.can?(:view, resource)
+    resource.verify
+  end
+
+  def test_is_false_if_resource_is_nil
+    assert ! @user.can?(:view, nil)
+  end
+
+  # can_create?
+  def test_is_true_if_resource_is_creatable_by
+    resource = MiniTest::Mock.new
+    resource.expect(:creatable_by?, true, [@user])
+    assert @user.can?(:create, resource)
+    resource.verify
+  end
+
+  def test_is_false_if_resource_is_not_creatable_by
+    resource = MiniTest::Mock.new
+    resource.expect(:creatable_by?, false, [@user])
+    assert ! @user.can?(:create, resource)
+    resource.verify
+  end
+
+  def test_is_false_if_resource_is_nil
+    assert ! @user.can?(:create, nil)
+  end
+
+  # can_update?
+  def test_is_true_if_resource_is_updatable_by
+    resource = MiniTest::Mock.new
+    resource.expect(:updatable_by?, true, [@user])
+    assert @user.can?(:update, resource)
+    resource.verify
+  end
+
+  def test_is_false_if_resource_is_not_updatable_by
+    resource = MiniTest::Mock.new
+    resource.expect(:updatable_by?, false, [@user])
+    assert ! @user.can?(:update, resource)
+    resource.verify
+  end
+
+  def test_is_false_if_resource_is_nil
+    assert ! @user.can?(:update, nil)
+  end
+
+  # can_destroy?
+  def test_is_true_if_resource_is_destroyable_by
+    resource = MiniTest::Mock.new
+    resource.expect(:destroyable_by?, true, [@user])
+    assert @user.can?(:destroy, resource)
+    resource.verify
+  end
+
+  def test_is_false_if_resource_is_not_destroyable_by
+    resource = MiniTest::Mock.new
+    resource.expect(:destroyable_by?, false, [@user])
+    assert ! @user.can?(:destroy, resource)
+    resource.verify
+  end
+
+  def test_is_false_if_resource_is_nil
+    assert ! @user.can?(:destroy, nil)
+  end
+end

data/test/enforcers_test.rb

@@ -0,0 +1,33 @@
+require "test_helper"
+
+class EnforcersTest < MiniTest::Unit::TestCase
+  def setup
+    @article = MiniTest::Mock.new
+    @user = MiniTest::Mock.new
+    @controller = Controller.new
+    @controller.article = @article
+    @controller.current_user = @user
+  end
+
+  def test_not_raise_error_if_can
+    @user.expect(:can?, true, [:view, @article])
+    @controller.show
+    @user.verify
+  end
+
+  def test_raises_if_invalid_action_given
+    @controller.current_user = User.new
+    assert_raises(Cannabis::Exceptions::InvalidAction) { @controller.vaporize }
+  end
+
+  def test_raise_error_if_cannot
+    @user.expect(:can?, false, [:view, @article])
+    assert_raises(Cannabis::Exceptions::Transgression) { @controller.show }
+    @user.verify
+  end
+
+  def test_be_able_to_override_can_xx_method
+    @controller.current_user = nil
+    assert_raises(Cannabis::Exceptions::Transgression) { @controller.update }
+  end
+end

data/test/test_helper.rb

@@ -0,0 +1,33 @@
+require "minitest/autorun"
+require "cannabis"
+
+class User
+  include Cannabis::Cans
+end
+
+class Resource
+  include Cannabis::Ables
+end
+
+class Controller
+  include Cannabis::Enforcers
+  attr_accessor :current_user, :article
+
+  # Overriding example
+  def can?(action, resource)
+    return false if action == :update and current_user.nil?
+    super
+  end
+
+  def show
+    authorize!(:view, article)
+  end
+
+  def vaporize
+    authorize!(:vaporize, article)
+  end
+
+  def update
+    authorize!(:update, article)
+  end
+end

metadata

@@ -0,0 +1,97 @@
+--- !ruby/object:Gem::Specification 
+name: cannabis
+version: !ruby/object:Gem::Version 
+  prerelease: false
+  segments: 
+  - 0
+  - 2
+  - 0
+  version: 0.2.0
+platform: ruby
+authors: 
+- "Jakub Ku\xC5\xBAma"
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2010-12-02 00:00:00 +01:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: bundler
+  prerelease: false
+  requirement: &id001 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        segments: 
+        - 1
+        - 0
+        - 0
+        version: 1.0.0
+  type: :development
+  version_requirements: *id001
+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: 
+- qoobaa@gmail.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: []
+
+files: 
+- .gitignore
+- Gemfile
+- LICENSE
+- README.rdoc
+- Rakefile
+- cannabis.gemspec
+- lib/cannabis.rb
+- lib/cannabis/ables.rb
+- lib/cannabis/cans.rb
+- lib/cannabis/enforcers.rb
+- lib/cannabis/exceptions.rb
+- lib/cannabis/version.rb
+- test/ables_test.rb
+- test/cannabis_test.rb
+- test/cans_test.rb
+- test/enforcers_test.rb
+- test/test_helper.rb
+has_rdoc: true
+homepage: http://rubygems.org/gems/cannabis
+licenses: []
+
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      segments: 
+      - 0
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      segments: 
+      - 1
+      - 3
+      - 6
+      version: 1.3.6
+requirements: []
+
+rubyforge_project: cannabis
+rubygems_version: 1.3.7
+signing_key: 
+specification_version: 3
+summary: Simple permissions system
+test_files: []
+