pundit 0.2.1 → 0.2.2

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 6dc0e920a5482e8b695a1cc1afd205fdc7752ad2
+  data.tar.gz: 1354dab74c79e3673cc034ccccea04688e4cb07a
+SHA512:
+  metadata.gz: 0b745c98f6c3aa8376e97f3270ae6f3358339f13eb2fdd57c8adfc0e47f2dee073138866b7df986317d3bd19f6d23c80f7ffb6311a99b97c4f2fe46cb6924e93
+  data.tar.gz: bad3e8cb1c9c8888abf4b93521100ae0122eeebb19dbaaf1790e6beb20189dac55a7e60c017bf525ea5b7091ff9c2a07b3126bd928e6f8d22ded5b0b1f3e9ab2

data/.travis.yml

@@ -1,6 +1,7 @@
 language: ruby
 rvm:
-  - 1.9.2
   - 1.9.3
+  - 2.0.0
+  - 2.1.0
   - jruby-19mode
-  - rbx-19mode
+  - rbx-2.2.3

data/README.md

@@ -1,6 +1,7 @@
 # Pundit
 
 [![Build Status](https://secure.travis-ci.org/elabs/pundit.png?branch=master)](https://travis-ci.org/elabs/pundit)
+[![Code Climate](https://codeclimate.com/github/elabs/pundit.png)](https://codeclimate.com/github/elabs/pundit)
 
 Pundit provides a set of helpers which guide you in leveraging regular Ruby
 classes and object oriented design patterns to build a simple, robust and
@@ -28,10 +29,14 @@ with some useful defaults for you:
 rails g pundit:install
 ```
 
+After generating your application policy, restart the Rails server so that Rails
+can pick up any classes in the new `app/policies/` directory.
+
 ## Policies
 
 Pundit is focused around the notion of policy classes. We suggest that you put
-these classes in `app/policies`. This is a simple example:
+these classes in `app/policies`. This is a simple example that allows updating
+a post if the user is an admin, or if the post is unpublished:
 
 ``` ruby
 class PostPolicy
@@ -42,18 +47,18 @@ class PostPolicy
     @post = post
   end
 
-  def create?
+  def update?
     user.admin? or not post.published?
   end
 end
 ```
 
 As you can see, this is just a plain Ruby class. As a convenience, we can inherit
-from Struct:
+from Struct or use Struct.new to define the policy class:
 
 ``` ruby
-class PostPolicy < Struct.new(:user, :post)
-  def create?
+PostPolicy = Struct.new(:user, :post) do
+  def update?
     user.admin? or not post.published?
   end
 end
@@ -68,7 +73,7 @@ Pundit makes the following assumptions about this class:
 - The second argument is some kind of model object, whose authorization
   you want to check. This does not need to be an ActiveRecord or even
   an ActiveModel object, it can be anything really.
-- The class implements some kind of query method, in this case `create?`.
+- The class implements some kind of query method, in this case `update?`.
   Usually, this will map to the name of a particular controller action.
 
 That's it really.
@@ -77,13 +82,13 @@ Supposing that you have an instance of class `Post`, Pundit now lets you do
 this in your controller:
 
 ``` ruby
-def create
-  @post = Post.new(params[:post])
+def update
+  @post = Post.find(params[:id])
   authorize @post
-  if @post.save
+  if @post.update(post_params)
     redirect_to @post
   else
-    render :new
+    render :edit
   end
 end
 ```
@@ -91,11 +96,11 @@ end
 The authorize method automatically infers that `Post` will have a matching
 `PostPolicy` class, and instantiates this class, handing in the current user
 and the given record. It then infers from the action name, that it should call
-`create?` on this instance of the policy. In this case, you can imagine that
+`update?` on this instance of the policy. In this case, you can imagine that
 `authorize` would have done something like this:
 
 ``` ruby
-raise "not authorized" unless PostPolicy.new(current_user, @post).create?
+raise "not authorized" unless PostPolicy.new(current_user, @post).update?
 ```
 
 You can pass a second argument to `authorize` if the name of the permission you
@@ -115,8 +120,8 @@ method in both the view and controller. This is especially useful for
 conditionally showing links or buttons in the view:
 
 ``` erb
-<% if policy(@post).create? %>
-  <%= link_to "New post", new_post_path %>
+<% if policy(@post).update? %>
+  <%= link_to "Edit post", edit_post_path(@post) %>
 <% end %>
 ```
 
@@ -124,16 +129,16 @@ conditionally showing links or buttons in the view:
 
 Pundit adds a method called `verify_authorized` to your controllers. This
 method will raise an exception if `authorize` has not yet been called. You
-should run this method in an `after_filter` to ensure that you haven't
+should run this method in an `after_action` to ensure that you haven't
 forgotten to authorize the action. For example:
 
 ``` ruby
 class ApplicationController < ActionController::Base
-  after_filter :verify_authorized, :except => :index
+  after_action :verify_authorized, :except => :index
 end
 ```
 
-Likewise, pundit also adds `verify_policy_scoped` to your controller.  This
+Likewise, Pundit also adds `verify_policy_scoped` to your controller.  This
 will raise an exception in the vein of `verify_authorized`.  However it tracks
 if `policy_scoped` is used instead of `authorize`.  This is mostly useful for
 controller actions like `index` which find collections with a scope and don't
@@ -141,7 +146,7 @@ authorize individual instances.
 
 ``` ruby
 class ApplicationController < ActionController::Base
-  after_filter :verify_policy_scoped, :only => :index
+  after_action :verify_policy_scoped, :only => :index
 end
 ```
 
@@ -152,18 +157,18 @@ particular user has access to. When using Pundit, you are expected to
 define a class called a policy scope. It can look something like this:
 
 ``` ruby
-class PostPolicy < Struct.new(:user, :post)
-  class Scope < Struct.new(:user, :scope)
+PostPolicy = Struct.new(:user, :post) do
+  self::Scope = Struct.new(:user, :scope) do
     def resolve
       if user.admin?
-        scope
+        scope.all
       else
         scope.where(:published => true)
       end
     end
   end
 
-  def create?
+  def update?
     user.admin? or not post.published?
   end
 end
@@ -215,7 +220,7 @@ class, instead of letting Pundit infer it. This can be done like so:
 ``` ruby
 class Post
   def self.policy_class
-    PostablePolicyClass
+    PostablePolicy
   end
 end
 ```
@@ -264,6 +269,26 @@ class ApplicationPolicy
 end
 ```
 
+## Rescuing a denied Authorization in Rails
+
+Pundit raises a `Pundit::NotAuthorizedError` you can [rescue_from](http://guides.rubyonrails.org/action_controller_overview.html#rescue-from) in your `ApplicationController`. You can customize the `user_not_authorized` method in every controller.
+
+```ruby
+class ApplicationController < ActionController::Base
+  protect_from_forgery
+  include Pundit
+
+  rescue_from Pundit::NotAuthorizedError, with: :user_not_authorized
+
+  private
+
+  def user_not_authorized
+    flash[:error] = "You are not authorized to perform this action."
+    redirect_to request.headers["Referer"] || root_path
+  end
+end
+```
+
 ## Manually retrieving policies and scopes
 
 Sometimes you want to retrieve a policy for a record outside the controller or
@@ -282,40 +307,62 @@ Pundit.policy_scope(user, Post)
 The bang methods will raise an exception if the policy does not exist, whereas
 those without the bang will return nil.
 
-## Pundit and strong_parameters
+## Customize Pundit user
 
-In Rails 3 using [strong_parameters](https://github.com/rails/strong_parameters)
-or a standard Rails 4 setup, mass-assignment protection is handled in the controller. 
-Pundit helps you permit different attributes for different users.
+In some cases your controller might not have access to `current_user`, or your
+`current_user` is not the method that should be invoked by Pundit. Simply
+define a method in your controller called `pundit_user`.
 
 ```ruby
-class PostPolicy < Struct.new(:user, :post)
+def pundit_user
+  User.find_by_other_means
+end
+```
+
+## Strong parameters
+
+In Rails 4 (or Rails 3.2 with the
+[strong_parameters](https://github.com/rails/strong_parameters) gem),
+mass-assignment protection is handled in the controller.
+Pundit helps you permit different users to set different attributes. Don't
+forget to provide your policy an instance of object or a class so correct
+permissions could be loaded.
+
+```ruby
+# app/policies/post_policy.rb
+class PostPolicy < ApplicationPolicy
   def permitted_attributes
     if user.admin? || user.owner_of?(post)
-      [:title, :body]
+      [:title, :body, :tag_list]
     else
-      [:body]
+      [:tag_list]
     end
   end
 end
 
+# app/controllers/posts_controller.rb
 class PostsController < ApplicationController
   def update
-    # ...
-    if @post.update_attributes(post_attributes)
-    # ...
+    @post = Post.find(params[:id])
+    if @post.update(post_params)
+      redirect_to @post
+    else
+      render :edit
+    end
   end
 
   private
 
-  def post_attributes
-    params.require(:post).permit(policy(@post).permitted_attributes)
+  def post_params
+    params.require(:post).permit(*policy(@post || Post).permitted_attributes)
   end
 end
 ```
 
 ## RSpec
 
+### Policy Specs
+
 Pundit includes a mini-DSL for writing expressive tests for your policies in RSpec.
 Require `pundit/rspec` in your `spec_helper.rb`:
 
@@ -329,22 +376,55 @@ Then put your policy specs in `spec/policies`, and make them look somewhat like
 describe PostPolicy do
   subject { PostPolicy }
 
-  permissions :create? do
+  permissions :update? do
     it "denies access if post is published" do
-      should_not permit(User.new(:admin => false), Post.new(:published => true))
+      expect(subject).not_to permit(User.new(:admin => false), Post.new(:published => true))
     end
 
     it "grants access if post is published and user is an admin" do
-      should permit(User.new(:admin => true), Post.new(:published => true))
+      expect(subject).to permit(User.new(:admin => true), Post.new(:published => true))
     end
 
     it "grants access if post is unpublished" do
-      should permit(User.new(:admin => false), Post.new(:published => false))
+      expect(subject).to permit(User.new(:admin => false), Post.new(:published => false))
     end
   end
 end
 ```
 
+An alternative approach to Pundit policy specs is scoping them to a user context as outlined in this
+[excellent post](http://thunderboltlabs.com/blog/2013/03/27/testing-pundit-policies-with-rspec/).
+
+### View Specs
+
+When writing view specs, you'll notice that the policy helper is not available
+and views under test that use it will fail. Thankfully, it's very easy to stub
+out the policy to have it return whatever is appropriate for the spec.
+
+``` ruby
+describe "users/show" do
+  before(:each) do
+    user = assign(:user, build_stubbed(:user))
+    controller.stub(:current_user).and_return user
+  end
+
+  it "renders the destroy action" do
+    allow(view).to receive(:policy).and_return double(edit?: false, destroy?: true)
+
+    render
+    expect(rendered).to match 'Destroy'
+  end
+end
+```
+
+This technique enables easy unit testing of tricky conditionaly view logic
+based on what is or is not authorized.
+
+# External Resources
+
+- [Migrating to Pundit from CanCan](http://blog.carbonfive.com/2013/10/21/migrating-to-pundit-from-cancan/)
+- [Testing Pundit Policies with RSpec](http://thunderboltlabs.com/blog/2013/03/27/testing-pundit-policies-with-rspec/)
+
 # License
 
 Licensed under the MIT license, see the separate LICENSE.txt file.

data/Rakefile

@@ -1,4 +1,5 @@
 require 'rubygems'
+require 'bundler/gem_tasks'
 require 'rspec/core/rake_task'
 require 'yard'
 

data/lib/pundit.rb

@@ -12,8 +12,8 @@ module Pundit
 
   class << self
     def policy_scope(user, scope)
-      policy = PolicyFinder.new(scope).scope
-      policy.new(user, scope).resolve if policy
+      policy_scope = PolicyFinder.new(scope).scope
+      policy_scope.new(user, scope).resolve if policy_scope
     end
 
     def policy_scope!(user, scope)
@@ -21,8 +21,8 @@ module Pundit
     end
 
     def policy(user, record)
-      scope = PolicyFinder.new(record).policy
-      scope.new(user, record) if scope
+      policy = PolicyFinder.new(record).policy
+      policy.new(user, record) if policy
     end
 
     def policy!(user, record)
@@ -34,11 +34,13 @@ module Pundit
     if respond_to?(:helper_method)
       helper_method :policy_scope
       helper_method :policy
+      helper_method :pundit_user
     end
     if respond_to?(:hide_action)
       hide_action :authorize
       hide_action :verify_authorized
       hide_action :verify_policy_scoped
+      hide_action :pundit_user
     end
   end
 
@@ -61,10 +63,16 @@ module Pundit
 
   def policy_scope(scope)
     @_policy_scoped = true
-    Pundit.policy_scope!(current_user, scope)
+    @policy_scope or Pundit.policy_scope!(pundit_user, scope)
   end
+  attr_writer :policy_scope
 
   def policy(record)
-    Pundit.policy!(current_user, record)
+    @policy or Pundit.policy!(pundit_user, record)
+  end
+  attr_writer :policy
+
+  def pundit_user
+    current_user
   end
 end

data/lib/pundit/rspec.rb

@@ -4,10 +4,14 @@ module Pundit
       extend ::RSpec::Matchers::DSL
 
       matcher :permit do |user, record|
-        match do |policy|
+        match_for_should do |policy|
           permissions.all? { |permission| policy.new(user, record).public_send(permission) }
         end
 
+        match_for_should_not do |policy|
+          permissions.none? { |permission| policy.new(user, record).public_send(permission) }
+        end
+
         failure_message_for_should do |policy|
           "Expected #{policy} to grant #{permissions.to_sentence} on #{record} but it didn't"
         end

data/lib/pundit/version.rb

@@ -1,3 +1,3 @@
 module Pundit
-  VERSION = "0.2.1"
+  VERSION = "0.2.2"
 end

data/pundit.gemspec

@@ -10,7 +10,8 @@ Gem::Specification.new do |gem|
   gem.email         = ["jonas.nicklas@gmail.com", "dev@elabs.se"]
   gem.description   = %q{Object oriented authorization for Rails applications}
   gem.summary       = %q{OO authorization for Rails}
-  gem.homepage      = "http://github.com/elabs/pundit"
+  gem.homepage      = "https://github.com/elabs/pundit"
+  gem.license       = "MIT"
 
   gem.files         = `git ls-files`.split($/)
   gem.executables   = gem.files.grep(%r{^bin/}).map{ |f| File.basename(f) }
@@ -19,6 +20,7 @@ Gem::Specification.new do |gem|
 
   gem.add_dependency "activesupport", ">= 3.0.0"
   gem.add_development_dependency "activerecord", ">= 3.0.0"
+  gem.add_development_dependency "bundler", "~> 1.3"
   gem.add_development_dependency "rspec", "~>2.0"
   gem.add_development_dependency "pry"
   gem.add_development_dependency "rake"

data/spec/pundit_spec.rb

@@ -56,11 +56,11 @@ class ArticleTag
 end
 
 describe Pundit do
-  let(:user) { stub }
+  let(:user) { double }
   let(:post) { Post.new(user) }
   let(:comment) { Comment.new }
   let(:article) { Article.new }
-  let(:controller) { stub(:current_user => user, :params => { :action => "update" }).tap { |c| c.extend(Pundit) } }
+  let(:controller) { double(:current_user => user, :params => { :action => "update" }).tap { |c| c.extend(Pundit) } }
   let(:artificial_blog) { ArtificialBlog.new }
   let(:article_tag) { ArticleTag.new }
 
@@ -226,6 +226,12 @@ describe Pundit do
     end
   end
 
+  describe "#pundit_user" do
+    it 'returns the same thing as current_user' do
+      controller.pundit_user.should eq controller.current_user
+    end
+  end
+
   describe ".policy" do
     it "returns an instantiated policy" do
       policy = controller.policy(post)
@@ -236,6 +242,13 @@ describe Pundit do
     it "throws an exception if the given policy can't be found" do
       expect { controller.policy(article) }.to raise_error(Pundit::NotDefinedError)
     end
+
+    it "allows policy to be injected" do
+      new_policy = OpenStruct.new
+      controller.policy = new_policy
+
+      controller.policy(post).should == new_policy
+    end
   end
 
   describe ".policy_scope" do
@@ -246,5 +259,12 @@ describe Pundit do
     it "throws an exception if the given policy can't be found" do
       expect { controller.policy_scope(Article) }.to raise_error(Pundit::NotDefinedError)
     end
+
+    it "allows policy_scope to be injected" do
+      new_scope = OpenStruct.new
+      controller.policy_scope = new_scope
+
+      controller.policy_scope(post).should == new_scope
+    end
   end
 end

metadata

@@ -1,8 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: pundit
 version: !ruby/object:Gem::Version
-  version: 0.2.1
-  prerelease: 
+  version: 0.2.2
 platform: ruby
 authors:
 - Jonas Nicklas
@@ -10,44 +9,53 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-06-18 00:00:00.000000000 Z
+date: 2014-02-07 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
   requirement: !ruby/object:Gem::Requirement
-    none: false
     requirements:
-    - - ! '>='
+    - - '>='
       - !ruby/object:Gem::Version
         version: 3.0.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
-    none: false
     requirements:
-    - - ! '>='
+    - - '>='
       - !ruby/object:Gem::Version
         version: 3.0.0
 - !ruby/object:Gem::Dependency
   name: activerecord
   requirement: !ruby/object:Gem::Requirement
-    none: false
     requirements:
-    - - ! '>='
+    - - '>='
       - !ruby/object:Gem::Version
         version: 3.0.0
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
-    none: false
     requirements:
-    - - ! '>='
+    - - '>='
       - !ruby/object:Gem::Version
         version: 3.0.0
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.3'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.3'
 - !ruby/object:Gem::Dependency
   name: rspec
   requirement: !ruby/object:Gem::Requirement
-    none: false
     requirements:
     - - ~>
       - !ruby/object:Gem::Version
@@ -55,7 +63,6 @@ dependencies:
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
-    none: false
     requirements:
     - - ~>
       - !ruby/object:Gem::Version
@@ -63,49 +70,43 @@ dependencies:
 - !ruby/object:Gem::Dependency
   name: pry
   requirement: !ruby/object:Gem::Requirement
-    none: false
     requirements:
-    - - ! '>='
+    - - '>='
       - !ruby/object:Gem::Version
         version: '0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
-    none: false
     requirements:
-    - - ! '>='
+    - - '>='
       - !ruby/object:Gem::Version
         version: '0'
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement
-    none: false
     requirements:
-    - - ! '>='
+    - - '>='
       - !ruby/object:Gem::Version
         version: '0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
-    none: false
     requirements:
-    - - ! '>='
+    - - '>='
       - !ruby/object:Gem::Version
         version: '0'
 - !ruby/object:Gem::Dependency
   name: yard
   requirement: !ruby/object:Gem::Requirement
-    none: false
     requirements:
-    - - ! '>='
+    - - '>='
       - !ruby/object:Gem::Version
         version: '0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
-    none: false
     requirements:
-    - - ! '>='
+    - - '>='
       - !ruby/object:Gem::Version
         version: '0'
 description: Object oriented authorization for Rails applications
@@ -134,29 +135,29 @@ files:
 - lib/pundit/version.rb
 - pundit.gemspec
 - spec/pundit_spec.rb
-homepage: http://github.com/elabs/pundit
-licenses: []
+homepage: https://github.com/elabs/pundit
+licenses:
+- MIT
+metadata: {}
 post_install_message: 
 rdoc_options: []
 require_paths:
 - lib
 required_ruby_version: !ruby/object:Gem::Requirement
-  none: false
   requirements:
-  - - ! '>='
+  - - '>='
     - !ruby/object:Gem::Version
       version: '0'
 required_rubygems_version: !ruby/object:Gem::Requirement
-  none: false
   requirements:
-  - - ! '>='
+  - - '>='
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 1.8.25
+rubygems_version: 2.0.3
 signing_key: 
-specification_version: 3
+specification_version: 4
 summary: OO authorization for Rails
 test_files:
 - spec/pundit_spec.rb