accessly 1.0.1 → 1.0.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 815f41738a2e4a9ff10656b7328cfcbce68ceb41
-  data.tar.gz: 9920d928acb62e3a3f823f28a2322cd0a8dba174
+  metadata.gz: 96505b522e737820634c4c02ab4c861880008a70
+  data.tar.gz: eee707f0a8667c4e9f383e827197f64db141412f
 SHA512:
-  metadata.gz: 120ca23c06d76c839e22860b01483c182e32ecb6ce1f67e8377fddeb46871d70ecb6acc85a474acb3061ecc6fc7e2bc9411b0ecba71fc20811d20429c126862b
-  data.tar.gz: ed13d76b6ee3b35bed3f3ba0b10c330511b1f0e602e25651b4b530ce153f229a1cb81d4dfe7cdaca6cecf2fadd332390fbfda99dabf304093bf8027dc57d209e
+  metadata.gz: 504dd75a1ce9ae60c89dd3e335de18cb7ef46e45bc2a39d67e07407d94eec0daffbeedcf70ac8a045cdb26c5be2c584c3e756cbbca46757ac9826281b3ad00dd
+  data.tar.gz: 511e3129de53be6bb92c8519db2dd9fc29b392851337dfb38d0104116eb7d56cd0d85f4957465bfcb15b6817e1a602225b5a42e88df56d06aecaafc65ba81ae5

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    accessly (1.0.0)
+    accessly (1.0.2)
       activerecord (~> 5.0)
 
 GEM

data/README.md

@@ -64,6 +64,18 @@ class ApplicationFeaturePolicy < Accessly::Policy::Base
 end
 ```
 
+#### ACTIONS
+
+Accessly policies rely on a definition of `actions` and/or `actions_on_objects` for effective use. This example uses `actions` which represent a "permission" that can be granted to an actor for later validation within your app's business logic.
+
+- `actions` map a symbol to an integer value.
+- An `action` value should be a unique integer within each policy.
+- removing/editing `actions` and values can have negative consequences if the underlying data is not migrated
+
+Defined policy `actions` become part of the policy API. (see examples below)
+
+#### Policy API Example
+
 With this policy we can `grant` permissions to a user
 
 ```ruby
@@ -107,6 +119,18 @@ class UserPolicy < Accessly::Policy::Base
 end
 ```
 
+#### ACTIONS ON OBJECTS
+
+Accessly policies rely on a definition of `actions` and/or `actions_on_objects` for effective use. This example uses `actions_on_objects` which associate a "permission" with an object in your system.  The "object" is typically an ActiveRecord object.
+
+- `actions_on_objects` map a symbol to an integer value.
+- An `actions_on_objects` value should be a unique integer within each policy.
+- removing/editing `actions_on_objects` and values can have negative consequences if the underlying data is not migrated
+
+Defined policy `actions_on_objects` become part of the policy API. (see examples below)
+
+#### Policy API Example
+
 We differentiate permissions by a `namespace` which by default is the name of your policy class.  However,
 it may be necessary to override the default behavior represented in the above example.
 

data/lib/accessly/policy/base.rb

@@ -1,6 +1,10 @@
 module Accessly
   module Policy
     class Base
+      # Module that will hold our meta-programmed action methods just above
+      # the policy class in the inheritance hierarchy; allowing for them to
+      # be overridden in the policy.
+      ACTIONS_MODULE = :Actions
 
       attr_reader :actor
 
@@ -8,17 +12,82 @@ module Accessly
         @actor = actor
       end
 
+      # Meta-programs action methods from actions supplied.
+      # Used in policies as a DSL to declare actions.
+      #
+      # This defines the actions on the `actions_module` so that they are
+      # positioned higher in the inheritance tree than methods defined on the
+      # class itself. This will allow us to define methods that override these
+      # base methods and call `super`.
+      #
+      # @param actions [Hash] the actions to define on the policy
+      #
+      # @example Define Actions
+      #
+      #   # This example causes the following methods to be defined:
+      #   # some_action? : Returns true if the actor has the some_action
+      #   #   permission, false otherwise
+      #   # flip_the_flop? : Returns true if the actor has the flip_the_flop
+      #   #   permission, false otherwise
+      #   # create? : Returns true if the actor has the create permission, false
+      #   #   otherwise
+      #   actions(
+      #     some_action: 1,
+      #     flip_the_flop: 2,
+      #     create: 3
+      #   )
+      #
+      # @return [Hash] actions
       def self.actions(actions)
         _actions.merge!(actions)
         actions.each do |action, action_id|
-          _define_action_methods(action, action_id)
+          actions_module.module_eval do
+            define_method(:"#{action}?") do |*args|
+              _can_do_action?(action, action_id, args.first)
+            end
+          end
         end
       end
 
+      # Meta-programs action_on_objects methods from the actions supplied.
+      # Used in policies as a DSL to declare actions on objects.
+      # It is different from actions in that it will also define a method
+      # for listing all objects authorized with this action for the given
+      # actor and that these actions will always be associated not only with
+      # an actor, but with an object of the action.
+      #
+      # @param actions_on_objects [Hash] the actions on objects to define
+      # on the policy
+      #
+      # @example Define Actions On Objects
+      #
+      #   # This example causes the following methods to be defined:
+      #   # edit : Returns an ActiveRecord::Relation of the objects on which
+      #   #   the actor has the edit permission
+      #   # edit?(object) : Returns true if the actor has the edit permission
+      #   #   on the given object, false otherwise
+      #   # show : Returns an ActiveRecord::Relation of the objects on which
+      #   #   the actor has the show permission
+      #   # show?(object) : Returns true if the actor has the show permission
+      #   #   on the given object, false otherwise
+      #   actions_on_objects(
+      #     edit: 1,
+      #     show: 2
+      #   )
+      #
+      # @return [Hash] actions_on_objects
       def self.actions_on_objects(actions_on_objects)
         _actions_on_objects.merge!(actions_on_objects)
         actions_on_objects.each do |action, action_id|
-          _define_action_methods(action, action_id)
+          actions_module.module_eval do
+            define_method(:"#{action}?") do |*args|
+              _can_do_action?(action, action_id, args.first)
+            end
+
+            define_method(action) do |*args|
+              _list_for_action(action, action_id)
+            end
+          end
         end
       end
 
@@ -102,85 +171,31 @@ module Accessly
 
       private
 
-      def _get_action_id(action, object_id = nil)
-        if object_id.nil?
-          _get_general_action_id!(action)
+      # Accessor for the actions module that will hold our meta-programmed
+      # methods.
+      # We put these methods in this module so that they are positioned
+      # above the policy in the inheritance chain. We can then override
+      # the methods in our policy as needed and call super to access the
+      # previous definition.
+      #
+      # @return [ACTIONS_MODULE] the module for holding actions currently
+      #   defined on this class.
+      def self.actions_module
+        if const_defined?(ACTIONS_MODULE, _search_ancestors = false)
+          mod = const_get(ACTIONS_MODULE)
         else
-          _get_action_on_object_id!(action)
+          mod = const_set(ACTIONS_MODULE, Module.new)
+          include mod
         end
-      end
 
-      # Determines whether the caller is trying to call an action method
-      # in the format `action_name?`. If so, this calls that method with
-      # the given arguments.
-      def method_missing(method_name, *args)
-        action_method_name = _resolve_action_method_name(method_name)
-        if action_method_name.nil?
-          super
-        else
-          send(action_method_name, *args)
-        end
+        mod
       end
 
-      # Parses an action name from a given method name of the format
-      # `action_name?` or `action_name and returns the action method
-      # or the list method name. If the method name does not follow
-      # one of those formats, this assumes the caller is not calling
-      # an action or list method and returns nil.
-      def _resolve_action_method_name(method_name)
-        action_method_match = /\A(\w+)(\??)\z/.match(method_name)
-
-        return nil if action_method_match.nil? || action_method_match[1].nil?
-
-        action_name = action_method_match[1].to_sym
-        is_predicate = action_method_match[2] == "?"
-
-        if !_action_defined?(action_name)
-          nil
-        elsif is_predicate
-          _action_method_name(action_name)
+      def _get_action_id(action, object_id = nil)
+        if object_id.nil?
+          _get_general_action_id!(action)
         else
-          _action_list_method_name(action_name)
-        end
-      end
-
-      # The implementation for action methods follow the naming format
-      # `_resolve_action_name`. This is to allow child Policies to override
-      # the action method and still be able to call `super` when they
-      # need to call the base implementation of the action method.
-      def self._action_method_name(action_name)
-        "_resolve_#{action_name}"
-      end
-
-      def _action_method_name(action_name)
-        self.class._action_method_name(action_name)
-      end
-
-      # The implementation for list methods follow the naming format
-      # `_list_action_name`. This is to allow child Policies to override
-      # the list method and still be able to call `super` when they
-      # need to call the base implementation of the lsit method.
-      def self._action_list_method_name(action_name)
-        "_list_#{action_name}"
-      end
-
-      def _action_list_method_name(action_name)
-        self.class._action_list_method_name(action_name)
-      end
-
-      # Defines the action method on the Policy class for the given
-      # action name.
-      def self._define_action_methods(action, action_id)
-        unless method_defined?(_action_method_name(action))
-          define_method(_action_method_name(action)) do |*args|
-            _can_do_action?(action, action_id, args.first)
-          end
-        end
-
-        unless method_defined?(_action_list_method_name(action))
-          define_method(_action_list_method_name(action)) do |*args|
-            _list_for_action(action, action_id)
-          end
+          _get_action_on_object_id!(action)
         end
       end
 

data/lib/accessly/version.rb

@@ -1,3 +1,3 @@
 module Accessly
-  VERSION = "1.0.1"
+  VERSION = "1.0.2"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: accessly
 version: !ruby/object:Gem::Version
-  version: 1.0.1
+  version: 1.0.2
 platform: ruby
 authors:
 - Aaron Milam
@@ -10,7 +10,7 @@ authors:
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2018-06-15 00:00:00.000000000 Z
+date: 2018-10-12 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activerecord