eaco 0.5.0

data/lib/eaco/dsl/actor.rb

@@ -0,0 +1,139 @@
+module Eaco
+  module DSL
+
+    ##
+    # Parses the Actor DSL, that describes how to harvest {Designator}s from
+    # an {Actor} and how to identify it as an +admin+, or superuser.
+    #
+    #   actor User do
+    #     admin do |user|
+    #       user.admin?
+    #     end
+    #
+    #     designators do
+    #       authenticated from: :class
+    #       user          from: :id
+    #       group         from: :group_ids
+    #     end
+    #   end
+    #
+    class Actor < Base
+      autoload :Designators, 'eaco/dsl/actor/designators'
+
+      ##
+      # Initializes an Actor class.
+      #
+      # @see Eaco::Actor
+      #
+      def initialize(*)
+        super
+
+        target_eval do
+          include Eaco::Actor
+
+          def designators
+            @_designators
+          end
+
+          def admin_logic
+            @_admin_logic
+          end
+        end
+      end
+
+      ##
+      # Defines the designators that apply to this {Actor}.
+      #
+      # Example:
+      #
+      #   actor User do
+      #     designators do
+      #       authenticated from: :class
+      #       user          from: :id
+      #       group         from: :group_ids
+      #     end
+      #   end
+      #
+      # {Designator} names are collected using +method_missing+, and are
+      # named after the method name. Implementations are looked up in
+      # a +Designators+ module in the {Actor}'s class.
+      #
+      # Each designator implementation is expected to be named after the
+      # designator's name, camelized, and inherit from {Eaco::Designator}.
+      #
+      # TODO all designators share the same namespace. This is due to the
+      # fact that designator string representations aren't scoped by the
+      # Actor model they belong to. As such when instantiating a designator
+      # from +Eaco::Designator.make+ the registry is consulted to find the
+      # designator implementation.
+      #
+      # @see DSL::Actor::Designators
+      #
+      def designators(&block)
+        new_designators = target_eval do
+          @_designators = Designators.eval(self, &block).result.freeze
+        end
+
+        Actor.register_designators(new_designators)
+      end
+
+      ##
+      # Defines the boolean logic that determines whether an {Actor} is an
+      # admin. Usually you'll have an +admin+ method on your model, that you
+      # can call from here. Or, feel free to just return +false+ to disable
+      # this functionality.
+      #
+      # Example:
+      #
+      #   actor User do
+      #     admin do |user|
+      #       user.admin?
+      #     end
+      #   end
+      #
+      def admin(&block)
+        target_eval do
+          @admin_logic = block
+        end
+      end
+
+      class << self
+        ##
+        # Looks up the given designator implementation by its +name+.
+        #
+        # @param name [Symbol] the designator name.
+        #
+        # @raise [Eaco::Malformed] if the designator is not found.
+        #
+        # @return [Class]
+        #
+        def find_designator(name)
+          all_designators.fetch(name.intern)
+
+        rescue KeyError
+          raise Malformed, "Designator not found: #{name.inspect}"
+        end
+
+        ##
+        # Saves the given designators in the global designators registry.
+        #
+        # @param new_designators [Hash]
+        #
+        # @return [Hash] the designators registry.
+        #
+        def register_designators(new_designators)
+          all_designators.update(new_designators)
+        end
+
+        private
+          ##
+          # @return [Hash] a registry of all the defined designators.
+          #
+          def all_designators
+            @_all_designators ||= {}
+          end
+      end
+    end
+
+  end
+end

data/lib/eaco/dsl/actor/designators.rb

@@ -0,0 +1,110 @@
+module Eaco
+  module DSL
+    class Actor < Base
+
+      ##
+      # Designators collector using +method_missing+.
+      #
+      # Parses the following DSL:
+      #
+      #   actor User do
+      #     designators do
+      #       authenticated from: :class
+      #       user          from: :id
+      #       group         from: :group_ids
+      #     end
+      #   end
+      #
+      # and looks up within the Designators namespace of the Actor model the
+      # concrete implementations of the described designators.
+      #
+      # Here the User model is expected to define an User::Designators module
+      # and to implement within it a +class Authenticated < Eaco::Designator+
+      #
+      # @see Designator
+      #
+      class Designators < Base
+        ##
+        # Sets up the designators registry.
+        #
+        def initialize(*)
+          super
+
+          @designators = {}
+        end
+
+        ##
+        # The parsed designators, keyed by type symbol and with concrete
+        # implementations as values.
+        #
+        # @return [Hash]
+        #
+        attr_reader :designators
+        alias result designators
+
+        private
+          ##
+          # Looks up the implementation for the designator of the given
+          # +name+, configures it with the given +options+ and saves it in
+          # the designators registry.
+          #
+          # @param name [Symbol]
+          # @param options [Hash]
+          #
+          # @return [Class]
+          #
+          # @see #implementation_for
+          #
+          def define_designator(name, options)
+            designators[name] = implementation_for(name).configure!(options)
+          end
+          alias method_missing define_designator
+
+          ##
+          # Looks up the +name+ designator implementation in the {Actor}'s
+          # +Designators+ namespace.
+          #
+          # @param name [Symbol]
+          #
+          # @return [Class]
+          #
+          # @raise [Malformed] if the implementation class is not found.
+          #
+          # @see #container
+          # @see Designator.type
+          #
+          def implementation_for(name)
+            impl = name.to_s.camelize.intern
+
+            unless container.const_defined?(impl)
+              raise Malformed, <<-EOF
+                Implementation #{container}::#{impl} for Designator #{name} not found.
+              EOF
+            end
+
+            container.const_get(impl)
+          end
+
+          ##
+          # Looks up the +Designators+ namespace within the {Actor}'s class.
+          #
+          # @return [Class]
+          #
+          # @raise Malformed if the +Designators+ module cannot be found.
+          #
+          # @see #implementation_for
+          #
+          def container
+            @_container ||= begin
+              unless target.const_defined?(:Designators)
+                raise Malformed, "Please put designators implementations in #{target}::Designators"
+              end
+
+              target.const_get(:Designators)
+            end
+          end
+      end
+
+    end
+  end
+end

data/lib/eaco/dsl/base.rb

@@ -0,0 +1,52 @@
+module Eaco
+  module DSL
+
+    ##
+    # Base DSL class. Provides handy access to the +target+ class being
+    # manipulated, DSL-specific options, and a {#target_eval} helper to do
+    # +instance_eval+ on the +target+.
+    #
+    # Nothing too fancy.
+    #
+    class Base
+
+      ##
+      # Executes a DSL block in the context of a DSL manipulator.
+      #
+      # @see DSL::ACL
+      # @see DSL::Actor
+      # @see DSL::Resource
+      #
+      # @return [Base]
+      #
+      def self.eval(klass, options = {}, &block)
+        new(klass, options).tap do |dsl|
+          dsl.instance_eval(&block) if block
+        end
+      end
+
+      # The target class of the manipulation
+      attr_reader :target
+
+      # DSL-specific options
+      attr_reader :options
+
+      ##
+      # @param target [Class]
+      # @param options [Hash]
+      #
+      def initialize(target, options)
+        @target, @options = target, options
+      end
+
+      protected
+        ##
+        # Evaluates the given block in the context of the target class
+        #
+        def target_eval(&block)
+          target.instance_eval(&block)
+        end
+    end
+
+  end
+end

data/lib/eaco/dsl/resource.rb

@@ -0,0 +1,129 @@
+module Eaco
+  module DSL
+
+    ##
+    # Parses the Resource definition DSL.
+    #
+    # Example:
+    #
+    #   authorize Document do
+    #     roles :owner, :editor, :reader
+    #
+    #     role :owner, 'Author'
+    #
+    #     permissions do
+    #       reader   :read
+    #       editor   reader, :edit
+    #       owner    editor, :destroy
+    #     end
+    #   end
+    #
+    # The DSL installs authorization in your +Document+ model,
+    # defining three access roles.
+    #
+    # The +owner+ role is given a label of "Author".
+    #
+    # Each role has then different abilities, defined in the
+    # permissions block.
+    #
+    # @see DSL::Resource::Permissions
+    #
+    class Resource < Base
+      autoload :Permissions, 'eaco/dsl/resource/permissions'
+
+      ##
+      # Sets up an authorized resource. The only required API
+      # is +accessible_by+. For available implementations, see
+      # the {Adapters} module.
+      #
+      # @see Resource
+      #
+      def initialize(*)
+        super
+
+        target_eval do
+          include Eaco::Resource
+
+          def permissions
+            @_permissions
+          end
+
+          def roles
+            @_roles || []
+          end
+
+          def roles_priority
+            @_roles_priority ||= {}.tap do |priorities|
+              roles.each_with_index {|role, idx| priorities[role] = idx }
+            end.freeze
+          end
+
+          def roles_with_labels
+            @_roles_with_labels ||= roles.inject({}) do |labels, role|
+              labels.update(role => role.to_s.humanize)
+            end
+          end
+
+          # Reset memoizations when this method is called on the target class,
+          # so that reloading the authorizations configuration file will
+          # refresh the models' configuration.
+          @_roles_priority = nil
+          @_roles_with_labels = nil
+        end
+      end
+
+      ##
+      # Defines the permissions on this resource.
+      # The evaluated registries are memoized in the target class.
+      #
+      # @return [void]
+      #
+      def permissions(&block)
+        target_eval do
+          @_permissions = Permissions.eval(self, &block).result.freeze
+        end
+      end
+
+      ##
+      # Defines the roles valid for this resource. e.g.
+      #
+      #     authorize Foobar do
+      #       roles :owner, :editor, :reader
+      #     end
+      #
+      # Roles defined first have higher priority.
+      #
+      # If the same user is at the same time +reader+ and +editor+, the
+      # resulting role is +editor+.
+      #
+      # @param keys [Variadic]
+      #
+      # @return [void]
+      #
+      def roles(*keys)
+        target_eval do
+          @_roles = keys.flatten.freeze
+        end
+      end
+
+      ##
+      # Sets the given label on the given role.
+      #
+      # TODO rename this method, or use it to pass options
+      # to improve readability of the DSL and to store more
+      # metadata with each role for future extensibility.
+      #
+      # @param role [Symbol]
+      # @param label [String]
+      #
+      # @return [void]
+      #
+      def role(role, label)
+        target_eval do
+          roles_with_labels[role] = label
+        end
+      end
+    end
+
+  end
+end

data/lib/eaco/dsl/resource/permissions.rb

@@ -0,0 +1,131 @@
+module Eaco
+  module DSL
+    class Resource < Base
+
+      ##
+      # Permission collector, based on +method_missing+.
+      #
+      # Example:
+      #
+      #   1 authorize Foobar do
+      #   2   permissions do
+      #   3     reader :read_foo, :read_bar
+      #   4     editor reader, :edit_foo, :edit_bar
+      #   5     owner  editor, :destroy
+      #   6   end
+      #   7 end
+      #
+      # Within the block, each undefined method call defines a new
+      # method that returns the given arguments.
+      #
+      # After evaluating line 3 above:
+      #
+      #   >> reader
+      #   => #<Set{ :read_foo, :read_bar }>
+      #
+      # The method is used then on line 4, giving the +editor+ role the
+      # same set of permissions granted to the +reader+, plus its own
+      # set of permissions:
+      #
+      #   >> editor
+      #   => #<Set{ :read_foo, :read_bar, :edit_foo, :edit_bar }>
+      #
+      class Permissions < Base
+
+        ##
+        # Evaluates the given block in the context of a new collector
+        #
+        # Returns an Hash of permissions, keyed by role.
+        #
+        #   >> Permissions.eval do
+        #    |   permissions do
+        #    |     reader :read
+        #    |     editor reader, :edit
+        #    |   end
+        #    | end
+        #
+        #   => {
+        #    |   reader: #<Set{ :read },
+        #    |   editor: #<Set{ :read, :edit }
+        #    | }
+        #
+        # @return [Permissions]
+        #
+        def self.eval(*, &block)
+          super
+        end
+
+        ##
+        # Sets up an hash with a default value of a new Set.
+        #
+        def initialize(*)
+          super
+
+          @permissions = Hash.new {|hsh, key| hsh[key] = Set.new}
+        end
+
+        ##
+        # Returns the collected permissions in a plain Hash, lacking the
+        # default block used by the collector's internals - to give to
+        # the outside an Hash with a predictable behaviour :-).
+        #
+        # @return [Hash]
+        #
+        def result
+          Hash.new.merge(@permissions)
+        end
+
+        private
+          ##
+          # Here the method name is the role code. If we already have defined
+          # permissions for the given role, those are returned.
+          #
+          # Else, {#save_permission} is called to memoize the given permissions
+          # for the +role+.
+          #
+          # @param role [Symbol]
+          # @param permissions [Array] permissions to grant to the given +role+.
+          #
+          # @return [Set]
+          #
+          def method_missing(role, *permissions)
+            if @permissions.key?(role)
+              @permissions[role]
+            else
+              save_permission(role, permissions)
+            end
+          end
+
+          ##
+          # Memoizes the given set of permissions for the given role.
+          #
+          # @param role [Symbol]
+          # @param permissions [Array]
+          #
+          # @return [Set]
+          #
+          # @raise [Malformed] if the syntax is not valid.
+          #
+          def save_permission(role, permissions)
+            permissions = permissions.inject(Set.new) do |set, perm|
+              if perm.is_a?(Symbol)
+                set.add perm
+
+              elsif perm.is_a?(Set)
+                set.merge perm
+
+              else
+                raise Malformed, <<-EOF
+                  Invalid #{role} permission definition: #{perm.inspect}.
+                  Permissions can be defined only by plain symbols.
+                EOF
+              end
+            end
+
+            @permissions[role].merge(permissions)
+          end
+      end
+
+    end
+  end
+end