controller_policies 0.1.0 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: db99c9c096c0c752d9d035f928f7c92e9f6efff716975d2e4672b3c18443b16a
-  data.tar.gz: 01a131a24ad0f546ada81e5d10c1d27564591147c09004a97e6691150d18be71
+  metadata.gz: 77ea62355c4991dfc6d3aa1da19d75bbb231e170c6451ed11cc43cb38d53f158
+  data.tar.gz: be3d3097f5385f681016c8fd7ee415fc3a6fbdf21acc1320ce6d8891c4f723d7
 SHA512:
-  metadata.gz: 05ebbc1bad897b0b6fecf8280f625a5f4d73013255c0dee1e7ab5a6e564fc9aedd21772b9b0bd27d159cf698e09377b3b829dcf5ee60584c95a250841536a336
-  data.tar.gz: 5e23aa2064c53ea42acea98b1bffaa89767558e4fe2a7a7938b2331b258f0dc0c661f1b8542d866cacf44ec453a222e34019b0c8b7e1b77e1091be89281b84bd
+  metadata.gz: 289d8b06bca9542f79799779f2fba6444434ce41b85725e0c89cea6a182f5add24c5a32dbfbd9ed52aae4607cd36c9cd830db4b780fecf050075d1c15b94bd4a
+  data.tar.gz: 0d06f4170f6d708f487ce08e4533b93aaaac9916e342fa7a58eaeae3a86be0fde188459ea2299819cc6cc4c553402fc8d80373a00d2c98a3136f6a86ffc3513d

data/README.md

@@ -5,7 +5,7 @@
 Add this line to your application's Gemfile:
 
 ```ruby
-gem 'controller_policies', '~> 0.1'
+gem 'controller_policies', '~> 1.0'
 ```
 
 ## Usage
@@ -20,7 +20,7 @@ rails g policy_definition my/namespace
 
 This will generate a file: `app/policies/my/namespace/definitions.rb`
 
-The developer should edit this file and add the policies for the app.
+The developer should edit this file and add the policies for the app. **It is important to note that the location of the definitions file should reflect the namespace of the associated controllers.**
 
 ### `actions` key
 
@@ -29,13 +29,15 @@ The `actions` key is an array of strings that contain a list of supported contro
 For example, you have this definition:
 
 ```ruby
-module Base
-  DEFINITIONS = {
-    code: 'policy_code',
-    name: 'Policy Name',
-    description: 'I am a policy.',
-    actions: ['feature_app/users', 'data_app/products#index', 'subscriptions']
-  }
+module Policies
+  module Base
+    DEFINITIONS = {
+      code: 'policy_code',
+      name: 'Policy Name',
+      description: 'I am a policy.',
+      actions: ['feature_app/users', 'data_app/products#index', 'subscriptions']
+    }
+  end
 end
 ```
 
@@ -61,7 +63,7 @@ Simply add the line `has_enforced_policies`, and pass a block with one argument
 ```ruby
 class MyController < ApplicationController
   has_enforced_policies do |ability_code|
-    current_user.abilities.include? ability_code
+    render 'unauthorized' unless current_user.abilities.include? ability_code
   end
 
   # ...
@@ -73,14 +75,28 @@ class MyController < ApplicationController
   has_enforced_policies
 
   def ability?(ability_code)
-    current_user.abilities.include? ability_code
+    render 'unauthorized' unless current_user.abilities.include? ability_code
   end
   # ...
 end
 ```
 
+It is recommended to use `render` or `redirect_to` within this block **to prevent the controllers from executing the action** when the ability did not exist in the data. The ability checking is done in a `before_action` callback, hence using `render` or `redirect_to` will stop further controller actions. This is a Rails behavior.
+
 Since storing abilities are very flexible and there are truly infinite ways of doing it, *this gem did not support that feature.* Instead, the developer must define their own ability checking.
 
+## Skipping Policy Enforcement in Certain Actions
+
+There might be an event where there is a need to skip automatic policy enforcements in certain actions. As explained above, the policy enforcement is done in a `before_action` callback. To skip a policy enforcement, simply use the `skip_before_action :check_abilities_by_definition` method from Rails. The `:only` and `:except` options are also available to filter actions.
+
+```ruby
+class MyOtherController < MyController
+  skip_before_action :check_abilities_by_definition, only: [:new, :edit]
+
+  # ...
+end
+```
+
 ## Ability
 
 The Ability class is a model for abilities that come from the definition files.
@@ -91,25 +107,37 @@ The Ability class is a model for abilities that come from the definition files.
 
 Get all abilities from all definitions.
 
+```ruby
+Ability.all
+```
+
 #### #all_codes
 
 Get all ability codes from all definitions.
 
-#### #where(query)
+```ruby
+Ability.all_codes
+```
 
-Filter abilities based on namespace. `query` can be a String, Module or Class.
+#### #where(*queries)
 
-#### #find(query)
+Filter abilities based on namespace. `queries` can be an array of Strings, Modules or Classes.
 
-Find an ability within a namespace. `query` can be a String, Module or Class.
+```ruby
+Ability.where(Policies::FeatureOne, Policies::FeatureTwo, Policies::FeatureOne::SubFeatureA)
+```
+
+```ruby
+Ability.where('/feature_one', '/feature_two', '/feature_one/sub_feature_a')
+```
 
 #### #match(expression)
 
 Match abilities based on a matching string or regex. The matcher is based on the namespace. `expression` can be a Regexp or String.
 
-#### #mill(expression)
-
-Find an ability based on a matching string or regex. The matcher is based on the namespace. `expression` can be a Regexp or String.
+```ruby
+Ability.match(/Policies::FeatureOne(::)?(.)*/)
+```
 
 ### Instance Methods
 
@@ -117,18 +145,34 @@ Find an ability based on a matching string or regex. The matcher is based on the
 
 The code of the ability.
 
+```ruby
+ability.code
+```
+
 #### #name
 
 The name of the ability.
 
+```ruby
+ability.name
+```
+
 #### #description
 
 The description of the ability.
 
+```ruby
+ability.description
+```
+
 #### #actions
 
 Controller actions that the ability can check against.
 
+```ruby
+ability.actions
+```
+
 ## Contributing
 
 Bug reports and pull requests are welcome on GitHub at https://github.com/tieeeeen1994/controller_policies. 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/tieeeeen1994/controller_policies/blob/master/CODE_OF_CONDUCT.md).

data/lib/ability.rb

@@ -33,19 +33,23 @@ class Ability
     end
 
     # Filter abilities based on namespace.
-    def where(query)
-      case query.class.to_s
-      when 'String'
-        all.select { |ability| ability.namespace.to_s == trim(query).camelize }
-      when 'Module', 'Class'
-        all.select { |ability| ability.namespace == query }
+    def where(*queries)
+      results = []
+      queries.each do |query|
+        case query.class.to_s
+        when 'String'
+          results += all.select { |ability| ability.namespace.to_s == "Policies::#{trim(query).camelize}" }
+        when 'Module', 'Class'
+          results += all.select { |ability| ability.namespace == query }
+        end
       end
+      results
     end
 
     # Find an ability within a namespace.
-    def find(query_string)
-      where(query_string).first
-    end
+    # def find(query_string)
+    #   where(query_string).first
+    # end
 
     # Match abilities based on a matching string or regex. The matcher is based on the namespace.
     def match(expression)
@@ -56,9 +60,9 @@ class Ability
     end
 
     # Find an ability based on a matching string or regex. The matcher is based on the namespace.
-    def mill(expression)
-      match(expression).first
-    end
+    # def mill(expression)
+    #   match(expression).first
+    # end
 
     # Path to the policy folder.
     def policy_path
@@ -78,7 +82,7 @@ class Ability
     end
 
     def definition_files_post_processing(file_path)
-      module_constant = convert_namespace(file_path)
+      module_constant = "Policies::#{convert_namespace(file_path)}".constantize
       policy_definitions = module_constant::DEFINITIONS
       policy_definitions.map do |policy_definition|
         policy_definition[:namespace] = module_constant
@@ -97,7 +101,7 @@ class Ability
     end
 
     def convert_namespace(file_path)
-      trim(file_path[policy_path.to_s.length..-4].split('/')[0...-1].join('/')).camelize.constantize
+      trim(file_path[policy_path.to_s.length..-4].split('/')[0...-1].join('/')).camelize
     end
   end
 end

data/lib/controller_policies/action_controller_patch.rb

@@ -10,5 +10,9 @@ module ControllerPolicies
 
       define_method(:ability?, &block)
     end
+
+    def no_enforced_policies(arguments = {})
+      skip_before_action :check_abilities_by_definition, arguments
+    end
   end
 end

data/lib/controller_policies/railtie.rb

@@ -19,10 +19,10 @@ module ControllerPolicies
 
     initializer 'controller_policies.autoloaders' do
       Rails.autoloaders.each do |autoloader|
-        autoloader.ignore(Rails.root.join('app/policies'))
+        autoloader.ignore(Ability.policy_path)
       end
 
-      Dir[Rails.root.join('app/policies/**/*.rb')].each { |definition| require definition }
+      Dir[Ability.policy_path.join('**/*.rb')].each { |definition| require definition }
     end
   end
 end

data/lib/controller_policies/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module ControllerPolicies
-  VERSION = '0.1.0'
+  VERSION = '1.0.0'
 end

data/lib/generators/templates/definitions.rb.tt

@@ -1,22 +1,24 @@
 # frozen_string_literal: true
 
-module <%= name.camelize %>
-  DEFINITIONS = [
-    {
-      # Used as identifier for the policy.
-      code: 'Policy-Code',
-      # Readable name for the policy.
-      name: 'Readable Policy Name',
-      # Readable description for the policy.
-      description: 'Short description of what this policy allows',
-      # Controller actions the policy applies to. It works as matchers based on routes.
-      # It can be empty for manual policy checking.
-      actions: ['feature_app/users', 'data_app/products#index', 'subscriptions']
-    },
-    {
-      code: 'Another-Policy-Code',
-      name: 'Another Policy',
-      description: 'Long description.',
-    }
-  ].freeze
+module Policies
+  module <%= name.camelize %>
+    DEFINITIONS = [
+      {
+        # Used as identifier for the policy.
+        code: 'Policy-Code',
+        # Readable name for the policy.
+        name: 'Readable Policy Name',
+        # Readable description for the policy.
+        description: 'Short description of what this policy allows',
+        # Controller actions the policy applies to. It works as matchers based on routes.
+        # It can be empty for manual policy checking.
+        actions: ['feature_app/users', 'data_app/products#index', 'subscriptions']
+      },
+      {
+        code: 'Another-Policy-Code',
+        name: 'Another Policy',
+        description: 'Long description.',
+      }
+    ].freeze
+  end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: controller_policies
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 1.0.0
 platform: ruby
 authors:
 - Tien
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2024-04-12 00:00:00.000000000 Z
+date: 2024-08-30 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -65,7 +65,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.3
+rubygems_version: 3.5.11
 signing_key:
 specification_version: 4
 summary: Allows the developer to define policies for controllers.