load_and_authorize_resource 0.1.0 → 0.2.0

data/README.md

@@ -4,6 +4,14 @@ Auto-loads and authorizes resources in Rails 3 and up.
 
 This was inspired heavily by functionality in the [CanCan](https://github.com/ryanb/cancan) gem, but built to work mostly independent of any authorization library.
 
+[Documentation](http://rubydoc.info/github/seven1m/load_and_authorize_resource/master/frames)
+
+## Mascot
+
+This is LAAR. He's a horse my daughter drew.
+
+![LAAR](https://raw.github.com/seven1m/load_and_authorize_resource/master/mascot.png)
+
 ## Assumptions
 
 This library assumes your app follows some (fairly common) conventions:
@@ -13,6 +21,24 @@ This library assumes your app follows some (fairly common) conventions:
 3. Your User model has methods like `can_read?`, `can_update?`, `can_delete?`, etc. (This works great with [Authority](https://github.com/nathanl/authority) gem, but naturally can work with any authorization library, given you/it defines those methods.)
 4. You have a method on your controller that returns the resource parameters, e.g. `note_params`. You're probably already doing this if you're using [StrongParameters](https://github.com/rails/strong_parameters) or Rails 4.
 
+## Installing
+
+Add to your Gemfile:
+
+```
+gem 'load_and_authorize_resource'
+```
+
+...and run `bundle install`.
+
+Then add the following to your ApplicationController:
+
+```ruby
+class ApplicationController < ActionController::Base
+  include LoadAndAuthorizeResource
+end
+```
+
 ## Loading and Authorizing the Resource
 
 ```ruby
@@ -38,6 +64,8 @@ For each controller action, `current_user.can_<action>?(@note)` is consulted. If
 
 This works very nicely along with the [Authority](https://github.com/nathanl/authority) gem.
 
+If you don't wish to authorize, or if you wish to do the loading yourself, you can just call `load_resource` and/or `authorize_resource`. Also, each macro accepts the normal before_filter options such as `:only` and `:except` if you wish to only apply the filters to certain actions.
+
 ## Loading and Authorizing the Parent Resource
 
 Also loads and authorizes the parent resource(s)... given the following routes:
@@ -70,7 +98,11 @@ class NotesController < ApplicationController
 end
 ```
 
-Further, a private method is defined with the name of the resource that returns an ActiveRecord::Relation scoped to the `@parent` (if present). It basically looks like this:
+If you don't wish to authorize, or if you wish to do the loading yourself, you can just call `load_parent` and/or `authorize_parent`. Also, each macro accepts the normal before_filter options such as `:only` and `:except` if you wish to only apply the filters to certain actions.
+
+### Accessing Children
+
+When you setup to load a parent resoure, a private method is defined with the name of the child resource that returns an ActiveRecord::Relation scoped to the `@parent` (if present). It basically looks like this:
 
 ```ruby
 class NotesController < ApplicationController
@@ -78,9 +110,9 @@ class NotesController < ApplicationController
   private
 
   def notes
-    if @parent
-      @parent.notes.scoped
-    else
+    if @person
+      @person.notes.scoped
+    elsif !required(:parent)
       Note.scoped
     end
   end
@@ -104,13 +136,13 @@ For parent resources, `current_user.can_read?(@parent)` is consulted. If false,
 
 If none of the parent IDs are present, e.g. `person_id` and `group_id` are both absent in `params`, then a `LoadAndAuthorizeResource::ParameterMissing` exception is raised.
 
-### Shallow Routes
+### Shallow (Optional) Routes
 
-You can make the parent loading and authorization optional by setting the `shallow` option:
+You can make the parent loading and authorization optional by making it `optional`:
 
 ```ruby
 class NotesController < ApplicationController
-  load_and_authorize_parent :person, :group, shallow: true
+  load_and_authorize_parent :person, :group, optional: true
 end
 ```
 

data/lib/load_and_authorize_resource.rb

@@ -6,6 +6,12 @@ module LoadAndAuthorizeResource
   class ParameterMissing < KeyError; end
   class AccessDenied < StandardError; end
 
+  # Controller method names to action verb mapping
+  #
+  # Other controller methods will use the name of the action, e.g.
+  # if your controller action is `rotate`, then it will be assumed
+  # to be your verb too: `current_user.can_rotate?(resource)`
+  #
   METHOD_TO_ACTION_NAMES = {
     'show'    => 'read',
     'new'     => 'create',
@@ -44,7 +50,7 @@ module LoadAndAuthorizeResource
     #
     # 1. look for `params[:person_id]`
     # 2. if present, call `Person.find(params[:person_id])`
-    # 3. set @person and @parent
+    # 3. set @person
     #
     # If we've exhausted our list of potential parent resources without
     # seeing the needed parameter (:person_id or :group_id), then a
@@ -62,62 +68,90 @@ module LoadAndAuthorizeResource
     #       load_parent :person, :group, shallow: true
     #     end
     #
+    # The `:shallow` option is aliased to `:optional` in cases where it
+    # sense to think about parent resources that way. Further, you can
+    # call the macro more than once should you want to make some
+    # optional and some not:
+    #
+    #     class NotesController < ApplicationController
+    #       load_parent :person, group, optional: true
+    #       load_parent :book
+    #     end
+    #
     # Additionally, a private method is defined with the same name as
-    # the resource. The method looks basically like this:
+    # the resource. The method looks basically like this (if you were
+    # to write it yourself):
     #
     #     class NotesController < ApplicationController
     #
     #       private
     #
     #       def notes
-    #         if @parent
-    #           @parent.notes.scoped
-    #         else
+    #         if @person
+    #           @person.notes.scoped
+    #         elsif not required(:person)
     #           Note.scoped
     #         end
     #       end
     #     end
     #
+    # You can change the name of this accessor if it is not the same
+    # as the resource this controller represents:
+    #
+    #     class NotesController < ApplicationController
+    #       load_parent :group, children: :people
+    #     end
+    #
+    # This will create a private method called "people" that either returns
+    # `@group.people.scoped` or Person.scoped (only if @group is optional).
+    #
+    # @param names [Array<String, Symbol>] one or more names of resources in lower case
+    # @option options [Boolean] :optional set to true to allow non-nested routes, e.g. `/notes` in addition to `/people/1/notes`
+    # @option options [Boolean] :shallow (alias for :optional)
+    # @option options [Boolean] :except controller actions to ignore when applying this filter
+    # @option options [Boolean] :only controller actions to apply this filter
+    # @option options [String, Symbol] :children name of child accessor (inferred from controller name, e.g. "notes" for the NotesController)
+    #
     def load_parent(*names)
       options = names.extract_options!.dup
-      self.nested_resource_options ||= {}
-      self.nested_resource_options[:load] = {
-        options: {shallow: options.delete(:shallow)},
-        resources: names
-      }
+      required = !(options.delete(:shallow) || options.delete(:optional))
+      save_nested_resource_options(:load, names, required)
+      define_scope_method(names, options.delete(:children))
       before_filter :load_parent, options
-      define_scope_method
     end
 
     # Macro sets a before filter to authorize the parent resource.
-    # Assumes there is a `@parent` variable.
+    # Assumes ther resource is already set (in a before filter).
     #
     #     class NotesController < ApplicationController
-    #       authorize_parent
+    #       authorize_parent :group
     #     end
     #
-    # If `@parent` is not found, or calling `current_user.can_read?(@parent)` fails,
+    # If `@group` is not found, or calling `current_user.can_read?(@group)` fails,
     # an exception will be raised.
     #
     # If the parent resource is optional, and you only want to check authorization
     # if it is set, you can set the `:shallow` option to `true`:
     #
     #     class NotesController < ApplicationController
-    #       authorize_parent shallow: true
+    #       authorize_parent :group, shallow: true
     #     end
     #
-    def authorize_parent(options={})
-      self.nested_resource_options ||= {}
-      self.nested_resource_options[:auth] = {
-        options: {shallow: options.delete(:shallow)}
-      }
+    # @option options [Boolean] :shallow set to true to allow non-nested routes, e.g. `/notes` in addition to `/people/1/notes`
+    # @option options [Boolean] :except controller actions to ignore when applying this filter
+    # @option options [Boolean] :only controller actions to apply this filter
+    #
+    def authorize_parent(*names)
+      options = names.extract_options!.dup
+      required = !(options.delete(:shallow) || options.delete(:optional))
+      save_nested_resource_options(:auth, names, required)
       before_filter :authorize_parent, options
     end
 
     # A convenience method for calling both `load_parent` and `authorize_parent`
     def load_and_authorize_parent(*names)
       load_parent(*names)
-      authorize_parent(names.extract_options!)
+      authorize_parent(*names)
     end
 
     # Load the resource and set to an instance variable.
@@ -135,22 +169,28 @@ module LoadAndAuthorizeResource
     # new resource. For `create`, instantiates and
     # sets attributes to `<resource>_params`.
     #
+    # @option options [Boolean] :except controller actions to ignore when applying this filter
+    # @option options [Boolean] :only controller actions to apply this filter (default is show, new, create, edit, update, and destroy)
+    # @option options [String, Symbol] :children name of child accessor (inferred from controller name, e.g. "notes" for the NotesController)
+    #
     def load_resource(options={})
+      options = options.dup
       unless options[:only] or options[:except]
         options.reverse_merge!(only: [:show, :new, :create, :edit, :update, :destroy])
       end
+      define_scope_method([], options.delete(:children))
       before_filter :load_resource, options
-      define_scope_method
     end
 
-    # Checks authorization on resource by calling one of:
+    # Checks authorization on the already-loaded resource.
+    #
+    # This method calls `current_user.can_<action>?(@resource)` and raises an exception if the answer is 'no'.
     #
-    # * `current_user.can_read?(@note)`
-    # * `current_user.can_create?(@note)`
-    # * `current_user.can_update?(@note)`
-    # * `current_user.can_delete?(@note)`
+    # @option options [Boolean] :except controller actions to ignore when applying this filter
+    # @option options [Boolean] :only controller actions to apply this filter
     #
     def authorize_resource(options={})
+      options = options.dup
       unless options[:only] or options[:except]
         options.reverse_merge!(only: [:show, :new, :create, :edit, :update, :destroy])
       end
@@ -163,19 +203,50 @@ module LoadAndAuthorizeResource
       authorize_resource(options)
     end
 
+    # Returns the name of the resource, in singular form, e.g. "note"
+    #
+    # By default, this is simply `controller_name.singularize`.
+    #
+    def resource_name
+      controller_name.singularize
+    end
+
+    # Returns the name of the resource, in plural form, e.g. "notes"
+    #
+    # By default, this is simply the `controller_name`.
+    #
+    def resource_accessor_name
+      controller_name
+    end
+
     protected
 
     # Defines a method with the same name as the resource (`notes` for the NotesController)
     # that returns a scoped relation, either @parent.notes, or Note itself.
-    def define_scope_method
-      define_method(controller_name) do
-        if @parent
-          @parent.send(controller_name).scoped
-        else
-          controller_name.classify.constantize.scoped
+    def define_scope_method(parents, name=nil)
+      name ||= resource_accessor_name
+      self.nested_resource_options ||= {}
+      self.nested_resource_options[:accessors] ||= []
+      unless self.nested_resource_options[:accessors].include?(name)
+        self.nested_resource_options[:accessors] << name
+        define_method(name) do
+          parents.each do |parent|
+            if resource = instance_variable_get("@#{parent}")
+              return resource.send(name).scoped
+            end
+          end
+          name.to_s.classify.constantize.scoped
         end
+        private(name)
       end
-      private(controller_name)
+    end
+
+    # Stores groups of names and options (required) on a class attribute on the controller
+    def save_nested_resource_options(key, names, required)
+      self.nested_resource_options ||= {}
+      self.nested_resource_options[key] ||= []
+      group = {resources: names, required: required}
+      self.nested_resource_options[key] << group
     end
   end
 
@@ -184,23 +255,24 @@ module LoadAndAuthorizeResource
   # Loop over each parent resource, and try to find a matching parameter.
   # Then lookup the resource using the supplied id.
   def load_parent
-    keys = self.class.nested_resource_options[:load][:resources]
-    parent = keys.detect do |key|
-      if id = params["#{key}_id".to_sym]
-        @parent = key.to_s.classify.constantize.find(id)
-        instance_variable_set "@#{key}", @parent
+    self.class.nested_resource_options[:load].each do |group|
+      parent = group[:resources].detect do |key|
+        if id = params["#{key}_id".to_sym]
+          parent = key.to_s.classify.constantize.find(id)
+          instance_variable_set "@#{key}", parent
+        end
       end
+      verify_shallow_route!(group) unless parent
     end
-    verify_shallow_route! unless @parent
   end
 
   # Loads/instantiates the resource object.
   def load_resource
-    scope = send(controller_name)
+    scope = send(resource_accessor_name)
     if ['new', 'create'].include?(params[:action].to_s)
       resource = scope.new
       if 'create' == params[:action].to_s
-        resource.attributes = send("#{controller_name.singularize}_params")
+        resource.attributes = send("#{resource_name}_params")
       end
     elsif params[:id]
       resource = scope.find(params[:id])
@@ -212,21 +284,26 @@ module LoadAndAuthorizeResource
 
   # Verify the current user is authorized to view the parent resource.
   # Assumes that `load_parent` has already been run and that `@parent` is set.
-  # If `@parent` is empty and the `shallow` option is enabled, don't
-  # perform any authorization check.
+  # If `@parent` is empty and the parent is optional, don't perform any
+  # authorization check.
   def authorize_parent
-    if not @parent and not self.class.nested_resource_options[:auth][:options][:shallow]
-      raise ParameterMissing.new('parent resource not found')
-    end
-    if @parent
-      authorize_resource(@parent, :read)
+    self.class.nested_resource_options[:auth].each do |group|
+      group[:resources].each do |name|
+        parent = instance_variable_get("@#{name}")
+        if not parent and group[:required]
+          raise ParameterMissing.new('parent resource not found')
+        end
+        if parent
+          authorize_resource(parent, :read)
+        end
+      end
     end
   end
 
   # Asks the current_user if he/she is authorized to perform the given action.
   def authorize_resource(resource=nil, action=nil)
-    resource ||= instance_variable_get("@#{controller_name.singularize}")
-    action ||= METHOD_TO_ACTION_NAMES[params[:action].to_s]
+    resource ||= instance_variable_get("@#{resource_name}")
+    action ||= METHOD_TO_ACTION_NAMES[params[:action].to_s] || params[:action].presence
     raise ArgumentError unless resource and action
     unless current_user.send("can_#{action}?", resource)
       raise AccessDenied.new("#{current_user} cannot #{action} #{resource}")
@@ -234,15 +311,19 @@ module LoadAndAuthorizeResource
   end
 
   # Verify this shallow route is allowed, otherwise raise an exception.
-  def verify_shallow_route!
-    return if self.class.nested_resource_options[:load][:options][:shallow]
-    expected = self.class.nested_resource_options[:load][:resources].map { |n| ":#{n}_id" }
+  def verify_shallow_route!(group)
+    return unless group[:required]
+    expected = group[:resources].map { |n| ":#{n}_id" }
     raise ParameterMissing.new(
       "must supply one of #{expected.join(', ')}"
     )
   end
 
   def resource_name
-    controller_name.singularize
+    self.class.resource_name
+  end
+
+  def resource_accessor_name
+    self.class.resource_accessor_name
   end
 end

data/lib/load_and_authorize_resource.rb.20130712142746.patch

@@ -0,0 +1,37 @@
+--- lib/load_and_authorize_resource.rb	2013-07-11 21:52:43.091465423 -0500
++++ /tmp/vu0jgwl/146	2013-07-12 14:27:46.872763565 -0500
+@@ -178,6 +178,7 @@
+       unless options[:only] or options[:except]
+         options.reverse_merge!(only: [:show, :new, :create, :edit, :update, :destroy])
+       end
++      define_scope_method([], options.delete(:children))
+       before_filter :load_resource, options
+     end
+ 
+@@ -224,15 +225,19 @@
+     # that returns a scoped relation, either @parent.notes, or Note itself.
+     def define_scope_method(parents, name=nil)
+       name ||= resource_accessor_name
+-      define_method(name) do
+-        parents.each do |parent|
+-          if resource = instance_variable_get("@#{parent}")
+-            return resource.send(name).scoped
++      nested_resource_options[:accessors] ||= []
++      unless nested_resource_options[:accessors].include?(name)
++        nested_resource_options[:accessors] << name
++        define_method(name) do
++          parents.each do |parent|
++            if resource = instance_variable_get("@#{parent}")
++              return resource.send(name).scoped
++            end
+           end
++          name.to_s.classify.constantize.scoped
+         end
+-        name.to_s.classify.constantize.scoped
++        private(name)
+       end
+-      private(name)
+     end
+ 
+     # Stores groups of names and options (required) on a class attribute on the controller
+

metadata

@@ -2,14 +2,14 @@
 name: load_and_authorize_resource
 version: !ruby/object:Gem::Version
   prerelease: 
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Tim Morgan
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-07-09 00:00:00.000000000 Z
+date: 2013-07-12 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   prerelease: false
@@ -82,6 +82,7 @@ extensions: []
 extra_rdoc_files: []
 files:
 - README.md
+- lib/load_and_authorize_resource.rb.20130712142746.patch
 - lib/load_and_authorize_resource.rb
 homepage: https://github.com/seven1m/load_and_authorize_resource
 licenses: []