consul 0.8.0 → 0.9.0

data/README.md

@@ -1,19 +1,25 @@
-Consul - A scope-based authorization solution
-=============================================
+Consul - A next gen authorization solution
+==========================================
 
 [![Build Status](https://secure.travis-ci.org/makandra/consul.png?branch=master)](https://travis-ci.org/makandra/consul)
 
-Consul is a authorization solution for Ruby on Rails that uses scopes to control what a user can see or edit.
+Consul is a authorization solution for Ruby on Rails where you describe *sets of accessible things* to control what a user can see or edit.
 
 We have used Consul in combination with [assignable_values](https://github.com/makandra/assignable_values) to solve a variety of authorization requirements ranging from boring to bizarre.
-
 Also see our crash course video: [Solving bizare authorization requirements with Rails](http://bizarre-authorization.talks.makandra.com/).
 
 
-Describing a power for your application
----------------------------------------
+Describing access to your application
+-------------------------------------
+
+You describe access to your application by putting a `Power` model into `app/models/power.rb`.
+Inside your `Power` you can talk about what is accessible for the current user, e.g.
+
+- [A scope of records a user may see](#scope-powers-relations)
+- [Whether the user is allowed to use a particular screen](#boolean-powers)
+- [A list of values a user may assign to a particular attribute](#validating-assignable-values)
 
-You describe access to your application by putting a `Power` model into `app/models/power.rb`:
+A `Power` might look like this:
 
     class Power
       include Consul::Power
@@ -22,46 +28,101 @@ You describe access to your application by putting a `Power` model into `app/mod
         @user = user
       end
 
-      power :notes do
-        Note.by_author(@user)
-      end
-
       power :users do
         User if @user.admin?
       end
 
+      power :notes do
+        Note.by_author(@user)
+      end
+
       power :dashboard do
         true # not a scope, but a boolean power. This is useful to control access to stuff that doesn't live in the database.
       end
 
     end
 
-There are no restrictions on the name or constructor arguments of your power class.
+There are no restrictions on the name or constructor arguments of your this class.
+
+You can deposit all kinds of objects in your power. See the sections below for details.
 
 
-Querying a power
-----------------
+### Scope powers (relations)
 
-Common things you might want from a power:
 
-1. Get its scope
-2. Ask whether it is there
-3. Raise an error unless it its there
-4. Ask whether a given record is included in its scope
-5. Raise an error unless a given record is included in its scope
+A typical use case in a Rails application is to restrict access to your ActiveRecord models. For example:
+
+- Anonymous visitors may only see public posts
+- Users may only see their own notes
+- Only admins may edit users
+
+You do this by making your powers return an ActiveRecord scope (or "relation"):
+
+    class Power
+      ...
+
+      power :notes do
+        Note.by_author(@user)
+      end
+
+      power :users do
+        User if @user.admin?
+      end
+
+    end
 
-Here is how to do all of that:
+You can now query these powers in order to retrieve the scope:
 
     power = Power.new(user)
-    power.notes # => returns an ActiveRecord::Scope
-    power.notes? # => returns true if Power#notes returns a scope
-    power.notes! # => raises Consul::Powerless unless Power#notes returns a scope
+    power.notes  # => returns an ActiveRecord::Scope
+
+Or you can ask if the power is given (meaning it's not `nil`):
+
+    power.notes? # => returns true if Power#notes returns a scope and not nil
+
+Or you can raise an error unless a power its given, e.g. to guard access into a controller action:
+
+    power.notes? # => returns true if Power#notes returns a scope, even if it's empty
+
+Or you ask whether a given record is included in its scope (can be [optimized](#optimizing-record-checks-for-scope-powers)):
+
     power.note?(Note.last) # => returns whether the given Note is in the Power#notes scope. Caches the result for subsequent queries.
+
+Or you can raise an error unless a given record is included in its scope:
+
     power.note!(Note.last) # => raises Consul::Powerless unless the given Note is in the Power#notes scope
 
+See our crash course video [Solving bizare authorization requirements with Rails](http://bizarre-authorization.talks.makandra.com/) for many different use cases you can cover with this pattern.
+
 
-Boolean powers
---------------
+
+### Defining different powers for different actions
+
+If you have different access rights for e.g. viewing or updating posts, simply use different powers:
+
+
+    class Power
+      ...
+
+      power :notes do
+        Note.published
+      end
+
+      power :updatable_notes do
+        Note.by_author(@user)
+      end
+
+      power :destroyable_notes do
+        Note if @user.admin?
+      end
+
+    end
+
+There is also a [shortcut to map different powers to RESTful controller actions](#protect-entry-into-controller-actions).
+
+
+
+### Boolean powers
 
 Boolean powers are useful to control access to stuff that doesn't live in the database:
 
@@ -76,12 +137,12 @@ Boolean powers are useful to control access to stuff that doesn't live in the da
 
 You can query it like the other powers:
 
+    power = Power.new(@user)
     power.dashboard? # => true
     power.dashboard! # => raises Consul::Powerless unless Power#dashboard? returns true
 
 
-Powers that give no access at all
----------------------------------
+### Powers that give no access at all
 
 Note that there is a difference between having access to an empty list of records, and having no access at all.
 If you want to express that a user has no access at all, make the respective power return `nil`.
@@ -99,15 +160,40 @@ Note how the power in the example below returns `nil` unless the user is an admi
 
 When a non-admin queries the `:users` power, she will get the following behavior:
 
-    power.notes # => returns nil
-    power.notes? # => returns false
-    power.notes! # => raises Consul::Powerless
-    power.note?(Note.last) # => returns false
-    power.note!(Note.last) # => raises Consul::Powerless
+    power = Power.new(@user)
+    power.users # => returns nil
+    power.users? # => returns false
+    power.users! # => raises Consul::Powerless
+    power.user?(User.last) # => returns false
+    power.user!(User.last) # => raises Consul::Powerless
+
+
+
+### Powers that only check a given object
+
+Sometimes it is not convenient to define powers as a collection. Sometimes you only want to store a method that
+checks whether a given object is accessible.
 
+To do so, simply define a power that ends in a question mark:
 
-Other types of powers
----------------------
+
+    class Power
+      ...
+
+      power :updatable_post? do |post|
+        post.author == @user
+      end
+
+    end
+
+You can query such an power as always:
+
+    power = Power.new(@user)
+    power.updatable_post?(Post.last) # return true if the author of the post is @user
+    power.updatable_post!(Post.last) # raises Consul::Powerless unless the author of the post is @user
+
+
+### Other types of powers
 
 A power can return any type of object. For instance, you often want to return an array:
 
@@ -134,23 +220,21 @@ You can query it like any other power. E.g. if a non-admin queries this power sh
     power.assignable_note_state!('published') # => raises Consul::Powerless
 
 
-Defining multiple powers at once
---------------------------------
+### Defining multiple powers at once
 
 You can define multiple powers at once by giving multiple power names:
 
     class Power
       ...
 
-      power :destroyable_users, updatable_users do
+      power :destroyable_users, :updatable_users do
         User if admin?
       end
 
     end
 
 
-Powers that require context (arguments)
----------------------------------------
+### Powers that require context (arguments)
 
 Sometimes it can be useful to define powers that require context. To do so, just take an argument in your `power` block:
 
@@ -164,11 +248,52 @@ Sometimes it can be useful to define powers that require context. To do so, just
           %w[committed started finished]
         end
       end
+      
+    end
 
 When querying such a power, you always need to provide the context, e.g.:
 
     story = ...
-    Power.current_assignable_story_state?(story, 'finished')
+    Power.current.assignable_story_state?(story, 'finished')
+
+
+### Optimizing record checks for scope powers
+
+You can query a scope power for a given record, e.g.
+
+    class Power
+      ...
+
+      power :posts do |post|
+        Post.where(:author_id => @user.id)
+      end
+    end
+
+    power = Power.new(@user)
+    power.post?(Post.last)
+
+What Consul does internally is fetch **all** the IDs of the `power.posts` scope and test if the given
+record's ID is among them. This list of IDs is cached for subsequent calls, so you will only touch the database once.
+
+As scary as it might sound, fetching all IDs of a scope scales quiet nicely for many thousand records. There will
+however be the point where you want to optimize this.
+
+What you can do in Consul is to define a second power that checks a given record in plain Ruby:
+
+    class Power
+      ...
+
+      power :posts do |post|
+        Post.where(:author_id => @user.id)
+      end
+
+      power :post? do |post|
+        post.author_id == @user.id
+      end
+
+    end
+
+This way you do not need to touch the database at all.
 
 
 Role-based permissions
@@ -379,10 +504,10 @@ You can find a full list of available dynamic calls below:
 | Dynamic call                                            | Equivalent                                 |
 |---------------------------------------------------------|--------------------------------------------|
 | `Power.current.send(:notes)`                            | `Power.current.notes`                      |
-| `Power.current.include?(:notes)`                        | `Power.current.notes?`                     |
-| `Power.current.include!(:notes)`                        | `Power.current.notes!`                     |
-| `Power.current.include?(:notes, Note.last)`             | `Power.current.note?(Note.last)`           |
-| `Power.current.include!(:notes, Note.last)`             | `Power.current.note!(Note.last)`           |
+| `Power.current.include_power?(:notes)`                  | `Power.current.notes?`                     |
+| `Power.current.include_power!(:notes)`                  | `Power.current.notes!`                     |
+| `Power.current.include_object?(:notes, Note.last)`      | `Power.current.note?(Note.last)`           |
+| `Power.current.include_object!(:notes, Note.last)`      | `Power.current.note!(Note.last)`           |
 | `Power.current.for_record(Note.last)`                   | `Power.current.notes`                      |
 | `Power.current.for_record(:updatable, Note.last)`       | `Power.current.updatable_notes`            |
 | `Power.current.for_model(Note)`                         | `Power.current.notes`                      |

data/Rakefile

@@ -31,7 +31,7 @@ namespace :all do
   desc "Bundle all spec apps"
   task :bundle do
     for_each_directory_of('spec/**/Gemfile') do |directory|
-      system("cd #{directory} && rm -f Gemfile.lock && bundle install")
+      system("cd #{directory} && bundle install")
     end
   end
 

data/lib/consul/controller.rb

@@ -86,7 +86,7 @@ module Consul
         private
 
         define_method :check_power do
-          send(power_method).include!(power_name_for_current_action)
+          send(power_method).include_power!(power_name_for_current_action)
         end
 
         if direct_access_method

data/lib/consul/power.rb

@@ -7,48 +7,41 @@ module Consul
       base.send :include, Memoizer
     end
 
-    def include?(name, *args)
-      args = args.dup
+    private
 
-      context, record = context_and_record_from_args(args, name)
+    def default_include_power?(power_name, *context)
+      # Everything that is not nil is considered as included
+      !!send(power_name, *context)
+    end
 
-      power_value = send(name, *context)
-      if record.nil?
-        !!power_value
-      else
-        # record is given
-        if power_value.nil?
-          false
-        elsif Util.scope?(power_value)
-          if Util.scope_selects_all_records?(power_value)
-            true
-          else
-            power_ids_name = self.class.power_ids_name(name)
-            send(power_ids_name, *context).include?(record.id)
-          end
-        elsif Util.collection?(power_value)
-          power_value.include?(record)
+    def default_include_object?(power_name, *args)
+      object = args.pop
+      context = args
+      power_value = send(power_name, *context)
+      if power_value.nil?
+        false
+      elsif Util.scope?(power_value)
+        if Util.scope_selects_all_records?(power_value)
+          true
         else
-          raise Consul::NoCollection, "can only call #include? on a collection, but power was of type #{power_value.class.name}"
+          power_ids_name = self.class.power_ids_name(power_name)
+          send(power_ids_name, *context).include?(object.id)
         end
+      elsif Util.collection?(power_value)
+        power_value.include?(object)
+      else
+        raise Consul::NoCollection, "can only call #include_object? on a collection, but power was of type #{power_value.class.name}"
       end
     end
 
-    def include!(*args)
-      include?(*args) or raise Consul::Powerless.new("No power to #{args.inspect}")
+    def default_power_ids(power_name, *args)
+      scope = send(power_name, *args)
+      database_touched
+      scope.collect_ids
     end
 
-    private
-
-    def context_and_record_from_args(args, name)
-      context_count = send(self.class.context_count_name(name))
-      context = []
-      context_count.times do
-        arg = args.shift or raise Consul::InsufficientContext, "Insufficient context for parametrized power: #{name}"
-        context << arg
-      end
-      record = args.shift
-      [context, record]
+    def powerless!(*args)
+      raise Consul::Powerless.new("No power to #{[*args].inspect}")
     end
 
     def boolean_or_nil?(value)
@@ -89,28 +82,31 @@ module Consul
         self.current = old_power
       end
 
-      private
+      def define_query_and_bang_methods(name, &query)
+        query_method = "#{name}?"
+        bang_method = "#{name}!"
+        define_method(query_method, &query)
+        define_method(bang_method) { |*args| send(query_method, *args) or powerless!(name, *args) }
+      end
 
       def define_power(name, &block)
-        define_method(name, &block)
-        define_method("#{name.to_s}?") { |*args| include?(name, *args) }
-        define_method("#{name.to_s}!") { |*args| include!(name, *args) }
-        define_method("#{name.to_s.singularize}?") { |*args| include?(name, *args) }
-        define_method("#{name.to_s.singularize}!") { |*args| include!(name, *args) }
-        context_count_method = context_count_name(name)
-        define_method(context_count_method) { block.arity >= 0 ? block.arity : 0 }
-        private context_count_method
-        ids_method = power_ids_name(name)
-        define_method(ids_method) do |*args|
-          scope = send(name, *args)
-          database_touched
-          scope.collect_ids
+        name = name.to_s
+        if name.ends_with?('?')
+          name_without_suffix = name.chop
+          define_query_and_bang_methods(name_without_suffix, &block)
+        else
+          define_method(name, &block)
+          define_query_and_bang_methods(name) { |*args| default_include_power?(name, *args) }
+          if name.singularize != name
+            define_query_and_bang_methods(name.singularize) { |*args| default_include_object?(name, *args) }
+          end
+          ids_method = power_ids_name(name)
+          define_method(ids_method) { |*args| default_power_ids(name, *args) }
+          memoize ids_method
         end
-        memoize ids_method
         name
       end
 
     end
-
   end
 end

data/lib/consul/power/dynamic_access.rb

@@ -4,18 +4,54 @@ module Consul
 
       module InstanceMethods
 
+        def include?(power_name, *args)
+          warn "#include? ist deprececated. Use #include_power? and #include_object? instead."
+          if args.size == 0
+            include_power?(power_name, *args)
+          else
+            include_object?(power_name, *args)
+          end
+        end
+
+        def include!(power_name, *args)
+          warn "#include! ist deprececated. Use #include_power! and #include_object! instead."
+          if args.size == 0
+            include_power!(power_name, *args)
+          else
+            include_object!(power_name, *args)
+          end
+        end
+
+        def include_power?(power_name, *context)
+          send("#{power_name}?", *context)
+        end
+
+        def include_power!(power_name, *context)
+          send("#{power_name}!", *context)
+        end
+
+        def include_object?(power_name, *context_and_object)
+          power_name = power_name.to_s
+          send("#{power_name.singularize}?", *context_and_object)
+        end
+
+        def include_object!(power_name, *context_and_object)
+          power_name = power_name.to_s
+          send("#{power_name.singularize}!", *context_and_object)
+        end
+
         def for_record(*args)
           send(name_for_record(*args))
         end
 
         def include_record?(*args)
           adjective, record = Util.adjective_and_argument(*args)
-          include?(name_for_record(*args), record)
+          include_object?(name_for_record(*args), record)
         end
 
         def include_record!(*args)
           adjective, record = Util.adjective_and_argument(*args)
-          include!(name_for_record(*args), record)
+          include_object!(name_for_record(*args), record)
         end
 
         def name_for_model(*args)
@@ -29,11 +65,11 @@ module Consul
         end
 
         def include_model?(*args)
-          include?(name_for_model(*args))
+          include_power?(name_for_model(*args))
         end
 
         def include_model!(*args)
-          include!(name_for_model(*args))
+          include_power!(name_for_model(*args))
         end
 
         def name_for_record(*args)

data/lib/consul/version.rb

@@ -1,3 +1,3 @@
 module Consul
-  VERSION = '0.8.0'
+  VERSION = '0.9.0'
 end

data/spec/rails-2.3/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: ../..
   specs:
-    consul (0.7.0)
+    consul (0.8.0)
       edge_rider
       memoizer
       rails

data/spec/rails-3.0/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: ../..
   specs:
-    consul (0.7.0)
+    consul (0.8.0)
       edge_rider
       memoizer
       rails

data/spec/rails-3.2/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: ../..
   specs:
-    consul (0.7.0)
+    consul (0.8.0)
       edge_rider
       memoizer
       rails

data/spec/shared/app_root/app/models/power.rb

@@ -13,10 +13,30 @@ class Power
     Client
   end
 
+  power :fast_clients do
+    Client.active
+  end
+
+  power :fast_client? do |client|
+    !client.deleted?
+  end
+
   power :client_notes do |client|
     client.notes
   end
 
+  power :fast_client_notes do |client|
+    client.notes
+  end
+
+  power :fast_client_note? do |client, note|
+    note.client_id == client.id
+  end
+
+  power :fast_client_note_without_collection? do |client, note|
+    note.client_id == client.id
+  end
+
   power :notes do
     Note.scoped(:joins => :client)
   end

data/spec/shared/consul/power_spec.rb

@@ -24,7 +24,7 @@ describe Consul::Power do
 
   context 'nil powers' do
 
-    describe '#include?' do
+    describe 'query methods' do
 
       context 'when no record is given' do
 
@@ -49,7 +49,7 @@ describe Consul::Power do
 
     end
 
-    describe '#include!' do
+    describe 'bang methods' do
 
       context 'when no record is given' do
 
@@ -86,7 +86,7 @@ describe Consul::Power do
       @user.power.client_notes(@client1).should == [@client1_note1, @client1_note2]
     end
 
-    describe '#include?' do
+    describe 'query methods' do
 
       context 'when no record is given' do
 
@@ -137,19 +137,55 @@ describe Consul::Power do
           @user.power.client_note?(@client1, @client2_note1).should be_false
         end
 
-      end
+        context 'optimization through additional definition of a Ruby method' do
+
+          it 'should not affect collection access' do
+            @user.power.fast_clients.to_a.should =~ [@client1, @client2]
+            @user.power.fast_client_ids.to_a.should =~ [@client1.id, @client2.id]
+            @user.power.fast_clients?.should be_true
+          end
+
+          it 'should no longer access the database when checking inclusion of a single record' do
+            @user.power.should_not_receive(:database_touched)
+            @user.power.fast_client?(@client1).should be_true
+            @user.power.fast_client?(@deleted_client).should be_false
+          end
 
-      context 'when a power with arguments is given insufficient context' do
+          it 'is used by and bang methods' do
+            @user.power.should_not_receive(:database_touched)
+            expect { @user.power.fast_client!(@client1) }.to_not raise_error
+            expect { @user.power.fast_client!(@deleted_client) }.to raise_error(Consul::Powerless)
+          end
+
+          it 'works with parametrized powers' do
+            @user.power.should_not_receive(:database_touched)
+            @user.power.fast_client_note?(@client1, @client1_note1).should be_true
+            @user.power.fast_client_note?(@client1, @client2_note1).should be_false
+            expect { @user.power.fast_client_note!(@client1, @client1_note1) }.to_not raise_error
+            expect { @user.power.fast_client_note!(@client1, @client2_note1) }.to raise_error(Consul::Powerless)
+          end
+
+          it 'works when only the optimized power is defined, without a collection power' do
+            @user.power.should_not_receive(:database_touched)
+            @user.power.fast_client_note_without_collection?(@client1, @client1_note1).should be_true
+            @user.power.fast_client_note_without_collection?(@client1, @client2_note1).should be_false
+          end
 
-        it 'should raise an error' do
-          expect { @user.power.client_notes? }.to raise_error(Consul::InsufficientContext)
         end
 
       end
 
+      #context 'when a power with arguments is given insufficient context' do
+      #
+      #  it 'should raise an error' do
+      #    expect { @user.power.client_notes? }.to raise_error(ArgumentError)
+      #  end
+      #
+      #end
+
     end
 
-    describe '#include!' do
+    describe 'bang methods' do
 
       context 'when no record is given' do
 
@@ -207,7 +243,7 @@ describe Consul::Power do
       @user.power.key_figures.should == %w[amount working_costs]
     end
 
-    describe '#include?' do
+    describe 'query methods' do
 
       context 'when no record is given' do
 
@@ -237,7 +273,7 @@ describe Consul::Power do
 
     end
 
-    describe '#include!' do
+    describe 'bang methods' do
 
       context 'when no record is given' do
 
@@ -275,7 +311,7 @@ describe Consul::Power do
       @user.power.always_false.should == false
     end
 
-    describe '#include?' do
+    describe 'query methods' do
 
       context 'when no record is given' do
 
@@ -295,15 +331,15 @@ describe Consul::Power do
 
       context 'with a given record' do
 
-        it 'should raise Consul::NoCollection' do
-          expect { @user.power.always_true?('foo') }.to raise_error(Consul::NoCollection)
-        end
+        #it 'should raise Consul::NoCollection' do
+        #  expect { @user.power.always_true?('foo') }.to raise_error(Consul::NoCollection)
+        #end
 
       end
 
     end
 
-    describe '#include!' do
+    describe 'bang methods' do
 
       context 'when no record is given' do
 
@@ -323,9 +359,10 @@ describe Consul::Power do
 
       context 'with a given record' do
 
-        it 'should raise Consul::NoCollection' do
-          expect { @user.power.always_true!('foo') }.to raise_error(Consul::NoCollection)
-        end
+        #it 'should raise Consul::NoCollection' do
+        #  expect { @user.power.always_true!('foo') }.to raise_error(Consul::NoCollection)
+        #end
+
       end
 
     end
@@ -339,7 +376,7 @@ describe Consul::Power do
       @user.power.api_key.should == 'secret-api-key'
     end
 
-    describe '#include?' do
+    describe 'query methods' do
 
       context 'when no record is given' do
 
@@ -357,15 +394,15 @@ describe Consul::Power do
 
       context 'with a given record' do
 
-        it 'should raise Consul::NoCollection' do
-          expect { @user.power.api_key?('foo') }.to raise_error(Consul::NoCollection)
-        end
+        #it 'should raise Consul::NoCollection' do
+        #  expect { @user.power.api_key?('foo') }.to raise_error(Consul::NoCollection)
+        #end
 
       end
 
     end
 
-    describe '#include!' do
+    describe 'bang methods' do
 
       context 'when no record is given' do
 
@@ -383,9 +420,9 @@ describe Consul::Power do
 
       context 'with a given record' do
 
-        it 'should raise Consul::NoCollection' do
-          expect { @user.power.api_key!('foo') }.to raise_error(Consul::NoCollection)
-        end
+        #it 'should raise Consul::NoCollection' do
+        #  expect { @user.power.api_key!('foo') }.to raise_error(Consul::NoCollection)
+        #end
 
       end
 

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification 
 name: consul
 version: !ruby/object:Gem::Version 
-  hash: 63
+  hash: 59
   prerelease: 
   segments: 
   - 0
-  - 8
+  - 9
   - 0
-  version: 0.8.0
+  version: 0.9.0
 platform: ruby
 authors: 
 - Henning Koch
@@ -15,7 +15,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2013-05-22 00:00:00 +02:00
+date: 2013-07-19 00:00:00 +02:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency