dude_policy 0.1.1 → 0.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ea59aff3b035ce29f5f37fae1b57ff7fa4a7a64626dfde17ff03265877612aad
-  data.tar.gz: 9060298e426595b6b91564a39041101937b50212b9389f5aee1d1a9f931af223
+  metadata.gz: 66aa43b5017af33bec8c323d9cba09e09e7f1537654dc462da4bcd20bc4e63ad
+  data.tar.gz: 7c937f1c730de57477f4062cf289d5d350de7e708f32b753fcde8401c4c8d896
 SHA512:
-  metadata.gz: d302e8aa34fc76f754692d10177c22a66c73d0605cf329877bbe16cec1df6c316225bbfc001c011b93df80d1eef3faf5605acf96464063b8c978b5f662e095ad
-  data.tar.gz: 2d082b2f92376f1230c2b6c637a28a8733bf3c89cbc03e916f68a8128522d087e4b9432e650dad89271e27fd620e9f4adcb20a9101b75e1896decc1fe3dc0769
+  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

@@ -12,7 +12,7 @@ Here are some examples what I mean:
 # 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
 ```
 
+```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
@@ -93,9 +121,12 @@ 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 `app/policy` a directory in your Ruby on Rails app
+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
 
-And create your policy file:
+There create your policy file:
 
 
 ```ruby
@@ -109,7 +140,6 @@ class ArticlePolicy < DudePolicy::BasePolicy
 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`
@@ -119,7 +149,7 @@ You also need to tell your models what role they play
 
 ```ruby
 class Article < ApplicationRecord
-  include DudePolicy::HasPolicy
+  include DudePolicy::HasPolicy  # will add a method `article.policy`
 
   # ...
 end
@@ -128,8 +158,8 @@ end
 
 ```ruby
 class User < ApplicationRecord
-  include DudePolicy::IsADude
-  include DudePolicy::HasPolicy
+  include DudePolicy::IsADude   # will add a method `user.dude`
+  include DudePolicy::HasPolicy # will add a method `user.policy`
 
   # ...
 end
@@ -144,14 +174,14 @@ 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
+> 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
-<td><%= link_to 'Edit', edit_article_path(article) if current_user.dude.able_to_update_article?(article) %></td>
+<%= link_to 'Edit', edit_article_path(@article) if current_user.dude.able_to_update_article?(@article) %>
 ```
 
 #### protect controllers
@@ -174,6 +204,10 @@ class ArticlesController < ApplicationController
 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
@@ -209,8 +243,8 @@ end
 
 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.
+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
@@ -253,6 +287,9 @@ RSpec.describe ArticlePolicy do
 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))
@@ -260,7 +297,7 @@ When it comes to policy tests this can lead to huge security disasters ([full ex
 ##### 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
+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
@@ -337,9 +374,140 @@ end
 > 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)
+```
+
+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_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.1"
+  VERSION = "0.2"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: dude_policy
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: '0.2'
 platform: ruby
 authors:
 - Tomas Valent
-autorequire: 
+autorequire:
 bindir: exe
 cert_chain: []
-date: 2020-04-13 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: []