authority 2.0.0 → 2.0.1

data/CHANGELOG.markdown

@@ -2,6 +2,10 @@
 
 This is mainly to document major new features and backwards-incompatible changes.
 
+## v2.0.1
+
+Documentation and test cleanup.
+
 ## v2.0.0
 
 - **Breaking change**: models now assume their authorizer is `ApplicationAuthorizer` unless told otherwise. Generator creates a blank `ApplicationAuthorizer`. This, combined with the change in v1.1.0, makes the `default_strategy` proc obsolete in favor of straightforward inheritance of a `default` method, so support for `config.default_strategy` is removed.

data/README.markdown

@@ -87,9 +87,10 @@ The authorization process generally flows like this:
                                |                                     # calls `default`...
                                v
         AdminAuthorizer.default(:creatable, current_user)            # *You define this method.* 
-                                                                     # If you don't, the one inherited 
-                                                                     # from Authority::Authorizer just 
-                                                                     # returns false.
+                                                                     # If you don't, it will use the one 
+                                                                     # inherited from ApplicationAuthorizer.
+                                                                     # (Its parent, Authority::Authorizer,
+                                                                     # defines the method as `return false`.)
 
 If the answer is `false` and the original caller was a controller, this is treated as a `SecurityViolation`. If it was a view, maybe you just don't show a link.
 
@@ -260,27 +261,47 @@ end
 
 Anytime a controller finds a user attempting something they're not authorized to do, a [Security Violation](#security_violations_and_logging) will result. Controllers get two ways to check authorization:
 
-- `authorize_actions_for Transaction` protects multiple controller actions with a `before_filter`, which performs a **class-level** check. If the current user is never allowed to delete a `Transaction`, they'll never even get to the controller's `destroy` method.
-- `authorize_action_for @transaction` can be called inside a single controller action, and performs an **instance-level** check. If called inside `update`, it will check whether the current user is allowed to update this particular `@transaction` instance.
+- `authorize_actions_for Llama` protects multiple controller actions with a `before_filter`, which performs a **class-level** check. If the current user is never allowed to delete a `Llama`, they'll never even get to the controller's `destroy` method.
+- `authorize_action_for @llama` can be called inside a single controller action, and performs an **instance-level** check. If called inside `update`, it will check whether the current user is allowed to update this particular `@llama` instance.
 
-The relationship between controller actions and abilities - like checking `readable_by?` on the `index` action - is configurable both globally, using `config.controller_action_map`, and per controller, as below.
+How does Authority know to check `deletable_by?` before the controller's `destroy` action? It checks your configuration. These mappings are configurable globally from the initializer file. Defaults are as follows:
 
 ```ruby
-class LlamaController < ApplicationController
+config.controller_action_map = {
+ :index   => 'read',    # `index` controller action will check `readable_by?`
+ :show    => 'read',
+ :new     => 'create',  # `new` controller action will check `creatable_by?`
+ :create  => 'create',  # ...etc
+ :edit    => 'update',
+ :update  => 'update',
+ :destroy => 'delete'
+}
+```
+
+They are also configurable per controller, as follows:
+
+```ruby
+class LlamasController < ApplicationController
 
   # Check class-level authorizations before all actions except :create
   # Also, to authorize this controller's 'neuter' action, ask whether `current_user.can_update?(Llama)`
   authorize_actions_for Llama, :except => :create, :actions => {:neuter => :update},
   
   # To authorize this controller's 'breed' action, ask whether `current_user.can_create?(Llama)`
-  authority_action :breed => 'new'
+  authority_action :breed => 'create'
 
   ...
 
   def edit
     @llama = Llama.find(params[:id])
+    authorize_action_for(@llama)        # Check to see if you're allowed to edit this llama. failure == SecurityViolation    
+  end
+
+  def update
+    @llama = Llama.find(params[:id])
+    authorize_action_for(@llama)        # Check to see if you're allowed to edit this llama.
     @llama.attributes = params[:llama]  # Don't save the attributes before authorizing
-    authorize_action_for(@llama)        # failure == SecurityViolation
+    authorize_action_for(@llama)        # Check again, to see if the changes are allowed.
     if @llama.save?
     # etc
   end
@@ -329,6 +350,8 @@ end
 
 If you want different error handling per controller, define `fire_ze_missiles` on each of them.
 
+Your method will be handed the `SecurityViolation`, which has a `message` method. In case you want to build your own message, it also exposes `user`, `action` and `resource`.
+
 <a name="credits">
 ## Credits, AKA 'Shout-Outs'
 

data/TODO.markdown

@@ -7,8 +7,5 @@
 
 ## Documentation
 
-- Example of checking clean/dirty attributes in instance-level checks. For example, if I'm only allowed to update blue laser cannons, can I make them red? Maybe I need to check whether the old value was blue?
-
 ## Features
 
-- It would be nice to have an `authorized_link_to` method, which determines from the given path and the user's permissions whether to show the link. Not sure yet how hard this would be.

data/lib/authority/abilities.rb

@@ -27,6 +27,7 @@ module Authority
         RUBY
       end
 
+      # @return [Class] of the designated authorizer
       def authorizer
         @authorizer ||= authorizer_name.constantize # Get an actual reference to the authorizer class
       rescue NameError

data/lib/authority/configuration.rb

@@ -1,7 +1,7 @@
 module Authority
   class Configuration
 
-    # Has default settings, overrideable in the initializer.
+    # Has default settings, which can be overridden in the initializer.
 
     attr_accessor :abilities, :controller_action_map, :user_method, :security_violation_handler, :logger
 

data/lib/authority/controller.rb

@@ -11,7 +11,7 @@ module Authority
 
     def self.security_violation_callback
       Proc.new do |exception|
-        # Through the magic of ActiveSupport's Proc#bind, `ActionController::Base#rescue_from`
+        # Through the magic of ActiveSupport's `Proc#bind`, `ActionController::Base#rescue_from`
         # can call this proc and make `self` the actual controller instance
         self.send(Authority.configuration.security_violation_handler, exception)
       end
@@ -59,13 +59,13 @@ module Authority
 
     private
 
-    # The before filter that will be setup to run when the class method
+    # The `before_filter` that will be setup to run when the class method
     # `authorize_actions_for` is called
     def run_authorization_check
       authorize_action_for self.class.authority_resource
     end
 
-    # Convenience wrapper for sending configured user_method to extract the
+    # Convenience wrapper for sending configured `user_method` to extract the
     # request's current user
     #
     # @return [Object] the user object returned from sending the user_method
@@ -73,7 +73,7 @@ module Authority
       send(Authority.configuration.user_method)
     end
 
-    # To be run in a before_filter; ensure this controller action is allowed for the user
+    # To be run in a `before_filter`; ensure this controller action is allowed for the user
     #
     # @param authority_resource [Class], the model class associated with this controller
     # @raise [MissingAction] if controller action isn't a key in `config.controller_action_map`

data/lib/authority/version.rb

@@ -1,3 +1,3 @@
 module Authority
-  VERSION = "2.0.0"
+  VERSION = "2.0.1"
 end

data/lib/generators/authority/install_generator.rb

@@ -25,7 +25,7 @@ module Authority
       private
 
       def create_authorizers_directory
-        # creates empty directory if none; doesn't empty the directory
+        # Creates empty directory if none; doesn't empty the directory
         empty_directory "app/authorizers" 
       end
 

data/lib/generators/templates/authority_initializer.rb

@@ -10,6 +10,7 @@ Authority.configure do |config|
   # config.user_method = :current_user
   
   # CONTROLLER_ACTION_MAP
+  # =====================
   # For a given controller method, what verb must a user be able to do?
   # For example, a user can access 'show' if they 'can_read' the resource.
   #
@@ -29,6 +30,7 @@ Authority.configure do |config|
   # }
 
   # ABILITIES
+  # =========
   # Teach Authority how to understand the verbs and adjectives in your system. Perhaps you
   # need {:microwave => 'microwavable'}. I'm not saying you do, of course. Stop looking at 
   # me like that.
@@ -43,6 +45,7 @@ Authority.configure do |config|
   # }
 
   # SECURITY_VIOLATION_HANDLER
+  # ==========================
   # If a SecurityViolation is raised, what controller method should be used to rescue it?
   #
   # Default is:
@@ -50,6 +53,7 @@ Authority.configure do |config|
   # config.security_violation_handler = :authority_forbidden # Defined in controller.rb
   
   # LOGGER
+  # ======
   # If a user tries to perform an unauthorized action, where should we log that fact?
   # Provide a logger object which responds to `.warn(message)`, unless your 
   # security_violation_handler calls a different method.

data/spec/authority/abilities_spec.rb

@@ -35,14 +35,10 @@ describe Authority::Abilities do
     end
 
     it "should raise a friendly error if the authorizer doesn't exist" do
-      AbilityModel.instance_variable_set(:@authorizer, nil)
-      AbilityModel.authorizer_name = 'NonExistentAuthorizer'
-      expect { AbilityModel.authorizer }.to raise_error(Authority::NoAuthorizerError)
-
-      # Cleanup to prevent affecting other tests
-      # TODO: Clean up this cleanup code. :)
-      AbilityModel.instance_variable_set(:@authorizer, nil)
-      AbilityModel.authorizer_name = 'ApplicationAuthorizer'
+      class NoAuthorizerModel < AbilityModel; end ;
+      NoAuthorizerModel.instance_variable_set(:@authorizer, nil)
+      NoAuthorizerModel.authorizer_name = 'NonExistentAuthorizer'
+      expect { NoAuthorizerModel.authorizer }.to raise_error(Authority::NoAuthorizerError)
     end
 
   end
@@ -91,8 +87,9 @@ describe Authority::Abilities do
       @ability_model.should respond_to(:authorizer)
     end
 
-    # TODO: Nathan will comment more clearly in the future
-    # aka "don't memoize" (to prevent dirty models from contaminating authorization)
+    # When checking instance methods, we want to ensure that every check uses a new
+    # instance of the authorizer. Otherwise, you might check, make a change to the
+    # model instance, check again, and get an outdated answer.
     it "should always create a new authorizer instance when accessing the authorizer" do
       @ability_model.class.authorizer.should_receive(:new).with(@ability_model).twice
       2.times { @ability_model.authorizer }

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: authority
 version: !ruby/object:Gem::Version
-  version: 2.0.0
+  version: 2.0.1
   prerelease: 
 platform: ruby
 authors:
@@ -10,11 +10,11 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-04-30 00:00:00.000000000 Z
+date: 2012-06-16 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
-  requirement: &2152144680 !ruby/object:Gem::Requirement
+  requirement: &75848730 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -22,7 +22,7 @@ dependencies:
         version: 3.0.0
   type: :runtime
   prerelease: false
-  version_requirements: *2152144680
+  version_requirements: *75848730
 description: Authority helps you authorize actions in your Rails app. It's ORM-neutral
   and has very little fancy syntax; just group your models under one or more Authorizer
   classes and write plain Ruby methods on them.
@@ -90,20 +90,9 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 1.8.16
+rubygems_version: 1.8.10
 signing_key: 
 specification_version: 3
 summary: Authority helps you authorize actions in your Rails app using plain Ruby
   methods on Authorizer classes.
-test_files:
-- spec/authority/abilities_spec.rb
-- spec/authority/authorizer_spec.rb
-- spec/authority/configuration_spec.rb
-- spec/authority/controller_spec.rb
-- spec/authority/user_abilities_spec.rb
-- spec/authority_spec.rb
-- spec/spec_helper.rb
-- spec/support/ability_model.rb
-- spec/support/example_controllers.rb
-- spec/support/mock_rails.rb
-- spec/support/user.rb
+test_files: []