bullet_train-roles 1.2.26 → 1.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9625ec4f32bd16e26eada29e5ce0b5729f2f617168e3253114faa7967b5205d9
-  data.tar.gz: 3b4efafb09fedbfdda9eb3f53f107a8d7a4707a0f73837736bd31e6f4a1ee53d
+  metadata.gz: 3f8c33aae9d0e533cc182a9d259bc4ac2ee4b112adbc9459d11fcefcb42dd887
+  data.tar.gz: 88657dc68c22e4a9772e4609707e31f551249c078d940f1865b3b84f0fda11d9
 SHA512:
-  metadata.gz: 79a6fdc2eba96b047abdbfe98bd9f8c6f715be305c3ceb4ef08fcecef6aae24b7a8274a1198c353e01f2e98a5b2eb9d5e61d24127a8b0a20a080e674e2dd027b
-  data.tar.gz: 8a4c80d42f06b40ef084db983e97141a971cb9222ba96ca29dcbc025daef3160df669d9744f6950f699ce12e1b03e5dd4b67400e0982865fd29456432ab1dd5d
+  metadata.gz: 2d74e06824a7f9888c93cba13d52e2412cb0b5a99025c8182038850f1e64205412fd60b2712e35f595958ffcf164a420749494db8eecf6422d19f686913543b5
+  data.tar.gz: 84a7524e8de44d2d34a5cd547d44da44081d052f168110c344a40188446a151bdd6c2e888bd32a170d5a8282a2cfaec1c63ca5a5c2c91c3361b1db937227519d

data/Gemfile.lock

@@ -9,7 +9,7 @@ GIT
 PATH
   remote: .
   specs:
-    bullet_train-roles (1.2.26)
+    bullet_train-roles (1.3.0)
       active_hash
       activesupport
       cancancan

data/README.md

@@ -58,7 +58,7 @@ The provided `Role` model is backed by a Yaml configuration in `config/models/ro
 
 To help explain this configuration and its options, we'll provide the following hypothetical example:
 
-```
+```yaml
 default:
   models:
     Project: read
@@ -92,6 +92,8 @@ Here's a breakdown of the structure of the configuration file:
  - `manageable_roles` provides a list of roles that can be assigned to other users by members that have the role being defined.
  - `includes` provides a list of other roles whose permissions should also be made available to members with the role being defined.
  - `manage`, `read`, etc. are all CanCanCan-defined actions that can be granted.
+  - `crud` is a special value that we substitute for the 4 CRUD actions - create, read, update and destroy.
+  This is instead of `manage` which covers all actions - 4 CRUD actions _and_ any extra actions the controller may respond to
 
 The following things are true given the example configuration above:
 
@@ -111,7 +113,7 @@ The following things are true given the example configuration above:
 
 You can also grant more granular permissions by supplying a list of the specific actions per resource, like so:
 
-```
+```yaml
 editor:
   models:
     project:
@@ -123,7 +125,7 @@ editor:
 
 All of these definitions are interpreted and translated into CanCanCan directives when we invoke the following Bullet Train helper in `app/models/ability.rb`:
 
-```
+```ruby
 permit user, through: :memberships, parent: :team
 ```
 
@@ -136,7 +138,7 @@ In the example above:
 
 To illustrate the flexibility of this approach, consider that you may want to grant non-administrative team members different permissions for different `Project` objects on a `Team`. In that case, `permit` actually allows us to re-use the same role definitions to assign permissions that are scoped by a specific resource, like this:
 
-```
+```ruby
 permit user, through: :projects_collaborators, parent: :project
 ```
 
@@ -149,7 +151,7 @@ In some situations, you don't want all roles to be available to all Grant Models
 
 By default all Grant Models will show all roles as options.  If you want to limit the roles available to a model, use the `roles_only` class method:
 
-```
+```ruby
 class Membership < ApplicationRecord
   include Roles::Support
   roles_only :admin, :editor, :reader # Add this line to restrict the Membership model to only these roles
@@ -158,7 +160,7 @@ end
 
 To access the array of all roles available for a particular model, use the `assignable_roles` class method.  For example, in your Membership form, you probably _only_ want to show the assignable_roles as options.  Your view could look like this:
 
-```
+```erb
 <% Membership.assignable_roles.each do |role| %>
   <% if role.manageable_by?(current_membership.roles) %>
     <!-- View component for showing a role option. Probably a checkbox -->
@@ -166,13 +168,72 @@ To access the array of all roles available for a particular model, use the `assi
 <% end %>
 ```
 
+## Checking user permissions
+
+Generally the CanCanCan helper method (`account_load_and_authorize_resource`) at the top of each controller will handle checking user permissions and will only load resources appropriate for the current user.
+
+However, you may also want to check if a user can perform a specific action.  For example, in a view you may want to only show the edit button if the current user has permissions to edit the object.  For this, you can use regular CanCanCan helpers.  For example:
+
+```
+<%= link_to "Edit", [:account, @document] if can? :edit, @document %>
+```
+
+Sometimes, you might want to check for the presence of a specific role. We provide a helper to check for the admin role:
+```
+@membership.admin?
+```
+
+For all other roles, you can check for their presence like this:
+
+```
+@membership.roles.include?(Role.find("developer"))
+```
+
+However, when you do that, you're only checking the roles that have been directly assigned to that membership.
+
+Imagine a scenario like this:
+```
+# roles.yml
+admin:
+  includes:
+    - editor
+    - billing
+
+# somewhere else in your app:
+@membership.roles << Role.admin
+@membership.roles.include?(Role.find("editor"))
+=> false
+```
+
+While that's technically correct that the user doesn't have the editor role, we probably want that to return true if we're checking what the user can and can't do.  For this situation, we really want to check if the user can perform a role rather than if they've had that role assigned to them.
+
+```
+# roles.yml
+
+admin:
+  includes:
+    - editor
+    - billing
+
+# somewhere else in your app:
+
+@membership.roles << Role.admin
+@membership.roles.can_perform_role?(Role.find("editor"))
+=> true
+
+# You can also pass the role key as a symbol for a more concise syntax
+@membership.roles.can_perform_role?(:editor)
+=> true
+```
+
 
 ## Debugging
+
 If you want to see what CanCanCan directives are being created by your permit calls, you can add the `debug: true` option to your `permit` statement in `app/models/ability.rb`.
 
 Likewise, to see what abilities are being added for a certain user, you can run the following on the Rails console:
 
-```
+```ruby
 user = User.first
 Ability.new(user).permit user, through: :projects_collaborators, parent: :project, debug: true
 ```

data/bullet_train-roles.gemspec

@@ -10,7 +10,7 @@ Gem::Specification.new do |spec|
 
   spec.summary = "Yaml-backed ApplicationHash for CanCan Roles"
   spec.description = "Yaml-backed ApplicationHash for CanCan Roles"
-  spec.homepage = "https://github.com/bullet-train-co/bullet_train-roles"
+  spec.homepage = "https://github.com/bullet-train-co/bullet_train-core/tree/main/bullet_train-roles"
   spec.license = "MIT"
   spec.required_ruby_version = Gem::Requirement.new(">= 2.7.0")
 

data/lib/bullet_train/roles/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Roles
-  VERSION = "1.2.26"
+  VERSION = "1.3.0"
 end

data/lib/models/role.rb

@@ -19,9 +19,15 @@ class Role < ActiveYaml::Base
     find_by_key("default")
   end
 
+  # Allow us to use either symbols or strings when searching
+  def self.find_by_key(key)
+    super(key.to_s)
+  end
+
   def self.includes(role_or_key)
-    role_key = role_or_key.is_a?(Role) ? role_or_key.key : role_or_key
+    role_key = role_or_key.is_a?(Role) ? role_or_key.key : role_or_key.to_s
     role = Role.find_by_key(role_key)
+    return [] if role.nil?
     return Role.all.select(&:assignable?) if role.default?
     result = []
     all.each do |role|
@@ -35,7 +41,7 @@ class Role < ActiveYaml::Base
   end
 
   def self.find(key)
-    all.find { |role| role.key == key }
+    all.find { |role| role.key == key.to_s }
   end
 
   # We don't want to ever use the automatically generated ids from ActiveYaml.  These are created based on the order of objects in the yml file

data/lib/roles/support.rb

@@ -70,6 +70,20 @@ module Roles
         Role::Collection.new(self, (self.class.default_roles + roles_without_defaults).compact.uniq)
       end
 
+      # Tests if the user can perform a given role
+      # They can have the role assigned directly, or the role can be included in another role they have
+      def can_perform_role?(role_or_key)
+        role_key = role_or_key.is_a?(Role) ? role_or_key.key : role_or_key
+        role = Role.find_by_key(role_key)
+        return true if roles.include?(role)
+        # Check all the roles that this role is included into
+        Role.includes(role_key).each do |included_in_role|
+          return true if roles.include?(included_in_role)
+          return true if can_perform_role?(included_in_role)
+        end
+        false
+      end
+
       def roles=(roles)
         update(role_ids: roles.map(&:key))
       end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: bullet_train-roles
 version: !ruby/object:Gem::Version
-  version: 1.2.26
+  version: 1.3.0
 platform: ruby
 authors:
 - Prabin Poudel
@@ -9,7 +9,7 @@ authors:
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2023-05-18 00:00:00.000000000 Z
+date: 2023-08-11 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: byebug
@@ -195,11 +195,11 @@ files:
 - lib/roles/permit.rb
 - lib/roles/support.rb
 - lib/roles/user.rb
-homepage: https://github.com/bullet-train-co/bullet_train-roles
+homepage: https://github.com/bullet-train-co/bullet_train-core/tree/main/bullet_train-roles
 licenses:
 - MIT
 metadata:
-  homepage_uri: https://github.com/bullet-train-co/bullet_train-roles
+  homepage_uri: https://github.com/bullet-train-co/bullet_train-core/tree/main/bullet_train-roles
   source_code_uri: https://github.com/bullet-train-co/bullet_train-roles
   changelog_uri: https://github.com/bullet-train-co/bullet_train-roles/blob/main/CHANGELOG.md
 post_install_message: