role_plays 0.1.0

data/Rakefile

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+require "rubocop/rake_task"
+
+RuboCop::RakeTask.new
+
+task default: %i[spec rubocop]

data/lib/role_plays/base_struct.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+require "dry-struct"
+
+require_relative "types"
+
+module RolePlays
+  # Base of the value objects a policy is built from. They are values on purpose: a declaration is
+  # read many times and changed by no one, so extending a role returns a new struct rather than
+  # mutating the one another policy may have been given.
+  class BaseStruct < Dry::Struct
+    transform_keys(&:to_sym)
+  end
+end

data/lib/role_plays/mixin.rb

@@ -0,0 +1,392 @@
+# frozen_string_literal: true
+
+require_relative "base_struct"
+require_relative "types"
+
+module RolePlays
+  # Declarative, role based authorization DSL.
+  #
+  #   class OrderPolicy
+  #     include RolePlays::Mixin
+  #
+  #     context :user, :order, :order_relation
+  #
+  #     role :user do
+  #       action :create, -> { true }
+  #       action :destroy do
+  #         order.user_id == user.id
+  #       end
+  #       action :edit do
+  #         order.user_id == user.id && order.completed?
+  #       end
+  #
+  #       permitted_attributes %i[title description]
+  #       permitted_attributes :list, %i[page per_page]
+  #       permitted_attributes(:create) do
+  #         %i[title description] + (order ? [:user_id] : [])
+  #       end
+  #
+  #       scope :list, -> { order_relation.where(sent: true) }
+  #       scope -> { order_relation.where(user_id: user.id) }
+  #     end
+  #
+  #     # Roles listed together share the block, each one getting the same declarations
+  #     role %i[user access_code] do
+  #       action :list, -> { true }
+  #
+  #       scope -> { order_relation.where(user_id: user.id) }
+  #     end
+  #
+  #     role :admin do
+  #     end
+  #
+  #     role :any do
+  #       action :list, -> { true }
+  #     end
+  #   end
+  #
+  #   policy = OrderPolicy.new(role: :user, user: current_user, order: order,
+  #                            order_relation: Order.completed)
+  #
+  #   policy.can?(:destroy)               # => true / false
+  #   policy.permitted_attributes(:list)  # => %i[page per_page]
+  #   policy.scope(:list)                 # => Order.completed.where(sent: true)
+  #
+  # Every declared action also gets a `can_<action>?` predicate — `can_create?`, `can_destroy?` — so
+  # a policy can replace a hand written one without touching its callers.
+  #
+  # `role:` is the only argument the policy asks for. Every other keyword is arbitrary: it is kept as
+  # context and answered as a reader, so a policy is given what it actually talks about — `user`,
+  # `order`, `order_relation` — rather than a fixed record/relation/options triple. `context`
+  # declares those names, which makes them optional: a declared name reads as `nil` when the caller
+  # leaves it out, while an undeclared one raises, so a typo in a handler is not read as `nil`.
+  #
+  # The role is a symbol such as :user or :provider_location, selected from the authenticated user by
+  # the caller — the policy is told which role it answers for instead of resolving it from a user
+  # itself, so the same rules answer for a request, a background job or a spec.
+  #
+  # Roles are stored per class as RolePlays::Mixin::Role structs. An action is looked up on the
+  # current role first and falls back to the :any role, so shared permissions can be declared once.
+  # Unknown role/action pairs are denied. Nothing is inherited: a policy declares the roles it
+  # answers for, and a role shared between policies is passed around as a Role struct built with
+  # RoleBuilder.
+  #
+  # Permitted attributes and scopes are declared the same way, keyed by a label (:default when
+  # omitted) and resolved with the same role/:any fallback. An unknown attributes label yields an
+  # empty list, an unknown scope label yields `nil` — narrowing a relation to nothing is left to the
+  # caller, the only side that knows which relation the policy was built around.
+  #
+  # A policy is built once and never mutated afterwards. Action, attribute and scope bodies take no
+  # arguments and are evaluated against the policy instance, which gives them access to +role+, to
+  # every context keyword and to any helper method defined on the policy class itself.
+  # The DSL is one module on purpose — the declarations, the lookups and the readers they feed are
+  # one contract, so it is read top to bottom rather than split across files.
+  module Mixin
+    # Role every other role falls back to for actions it does not declare itself.
+    ANY_ROLE = :any
+
+    # Label a `permitted_attributes` declaration is filed under when none is given.
+    DEFAULT_ATTRIBUTES_LABEL = :default
+
+    # Label a `scope` declaration is filed under when none is given.
+    DEFAULT_SCOPE_LABEL = :default
+
+    # Marks the modules holding the readers `context` generates, so a keyword named after one of
+    # them is recognised as declared instead of as shadowing a method of the policy.
+    module ContextReaders; end
+
+    # What one role may do: the actions it declares, the attributes it may submit per label and the
+    # scopes it may read per label. Built by RoleBuilder from a `role` block, or by hand to share a
+    # role between policies.
+    class Role < BaseStruct
+      attribute :role, Types::Strict::Symbol
+      attribute :actions, Types::Hash.map(Types::Strict::Symbol, Types.Interface(:call)).default({}.freeze)
+      attribute :permitted_attributes,
+                Types::Hash.map(Types::Strict::Symbol, Types.Interface(:call)).default({}.freeze)
+      attribute :scopes, Types::Hash.map(Types::Strict::Symbol, Types.Interface(:call)).default({}.freeze)
+
+      def action_for(name)
+        actions[name]
+      end
+
+      def permitted_attributes_for(label)
+        permitted_attributes[label]
+      end
+
+      def scope_for(label)
+        scopes[label]
+      end
+
+      # Later declarations win, so a policy can extend or override a role it was given
+      def merge(other)
+        new(actions: actions.merge(other.actions),
+            permitted_attributes: permitted_attributes.merge(other.permitted_attributes),
+            scopes: scopes.merge(other.scopes))
+      end
+    end
+
+    # Collects `action`, `permitted_attributes` and `scope` declarations of a single `role` block
+    class RoleBuilder
+      def self.build(role, &block)
+        builder = new
+        builder.instance_eval(&block) if block
+
+        Role.new(role: role.to_sym, actions: builder.actions, permitted_attributes: builder.attributes,
+                 scopes: builder.scopes)
+      end
+
+      attr_reader :actions, :attributes, :scopes
+
+      def initialize
+        @actions = {}
+        @attributes = {}
+        @scopes = {}
+      end
+
+      def action(name, handler = nil, &block)
+        callable = handler || block
+        raise ArgumentError, "action :#{name} requires a lambda or a block" if callable.nil?
+        raise ArgumentError, "action :#{name} handler must not take required arguments" if callable.arity.positive?
+
+        @actions[name.to_sym] = callable
+      end
+
+      # Declares the attributes a role may submit, keyed by label (:default when omitted).
+      # The attributes can be listed literally or computed by a lambda or a block:
+      #
+      #   permitted_attributes %i[title description]
+      #   permitted_attributes :list, %i[page per_page]
+      #   permitted_attributes(:create) { own_order? ? %i[title user_id] : %i[title] }
+      def permitted_attributes(label = DEFAULT_ATTRIBUTES_LABEL, attributes = nil, &block)
+        unless label.is_a?(Symbol)
+          attributes = label
+          label = DEFAULT_ATTRIBUTES_LABEL
+        end
+
+        attributes ||= block
+        raise ArgumentError, "permitted_attributes :#{label} requires a list, a lambda or a block" if attributes.nil?
+
+        if attributes.respond_to?(:call) && attributes.arity.positive?
+          raise ArgumentError, "permitted_attributes :#{label} handler must not take required arguments"
+        end
+
+        @attributes[label.to_sym] = attributes.respond_to?(:call) ? attributes : -> { attributes }
+      end
+
+      # Declares how a role narrows a relation, keyed by a label (:default when omitted).
+      # The body reads the keyword the policy carries its relation in:
+      #
+      #   scope -> { order_relation.where(user_id: user.id) }
+      #   scope :list, -> { order_relation.where(sent: true) }
+      #   scope(:report) { own_orders.where(created_at: period) }
+      def scope(label = DEFAULT_SCOPE_LABEL, handler = nil, &block)
+        unless label.is_a?(Symbol)
+          handler = label
+          label = DEFAULT_SCOPE_LABEL
+        end
+
+        handler ||= block
+        raise ArgumentError, "scope :#{label} requires a lambda or a block" if handler.nil?
+        raise ArgumentError, "scope :#{label} handler must not take required arguments" if handler.arity.positive?
+
+        @scopes[label.to_sym] = handler
+      end
+    end
+
+    def self.included(base)
+      base.extend(ClassMethods)
+    end
+
+    # The DSL a policy class answers, and the lookups it resolves a declaration with
+    module ClassMethods
+      # Declares one or more roles, either with a block of actions or with a prebuilt Role struct.
+      # Names given as a list or as an array share the block, which is evaluated once and filed
+      # under each of them, so roles with identical permissions are declared together:
+      #
+      #   role :user do ... end
+      #   role %i[user access_code] do ... end
+      def role(*roles, &block)
+        roles = roles.flatten
+        raise ArgumentError, "role requires at least one role name" if roles.empty?
+
+        shared = nil
+        roles.each do |role_or_name|
+          next declare_role(role_or_name) if role_or_name.is_a?(Role)
+
+          shared ||= RoleBuilder.build(role_or_name, &block)
+          declare_role(shared.new(role: role_or_name.to_sym))
+        end
+      end
+
+      # Files a Role struct under its name, merging it into an already declared role of the
+      # same name so a later declaration extends or overrides the earlier one
+      def declare_role(role)
+        declared = policy_roles[role.role]
+
+        policy_roles[role.role] = declared ? declared.merge(role) : role
+        define_action_predicates(role.actions.keys)
+      end
+
+      # The roles this policy declares — nothing is inherited, so a role shared with another policy
+      # is composed in as a Role struct rather than picked up from a parent class
+      def policy_roles
+        @policy_roles ||= {}
+      end
+
+      def action_handler(role, action)
+        policy_roles[role]&.action_for(action) || policy_roles[ANY_ROLE]&.action_for(action)
+      end
+
+      def permitted_attributes_handler(role, label)
+        policy_roles[role]&.permitted_attributes_for(label) || policy_roles[ANY_ROLE]&.permitted_attributes_for(label)
+      end
+
+      def scope_handler(role, label)
+        policy_roles[role]&.scope_for(label) || policy_roles[ANY_ROLE]&.scope_for(label)
+      end
+
+      # Defines a `can_<action>?` predicate per declared action, so a policy answers the same
+      # `can_create?` / `can_destroy?` messages a hand written one does:
+      #
+      #   action :create   # => can_create?  == can?(:create)
+      #   action :destroy  # => can_destroy? == can?(:destroy)
+      #
+      # Called for every `role` declaration, so the predicates cover the actions of all roles —
+      # each one still resolves the handler for the current role at call time. The methods live on
+      # a module included into the policy, so a predicate written by hand on the class always wins.
+      def define_action_predicates(*actions)
+        actions.flatten.each do |action|
+          action = action.to_sym
+          predicate = :"can_#{action}?"
+          next if action_predicates.method_defined?(predicate)
+
+          action_predicates.define_method(predicate) { can?(action) }
+        end
+      end
+
+      # Module holding the generated predicates of this class, included on first use
+      def action_predicates
+        @action_predicates ||= Module.new.tap { |generated| include generated }
+      end
+
+      # Declares the keywords the policy is built with, giving each one a reader that answers `nil`
+      # when the caller left it out, so a handler can treat it as optional:
+      #
+      #   context :user, :order, :order_relation
+      #
+      #   action(:create) { %i[title] + (order ? [:user_id] : []) }
+      #
+      # Declaring is optional — any keyword `new` is given is readable by name anyway. What the
+      # declaration adds is the `nil` for a keyword that was not passed: an undeclared name always
+      # raises, so a typo in a handler cannot quietly answer `nil`.
+      def context(*names)
+        names.flatten.each do |name|
+          name = name.to_sym
+          policy_context_keys << name unless policy_context_keys.include?(name)
+          next if method_defined?(name) || private_method_defined?(name)
+
+          context_readers.define_method(name) { context[name] }
+        end
+      end
+
+      # The names this policy declares with `context`
+      def policy_context_keys
+        @policy_context_keys ||= []
+      end
+
+      # Module holding the generated context readers of this class, included on first use
+      def context_readers
+        @context_readers ||= Module.new.tap do |generated|
+          generated.extend(ContextReaders)
+          include generated
+        end
+      end
+
+      # Whether a keyword of this name would be unreachable because the policy answers it already.
+      # A reader generated by `context` does not count — answering it is what it is there for.
+      def reserved_context_name?(name)
+        return false unless method_defined?(name) || private_method_defined?(name)
+
+        !instance_method(name).owner.is_a?(ContextReaders)
+      end
+    end
+
+    attr_reader :role, :context
+
+    # The role is the name a `role` declaration was filed under, `nil` standing for no role at all,
+    # which leaves only the :any declarations. It is the only argument the policy asks for — every
+    # other keyword is kept as context and read back by name:
+    #
+    #   OrderPolicy.new(role: :user, user: current_user, order: order, order_relation: Order.all)
+    def initialize(role:, **context)
+      reject_shadowing_context!(context)
+
+      @role = role&.to_sym
+      @context = context.freeze
+    end
+
+    def can?(action)
+      handler = self.class.action_handler(role, action.to_sym)
+      return false if handler.nil?
+
+      !!instance_exec(&handler)
+    end
+
+    def cannot?(action)
+      !can?(action)
+    end
+
+    # Attributes the current role may submit for the given label, always as an array
+    # ready to be handed to ActionController::Parameters#permit
+    def permitted_attributes(label = DEFAULT_ATTRIBUTES_LABEL)
+      handler = self.class.permitted_attributes_handler(role, label.to_sym)
+      return [] if handler.nil?
+
+      wrap_attributes(instance_exec(&handler))
+    end
+
+    # The relation narrowed to what the current role may see under the given label, or `nil` when
+    # neither that role nor :any declares the label. The policy carries its relation in a keyword of
+    # its own naming, so saying "nothing is visible" is left to the caller:
+    #
+    #   OrderPolicy.new(role:, order_relation: Order.all).scope(:list) || Order.none
+    def scope(label = DEFAULT_SCOPE_LABEL)
+      handler = self.class.scope_handler(role, label.to_sym)
+      return nil if handler.nil?
+
+      instance_exec(&handler)
+    end
+
+    private
+
+    # Reads a context keyword — `new(role: :user, order:)` answers `order` — so handlers can name
+    # what they need. An unknown name still raises NameError, so a typo is not read as `nil`.
+    def method_missing(name, *args)
+      return super unless args.empty? && context.key?(name)
+
+      context[name]
+    end
+
+    def respond_to_missing?(name, include_private = false)
+      context.key?(name.to_sym) || super
+    end
+
+    # A context keyword only reaches a handler through its reader, so one named after a method the
+    # policy already answers — `can?`, `context`, a helper of its own — would be silently unreadable
+    def reject_shadowing_context!(context)
+      shadowed = context.keys.select { |key| self.class.reserved_context_name?(key) }
+      return if shadowed.empty?
+
+      raise ArgumentError, "#{self.class} already defines #{shadowed.map { ":#{_1}" }.join(", ")}, " \
+                           "so the value passed under that name could never be read"
+    end
+
+    # A declared list is handed straight to `permit`, so a single attribute — or a nested hash —
+    # reads as the one element list it stands for rather than being splatted
+    def wrap_attributes(attributes)
+      return [] if attributes.nil?
+
+      attributes.is_a?(::Array) ? attributes : [attributes]
+    end
+  end
+end

data/lib/role_plays/types.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+require "dry-types"
+
+module RolePlays
+  # The types the structs of this gem are built from
+  module Types
+    include Dry.Types()
+  end
+end

data/lib/role_plays/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module RolePlays
+  VERSION = "0.1.0"
+end

data/lib/role_plays.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+require_relative "role_plays/version"
+require_relative "role_plays/base_struct"
+require_relative "role_plays/types"
+require_relative "role_plays/mixin"
+
+module RolePlays
+  class Error < StandardError; end
+end

data/sig/role_plays.rbs

@@ -0,0 +1,4 @@
+module RolePlays
+  VERSION: String
+  # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+end

metadata

@@ -0,0 +1,74 @@
+--- !ruby/object:Gem::Specification
+name: role_plays
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Aliexandr Andrade
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: dry-struct
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.6'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.6'
+description: 'RolePlays turns a policy into one readable class per resource, built
+  and asked explicitly the way Pundit and Action Policy policies are, with its rules
+  declared rather than defined method by method as in CanCanCan: every role declares
+  the actions it may take, the attributes it may submit and the scopes it may read,
+  all resolved with a shared :any fallback. The policy is told the role name rather
+  than a user, so the same rules answer for a request, a background job or a spec.'
+email:
+- veimar.94@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- Rakefile
+- lib/role_plays.rb
+- lib/role_plays/base_struct.rb
+- lib/role_plays/mixin.rb
+- lib/role_plays/types.rb
+- lib/role_plays/version.rb
+- sig/role_plays.rbs
+homepage: https://github.com/Alexander-Andrade/role_plays
+licenses:
+- MIT
+metadata:
+  allowed_push_host: https://rubygems.org
+  homepage_uri: https://github.com/Alexander-Andrade/role_plays
+  source_code_uri: https://github.com/Alexander-Andrade/role_plays
+  changelog_uri: https://github.com/Alexander-Andrade/role_plays
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.2.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.8
+specification_version: 4
+summary: Role based authorization policies, one per resource as in Pundit or Action
+  Policy, declared with a DSL in the spirit of CanCanCan.
+test_files: []