dude_policy 0.1.0 → 0.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c1b4e1e0aa981141b42efcca848389438987fb99a890d4dfcb2375b9567cf2de
-  data.tar.gz: e65b4dfdce1fbfb939b5e73caaae218c72c1b6e895daecdbd9bb5351ce8fe4ce
+  metadata.gz: 66aa43b5017af33bec8c323d9cba09e09e7f1537654dc462da4bcd20bc4e63ad
+  data.tar.gz: 7c937f1c730de57477f4062cf289d5d350de7e708f32b753fcde8401c4c8d896
 SHA512:
-  metadata.gz: 4a1d56704ffafee188c45bf81937b2663cf5d638ff4441bd11bd8aa780f1ffbc1a0f451f611e728fda2aaf7d40963c9505309e5371e8717a27881a48d8907116
-  data.tar.gz: 281ae48292156284ee965d9554969b4476923d53921f5fcdcd91214756386676bef6c5aceeff392849b8f34a867e634a1b7e01cfca863238fba257c54b5d4145
+  metadata.gz: 9ad555c4f1279d15c6c9dd3a171f4d575f9fa54b142a1e57819e7b1683d25bb5a350aaf669502daf827551642f057e5bd1777438f7db8cb63a3a9676f3982088
+  data.tar.gz: eb12c6da901ddd9ed616f027d023f3e8d2e7dd96dc02a350605d42dbbab6c654acae8fe3cc132058a3e0aff3b8756b2e7510d69dd4a0d260be7d8b42912d4632

data/.travis.yml

@@ -1,6 +1,8 @@
----
 language: ruby
-cache: bundler
 rvm:
-  - 2.6.3
-before_install: gem install bundler -v 2.1.1
+  - 2.5.3
+  - 2.6.5
+  - 2.7.0
+before_install:
+  - yes | gem update --system --force
+  - gem install bundler

data/Gemfile.lock

@@ -1,41 +1,50 @@
 PATH
   remote: .
   specs:
-    dude_policy (0.1.0)
+    dude_policy (0.1.1)
       activesupport (> 4.2)
 
 GEM
   remote: https://rubygems.org/
   specs:
-    activesupport (6.0.2.2)
+    activesupport (7.1.1)
+      base64
+      bigdecimal
       concurrent-ruby (~> 1.0, >= 1.0.2)
-      i18n (>= 0.7, < 2)
-      minitest (~> 5.1)
-      tzinfo (~> 1.1)
-      zeitwerk (~> 2.2)
-    concurrent-ruby (1.1.6)
-    diff-lcs (1.3)
-    i18n (1.8.2)
+      connection_pool (>= 2.2.5)
+      drb
+      i18n (>= 1.6, < 2)
+      minitest (>= 5.1)
+      mutex_m
+      tzinfo (~> 2.0)
+    base64 (0.1.1)
+    bigdecimal (3.1.4)
+    concurrent-ruby (1.2.2)
+    connection_pool (2.4.1)
+    diff-lcs (1.5.0)
+    drb (2.1.1)
+      ruby2_keywords
+    i18n (1.14.1)
       concurrent-ruby (~> 1.0)
-    minitest (5.14.0)
+    minitest (5.20.0)
+    mutex_m (0.1.2)
     rake (12.3.3)
-    rspec (3.9.0)
-      rspec-core (~> 3.9.0)
-      rspec-expectations (~> 3.9.0)
-      rspec-mocks (~> 3.9.0)
-    rspec-core (3.9.1)
-      rspec-support (~> 3.9.1)
-    rspec-expectations (3.9.1)
+    rspec (3.12.0)
+      rspec-core (~> 3.12.0)
+      rspec-expectations (~> 3.12.0)
+      rspec-mocks (~> 3.12.0)
+    rspec-core (3.12.2)
+      rspec-support (~> 3.12.0)
+    rspec-expectations (3.12.3)
       diff-lcs (>= 1.2.0, < 2.0)
-      rspec-support (~> 3.9.0)
-    rspec-mocks (3.9.1)
+      rspec-support (~> 3.12.0)
+    rspec-mocks (3.12.6)
       diff-lcs (>= 1.2.0, < 2.0)
-      rspec-support (~> 3.9.0)
-    rspec-support (3.9.2)
-    thread_safe (0.3.6)
-    tzinfo (1.2.7)
-      thread_safe (~> 0.1)
-    zeitwerk (2.3.0)
+      rspec-support (~> 3.12.0)
+    rspec-support (3.12.1)
+    ruby2_keywords (0.0.5)
+    tzinfo (2.0.6)
+      concurrent-ruby (~> 1.0)
 
 PLATFORMS
   ruby

data/README.md

@@ -5,14 +5,14 @@ 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
+current_user = User.find(432) # e.g. Devise or any other authentication solution
 
 current_user.dude.able_to_edit_article?(article)
 # => true
@@ -22,6 +22,12 @@ current_user.dude.able_to_add_article_review?(article)
 
 current_user.dude.able_to_delete_review?(review)
 # => false
+
+current_user.policy.able_to_view_articles?
+# => true
+
+current_user.policy.able_to_create_articles?
+# => false
 ```
 
 [RSpec](https://rspec.info/) examples:
@@ -34,15 +40,23 @@ RSpec.describe 'short demo' do
   let(:different_user)  { User.create }
 
   # you write tests like this:
-  it { expect(author_user.able_to_edit_article?(article)).to be_truthy }
+  it { expect(author_user.dude.able_to_edit_article?(article)).to be_truthy }
 
   # or you can take advantage of native `be_` RSpec matcher that converts any questionmark ending method to matcher
-  it { expect(author_user).to be_able_to_edit_article(article) }
-  it { expect(different_user).not_to be_able_to_edit_article(article) }
-  it { expect(author_user).not_to be_able_to_add_article_review(article) }
-  it { expect(different_user).to be_able_to_add_article_review(article) }
-  it { expect(author_user).not_to be_able_to_delete_review(article) }
-  it { expect(different_user).to be_able_to_add_article_review(article) }
+  it { expect(author_user.dude).to be_able_to_edit_article(article) }
+  it { expect(different_user.dude).not_to be_able_to_edit_article(article) }
+  it { expect(author_user.dude).not_to be_able_to_add_article_review(article) }
+  it { expect(different_user.dude).to be_able_to_add_article_review(article) }
+  it { expect(author_user.dude).not_to be_able_to_delete_review(article) }
+  it { expect(different_user.dude).to be_able_to_add_article_review(article) }
+  
+  it { expect(author_user.policy).to be_able_to_view_articles? }
+  it { expect(author_user.policy).not_to be_able_to_create_articles? }
+  
+  context "when paid subscription" do 
+    before { author_user.update_attributes(subscription: "paid") }
+    it { expect(author_user.policy).to be_able_to_create_articles? }
+  end
 end
 ```
 
@@ -69,10 +83,24 @@ class ArticlePolicy < DudePolicy::BasePolicy
 end
 ```
 
-Full example in example app
+```ruby
+# app/policy/user_policy.rb
+class UserPolicy < DudePolicy::BasePolicy
+  def able_to_view_articles?; true; end
+  
+  def able_to_create_articles?
+    return true if resource.subscription == "paid"
+    false
+  end
+end
+```
+
+> For more examples pls check the [example app](https://github.com/equivalent/dude_policy_example1)
 
 ## Installation
 
+[![Build Status](https://travis-ci.org/equivalent/dude_policy.svg?branch=master)](https://travis-ci.org/equivalent/dude_policy)
+
 Add this line to your application's Gemfile:
 
 ```ruby
@@ -89,17 +117,397 @@ 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, ...)
+
+Once you have your Authentication solution implemeted and `dude_policy`
+gem installed create a directory `app/policy`  in your Ruby on Rails
+app.
+
+> Note: Since Rails version 4 files in `app/anything` directories are autoloaded. So no additional magic is needed
+
+There 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: 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  # will add a method `article.policy`
+
+  # ...
+end
+```
+
+
+```ruby
+class User < ApplicationRecord
+  include DudePolicy::IsADude   # will add a method `user.dude`
+  include DudePolicy::HasPolicy # will add a method `user.policy`
+
+  # ...
+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](https://github.com/equivalent/dude_policy#philospophy) section of this README to fully understand the flow
+
+This way you will be implement it in your application:
+
+#### protect views
+
+```erb
+<%= link_to 'Edit', edit_article_path(@article) if current_user.dude.able_to_update_article?(@article) %>
+```
+
+#### 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
+```
+
+> gem provides error class `DudePolicy::NotAuthorized` so you
+> can implement [rescue_from](https://apidock.com/rails/ActiveSupport/Rescuable/ClassMethods/rescue_from) logic around not authenticated
+> scenarios. If you have no idea what I'm talking about pls check [example application code](https://github.com/equivalent/dude_policy_example1/blob/master/app/controllers/application_controller.rb)
+
+#### 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 policy methods for both
+roles. If you have 8 roles (admin/moderator/client-manager/external-employee/noob/...) test all policy methods from all eight perspectives.
+
+```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 }
 
-Gem will provide a way how to do `Authorization` (whan logged in user can/cannot do)
+    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
+```
+
+> note the be_*****() matcher is built in RSpec (no special magic in this gem). It's up to you if you prefere `expect(current_user.dude).to be_able_to_update_article(article)` or
+> `expect(current_user.dude.able_to_update_article?(article)).to be_truthy`. Both are valid from point of native RSpec.
+
+
+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 it on the same interface level 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)
+
+
+## Philosophy
+
+I've spent many years and tone of time playing around with different Authorization
+solutions and philosophies. All boils down to fact that [Policy Objects](https://blog.eq8.eu/article/policy-object.html) are the best you can implement.
+
+Problem is that although there are  decent policy object solutions usually
+they are not specific enough on implementation strategy  and teams/teammates still create a
+mess.
+
+So here are some core principles and their benefits:
+
+#### Access policies from model interface methods
+
+By accessing policy from `current_account.dude.able_to_do_something?(resource)` you'll
+overcome multiple challenges:
+
+* less chaos within the team
+* easier for Junior Developers to jump on the project with just basic MVC skill set
+* unified way how to write code and implementation of policies
+* performance - you don't load same objects as they are memoized on `model.policy` level (check source code)
+
+#### Stub policy in tests from perspective of current user  (`current_account.dude`)
+
+This may not be an issue if you are using general login solution gems
+like Devise. But in custom login solutions you may find it difficult to stub underlying resouces in request/controller tests.
+
+By writing everything from user/account perspective `allow(current_account.dude).to receive(...)` your stubs will have less maintenance headache
+
+
+#### Unified naming of policy methods
+
+Your policy objects are just simple Ruby objects so there is no
+restriction to name your methods in in anything you want.
+
+From experience I highly advise you to name the policy methods as
+`able_to_` + `action` + `resources names`
+
+example
+
+```ruby
+class ProductPolicy < DudePolicy::BasePolicy
+  def able_to_delete_product(dude:)
+    #...
+  end
+
+  def able_to_add_product_review_comment(dude:)
+    #...
+  end
+end
+
+class ReviewCommentPolicy < DudePolicy::BasePolicy
+  
+  def able_to_delete_review_comment(dude:)
+    #...
+  end
+end
+```
+
+this way you will be able to take advantage of built in RSpec feature
+and write tests like
+
+`it { expect(current_account.dude).to be_able_to_delete_review_comment(review_comment) }`
+
+
+Important thing is that **we write policy tests on the model method interface** 
+`current_account.dude` because we expect to stub them in
+resource/controller test on the same interface.
+
+> Avoid writing tests from perspective of `resource.policy` or `NameOfMyPolicy.new(current_account)`
+
+#### Nil is a user too
+
+Once you install gem you may notice that you are able to do
+`nil.dude.can_do_anything? => false`  and `nil.policy.can_do_anything? => false` this is a feature not a bug.
+
+Sometimes your application need to deal with `nil` as current_user and
+you don't want to have conditions `if current_user` all over the place.
+That's why gem implements [Null Object Pattern](https://avdi.codes/null-objects-and-falsiness/) on `nil.dude` method that returns `false` all the time
+
+
+#### Nothing new
+
+The gem/lib is really tiny. Only dependency is Rails itself. If you want
+to be vanilla Rails (no external gems) or implement this in other Ruby frameworks (e.g.
+Sinatra) feel free to copy individual files from the `lib` directly
+
+The whole gem is just  [delegator](https://github.com/equivalent/dude_policy/blob/master/lib/dude_policy/dude.rb), [nil extensions](https://github.com/equivalent/dude_policy/blob/master/lib/dude_policy/nil_extension.rb), memoized model methods [1](https://github.com/equivalent/dude_policy/blob/master/lib/dude_policy/has_policy.rb) [2](https://github.com/equivalent/dude_policy/blob/master/lib/dude_policy/is_a_dude.rb) and your [Policy Objects](https://blog.eq8.eu/article/policy-object.html).
+
+`PolicyObject + model method interface == Dude Policy gem`  It's not a rocket science.
+
+**The important part is the philosophy not the gem !**
+
+## How it works
+
+Core of the gem is the delegator that flips dependencies (e.g. `user.dude`)
+
+So you
+define `ArticlePolicy` that works with `article` and you pass `dude` as
+a keyword argument:
+
+```
+class ArticlePolicy < DudePolicy::BasePolicy
+  def able_to_do_something_on_article?(dude:)
+    #...
+    # `dude' represent the user
+    #...
+  end
+end
+```
+
+...by using `include PolicyDude::HasPolicy` your model have access to
+this policy via method `article.policy`
+
+
+The model responsible for representing current user (`User`) is able to
+access the "flip dependency delegator" by using `include PolicyDude::IsADude` (e.g `user.dude`)
+
+This allow us to call method of the argumet resource policy:
+
+```
+user.dude.able_to_do_something_on_article?(article)        ->    article.policy.able_to_do_something_on_article(dude: user)
+user.dude.able_to_do_something_on_somethig_else?(product)  ->    product.policy.able_to_do_something_on_somethig_else(dude: user)
+```
 
-For `Authentication` (is User logged in ?) you will need a different solution / gem (e.g. [Devise](https://github.com/heartcombo/devise), custom login solution, ...)
+So in theory you could access the policy from resource point of view
+`article.policy._____(dude: user)`  but **don't do this** as the philosophy is **you should write your code from perspective of current_user**
+( `user.dude.____(article)` )
 
 
+> `model.policy` is exposed mainly for debugging level & performance (model level memoization)
 
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/equivalent/dude_policy This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/[USERNAME]/dude_policy/blob/master/CODE_OF_CONDUCT.md).
+Bug reports and pull requests are welcome on GitHub at https://github.com/equivalent/dude_policy This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/equivalent/dude_policy/blob/master/CODE_OF_CONDUCT.md).
 
 
 ## License

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/nil_extension.rb

@@ -3,5 +3,9 @@ module DudePolicy
     def dude
       DudePolicy::NilDudePolicy.instance
     end
+
+    def policy
+      DudePolicy::NilDudePolicy.instance
+    end
   end
 end

data/lib/dude_policy/version.rb

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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: dude_policy
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: '0.2'
 platform: ruby
 authors:
 - Tomas Valent
-autorequire: 
+autorequire:
 bindir: exe
 cert_chain: []
-date: 2020-04-12 00:00:00.000000000 Z
+date: 2023-10-22 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -61,7 +61,7 @@ metadata:
   homepage_uri: https://github.com/equivalent/dude_policy
   source_code_uri: https://github.com/equivalent/dude_policy
   changelog_uri: https://github.com/equivalent/dude_policy/blob/master/CHANGELOG.md
-post_install_message: 
+post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -76,8 +76,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.0.3
-signing_key: 
+rubygems_version: 3.3.7
+signing_key:
 specification_version: 4
 summary: Policy objects for Ruby on Rails from perspectvie of current account
 test_files: []