eaco 0.5.0

data/lib/eaco/controller.rb

@@ -0,0 +1,158 @@
+require 'active_support/concern'
+
+module Eaco
+
+  ##
+  # An ActionController extension to verify authorization in Rails applications.
+  #
+  # Tested on Rails 3.2 and up on Ruby 2.0 and up.
+  #
+  module Controller
+    extend ActiveSupport::Concern
+
+    ##
+    # Controller authorization DSL.
+    #
+    module ClassMethods
+
+      ##
+      # Defines the ability required to access a given controller action.
+      #
+      # Example:
+      #
+      #   class DocumentsController < ApplicationController
+      #     authorize :index,           [:folder, :index]
+      #     authorize :show,            [:folder, :read]
+      #     authorize :create, :update, [:folder, :write]
+      #   end
+      #
+      # Here +@folder+ is expected to be an authorized +Resource+, and for the
+      # +index+ action the +current_user+ is checked to +can?(:index, @folder)+
+      # while for +show+, +can?(:read, @folder)+ and for +create+ and +update+
+      # checks that it +can?(:write, @folder)+.
+      #
+      # The special +:all+ action name requires the given ability on the given
+      # Resource for all actions.
+      #
+      # If an action has no authorization defined, access is granted.
+      #
+      # Adds {Controller#confront_eaco} as a +before_filter+.
+      #
+      # @param actions [Variadic] see above.
+      #
+      # @return void
+      #
+      def authorize(*actions)
+        target = actions.pop
+
+        actions.each {|action| authorization_permissions.update(action => target)}
+
+        @_eaco_filter_installed ||= begin
+          before_filter :confront_eaco
+          true
+        end
+      end
+
+      ##
+      # @return [Symbol] the permission required to access the given action.
+      #
+      def permission_for(action)
+        authorization_permissions[action] || authorization_permissions[:all]
+      end
+
+      protected
+        ##
+        # Permission requirements configured on this controller.
+        #
+        def authorization_permissions
+          @_authorization_permissions ||= {}
+        end
+    end
+
+    ##
+    # Asks Eaco whether thou shalt pass or not.
+    #
+    # The implementation is left in this method's body, despite a bit long for
+    # many's taste, as it is pretty imperative and simple code. Moreover, the
+    # less we pollute ActionController's namespace, the better.
+    #
+    # @return [void]
+    #
+    # @raise [Error] if the instance variable configured in {.authorize} is not found
+    # @raise [Forbidden] if the +current_user+ is not granted access.
+    #
+    #
+    # == La Guardiana
+    #                                            /\
+    #                           .-_-.           /  \
+    #                  ||   .-.(    .' .-.   // \  /
+    #                   \\\/ (((\   /)))  \ / // )(
+    #                    ) '._  ,-.   ___. )/ //(__)
+    #                    \_((( (  :)  \)))/ ,  / ||
+    #                     \_  \ '-' /_   /| ),// ||
+    #                       \ (_._.'_ \ (o__//  _||_
+    #                        \ )\  .(/ /  __)   \   \
+    #                        ( \ '_  .'  /(      |-. \
+    #                         \_'._'.\__/))))    (__)'.'.
+    #                        _._   |  |    _.-._ ||   \ '.
+    #                       / //--'  / '--//'-'/\||____\  '.
+    #                       \---.\ .----.//  //  ||//  '\   \
+    #                      /   ' \/    ' \\__\\ ,||\\_______.'
+    #                      \\___//\\____//\____\ ||
+    #           _.-'''---. /\___/  \____/  \\/   ||
+    #        ..'_.''''---.|   /.  \        /     ||
+    #      .'.-'O    __  /  _/  )_.--.____(      ||
+    #     / / /  \__/  /'  /\ \(__.--._____)     ||
+    #     | |    /\ \  \_.' | |   \      |       ||
+    #     \  '.__\,_.'.__/./ /     ) .   |\      ||
+    #      '..__ O --' ___..'     /\     /|'.    ||
+    #           ''----'           | \/\.' / /'.  ||
+    #                             |\(()).' /   \ ||
+    #                           _/ \ \/   /     \||
+    #                   __..--''    '.   |      |||
+    #               .-''            / '._|/     |||
+    #              /                __.- /      /||
+    #              \   ____..-----''    /      | ||
+    #               '.     )).         |       / ||
+    #                 ''._//  \        .-----./  ||
+    #                     '.   \      (.-----.)  ||
+    #                       '.  \      |    /    ||
+    #                         )_ \     |   |     ||
+    #                        /__'O\    ( ) (     ||
+    #          _______mrf,-'____/|/__   |\  \    ||
+    #                                   |    |   ||
+    #                                   |____)  (__)
+    #                                   '-----'  ||
+    #                                    \   |   ||
+    #                                     \  |   ||
+    #                                      \ |   ||
+    #                                       | \  ||
+    #                                       |_ \ ||
+    #                                       /_'O\||
+    #                                    .-'___/(__)
+    #
+    #                                    http://ascii.co.uk/art/guardiana
+    #
+    def confront_eaco
+      action = params[:action].intern
+      resource_ivar, permission = self.class.permission_for(action)
+
+      if resource_ivar && permission
+        resource = instance_variable_get(['@', resource_ivar].join.intern)
+
+        if resource.nil?
+          raise Error, <<-EOF
+            @#{resource_ivar} is not set, can't authorize #{self}##{action}
+          EOF
+        end
+
+        unless current_user.can? permission, resource
+          raise Forbidden, <<-EOF
+            `#{current_user}' not authorized to `#{action}' on `#{resource}'
+          EOF
+        end
+      end
+    end
+  end
+
+end

data/lib/eaco/cucumber.rb

@@ -0,0 +1,11 @@
+module Eaco
+
+  ##
+  # Namespace that holds all cucumber-related helpers.
+  #
+  module Cucumber
+    autoload :ActiveRecord, 'eaco/cucumber/active_record.rb'
+    autoload :World,        'eaco/cucumber/world.rb'
+  end
+
+end

data/lib/eaco/cucumber/active_record.rb

@@ -0,0 +1,163 @@
+begin
+  require 'active_record'
+rescue LoadError
+  abort "ActiveRecord requires the rails appraisal. Try `appraisal cucumber`"
+end
+
+require 'yaml'
+
+module Eaco
+  module Cucumber
+
+    ##
+    # +ActiveRecord+ configuration and connection.
+    #
+    # Database configuration is looked up in +features/active_record.yml+ by
+    # default. Logs are sent to +features/active_record.log+, truncating the
+    # file at each run.
+    #
+    # Environment variables:
+    #
+    # * +EACO_AR_CONFIG+ specify a different +ActiveRecord+ configuration file
+    # * +VERBOSE+ log to +stderr+
+    #
+    module ActiveRecord
+      autoload :Document,   'eaco/cucumber/active_record/document'   # Resource
+      autoload :User,       'eaco/cucumber/active_record/user'       # Actor
+      autoload :Department, 'eaco/cucumber/active_record/department' # Designator source
+      autoload :Position,   'eaco/cucumber/active_record/position'   # Designator source
+
+      extend self
+
+      ##
+      # Looks up ActiveRecord and sets the +logger+.
+      #
+      # @return [Class] +ActiveRecord::Base+
+      #
+      def active_record
+        @_active_record ||= ::ActiveRecord::Base.tap do |active_record|
+          active_record.logger = ::Logger.new(active_record_log).tap {|l| l.level = 0}
+        end
+      end
+
+      ##
+      # Log to stderr if +VERBOSE+ is given, else log to
+      # +features/active_record.log+
+      #
+      # @return [IO] the log destination
+      #
+      def active_record_log
+        @_active_record_log ||= ENV['VERBOSE'] ? $stderr :
+          'features/active_record.log'.tap {|f| File.open(f, "w+")}
+      end
+
+      ##
+      # @return [Logger] the logger configured, logging to {.active_record_log}.
+      #
+      def logger
+        active_record.logger
+      end
+
+      ##
+      # @return [ActiveRecord::Connection] the current +ActiveRecord+ connection
+      # object.
+      #
+      def connection
+        active_record.connection
+      end
+      alias adapter connection
+
+      ##
+      # Returns an Hash wit the database configuration.
+      #
+      # Caveat:the returned +Hash+ has a custom +.to_s+ method that formats
+      # the configuration as a +pgsql://+ URL.
+      #
+      # @return [Hash] the current database configuration
+      #
+      # @see {#config_file}
+      #
+      def configuration
+        @_config ||= YAML.load(config_file.read).tap do |conf|
+          def conf.to_s
+            'pgsql://%s:%s@%s/%s' % values_at(
+              :username, :password, :hostname, :database
+            )
+          end
+        end
+      end
+
+      ##
+      # @return [Pathname] the currently configured configuration file. Override
+      #                    using the +EACO_AR_CONFIG' envinronment variable.
+      #
+      def config_file
+        Pathname.new(ENV['EACO_AR_CONFIG'] || default_config_file)
+      end
+
+      ##
+      # @return [String] +active_record.yml+ relative to this source file.
+      #
+      # @raise [Errno::ENOENT] if the configuration file is not found.
+      #
+      def default_config_file
+        Pathname.new('features/active_record.yml').realpath
+
+      rescue Errno::ENOENT => error
+        raise error.class.new, <<-EOF.squeeze(' ')
+
+          #{error.message}.
+
+          Please define your Active Record database configuration in the
+          default location, or specify your configuration file location by
+          passing the `EACO_AR_CONFIG' environment variable.
+        EOF
+      end
+
+      ##
+      # Establish ActiveRecord connection using the given configuration hash
+      #
+      # @param config [Hash] the configuration to use, {#configuration} by default.
+      #
+      # @return [ActiveRecord::ConnectionAdapters::ConnectionPool]
+      #
+      # @raise [ActiveRecord::ActiveRecordError] if cannot connect
+      #
+      def connect!(config = self.configuration)
+        unless ENV['VERBOSE']
+          config = config.merge(min_messages: 'WARNING')
+        end
+
+        active_record.establish_connection(config)
+      end
+
+      ##
+      # Loads the defined {ActiveRecord#schema}
+      #
+      # @return [nil]
+      #
+      def define_schema!
+        load 'eaco/cucumber/active_record/schema.rb'
+      end
+
+      ##
+      # Drops and recreates the database specified in the {#configuration}.
+      #
+      # TODO untangle from postgres
+      #
+      # @return [void]
+      #
+      def recreate_database!
+        database = config.fetch(:database)
+        connect! config.merge(database: :postgres) # FIXME
+
+        connection.drop_database   database
+        connection.create_database database
+        connect! config
+
+        logger.info "Connected to #{config}"
+      end
+    end
+
+  end
+end

data/lib/eaco/cucumber/active_record/department.rb

@@ -0,0 +1,19 @@
+module Eaco
+  module Cucumber
+    module ActiveRecord
+
+      ##
+      # A department holds many {Position}s.
+      #
+      # For the background story, see {Eaco::Cucumber::World}.
+      #
+      # @see Position
+      # @see Eaco::Actor
+      # @see Eaco::Cucumber::World
+      #
+      class Department < ::ActiveRecord::Base
+      end
+
+    end
+  end
+end

data/lib/eaco/cucumber/active_record/document.rb

@@ -0,0 +1,18 @@
+module Eaco
+  module Cucumber
+    module ActiveRecord
+
+      ##
+      # This is an example of a {Eaco::Resource} that can be protected by an
+      # {Eaco::ACL}. For the background story, see {Eaco::Cucumber::World}.
+      #
+      # @see User
+      # @see Eaco::Resource
+      # @see Eaco::Cucumber::World
+      #
+      class Document < ::ActiveRecord::Base
+      end
+
+    end
+  end
+end

data/lib/eaco/cucumber/active_record/position.rb

@@ -0,0 +1,21 @@
+module Eaco
+  module Cucumber
+    module ActiveRecord
+
+      ##
+      # A Position is occupied by an {User} in a {Department}.
+      #
+      # For the background story, see {Eaco::Cucumber::World}.
+      #
+      # @see User
+      # @see Department
+      # @see Eaco::Cucumber::World
+      #
+      class Position < ::ActiveRecord::Base
+        belongs_to :user
+        belongs_to :department
+      end
+
+    end
+  end
+end

data/lib/eaco/cucumber/active_record/schema.rb

@@ -0,0 +1,36 @@
+module Eaco
+  module Cucumber
+    module ActiveRecord
+
+      # @!method schema
+      #
+      # Defines the database schema for the {Eaco::Cucumber::World} scenario.
+      #
+      # @see Eaco::Cucumber::World
+      #
+      ::ActiveRecord::Schema.define(version: '2015022301') do
+        create_table 'documents', force: true do |t|
+          t.string :name
+          t.text   :contents
+          t.column :acl, :jsonb
+        end
+
+        create_table 'users', force: true do |t|
+          t.string :name
+        end
+
+        create_table 'departments', force: true do |t|
+          t.string :abbr
+        end
+
+        create_table 'positions', force: true do |t|
+          t.string :job_title
+
+          t.references :user
+          t.references :department
+        end
+      end
+
+    end
+  end
+end

data/lib/eaco/cucumber/active_record/user.rb

@@ -0,0 +1,24 @@
+module Eaco
+  module Cucumber
+    module ActiveRecord
+
+      ##
+      # This is an example of a {Eaco::Actor} that can be authorized against
+      # the ACLs in a resource, such as the example {Document}.
+      #
+      # For the background story, see {Eaco::Cucumber::World}.
+      #
+      # @see Document
+      # @see Eaco::Actor
+      # @see Eaco::Cucumber::World
+      #
+      class User < ::ActiveRecord::Base
+        autoload :Designators, 'lib/eaco/cucumber/designators.rb'
+
+        has_many :positions
+        has_many :departments, through: :positions
+      end
+
+    end
+  end
+end