eaco 0.5.0

data/lib/eaco/error.rb

@@ -0,0 +1,36 @@
+module Eaco
+
+  ##
+  # An Eaco Runtime Error.
+  #
+  class Error < StandardError
+    # As we make use of heredoc for long error messages, squeeze subsequent
+    # spaces and remove newlines.
+    #
+    def initialize(message)
+      unless message =~ %r{EACO.+Error}
+        message = message.squeeze(' ').gsub("\n", '')
+      end
+
+      super message
+    end
+  end
+
+  # Raised when an Actor attempts an unauthorized access to a controller
+  # action that deals with a protected Resource.
+  #
+  # @see Actor
+  # @see Resource
+  # @see Controller
+  #
+  class Forbidden < Error; end
+
+  # Represents a configuration error of the Eaco framework, whether wrong
+  # options or wrong usage of the DSL, or invalid storage options for the
+  # ACL objects and authorized collection extraction strategy.
+  #
+  # @see DSL
+  #
+  class Malformed < Error; end
+
+end

data/lib/eaco/railtie.rb

@@ -0,0 +1,46 @@
+module Eaco
+
+  autoload :Controller, 'eaco/controller'
+
+  ##
+  # Initializer for Rails 3 and up.
+  #
+  # * Parses the configuration rules upon startup and, in development, after a
+  #   console +reload!+.
+  #
+  # * Installs {Controller} authorization filters in +ActionController::Base+.
+  #
+  class Railtie < ::Rails::Railtie
+
+    ##
+    # Calls {Eaco.parse_default_rules_file!}
+    #
+    # @!method parse_rules
+    #
+    initializer 'eaco.parse_rules' do
+      Eaco.parse_default_rules_file!
+
+      unless Rails.configuration.cache_classes
+        ActionDispatch::Reloader.to_prepare do
+          Eaco.parse_default_rules_file!
+        end
+      end
+    end
+
+    ##
+    # Adds {Controller} to +ActionController::Base+
+    #
+    # @!method install_controller_runtime
+    #
+    initializer 'eaco.install_controller_runtime' do
+      ActiveSupport.on_load :action_controller do
+
+        ActionController::Base.instance_eval do
+          include Eaco::Controller
+        end
+
+      end
+    end
+  end
+
+end

data/lib/eaco/rake.rb

@@ -0,0 +1,10 @@
+module Eaco
+
+  ##
+  # Namespace to all rake-related functionality.
+  #
+  module Rake
+    autoload :DefaultTask, 'eaco/rake/default_task.rb'
+  end
+
+end

data/lib/eaco/rake/default_task.rb

@@ -0,0 +1,164 @@
+module Eaco
+  module Rake
+
+    ##
+    # Defines the default Eaco rake task. It runs tests and generates the docs.
+    #
+    # Usage:
+    #
+    #   Eaco::Rake::DefaultTask.new
+    #
+    class DefaultTask
+      include ::Rake::DSL if defined?(::Rake::DSL)
+
+      ##
+      # Main +Eaco+ rake task.
+      #
+      # If running appraisals or running within Travis CI, run all specs and
+      # cucumber features.
+      #
+      # The concept here is to prepare the environment with the gems set we
+      # are testing against, and this is done by Appraisals and Travis, albeit
+      # in a different way. The first uses the +Appraisals+ file, the second
+      # instead relies on the +.travis.yml+ configuration.
+      #
+      # Documentation is generated at the end, once if running locally, but
+      # multiple times, once for each appraisal, on Travis.
+      #
+      def initialize
+        if running_appraisals?
+          task :default do
+            run_specs
+            run_cucumber
+          end
+
+        elsif running_in_travis?
+          task :default do
+            run_specs
+            run_cucumber
+            generate_documentation
+          end
+
+        else
+          desc 'Appraises specs and cucumber, generates documentation'
+          task :default do
+            run_appraisals
+            generate_documentation
+          end
+
+        end
+      end
+
+      ##
+      # Runs all appraisals (see +Appraisals+ in the source root)
+      # against the defined Rails version and generates the source
+      # documentation using Yard.
+      #
+      # Runs them in a subprocess as the appraisals gem makes use
+      # of fork/exec hijacking the process session root.
+      #
+      # @raise [RuntimeError] if the appraisals run fails.
+      #
+      # @return [void]
+      #
+      def run_appraisals
+        croak 'Running all appraisals'
+
+        pid = fork { invoke :appraisal }
+        _, status = Process.wait2(pid)
+        unless status.exitstatus == 0
+          bail "Appraisals failed with status #{status.exitstatus}"
+        end
+      end
+
+      ##
+      # Generate the documentation using +Yard+.
+      #
+      def generate_documentation
+        croak 'Generating documentation'
+
+        invoke :yard
+      end
+
+      ##
+      # Runs all specs under the +spec/+ directory
+      #
+      # @return [void]
+      #
+      def run_specs
+        croak 'Running specs'
+
+        invoke :spec
+      end
+
+      ##
+      # Runs all cucumber features in the +features/+ directory
+      #
+      # @return [void]
+      #
+      def run_cucumber
+        croak 'Evaluating cucumber features'
+
+        invoke :cucumber
+      end
+
+      private
+
+      ##
+      # Invokes the given rake task.
+      #
+      # @param task [Symbol] the task to invoke.
+      # @return [void]
+      #
+      def invoke(task)
+        ::Rake::Task[task].invoke
+      end
+
+      ##
+      # Fancily logs the given +msg+ to +$stderr+.
+      #
+      # @param msg [String] the message to bail out.
+      #
+      # @return [nil]
+      #
+      def croak(msg)
+        $stderr.puts fancy(msg)
+      end
+
+      ##
+      # Bails out the given error message.
+      #
+      # @param msg [String] the message to bail
+      # @raise [RuntimeError]
+      #
+      def bail(msg)
+        raise RuntimeError, fancy(msg)
+      end
+
+      ##
+      # Makes +msg+ fancy.
+      #
+      # @param msg [String]
+      # @return [String]
+      #
+      def fancy(msg)
+        ">>>\n>>> EACO: #{msg}\n>>>\n"
+      end
+
+      ##
+      # @return [Boolean] Are we running appraisals?
+      #
+      def running_appraisals?
+        ENV["APPRAISAL_INITIALIZED"]
+      end
+
+      ##
+      # @return [Boolean] Are we running on Travis CI?
+      #
+      def running_in_travis?
+        ENV["TRAVIS"]
+      end
+    end
+
+  end
+end

data/lib/eaco/resource.rb

@@ -0,0 +1,234 @@
+module Eaco
+
+  ##
+  # A Resource is an object that can be authorized. It has an {ACL}, that
+  # defines the access levels of {Designator}s. {Actor}s have many designators
+  # and the highest priority ones that matches the {ACL} yields the access
+  # level of the {Actor} to this {Resource}.
+  #
+  # If there is no match between the {Actor}'s designators and the {ACL}, then
+  # access is denied.
+  #
+  # Authorized resources are defined through the DSL, see {DSL::Resource}.
+  #
+  # TODO Negative authorizations
+  #
+  # @see ACL
+  # @see Actor
+  # @see Designator
+  #
+  # @see DSL::Resource
+  #
+  module Resource
+
+    # @private
+    def self.included(base)
+      base.extend ClassMethods
+    end
+
+    ##
+    # Singleton methods added to authorized Resources.
+    #
+    module ClassMethods
+      ##
+      # @return [Boolean] checks whether the given +role+ is valid in the
+      # context of this Resource.
+      #
+      # @param role [Symbol] role name.
+      #
+      def role?(role)
+        role.to_sym.in?(roles)
+      end
+
+      ##
+      # Checks whether the {ACL} and permissions defined on this Resource
+      # allow the given +actor+ to perform the given +action+ on it, that
+      # depends on the +role+ the user has on the resource, calculated from
+      # the {ACL}.
+      #
+      # @param action [Symbol]
+      # @param actor [Actor]
+      # @param resource [Resource]
+      #
+      # @return [Boolean]
+      #
+      def allows?(action, actor, resource)
+        return true if actor.is_admin?
+
+        role = role_of(actor, resource)
+        return false unless role
+
+        perms = permissions[role]
+        return false unless perms
+
+        perms.include?(action)
+      end
+
+      ##
+      # @return [Symbol] the given +actor+ role in the given resource, or +nil+ if no
+      # access is granted.
+      #
+      # @param actor_or_designator [Actor or Designator]
+      # @param resource [Resource]
+      #
+      def role_of(actor_or_designator, resource)
+        designators = if actor_or_designator.is_a?(Eaco::Designator)
+          [actor_or_designator]
+
+        elsif actor_or_designator.respond_to?(:designators)
+          actor_or_designator.designators
+
+        else
+          raise Error, <<-EOF
+            #{__method__} expects #{actor_or_designator.inspect}
+            to be a Designator or to `respond_to?(:designators)`
+          EOF
+        end
+
+        role_priority = nil
+        resource.acl.each do |designator, role|
+          if designators.include?(designator)
+            priority = roles_priority[role]
+          end
+
+          if priority && (role_priority.nil? || priority < role_priority)
+            role_priority = priority
+            break if role_priority == 0
+          end
+        end
+
+        roles[role_priority] if role_priority
+      end
+
+      ##
+      # The permissions defined for each role.
+      #
+      # @see DSL::Resource#initialize
+      #
+      def permissions
+      end
+
+      # The defined roles.
+      #
+      # @see DSL::Resource#initialize
+      #
+      def roles
+      end
+
+      # Roles' priority map keyed by role symbol.
+      #
+      # @see DSL::Resource#initialize
+      #
+      def roles_priority
+      end
+
+      # Role labels map keyed by role symbol
+      #
+      # @see DSL::Resource#initialize
+      #
+      def roles_with_labels
+      end
+    end
+
+    ##
+    # @return [Boolean] whether the given +action+ is allowed to the given +actor+.
+    #
+    # @param action [Symbol]
+    # @param actor [Actor]
+    #
+    def allows?(action, actor)
+      self.class.allows?(action, actor, self)
+    end
+
+    ##
+    # @return [Symbol] the role of the given +actor+
+    #
+    # @param actor [Actor]
+    #
+    def role_of(actor)
+      self.class.role_of(actor, self)
+    end
+
+    ##
+    # Grants the given +designator+ access to this Resource as the given +role+.
+    #
+    # @param role [Symbol]
+    # @param designator [Variadic], see {ACL#add}
+    #
+    # @return [ACL]
+    #
+    # @see #change_acl
+    #
+    def grant(role, *designator)
+      self.check_role!(role)
+
+      change_acl {|acl| acl.add(role, *designator) }
+    end
+
+    ##
+    # Revokes the given +designator+ access to this Resource.
+    #
+    # @param designator [Variadic], see {ACL#del}
+    #
+    # @return [ACL]
+    #
+    # @see #change_acl
+    #
+    def revoke(*designator)
+      change_acl {|acl| acl.del(*designator) }
+    end
+
+    # Grants the given set of +designators+ access as to this Resource as the
+    # given +role+.
+    #
+    # @param role [Symbol]
+    # @param designators [Array] of {Designator}, see {ACL#add}
+    #
+    # @return [ACL]
+    #
+    # @see #change_acl
+    #
+    def batch_grant(role, designators)
+      self.check_role!(role)
+
+      change_acl do |acl|
+        designators.each do |designator|
+          acl.add(role, designator)
+        end
+        acl
+      end
+    end
+
+    protected
+      ##
+      # Changes the ACL, calling the persistance setter if it changes.
+      #
+      # @yield [ACL] the current ACL or a new one if no ACL is set
+      #
+      # @return [ACL] the new ACL
+      #
+      def change_acl
+        acl = yield self.acl.try(:dup) || self.class.acl.new
+
+        self.acl = acl unless acl == self.acl
+
+        return self.acl
+      end
+
+      ##
+      # Checks whether the given +role+ is valid for this Resource.
+      #
+      # @param role [Symbol] the role name.
+      #
+      # @raise [Eaco::Error] if not valid.
+      #
+      def check_role!(role)
+        unless self.class.role?(role)
+          raise Error,
+            "The `#{role}' role is not valid for `#{self.class.name}' objects. " \
+            "Valid roles are: `#{self.class.roles.join(', ')}'"
+        end
+      end
+  end
+
+end