trust 0.5.0

data/lib/trust/controller/resource.rb

@@ -0,0 +1,306 @@
+# Copyright (c) 2012 Bingo Entreprenøren AS
+# Copyright (c) 2012 Teknobingo Scandinavia AS
+# Copyright (c) 2012 Knut I. Stenmark
+# Copyright (c) 2012 Patrick Hanevold
+#
+# Permission is hereby granted, free of charge, to any person obtaining
+# a copy of this software and associated documentation files (the
+# "Software"), to deal in the Software without restriction, including
+# without limitation the rights to use, copy, modify, merge, publish,
+# distribute, sublicense, and/or sell copies of the Software, and to
+# permit persons to whom the Software is furnished to do so, subject to
+# the following conditions:
+#
+# The above copyright notice and this permission notice shall be
+# included in all copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+# EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+# MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+# NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+# LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+# OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+# WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+module Trust
+  module Controller
+    class Resource
+# = Trust::Controller::Resource 
+# Collects information about the current resource and relations. 
+# Handles the loading of the resource and its possible parent, i.e. setting the relevant instance variables
+# It assumes the name of the resource is built on the controllers name, but this can be overridden in your
+# controller by setting the +model+
+#
+# Examples:
+#
+#    # controller name AccountsController
+#    resource.instance # => @account
+#
+#    # controller name Customer::AccountsController
+#    resource.instance # => @customer_account
+#
+      
+      delegate :logger, :to => Rails
+      attr_reader :properties, :params, :action
+      attr_reader :info, :parent_info, :relation
+
+      def initialize(controller, properties, action_name, params, request) # nodoc
+        @action = action_name.to_sym
+        
+        @controller, @properties, @params = controller, properties, params
+        @info = extract_resource_info(properties.model, params)
+        if properties.has_associations?
+          @parent_info = extract_parent_info(properties.associations, params, request)
+        end
+        @relation = @info.relation(@parent_info)
+      end
+
+      # Returns the instance variable in the controller
+      def instance
+        @controller.instance_variable_get(:"@#{instance_name}")
+      end
+      
+      # Sets the instance variable
+      # Normally set by +load+
+      # You can access this method from the resource object.
+      #
+      # ==== Example
+      #
+      #    resource.instance = Account.find_by_number(123456)
+      def instance=(instance)
+        @controller.instance_variable_set(:"@#{instance_name}", instance)
+      end      
+      
+      # Returns the parameters for the instance
+      #
+      # ==== Example
+      #
+      #     # in AccountsController
+      #     resource.instance_params  # same as params[:account]
+      def instance_params
+        info.params
+      end
+
+      # Returns the parents instance variable when you use +belongs_to+ for nested routes
+      def parent
+        @controller.instance_variable_get(:"@#{parent_name}")
+      end
+      
+      # Sets the parent instance variable
+      def parent=(instance)
+        @controller.instance_variable_set(:"@#{parent_name}", instance)
+      end
+
+      # Returns the cinstance variable for ollection
+      def instances
+        @controller.instance_variable_get(:"@#{plural_instance_name}")
+      end
+
+      # Sets the instance variable for collection
+      # You may want to set this variable in your index action, we do not yet support loading of collections
+      def instances=(instances)
+        @controller.instance_variable_set(:"@#{plural_instance_name}", instances)
+      end
+
+      # Returns either the instances or the instance. 
+      # We have found that this can be useful in some implementation patterns
+      def instantiated
+        instances || instance
+      end
+
+      # Returns the class for the resource
+      def klass
+        info.klass
+      end
+
+      # Loads the resource 
+      # See Trust::Controller::Properties which controls the behavior of this method.
+      # It will normally find the instance variable for existing object or initialize them as new.
+      # If using nested resources and +belongs_to+ has been declared in the controller it will use the 
+      # parent relation if found.
+      def load
+        self.parent = parent_info.object if parent_info
+        if properties.new_actions.include?(action)
+#          logger.debug "Trust.load: Setting new: class: #{klass} info.params: #{info.params.inspect}"
+          self.instance ||= relation.new(info.params)
+          @controller.send(:build, action) if @controller.respond_to?(:build)
+        elsif properties.member_actions.include?(action)
+#          logger.debug "Trust.load: Finding parent: #{parent.inspect}, relation: #{relation.inspect}"
+          self.instance ||= relation.find(params[:id])
+          @controller.send(:build, action) if @controller.respond_to?(:build)
+        else # other outcome would be collection actions
+#          logger.debug "Trust.load: Parent is: #{parent.inspect}, collection or unknown action."
+        end 
+      end
+      
+      # Returns the name of the instance for the resource
+      # ==== Example
+      #
+      #     # in AccountsController
+      #     resource.instance_name  # => :account
+      def instance_name
+        info.name
+      end
+      
+      # Returns the plural name of the instance for the resource
+      # ==== Example
+      #
+      #     # in AccountsController
+      #     resource.plural_instance_name  # => :accounts
+      def plural_instance_name
+        info.plural_name
+      end
+      
+      # Returns the name of the parent resource
+      # ==== Example
+      #
+      #     # in AccountsController where belongs_to :customer has been declared
+      #     resource.parent_name  # => :customer
+      def parent_name
+        parent_info && parent_info.name
+      end
+      
+      
+    private
+      def extract_resource_info(model, params) # nodoc
+        ResourceInfo.new(model, params)
+      end
+      
+      def extract_parent_info(associations, params, request) #nodoc
+        ParentInfo.new(associations, params, request)
+      end      
+    end
+
+    # ResorceInfo resolves information about the resource accessed in action controller
+    #
+    # Examples in PeopleController (simple case)
+    # ===
+    #   resource.info.klass => Person
+    #   resource.info.params => {:person => {...}}       # fetches the parameters for the resource
+    #   resource.info.name => :person
+    #   resource.info.plural_name => :people
+    #   resource.info.path => 'people'                   # this is the controller_path
+    #
+    # Examples in Lottery::AssignmentsController (with name space)
+    # ===
+    #   resource.info.klass => Lottery::Assignment
+    #   resource.info.params => {:lottery_assignment => {...}}
+    #   resource.info.name => :lottery_assignment
+    #   resource.info.plural_name => :lottery_assignments
+    #   resource.info.path => 'lottery/assignments'      # this is the controller_path
+    #
+    # Examples in ArchiveController (with inheritance) 
+    # Assumptions on routes:
+    #   resources :archives
+    #   resources :secret_acrvives, :controller => :archives
+    #   resources :public_acrvives, :controller => :archives
+    # examples below assumes that the route secret_arcives is being accessed at the moment
+    # ===
+    #   resource.info.klass => Archive
+    #   resource.info.params => {:secret_archive => {...}}
+    #   resource.info.name => :archive
+    #   resource.info.plural_name => :archives
+    #   resource.info.path => 'archive'                   # this is the controller_path
+    #   resource.info.real_class => SecretArchive         # Returns the real class which is accessed at the moment
+    #
+    
+    class Resource::Info
+      attr_reader :klass, :params, :name, :path, :real_class
+      
+      def params
+        @data
+      end
+   
+    protected
+      def self.var_name(klass)
+        klass.to_s.underscore.tr('/','_').to_sym
+      end
+      def var_name(klass)
+        self.class.var_name(klass)
+      end
+    end
+    
+
+    class Resource::ResourceInfo < Resource::Info
+
+      def initialize(model, params)
+        @path, params = model, params
+        @klass = model.to_s.classify.constantize
+        @name = model.to_s.singularize.underscore.gsub('/','_').to_sym
+        ptr = @klass.descendants.detect do |c|
+          params.key? var_name(c)
+        end || @klass
+        @real_class = ptr
+        @data = params[var_name(ptr)]
+      end
+
+      def plural_name
+        @plural_name ||= path.underscore.tr('/','_').to_sym
+      end
+
+      # returns an accessor for association. Tries with full name association first, and if that does not match, tries the demodularized association.
+      #
+      # Explanation:
+      #   Assuming 
+      #     resource is instance of Lottery::Package #1 (@lottery_package)
+      #     association is Lottery::Prizes
+      #     if association is named lottery_prizes, then that association is returned
+      #     if association is named prizes, then that association is returned
+      #   
+      def relation(associated_resource)
+        if associated_resource && associated_resource.object
+          name = associated_resource.as || plural_name
+          associated_resource.klass.reflect_on_association(name) ? 
+            associated_resource.object.send(name) : associated_resource.object.send(klass.to_s.demodulize.underscore.pluralize)
+        else
+          klass
+        end
+      end
+    end
+
+    class Resource::ParentInfo < Resource::Info
+      attr_reader :object,:as
+      def initialize(resources, params, request)
+        ptr = resources.detect do |r,as|
+          @klass = classify(r)
+          @as = as
+          ([@klass] + @klass.descendants).detect do |c|
+            @name = c.to_s.underscore.tr('/','_').to_sym
+            unless @id = request.symbolized_path_parameters["#{@name}_id".to_sym]
+              # see if name space handling is necessary
+              if c.to_s.include?('::')
+                @name = c.to_s.demodulize.underscore.to_sym
+                @id = request.symbolized_path_parameters["#{@name}_id".to_sym]
+              end
+            end
+            @id
+          end
+          @id
+        end
+        if ptr
+          @object = @klass.find(@id)
+        else
+          @klass = @name = nil
+        end
+        @data = params[var_name(ptr)]
+      end
+
+      def object?
+        !!@object
+      end
+
+      def real_class
+        @object && @object.class
+      end
+    private
+      def classify(resource)
+        case resource
+        when Symbol, String
+          resource.to_s.classify.constantize
+        else
+          resource
+        end
+      end
+    end
+  end
+end

data/lib/trust/controller.rb

@@ -0,0 +1,197 @@
+# Copyright (c) 2012 Bingo Entreprenøren AS
+# Copyright (c) 2012 Teknobingo Scandinavia AS
+# Copyright (c) 2012 Knut I. Stenmark
+# Copyright (c) 2012 Patrick Hanevold
+#
+# Permission is hereby granted, free of charge, to any person obtaining
+# a copy of this software and associated documentation files (the
+# "Software"), to deal in the Software without restriction, including
+# without limitation the rights to use, copy, modify, merge, publish,
+# distribute, sublicense, and/or sell copies of the Software, and to
+# permit persons to whom the Software is furnished to do so, subject to
+# the following conditions:
+#
+# The above copyright notice and this permission notice shall be
+# included in all copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+# EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+# MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+# NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+# LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+# OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+# WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+module Trust
+  module Controller
+    autoload :Resource,           'trust/controller/resource'
+    autoload :Properties,         'trust/controller/properties'
+    
+    extend ActiveSupport::Concern
+        
+    module ClassMethods
+      
+      # Returns the controller Trust::Controller::Properties.
+      # If no properties are instantiated, it will be instantiated
+      # 
+      # == Delegated methods
+      #
+      # The following methods are delegated to properties. See Trust::Controller::Properties for details
+      # * <tt>belongs_to</tt> - define one or more associations to parents
+      # * <tt>actions</tt> - acion definitions outside the restful actions
+      # * <tt>model</tt> - Redefine the model used in the controller (if it's name does not match the 
+      #   controller_path)
+      #
+      def properties
+        @properties ||= Trust::Controller::Properties.instantiate(self)
+      end      
+      
+      delegate :belongs_to, :actions, :model, :to => :properties
+
+      # Enables authorization in controller
+      # +trustee+ accepts +:off+ or a hash of +callback+ options such as +:except+ and +:only+
+      #
+      # +trustee+ automatically calls the class methods: +set_user+, +load_resource+ and +access_control+
+      #
+      # +trustee+ will raise an Trust::AccessDenied exception if the user is not permitted the action
+      # 
+      # ==== Examples
+      #
+      #   # enable permission check for all restful actions
+      #   class AccountsController < ApplicationController
+      #     login_required
+      #     trustee
+      #   end
+      #
+      #   # disable all permission check
+      #   class PasswordController < ApplicationController
+      #     # assuming login_required and trustee has been in your application controller
+      #     trustee :off
+      #   end
+      #
+      #   # enable permission check and loading for only :new and :create action
+      #   class AccountsController < ApplicationController
+      #     login_required
+      #     trustee :only => [:new, :create]
+      #   end
+      #
+      # ==== Caching Trust::AccessDenied exception
+      # Normally an exception handler is included in the ApplicationController. Example:
+      #   class ApplicationController < ActionController::Base
+      #     rescue_from Trust::AccessDenied do |exception|
+      #       redirect_to root_url, :alert => exception.message
+      #     end
+      #   end
+      
+
+      def trustee(*args)
+        module_eval do
+          include TrustInstanceMethods
+          set_user *args
+          load_resource *args
+          access_control *args
+          helper_method :can?, :resource
+        end
+      end
+      
+      # Enable or disable +before_filter+ callback for setting the current user
+      # Arguments:
+      #  :off - switch callback off
+      #  :only - only include these actions
+      #  :except - except these actions
+      def set_user(*args)
+        _filter_setting(:set_user, *args)
+      end
+      # Enable or disable +before_filter+ callback for setting the loading resource
+      # Arguments:
+      #  :off - switch callback off
+      #  :only - only include these actions
+      #  :except - except these actions
+      def load_resource(*args)
+        _filter_setting(:load_resource, *args)
+      end
+      # Enable or disable +before_filter+ callback for setting the access control, i.e. verifying permissions
+      # for the logged in user
+      # Arguments:
+      #  :off - switch callback off
+      #  :only - only include these actions
+      #  :except - except these actions
+      def access_control(*args)
+        _filter_setting(:access_control, *args)
+      end
+      
+    private
+      def _filter_setting(method, *args)
+        options = args.extract_options!
+        skip_before_filter method
+        unless args.include? :off
+          before_filter method, options
+        end
+      end
+    end
+    
+    module TrustInstanceMethods
+      # Returns the controller Trust::Controller::Properties.
+      # If no properties are instantiated, it will be instantiated
+      # 
+      # == Delegated methods
+      #
+      # The following methods are delegated to properties. See Trust::Controller::Properties for details
+      # * <tt>belongs_to</tt> - define one or more associations to parents
+      # * <tt>actions</tt> - acion definitions outside the restful actions
+      # * <tt>model</tt> - Redefine the model used in the controller (if it's name does not match the 
+      #   controller_path)
+      #
+      def properties
+        self.class.properties
+      end
+      
+      # Sets the current user. It assumes +current_user+ is defined
+      # This method is triggered as a callback on +before_filter+
+      # You may override this method.
+      #
+      # ==== Example
+      # 
+      #   def set_user
+      #     Trust::Authorization.user = Thread[:current_user]
+      #   end
+      def set_user
+        Trust::Authorization.user = current_user
+      end
+
+      # Returns the Trust::Controller::Resource resource for the controller.
+      # Available as a helper in views
+      # See Trust::Controller::Resource for relevant methods
+      def resource
+        @resource ||= Trust::Controller::Resource.new(self, self.class.properties, action_name, params, request)
+      end
+      
+      # Loads the resource which basically means loading the instance and eventual parent defined through +belongs_to+
+      # This method is triggered as a callback on +before_filter+
+      # See Trust::Controller::Resource for more information
+      def load_resource
+        resource.load
+      end
+      
+      # Performs the actual access_control
+      # This method is triggered as a callback on +before_filter+
+      def access_control
+        Trust::Authorization.authorize!(action_name, resource.instance || resource.klass, resource.parent)
+      end
+
+      # Tests for current users permissions
+      # If access control is not sufficient in controller, you may use this method.
+      # Also available as a helper in views
+      #
+      # ==== Examples
+      #   can? :edit                          # does the current user have permission to edit the current resource? 
+      #                                       # If there is a nested resource, the parent is automatically associated
+      #   can? :edit, @customer               # does the current user have permission to edit the given customer? 
+      #                                       # Parent is also passed on here.
+      #   can? :edit, @account, @client       # is current user allowed to edit the account associated with the client?
+      def can?(action_name, subject = resource.instance || resource.klass, parent = resource.parent)
+        Trust::Authorization.authorized?(action_name, subject, parent)
+      end
+    end
+  end
+end

data/lib/trust/exceptions.rb

@@ -0,0 +1,45 @@
+# Copyright (c) 2012 Bingo Entreprenøren AS
+# Copyright (c) 2012 Teknobingo Scandinavia AS
+# Copyright (c) 2012 Knut I. Stenmark
+# Copyright (c) 2012 Patrick Hanevold
+#
+# Permission is hereby granted, free of charge, to any person obtaining
+# a copy of this software and associated documentation files (the
+# "Software"), to deal in the Software without restriction, including
+# without limitation the rights to use, copy, modify, merge, publish,
+# distribute, sublicense, and/or sell copies of the Software, and to
+# permit persons to whom the Software is furnished to do so, subject to
+# the following conditions:
+#
+# The above copyright notice and this permission notice shall be
+# included in all copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+# EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+# MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+# NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+# LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+# OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+# WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+module Trust
+  class NoBlockError < StandardError; end
+  class UnsupportedCondition < StandardError; end
+  class RoleAssigmnentMissing < StandardError; end
+  
+  class AccessDenied < StandardError
+    attr_reader :action, :subject
+    attr_writer :default_message
+
+    def initialize(message = nil, action = nil, subject = nil)
+      @message = message
+      @action = action
+      @subject = subject
+      @default_message = I18n.t(:"unauthorized.default", :default => "You are not authorized to access this page.")
+    end
+
+    def to_s
+      @message || @default_message
+    end
+  end
+end

data/lib/trust/inheritable_attribute.rb

@@ -0,0 +1,91 @@
+# Copyright (c) 2012 Bingo Entreprenøren AS
+# Copyright (c) 2012 Teknobingo Scandinavia AS
+# Copyright (c) 2012 Knut I. Stenmark
+# Copyright (c) 2012 Patrick Hanevold
+#
+# Permission is hereby granted, free of charge, to any person obtaining
+# a copy of this software and associated documentation files (the
+# "Software"), to deal in the Software without restriction, including
+# without limitation the rights to use, copy, modify, merge, publish,
+# distribute, sublicense, and/or sell copies of the Software, and to
+# permit persons to whom the Software is furnished to do so, subject to
+# the following conditions:
+#
+# The above copyright notice and this permission notice shall be
+# included in all copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+# EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+# MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+# NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+# LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+# OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+# WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+module Trust
+  module InheritableAttribute
+
+    def self.deep_copy value
+      if value.is_a? Hash
+        Hash[*value.map{ |k,v| [self.deep_copy(k),self.deep_copy(v)] }.flatten(1)]
+      elsif value.is_a? Array
+        value.map{ |v| self.deep_copy(v) }
+      elsif value.is_a? Symbol
+        value
+      else
+        value.clone
+      end
+    end
+
+    extend ActiveSupport::Concern
+
+    module ClassMethods
+      # Creates an inheritable attribute with accessors in the singleton class. Derived classes inherit the
+      # attributes. This is especially helpful with arrays or hashes that are extended in the inheritance
+      # chain. Note that you have to initialize the inheritable attribute.
+      #
+      # Example:
+      #
+      #   class Cat
+      #     inheritable_attr :drinks
+      #     self.drinks = ["Becks"]
+      #
+      #   class Garfield < Cat
+      #     self.drinks << "Fireman's 4"
+      #
+      # and then, later
+      #
+      #   Cat.drinks      #=> ["Becks"]
+      #   Garfield.drinks #=> ["Becks", "Fireman's 4"]
+      def inheritable_attr(name, options = {})
+        src = <<-end_src
+          def #{name}=(v)
+            @#{name} = v
+          end
+
+          def #{name}
+            return @#{name} unless superclass.respond_to?(:#{name}) and value = superclass.#{name}
+            @#{name} ||= ::Trust::InheritableAttribute::deep_copy(value) # only do this once.
+          end
+        end_src
+        instance_eval src, __FILE__, __LINE__
+        if !options.key?(:instance_writer) || options[:instance_writer]
+          src = <<-end_src
+            def #{name}=(v)
+              self.class.#{name} = v
+            end
+          end_src
+          class_eval src, __FILE__, __LINE__
+        end
+        if !options.key?(:instance_reader) || options[:instance_reader]
+          src = <<-end_src
+            def #{name}
+              self.class.#{name}
+            end
+          end_src
+          class_eval src, __FILE__, __LINE__
+        end
+      end
+    end
+  end  
+end