authority 2.0.1 → 2.1.0

data/.travis.yml

@@ -12,4 +12,4 @@ gemfile:
   - gemfiles/3.0.gemfile
   - gemfiles/3.1.gemfile
   - gemfiles/3.2.gemfile
-  - Gemfile
+  - Gemfile

data/README.markdown

@@ -22,6 +22,7 @@ It requires that you already have some kind of user object in your application,
     <li><a href="#models">Models</a></li>
     <li><a href="#authorizers">Authorizers</a>
     <ul>
+      <li><a href="#passing_options">Passing Options</a></li>
       <li><a href="#default_methods">Default methods</a></li>
       <li><a href="#testing_authorizers">Testing Authorizers</a></li>
     </ul></li>
@@ -36,18 +37,32 @@ It requires that you already have some kind of user object in your application,
 <a name="overview">
 ## Overview
 
-The goals of Authority are:
+Using Authority, you have:
 
-- To allow broad, **class-level** rules. Examples: 
+- Broad, **class-level** rules. Examples: 
   - "Basic users cannot delete any Widget."
   - "Only admin users can create Offices."
-- To allow fine-grained, **instance-level** rules. Examples: 
+- Fine-grained, **instance-level** rules. Examples: 
   - "Management users can only edit schedules with date ranges in the future."
   - "Users can't create playlists more than 20 songs long unless they've paid."
-- To provide a clear syntax for permissions-based views. Example:
+- A clear syntax for permissions-based views. Example:
   - `link_to 'Edit Widget', edit_widget_path(@widget) if current_user.can_update?(@widget)`
-- To gracefully handle any access violations: by default, it displays a "you can't do that" screen and logs the violation.
-- To do all this with minimal effort and mess.
+- Graceful handling of access violations: by default, it displays a "you can't do that" screen and logs the violation.
+- Minimal effort and mess.
+
+Most importantly, you have **total flexibility**: Authority does not constrain you into using a particular scheme of roles and/or permissions.
+
+Authority lets you: 
+
+- Grant permissions based on users' points (like StackOverflow)
+- Check user roles in a separate, single-sign-on app
+- Disallow certain actions based on time or date
+- Allow an action only for users with compatible browsers
+- ...do anything else you can think of.
+
+All you have to do is define the methods you need on your authorizers. You have all the flexibility of normal Ruby classes. 
+
+**You** make the rules; Authority enforces them.
 
 <a name="flow_of_authority">
 ## The flow of Authority
@@ -180,6 +195,29 @@ ScheduleAuthorizer.updatable_by?(user)
 
 As you can see, you can specify different logic for every method on every model, if necessary. On the other extreme, you could simply supply a [default method](#default_methods) that covers all your use cases.
 
+<a name="passing_options">
+#### Passing Options 
+
+Any options you pass when checking permissions will be passed right up the chain. One use case for this would be if you needed an associated instance in order to do a class-level check. For example:
+
+```ruby
+# I don't have a comment instance to check, but I need to know
+# which post the user wants to comment on
+user.can_create?(Comment, :for => @post)
+```
+
+This would ultimately call `creatable_by?` on the designated authorizer with two arguments: the user and `{:for => @post}`. If you've defined that method yourself, you'd need to ensure that it accepts the options hash before doing this, or you'd get a "wrong number of arguments" error.
+
+There's nothing special about the hash key `:for`; I just think it reads well in this case. You can pass any options that make sense in your case.
+
+If you **don't** pass options, none will be passed to your authorizer, either.
+
+And you could always handle the case above without options if you don't mind creating an extra model instance:
+
+```ruby
+user.can_create?(Comment.new(:post => @post))
+```
+
 <a name="default_methods">
 #### Default Methods
 
@@ -361,18 +399,36 @@ Your method will be handed the `SecurityViolation`, which has a `message` method
 - [TMA](http://www.tma1.com) for employing me and letting me open source some of our code.
 
 <a name="contributing">
+
+## Responses, AKA 'Hollaback'
+
+Do you like Authority? Has it cleaned up your code, made you more personable, and taught you the Secret to True Happiness? Awesome! I'd **love** to get email from you - see my Github profile for the address.
+
 ## Contributing
 
-What should you contribute? Try the TODO file for ideas, or grep the project for 'TODO' comments.
+How can you contribute? Let me count the ways.
+
+### 1. Publicity
+
+If you like Authority, tell people! Blog, tweet, comment, or even... [shudder]... talk with people *in person*. If you feel up to it, I mean. It's OK if you don't.
+
+### 2. Documentation
+
+Add examples to the [wiki](http://github.com/nathanl/authority/wiki) to help others solve problems like yours.
+
+### 3. Issues
+
+Tell me your problems and/or ideas.
 
-How can you contribute?
+### 4. Code or documentation
 
-1. Let's talk! Before you do a bunch of work, open an issue so we can be sure we agree.
-2. Fork this project
-3. Create your feature branch (`git checkout -b my-new-feature`)
-4. `bundle install` to get all dependencies
-5. `rspec spec` to run all tests.
-6. Update/add tests for your changes and code until they pass.
-7. Commit your changes (`git commit -am 'Added some feature'`)
-8. Push to the branch (`git push origin my-new-feature`)
-9. Create a new Pull Request
+1. Have an idea. If you don't have one, check the TODO file or grep the project for 'TODO' comments.
+2. Open an issue so we can talk it over.
+3. Fork this project
+4. Create your feature branch (`git checkout -b my-new-feature`)
+5. `bundle install` to get all dependencies
+6. `rspec spec` to run all tests.
+7. Update/add tests for your changes and code until they pass.
+8. Commit your changes (`git commit -am 'Added some feature'`)
+9. Push to the branch (`git push origin my-new-feature`)
+10. Create a new Pull Request

data/TODO.markdown

@@ -5,7 +5,9 @@
 - Add tests for the generators
 - Test `ActionController` integration
 
-## Documentation
-
 ## Features
 
+### Use translation files
+
+- Move all user-facing messages into en.yml
+- Add other languages

data/lib/authority/abilities.rb

@@ -21,8 +21,12 @@ module Authority
       Authority.adjectives.each do |adjective|
 
         class_eval <<-RUBY, __FILE__, __LINE__ + 1
-          def #{adjective}_by?(user)
-            authorizer.#{adjective}_by?(user)
+          def #{adjective}_by?(user, options = {})
+            if options.empty?
+              authorizer.#{adjective}_by?(user)
+            else
+              authorizer.#{adjective}_by?(user, options)
+            end
           end
         RUBY
       end
@@ -38,8 +42,12 @@ module Authority
     Authority.adjectives.each do |adjective|
 
       class_eval <<-RUBY, __FILE__, __LINE__ + 1
-        def #{adjective}_by?(user)
-          authorizer.#{adjective}_by?(user)
+        def #{adjective}_by?(user, options = {})
+          if options.empty?
+            authorizer.#{adjective}_by?(user)
+          else
+            authorizer.#{adjective}_by?(user, options)
+          end
         end
 
         def authorizer

data/lib/authority/authorizer.rb

@@ -17,8 +17,12 @@ module Authority
     # Each instance method simply calls the corresponding class method
     Authority.adjectives.each do |adjective|
       class_eval <<-RUBY, __FILE__, __LINE__ + 1
-        def #{adjective}_by?(user)
-          self.class.#{adjective}_by?(user)
+        def #{adjective}_by?(user, options = {})
+          if options.empty?
+            self.class.#{adjective}_by?(user)
+          else
+            self.class.#{adjective}_by?(user, options)
+          end
         end
       RUBY
     end
@@ -26,14 +30,18 @@ module Authority
     # Each class method simply calls the `default` method
     Authority.adjectives.each do |adjective|
       class_eval <<-RUBY, __FILE__, __LINE__ + 1
-        def self.#{adjective}_by?(user)
-          default(:#{adjective}, user)
+        def self.#{adjective}_by?(user, options = {})
+          if options.empty?
+            default(:#{adjective}, user)
+          else
+            default(:#{adjective}, user, options)
+          end
         end
       RUBY
     end
 
     # Whitelisting approach: anything not specified will be forbidden
-    def self.default(adjective, user)
+    def self.default(adjective, user, options = {})
       false
     end
 

data/lib/authority/user_abilities.rb

@@ -10,8 +10,12 @@ module Authority
 
     Authority.verbs.each do |verb|
       class_eval <<-RUBY, __FILE__, __LINE__ + 1
-        def can_#{verb}?(resource)
-          resource.#{Authority.abilities[verb]}_by?(self)
+        def can_#{verb}?(resource, options = {})
+          if options.empty?
+            resource.#{Authority.abilities[verb]}_by?(self)
+          else
+            resource.#{Authority.abilities[verb]}_by?(self, options)
+          end
         end
       RUBY
     end

data/lib/authority/version.rb

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

data/spec/authority/abilities_spec.rb

@@ -52,9 +52,22 @@ describe Authority::Abilities do
         AbilityModel.should respond_to(method_name)
       end
 
-      it "should delegate `#{method_name}` to its authorizer class" do
-        AbilityModel.authorizer.should_receive(method_name).with(@user)
-        AbilityModel.send(method_name, @user)
+      describe "if given an options hash" do
+
+        it "should delegate `#{method_name}` to its authorizer class, passing the options" do
+          AbilityModel.authorizer.should_receive(method_name).with(@user, :lacking => 'nothing')
+          AbilityModel.send(method_name, @user, :lacking => 'nothing')
+        end
+
+      end
+
+      describe "if not given an options hash" do
+
+        it "should delegate `#{method_name}` to its authorizer class, passing no options" do
+          AbilityModel.authorizer.should_receive(method_name).with(@user)
+          AbilityModel.send(method_name, @user)
+        end
+
       end
 
     end
@@ -75,10 +88,24 @@ describe Authority::Abilities do
         @ability_model.should respond_to(method_name)
       end
 
-      it "should delegate `#{method_name}` to a new authorizer instance" do
-        AbilityModel.authorizer.stub(:new).and_return(@authorizer)
-        @authorizer.should_receive(method_name).with(@user)
-        @ability_model.send(method_name, @user)
+      describe "if given an options hash" do
+
+        it "should delegate `#{method_name}` to a new authorizer instance, passing the options" do
+          AbilityModel.authorizer.stub(:new).and_return(@authorizer)
+          @authorizer.should_receive(method_name).with(@user, :with => 'mayo')
+          @ability_model.send(method_name, @user, :with => 'mayo')
+        end
+
+      end
+
+      describe "if not given an options hash" do
+        
+        it "should delegate `#{method_name}` to a new authorizer instance, passing no options" do
+          AbilityModel.authorizer.stub(:new).and_return(@authorizer)
+          @authorizer.should_receive(method_name).with(@user)
+          @ability_model.send(method_name, @user)
+        end
+
       end
 
     end

data/spec/authority/authorizer_spec.rb

@@ -23,9 +23,23 @@ describe Authority::Authorizer do
         @authorizer.should respond_to(method_name)
       end
 
-      it "should delegate `#{method_name}` to the corresponding class method by default" do
-        @authorizer.class.should_receive(method_name).with(@user)
-        @authorizer.send(method_name, @user)
+
+      describe "if given an options hash" do
+
+        it "should delegate `#{method_name}` to the corresponding class method, passing the options" do
+          @authorizer.class.should_receive(method_name).with(@user, :under => 'God')
+          @authorizer.send(method_name, @user, :under => 'God')
+        end
+
+      end
+
+      describe "if not given an options hash" do
+
+        it "should delegate `#{method_name}` to the corresponding class method, passing no options" do
+          @authorizer.class.should_receive(method_name).with(@user)
+          @authorizer.send(method_name, @user)
+        end
+
       end
 
     end
@@ -41,10 +55,24 @@ describe Authority::Authorizer do
         Authority::Authorizer.should respond_to(method_name)
       end
 
-      it "should delegate `#{method_name}` to the authorizer's `default` method by default" do
-        able = method_name.sub('_by?', '').to_sym
-        Authority::Authorizer.should_receive(:default).with(able, @user)
-        Authority::Authorizer.send(method_name, @user)
+      describe "if given an options hash" do
+
+        it "should delegate `#{method_name}` to the authorizer's `default` method, passing the options" do
+          able = method_name.sub('_by?', '').to_sym
+          Authority::Authorizer.should_receive(:default).with(able, @user, :with => 'gusto')
+          Authority::Authorizer.send(method_name, @user, :with => 'gusto')
+        end
+
+      end
+
+      describe "if not given an options hash" do
+
+        it "should delegate `#{method_name}` to the authorizer's `default` method, passing no options" do
+          able = method_name.sub('_by?', '').to_sym
+          Authority::Authorizer.should_receive(:default).with(able, @user)
+          Authority::Authorizer.send(method_name, @user)
+        end
+
       end
 
     end
@@ -53,8 +81,19 @@ describe Authority::Authorizer do
 
   describe "the default method" do
 
-    it "should return false" do
-      Authority::Authorizer.default(:implodable, @user).should be_false
+    describe "if given an options hash" do
+
+      it "should return false" do
+        Authority::Authorizer.default(:implodable, @user, {:for => "my_object"}).should be_false
+      end
+    end
+
+    describe "if not given an options hash" do
+
+      it "should return false" do
+        Authority::Authorizer.default(:implodable, @user).should be_false
+      end
+
     end
 
   end

data/spec/authority/user_abilities_spec.rb

@@ -16,10 +16,24 @@ describe Authority::UserAbilities do
       @user.should respond_to(method_name)
     end
 
-    it "should delegate the authorization check to the resource provided" do
-      @ability_model.should_receive("#{Authority.abilities[verb]}_by?").with(@user)
-      @user.send(method_name, @ability_model)
+    describe "if given options" do
+
+      it "should delegate the authorization check to the resource, passing the options" do
+        @ability_model.should_receive("#{Authority.abilities[verb]}_by?").with(@user, :size => 'wee')
+        @user.send(method_name, @ability_model, :size => 'wee')
+      end
+
     end
+
+    describe "if not given options" do
+
+      it "should delegate the authorization check to the resource, passing no options" do
+        @ability_model.should_receive("#{Authority.abilities[verb]}_by?").with(@user)
+        @user.send(method_name, @ability_model)
+      end
+
+    end
+
   end
 
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: authority
 version: !ruby/object:Gem::Version
-  version: 2.0.1
+  version: 2.1.0
   prerelease: 
 platform: ruby
 authors:
@@ -10,11 +10,11 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-06-16 00:00:00.000000000 Z
+date: 2012-08-10 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
-  requirement: &75848730 !ruby/object:Gem::Requirement
+  requirement: &2160582080 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -22,7 +22,7 @@ dependencies:
         version: 3.0.0
   type: :runtime
   prerelease: false
-  version_requirements: *75848730
+  version_requirements: *2160582080
 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,9 +90,20 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 1.8.10
+rubygems_version: 1.8.16
 signing_key: 
 specification_version: 3
 summary: Authority helps you authorize actions in your Rails app using plain Ruby
   methods on Authorizer classes.
-test_files: []
+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