dude_policy 0.1.0 → 0.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c1b4e1e0aa981141b42efcca848389438987fb99a890d4dfcb2375b9567cf2de
-  data.tar.gz: e65b4dfdce1fbfb939b5e73caaae218c72c1b6e895daecdbd9bb5351ce8fe4ce
+  metadata.gz: ea59aff3b035ce29f5f37fae1b57ff7fa4a7a64626dfde17ff03265877612aad
+  data.tar.gz: 9060298e426595b6b91564a39041101937b50212b9389f5aee1d1a9f931af223
 SHA512:
-  metadata.gz: 4a1d56704ffafee188c45bf81937b2663cf5d638ff4441bd11bd8aa780f1ffbc1a0f451f611e728fda2aaf7d40963c9505309e5371e8717a27881a48d8907116
-  data.tar.gz: 281ae48292156284ee965d9554969b4476923d53921f5fcdcd91214756386676bef6c5aceeff392849b8f34a867e634a1b7e01cfca863238fba257c54b5d4145
+  metadata.gz: d302e8aa34fc76f754692d10177c22a66c73d0605cf329877bbe16cec1df6c316225bbfc001c011b93df80d1eef3faf5605acf96464063b8c978b5f662e095ad
+  data.tar.gz: 2d082b2f92376f1230c2b6c637a28a8733bf3c89cbc03e916f68a8128522d087e4b9432e650dad89271e27fd620e9f4adcb20a9101b75e1896decc1fe3dc0769

data/README.md

@@ -5,11 +5,11 @@ from point of view of current_user/current_account (the **dude**)
 
 ![](https://triblive.com/wp-content/uploads/2019/01/673808_web1_gtr-liv-goldenglobes-121718.jpg)
 
-Here are some examples what we mean:
+Here are some examples what I mean:
 
 
 ```ruby
-# irb
+# rails console
 article = Article.find(123)
 review  = Review.find(123)
 current_user = User.find(432) # e.g. Devise on any authentication solution
@@ -69,7 +69,7 @@ class ArticlePolicy < DudePolicy::BasePolicy
 end
 ```
 
-Full example in example app
+> For more examples pls check the [example app](https://github.com/equivalent/dude_policy_example1)
 
 ## Installation
 
@@ -89,13 +89,253 @@ Or install it yourself as:
 
 ## Usage
 
-### Gem is responsible for Authorization
+Gem is responsible for **Authorization** (what a logged in user can/cannot do)
+For **Authentication** (is User logged in ?) you will need a different solution / gem (e.g. [Devise](https://github.com/heartcombo/devise), custom login solution, ...)
 
-Gem will provide a way how to do `Authorization` (whan logged in user can/cannot do)
+Once you have your Authentication solution implemeted and `dude_policy`
+gem installed create `app/policy` a directory in your Ruby on Rails app
 
-For `Authentication` (is User logged in ?) you will need a different solution / gem (e.g. [Devise](https://github.com/heartcombo/devise), custom login solution, ...)
+And create your policy file:
 
 
+```ruby
+# app/policy/article_policy
+class ArticlePolicy < DudePolicy::BasePolicy
+  def able_to_update_article?(dude:)
+    return true if dude.admin?
+    return true if dude == resource.author
+    false
+  end
+end
+```
+
+> Note: Since Rails version 4 files in `app/anything` directories are autoloaded. So no additional magic is needed
+
+> Note: Policy should be name as the model suffixed with word "Policy". So if
+> you have `ConstructiveComment` model your policy should be named `ConstructiveCommentPolicy` located in `app/policy/constructive_comment_policy.rb`
+
+
+You also need to tell your models what role they play
+
+```ruby
+class Article < ApplicationRecord
+  include DudePolicy::HasPolicy
+
+  # ...
+end
+```
+
+
+```ruby
+class User < ApplicationRecord
+  include DudePolicy::IsADude
+  include DudePolicy::HasPolicy
+
+  # ...
+end
+```
+
+This way you will be able to call:
+
+```ruby
+user = User.find(123)
+user.dude.able_to_update_article?(@article)
+```
+
+> Note: same model can include both `DudePolicy::IsADude` and `DudePolicy::IsADude` but don't have to.
+
+> Note: please be sure to check the "Philosophy" section of this README to fully understand the flow
+
+This way you will be implement it in your application:
+
+#### protect views
+
+```erb
+<td><%= link_to 'Edit', edit_article_path(article) if current_user.dude.able_to_update_article?(article) %></td>
+```
+
+#### protect controllers
+
+```ruby
+# app/controllers/articles_controller.rb
+class ArticlesController < ApplicationController
+  # ...
+
+  def update
+    @article = Article.find_by(params[:id])
+    raise(DudePolicy::NotAuthorized) unless current_user.dude.able_to_update_article?(@article)
+
+    if @article.update(article_params)
+      redirect_to @article, notice: 'Article was successfully updated.'
+    else
+      render :edit
+    end
+  end
+end
+```
+
+#### protect business logic
+
+There are cases when you want to protect your business logic that is
+beyond MVC level. For example:
+
+```ruby
+# app/polcy/user_policy.rb
+class UserPolicy < DudePolicy::BasePolicy
+  def able_to_see_user_full_name?(dude:)
+    return true if dude.admin?
+    return true if dude == resource
+    false
+  end
+end
+
+
+# app/helpers/application_helper.rb
+def author_name(user)
+  return unless user
+  if current_user.dude.able_to_see_user_full_name?(user)
+    user.name
+  else
+    first_letter = user.name[0]
+    "#{first_letter}."
+  end
+end
+```
+
+#### RSpec  testing
+
+
+##### policy test
+
+You should be writing tests from perspective of current_user / current_account (the dude) and what roles they play.
+
+If you have 2 roles (admin/regular user) test all policiese for every
+role. If you have 8 roles (admin/moderator/client-manager/external-employee/noob/...) test every method from their perspective.
+
+```ruby
+# spec/policy/article_policy_spec.rb
+require 'rails_helper'
+RSpec.describe ArticlePolicy do
+  let(:article) { create :article, author: author }
+  let(:author)  { create :user }
+
+  context 'when nil user' do
+    let(:current_user) { nil }
+
+    it { expect(current_user.dude).not_to be_able_to_update_article(article) }
+    it { expect(current_user.dude).not_to be_able_to_delete_article(article) }
+  end
+
+  context 'when regular_user' do
+    let(:current_user) { create :user }
+
+    it { expect(current_user.dude).not_to be_able_to_update_article(article) }
+    it { expect(current_user.dude).not_to be_able_to_delete_article(article) }
+
+    context ' is author of article' do
+      let(:author) { current_user }
+      it { expect(current_user.dude).to be_able_to_update_article(article) }
+      it { expect(current_user.dude).to be_able_to_delete_article(article) }
+    end
+  end
+
+  context 'when admin' do
+    let(:current_user) { create :user, admin: true }
+    it { expect(current_user.dude).to be_able_to_update_article(article) }
+    it { expect(current_user.dude).not_to be_able_to_delete_article(article) }
+
+    context ' is author of article' do
+      let(:author) { current_user }
+      it { expect(current_user.dude).to be_able_to_update_article(article) }
+      it { expect(current_user.dude).to be_able_to_update_article(article) }
+    end
+  end
+end
+```
+
+
+Do yourself a favor and **don't write low level Unit Tests** like `expect(ArticlePolicy.new(article)).to be_able_to_update_article(dude: current_user)` !
+When it comes to policy tests this can lead to huge security disasters ([full explanation](https://blog.eq8.eu/assets/2019/unit-test.jpg))
+
+##### request test
+
+Now that we tested policy for every possible role of a user we can stub
+the policy. We want to do in on same interface as we tested our policies
+that means `allow(current_user.dude).to receive(:able_to_update_article?).and_return(true)`
+
+> note: simmilar approach we would apply if you write controller RSpec test
+
+
+```ruby
+require 'rails_helper'
+RSpec.describe "Articles", type: :request do
+  let(:article) { create :article }
+
+  describe "put /articles/xxxx" do
+    def trigger_update
+      if current_user
+        # devise login
+        sign_in current_user
+
+        # policies are tested with `spec/policy/article_spec.rb so we can stub
+        allow(current_user.dude)
+          .to receive(:able_to_update_article?)
+          .with(article)
+          .and_return(authorized)
+      end
+
+      put article_path(article), params: {format: :html, article: { title: 'cat' }}
+      article.reload
+    end
+
+    context 'when not authenticated' do
+      let(:current_user) { nil }
+
+      it { expect { trigger_update }.not_to change { article.title } }
+      it do
+        trigger_update
+        expect(response.status).to eq 302 # redirect by update
+        follow_redirect!
+        expect(response.body).to include('You need to sign in or sign up before continuing.')
+      end
+    end
+
+    context 'when authenticated' do
+      let(:current_user) { create :user }
+
+      context 'when not authorized' do
+        let(:authorized) { false }
+
+        it { expect { trigger_update }.not_to change { article.title } }
+        it do
+          trigger_update
+          expect(response.status).to eq 302 # redirect to root_path by `authenticate!` method is ApplicationController
+          follow_redirect!
+          expect(response.body).to include('Sorry current user is not authorized to perform this action')
+        end
+      end
+
+      context 'when authorized' do
+        let(:authorized) { true }
+
+        it { expect { trigger_update }.to change { article.title }.from('interesting article').to('cat') }
+        it do
+          trigger_update
+          expect(response.status).to eq 302
+          follow_redirect!
+          expect(response.body).to include('Article was successfully updated.')
+        end
+      end
+    end
+  end
+end
+```
+
+
+#### More examples
+
+> For more examples pls check the [example app](https://github.com/equivalent/dude_policy_example1)
+
 
 ## Contributing
 

data/lib/dude_policy/nil_dude_policy.rb

@@ -6,6 +6,12 @@ module DudePolicy
       false
     end
 
+    # test frameworks like RSpec test first if method responds to before calling it
+    # as this is a NullObject delegator it responds to any method call
+    def respond_to?(*)
+      true
+    end
+
     def inspect
       "<#DudePolicy##{object_id} on nil>"
     end

data/lib/dude_policy/version.rb

@@ -1,3 +1,3 @@
 module DudePolicy
-  VERSION = "0.1.0"
+  VERSION = "0.1.1"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: dude_policy
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.1
 platform: ruby
 authors:
 - Tomas Valent
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2020-04-12 00:00:00.000000000 Z
+date: 2020-04-13 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport