dynamican 0.1.7 → 1.0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d6dd7da02224c7b3e20e8b582f5929657255d33d4ddf81037a09e2c303df7182
-  data.tar.gz: 1c7f34c8b6335a89c21087243bdcaec746966ff76c7bc076204aefa736fce121
+  metadata.gz: ee2ebd9f3470a7ad1002ee3344a357fc1549e8065dffc09986f9c466577de8a9
+  data.tar.gz: e1cac4d8aa2b6f209dc6885cebe31d9ec5548af8578514aa9bf44fe1836fb697
 SHA512:
-  metadata.gz: ea646968f0358bada82722bda78c2895bd6763428823f02ab51866caedbd45e7af0f411b5e77850e2bb71f83751503922aed96cb39b906fd344ebcca453154d9
-  data.tar.gz: 3c29cc459e4aff80101d2ec436deba04c3600410e030cc4e3cf09ad575df8b3cd1f93602a8639937930733c82513a6ea8293eeddbb309cd9cb5afe7159bfd329
+  metadata.gz: 63e6761a9fed8385830c6f10697a0448ec08a8e2a781612ac54544ed810635bbfec6006c26e5054b653131a495815c6da5ed1842e11262736f9b1a274c9b0882
+  data.tar.gz: be88310e037fb8cb2e71af8f8616f1441a2963b4b65a6599762e92b6800e30cec6ede2216c5558d2ff8c8ffc7407c94e866c5894a3f8e15c31517dcb213ac5a6

data/README.md

@@ -1,30 +1,26 @@
 # Dynamican
-Dynamican is a flexible gem to introduce permissions on rails applications. It is very customizable because it stores all the rules inside the database and can be added to multiple models: for example you can add permissions to your Role model or to users. With a couple of overrides you can also add permissions to both Role and User and use role permissions through user.
+Dynamican is a flexible gem which introduces permissions on rails applications. It is very customizable because it stores all the rules inside the database and can be added to multiple models: for example you can add permissions to your Role and User models. With a couple of overrides you can also add permissions to both Role and User and allow user to use its roles permissions.
 
 ## Installation
 Inside your Gemfile put
 
     gem 'dynamican'
 
-then run `bundle install`
+and run `bundle install`, then you can launch the following command.
 
-Once you have the gem, open the source code and look for migrations folder. You need to create in your project those migrations and run them. Obviously if you already have the gem installed and you are only updating, you only need to create the migrations for the later versions of the gem.
+    rails g dynamican_migration
 
-In each model you want to have the feature, just put
+This command will generate a migration file in your project, which you can run with
 
-    include Dynamican::Model
+    rails db:migrate
 
-Create `config/dynamican.yml` file and compile it as follows for each of the models you included the code above into (let's say for instance you included Dynamican::Model into User and Role models)
+In each model you want to have the feature, just put the following.
 
-    associations:
-      role:
-        class_name: 'Role'
-      user:
-        class_name: 'User'
+    include Dynamican::Model
 
-### Using permissions on one model through another model
+### Using a model permissions on another model
 
-I wanted to have the possibility to assign permissions both directly to my User model and my Role model, so that if the User had one permission and one of its Role had another, the User could benefit from both. So i assigned the feature (as explained above) to both models and then decorated my User model like this
+I wanted to have the possibility to assign permissions both directly to my User model and my Role model, so that if the User had one permission and one of its Roles had another, the User could benefit from both. So i included the feature into both models and then decorated my User model like following.
 
     module Decorators
       module Models
@@ -32,16 +28,11 @@ I wanted to have the possibility to assign permissions both directly to my User
           module DynamicanOverrides
             def self.prepended(base)
               base.class_eval do
-                has_many :user_permission_connectors, class_name: 'Dynamican::PermissionConnector'
-                has_many :user_permissions, class_name: 'Dynamican::Permission', through: :user_permission_connectors, source: :permission
+                has_many :user_permissions, class_name: 'Dynamican::Permission', as: :permittable, inverse_of: :permittable, foreign_key: :permittable_id
                 has_many :role_permissions, through: :roles, class_name: 'Dynamican::Permission', source: :permissions
               end
             end
 
-            def permission_connectors
-              Dynamican::PermissionConnector.where(id: user_permission_connectors.ids + roles.map(&:permission_connectors).flatten.map(&:id))
-            end
-
             def permissions
               Dynamican::Permission.where(id: user_permissions.ids + role_permissions.ids)
             end
@@ -52,67 +43,84 @@ I wanted to have the possibility to assign permissions both directly to my User
       end
     end
 
-I personally have put this in `app/decorators/models/user/dynamican_overrides.rb` (you need to load the folder if you don't already have it) but you can make it work as you please. I recommend to keep it separate from the original User model though.
+I personally have put this in `app/decorators/models/user/dynamican_overrides.rb` (rails needs to load the folder of course); you can make it work as you please but i recommend to keep it separate from the original User model.
 
 ## Usage
 
 Now the hard part: the real configuration.
 
-Create one `Dynamican::Permission` for each pair of action-object you need. For example i created CRUD permissions for my models. Let's say, for instance, you have the Order model.
+Create one `Dynamican::Action` for each action you need. For example i created CRUD permissions.
+
+    a1 = Dynamican::Action.create(name: 'create')
+    a2 = Dynamican::Action.create(name: 'read')
+    a3 = Dynamican::Action.create(name: 'update')
+    a4 = Dynamican::Action.create(name: 'delete')
 
-    p1 = Dynamican::Permission.create(action: 'create', object_name: 'order')
-    p2 = Dynamican::Permission.create(action: 'read', object_name: 'order')
-    p3 = Dynamican::Permission.create(action: 'update', object_name: 'order')
-    p4 = Dynamican::Permission.create(action: 'delete', object_name: 'order')
+Then create one `Dynamican::Item` for each resource you want your permittables to have permissions to act on. This is not mandatory for every permission though: you can also set a permission to do a general action, like `login`. Right now i'm trying to setup permissions for my permittable (Role model) to act on Order model.
 
-To assign one of these permissions to your Role or User, you need to create a `Dynamican::PermissionConnector` like this
+    i1 = Dynamican::Item.create(name: 'Order')
 
-    user.permission_connectors.create(permission: p1)
+NOTE: conventionally, the name should be PascalCase, so there is a `before_validation` hook that classifies the name you are setting.
 
-Or simply
+Create one `Dynamican::Permission` for each action you want your `role` instance to have permissions for.
 
-    user.permissions << p1
+    p1 = Dynamican::Permission.create(action: a1, items: [i1], permittable: role)
+    p2 = Dynamican::Permission.create(action: a2, items: [i1], permittable: role)
+    p3 = Dynamican::Permission.create(action: a3, items: [i1], permittable: role)
+    p4 = Dynamican::Permission.create(action: a4, items: [i1], permittable: role)
 
-Now your user is considered able to create orders and you can check the permissions:
+Now your Role is considered able to create, read, update and destroy orders; you can evaluate permissions with `can?` method.
 
-    user.can? :create, :order
-    # Returns true
+    role.can? :create, :order
 
-    user.can? :read, :order
-    # Returns false
+    # true
 
-You can pass as second argument (the object) a symbol, a string, the class itself and also the instance (instances are used for condition evaluations).
-You can also pass an array of these elements and permissions for all elements will be evaluated. The `can?` method will return true only if all permissions are evaluated positively.
-You can also create custom permissions which don't need an object, simply leaving the `object_name` empty. Let's say you want to give permission to a certain user to dance
+    role.can? :else, :order
 
-    p5 = Dynamican::Permission.create(action: 'dance')
+    # false
 
-    user.permissions << p5
+You can pass as second argument (the item) a symbol, a string, the class itself and also the instance (instances are required for condition evaluations).
+If you pass an array of these elements, permissions for all single element will be evaluated. The `can?` method will return true only if permissions to all items are evaluated positively.
+You can also create custom permissions which don't need an item, (item is not required for permission creation). Let's say you want to give permission to a certain `user` to dance.
+
+    action_dance = Dynamican::Action.create(name: 'dance')
+    p5 = Dynamican::Permission.create(action: action_dance, permittable: user)
 
 Call the `can?` method without any second argument
 
     user.can? :dance
 
-    # Returns true
+    # true
 
 
-## Conditions
+### Conditions
 
-You can link a `Dynamican::PermissionConnector` to as many conditions as you want.
+You can link a `Dynamican::Permission` to as many conditions as you want. A permission having at least one condition linked to is considered conditional (Permission class have `conditional` and `unconditional` scopes)
 
-Conditions are created like this
+Conditions are created like this.
 
-    permission_connector.conditions.create(statement: '@user.orders.count < 5')
-    permission_connector.conditions.create(statement: '@object.field.present?')
+    permission.conditions.create(statement: '@user.orders.count < 5')
+    permission.conditions.create(statement: '@item.field.present?')
 
-You can store in conditions statements whatever conditions you like in plain ruby and the string will be evaulated. Inside the statements, object have to be called as instance variables. These instance variables need to be present and can be declared as follows:
+You can store in conditions statements whatever conditions you like in plain ruby and the string will be evaulated. Inside the statements, object have to be called as instance variables. These instance variables indeed need to be present and can be declared in a few ways.
 
-1. The model name of the instance you called `can?` from, like the user, will be defined automatically based on model name so if you call `user.can?` you will have `@user` variable defined.
-2. The object you pass as second argument (which should match the `object_name` of your permission) will be defined as `@object`, so if you call `user.can? :read, @order` you will have `@object` variable defined containing your `@order`.
+1. The model name of the instance you called `can?` from, like the user, will be defined automatically based both on a fixed name and on model name, so if you call `user.can?` you will have `@subject` variable (this is fixed) and `@user` variable defined because user is of class `User` (namespaces get cut out, so `Something::User` still turne into `@user`).
+2. The same thing happens with the item: it will be defined both as `@item` and as the name of its class, so if you call `user.can? :read, @order` you will have `@item` and `@order` variable defined containing your `@order` object.
 3. You can pass as third argument an hash of objects like this `user.can? :read, @order, time: Time.zone.now, whatever: @you_want` and you will have `@time` and `@whatever` variables defined.
 
-WARNING: since the condition statement gets evaluated, i recommend not to allow anyone except project developers to create conditions to prevent malicious code from being executed.
+WARNING: since the condition statement gets evaluated, i recommend not to allow anyone except project developers to create conditions, in order to prevent malicious code from being executed.
 
-If one `Dynamican::PermissionConnector` is linked to many conditions, the model will be allowed to make that action only if all conditions are true. If you want to set alternative conditions, you should store the or conditions inside the same statement, like this:
+If one `Dynamican::Permission` is linked to many conditions, the model will be allowed to make that action only if all conditions are true. If you want to set alternative conditions, you should store the `or` conditions inside the same condition statement, like this:
 
     condition.statement = '@user.nice? || @user.polite?'
+
+### Permission scopes
+
+You can apply the scope `for_action(action_name)` to Permission to find permissions bound to a specific action.
+There is a `for_item(item_name)` scope, which turns to string and then classifies automatically the argument to match it with the classified item name. The scope filters all Permission records that have an item with the specified name in its items list.
+There is also a `without_item` scope to filter records that are not linked to any item.
+As mentioned before, you can also use `conditional` and `unconditional` scopes to find objects with or without any condition attached.
+
+### Controller usage
+
+Your controllers now all have the `authorize!` method, which accepts one or two arguments: the first is the action, and the second (optional) is the item (or list of items) you want to check permissions for. As you can see, the usage is similar to the `can?` method. The reason is that is actually calls that method on the instance of `@current_user` and, whether permissions are evaluated as false, it raises an exception which is rescued by an `unauthorized` response rendered.

data/dynamican.gemspec

@@ -1,7 +1,7 @@
 Gem::Specification.new do |s|
   s.name        = 'dynamican'
-  s.version     = '0.1.7'
-  s.date        = '2020-04-12'
+  s.version     = '1.0.1'
+  s.date        = '2020-09-10'
   s.summary     = "Dynamic permissions"
   s.description = "Dynamic and flexible database configurable permissions for your application"
   s.authors     = ["Valerio Bellaveglia"]

data/lib/dynamican.rb

@@ -1,6 +1,8 @@
-require 'dynamican/configuration'
+require 'dynamican/authorization'
 require 'dynamican/evaluator'
 require 'dynamican/model'
-require 'models/dynamican/condition'
-require 'models/dynamican/permission_connector'
 require 'models/dynamican/permission'
+require 'models/dynamican/action'
+require 'models/dynamican/item'
+require 'models/dynamican/condition'
+require 'generators/dynamican_migration_generator'

data/lib/dynamican/authorization.rb

@@ -0,0 +1,25 @@
+module Dynamican
+  module Authorization
+    extend ActiveSupport::Concern
+
+    class UnauthorizedResource < StandardError; end
+
+    included do
+      rescue_from UnauthorizedResource, with: :unauthorized
+    end
+
+    def authorize!(action, item = nil)
+      raise UnauthorizedResource unless @current_user.can? action, item
+    end
+
+    def unauthorized
+      render status: :unauthorized
+    end
+  end
+end
+
+if defined? ActiveSupport
+  ActiveSupport.on_load(:action_controller) do
+    include Dynamican::Authorization
+  end
+end

data/lib/dynamican/evaluator.rb

@@ -1,42 +1,41 @@
 module Dynamican
   class Evaluator
-    attr_reader :subject, :action, :object, :object_name, :conditions_instances
+    attr_reader :subject, :action, :item, :item_name, :conditions_instances
 
-    def initialize(subject, action, object, conditions_instances = {})
+    def initialize(subject, action, item, conditions_instances = {})
       @subject = subject
       @action = action
-      @object = object
-      @object_name = calculate_object_name
+      @item = item
+      @item_name = calculate_item_name
       @conditions_instances = conditions_instances
     end
 
     def evaluate
       set_instance_variables
 
-      matching_connectors = subject.permission_connectors.for_action(action).for_object(object_name)
-      matching_conditions_statements = matching_connectors.conditional.map(&:conditions).flatten.map(&:statement)
+      matching_permissions = item.present? ? subject.permissions.for_action(action).for_item(item_name) : subject.permissions.for_action(action).without_item
+      matching_permissions_statements = matching_permissions.conditional.map(&:conditions).flatten.map(&:statement)
 
-      matching_connectors.unconditional.any? ||
-      matching_conditions_statements.any? && matching_conditions_statements.map { |statement| eval statement }.all?
+      matching_permissions.unconditional.any? ||
+      matching_permissions_statements.any? && matching_permissions_statements.map { |statement| eval statement }.all?
     end
 
     private
 
     def set_instance_variables
-      instance_variable_set("@#{subject.model_name.element}", subject)
+      instance_variable_set("@#{subject.class.name.demodulize.underscore}", subject)
+      instance_variable_set("@#{item.class.name.demodulize.underscore}", item)
 
-      conditions_instances.each do |instance_name, instance_object|
-        instance_variable_set("@#{instance_name}", instance_object)
+      conditions_instances.each do |instance_name, instance_item|
+        instance_variable_set("@#{instance_name}", instance_item)
       end
     end
 
-    def calculate_object_name
-      if object.class.in? [Symbol, String, Class]
-        object.to_s.downcase
-      elsif object.is_a?(NilClass)
-        nil
+    def calculate_item_name
+      if item.class.in? [Symbol, String, Class]
+        item.to_s.classify
       else
-        object.class.to_s.downcase
+        item.class.name.demodulize
       end
     end
   end

data/lib/dynamican/model.rb

@@ -3,15 +3,14 @@ module Dynamican
     extend ActiveSupport::Concern
 
     included do
-      has_many :permission_connectors, class_name: 'Dynamican::PermissionConnector'
-      has_many :permissions, class_name: 'Dynamican::Permission', through: :permission_connectors, source: :permission
+      has_many :permissions, class_name: 'Dynamican::Permission', as: :permittable, dependent: :destroy
     end
 
-    def can?(action, object = nil, conditions_instances = {})
-      if object.respond_to? :each
-        object.all? { |single_object| can? action, single_object }
+    def can?(action, item = nil, conditions_instances = {})
+      if item.respond_to? :each
+        item.all? { |single_item| can? action, single_item }
       else
-        Dynamican::Evaluator.new(self, action, object, conditions_instances).evaluate
+        Dynamican::Evaluator.new(self, action, item, conditions_instances).evaluate
       end
     end
   end

data/lib/generators/dynamican_migration_generator.rb

@@ -0,0 +1,53 @@
+require 'rails/generators'
+
+class DynamicanMigrationGenerator < Rails::Generators::Base
+
+  def create_migration_file
+    create_file "db/migrate/#{Time.zone.now.strftime("%Y%m%d%H%M%S")}_dynamican_migration.rb", migration_data
+  end
+
+  private
+
+  def migration_data
+<<MIGRATION
+  class DynamicanMigration < ActiveRecord::Migration[5.2]
+    def change
+      unless table_exists? :permissions
+        create_table :permissions do |t|
+          t.bigint :permittable_id
+          t.string :permittable_type
+          t.bigint :action_id
+
+          t.timestamps
+        end
+
+        create_table :actions do |t|
+          t.string :name
+
+          t.timestamps
+        end
+
+        create_table :items do |t|
+          t.string :name
+
+          t.timestamps
+        end
+
+        create_table :conditions do |t|
+          t.bigint :permission_id
+          t.string :statement
+          t.string :description
+
+          t.timestamps
+        end
+
+        create_table :items_permissions do |t|
+          t.bigint :item_id
+          t.bigint :permission_id
+        end
+      end
+    end
+  end
+MIGRATION
+  end
+end

data/lib/models/dynamican/action.rb

@@ -0,0 +1,9 @@
+module Dynamican
+  class Action < ActiveRecord::Base
+    has_many :permissions, class_name: 'Dynamican::Permission', inverse_of: :action, foreign_key: :action_id, dependent: :destroy
+
+    validates :name, presence: true, uniqueness: true
+
+    attr_readonly :name
+  end
+end

data/lib/models/dynamican/condition.rb

@@ -1,5 +1,7 @@
 module Dynamican
   class Condition < ActiveRecord::Base
-    has_and_belongs_to_many :permission_connectors, class_name: 'Dynamican::PermissionConnector', foreign_key: :condition_id
+    belongs_to :permission, class_name: 'Dynamican::Permission', inverse_of: :conditions, foreign_key: :permission_id
+
+    validates_presence_of :statement
   end
 end

data/lib/models/dynamican/item.rb

@@ -0,0 +1,15 @@
+module Dynamican
+  class Item < ActiveRecord::Base
+    has_and_belongs_to_many :permissions, class_name: 'Dynamican::Permission', inverse_of: :items, foreign_key: :item_id, dependent: :destroy
+
+    validates :name, presence: true, uniqueness: true
+
+    attr_readonly :name
+
+    before_validation :classify_name
+
+    def classify_name
+      self.name = self.name.classify
+    end
+  end
+end

data/lib/models/dynamican/permission.rb

@@ -1,10 +1,14 @@
 module Dynamican
   class Permission < ActiveRecord::Base
-    has_many :permission_connectors, class_name: 'Dynamican::PermissionConnector', inverse_of: :permission, foreign_key: :permission_id
+    belongs_to :permittable, polymorphic: true
+    belongs_to :action, class_name: 'Dynamican::Action', inverse_of: :permissions, foreign_key: :action_id
+    has_and_belongs_to_many :items, class_name: 'Dynamican::Item', inverse_of: :permissions, foreign_key: :permission_id
+    has_many :conditions, class_name: 'Dynamican::Condition', inverse_of: :permission, foreign_key: :permission_id
 
-    validates_presence_of :action
-
-    scope :for_action, -> (actions) { where(action: actions) }
-    scope :for_object, -> (object_names) { where(object_name: object_names) }
+    scope :for_action, -> (action_name) { joins(:action).where(actions: { name: action_name }) }
+    scope :for_item, -> (item_name) { joins(:items).where(items: { name: item_name.to_s.classify }) }
+    scope :without_item, -> { left_outer_joins(:items).where(items: { id: nil }) }
+    scope :conditional, -> { joins(:conditions) }
+    scope :unconditional, -> { left_outer_joins(:conditions).where(conditions: { id: nil }) }
   end
 end

metadata

@@ -1,17 +1,17 @@
 --- !ruby/object:Gem::Specification
 name: dynamican
 version: !ruby/object:Gem::Version
-  version: 0.1.7
+  version: 1.0.1
 platform: ruby
 authors:
 - Valerio Bellaveglia
-autorequire: 
+autorequire:
 bindir: bin
 cert_chain: []
-date: 2020-04-12 00:00:00.000000000 Z
+date: 2020-09-10 00:00:00.000000000 Z
 dependencies: []
 description: Dynamic and flexible database configurable permissions for your application
-email: 
+email:
 executables: []
 extensions: []
 extra_rdoc_files: []
@@ -20,18 +20,19 @@ files:
 - README.md
 - dynamican.gemspec
 - lib/dynamican.rb
-- lib/dynamican/configuration.rb
+- lib/dynamican/authorization.rb
 - lib/dynamican/evaluator.rb
 - lib/dynamican/model.rb
+- lib/generators/dynamican_migration_generator.rb
+- lib/models/dynamican/action.rb
 - lib/models/dynamican/condition.rb
+- lib/models/dynamican/item.rb
 - lib/models/dynamican/permission.rb
-- lib/models/dynamican/permission_connector.rb
-- migrations/0.1.2/dynamican_create_database_structure.rb
 homepage: https://github.com/ValerioBellaveglia/Dynamican
 licenses:
 - MIT
 metadata: {}
-post_install_message: 
+post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -46,8 +47,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.0.2
-signing_key: 
+rubygems_version: 3.1.2
+signing_key:
 specification_version: 4
 summary: Dynamic permissions
 test_files: []

data/lib/dynamican/configuration.rb

@@ -1,17 +0,0 @@
-module Dynamican
-  def self.configuration
-    @configuration ||= Configuration.new(configuration_hash)
-  end
-
-  def self.configuration_hash
-    @configuration_hash ||= HashWithIndifferentAccess.new(YAML.load_file('config/dynamican.yml'))
-  end
-
-  class Configuration
-    attr_accessor :associations
-
-    def initialize(configuration_hash)
-      @associations = configuration_hash[:associations]
-    end
-  end
-end

data/lib/models/dynamican/permission_connector.rb

@@ -1,14 +0,0 @@
-module Dynamican
-  class PermissionConnector < ActiveRecord::Base
-    Dynamican.configuration.associations.each do |association_name, association_options|
-      belongs_to association_name.to_sym, class_name: association_options[:class_name], inverse_of: association_options[:inverse_of], foreign_key: "#{association_name}_id".to_sym, optional: true
-    end
-    has_and_belongs_to_many :conditions, class_name: 'Dynamican::Condition', inverse_of: :permission_connectors, foreign_key: :permission_connector_id
-    belongs_to :permission, class_name: 'Dynamican::Permission', inverse_of: :permission_connectors, foreign_key: :permission_id
-
-    scope :conditional, -> { where(conditional: true) }
-    scope :unconditional, -> { where(conditional: false) }
-    scope :for_action, -> (action) { joins(:permission).where(permissions: { action: action }) }
-    scope :for_object, -> (object_name) { joins(:permission).where(permissions: { object_name: object_name }) }
-  end
-end

data/migrations/0.1.2/dynamican_create_database_structure.rb

@@ -1,31 +0,0 @@
-class DynamicanCreateDatabaseStructure < ActiveRecord::Migration[5.2]
-  def change
-    create_table :conditions do |t|
-      t.string :description
-      t.string :statement
-
-      t.timestamps
-    end
-
-    create_table :permissions do |t|
-      t.string :action
-      t.string :object_name
-
-      t.timestamps
-    end
-
-    create_table :permission_connectors do |t|
-      t.references :user
-      t.references :role
-      t.references :permission
-      t.boolean :conditional, default: false
-
-      t.timestamps
-    end
-
-    create_table :conditions_permission_connectors do |t|
-      t.bigint :condition_id
-      t.bigint :permission_connector_id
-    end
-  end
-end