cantango 0.8.0

data/spec/integration/performance/raw_performance.rb

@@ -0,0 +1,11 @@
+require 'dummy_spec_helper'
+require'integration/performance/helpers/ability_raw'
+
+describe "CanTango::Ability raw performance (without rails)" do
+ 
+  it "total without engines" do
+    @user = User.create!(:name => "Stanislaw")
+    CanTangoTest.new(@user)
+  end
+
+end

data/spec/integration/user/articles_spec.rb

@@ -0,0 +1,39 @@
+require 'dummy_spec_helper'
+
+feature "Articles", %q{
+  In order to have an awesome blog
+  As an author
+  I want to create and manage articles
+} do
+
+  background do
+    Article.create!(:title => 'one')
+    Article.create!(:title => 'two')
+
+    @user = User.create! :name => 'stanislaw', :role => 'user', :email => 'stanislaw@mail.ru'
+    @editor = User.create! :name => 'editor', :role => 'editor', :email => 'editor@mail.ru'
+  end
+
+  scenario "Article index" do
+    visit '/articles'
+    page.should have_content('one')
+    page.should have_content('two')
+  end
+
+  scenario "Show article to user stanislaw" do
+    visit '/login_user/stanislaw'
+
+    visit '/articles/one' # using friendly id :)
+    page.should have_content('one')
+    visit '/articles/two'
+    page.should have_content('two')
+  end
+
+  scenario "Show article to editor" do
+    visit '/login_user/editor'
+
+    visit '/articles/one' # using friendly id :)
+    page.should have_content('one')
+    #page.should have_content('two')
+  end
+end

data/spec/integration/user/concerto_spec.rb

@@ -0,0 +1,39 @@
+require 'dummy_spec_helper'
+
+feature "Concertos", %q{
+  In order to have an awesome musical pages 
+  As an user having role_groups 'composers'
+  I want to do something with concertos (According to role_groups)
+} do
+
+  background do
+    Concerto.create!(:title => 'one')
+    Concerto.create!(:title => 'two')
+
+    @composer = User.create!(:name => 'composer', :role_groups => 'composers', :email => 'stanislaw@mail.ru')
+    @musician = User.create! :name => 'musician', :role_groups => 'musicians', :email => 'editor@mail.ru'
+  end
+
+  scenario "Concerto index" do
+    visit '/concertos'
+    page.should have_content('one')
+    page.should have_content('two')
+  end
+
+  scenario "Show concerto to composer" do
+    visit '/login_user/composer'
+
+    visit '/concertos/one' # using friendly id :)
+    page.should have_content('one')
+    visit '/concertos/two'
+    page.should have_content('two')
+  end
+
+  scenario "Show concerto to musician" do
+    visit '/login_user/musician'
+
+    visit '/concertos/one' # using friendly id :)
+    page.should have_content('one')
+    #page.should have_content('two')
+  end
+end

data/spec/note_on_caching_and_dynamic.textile

@@ -0,0 +1,114 @@
+h1. Note on caching.
+
+First of all section of Ryan's wiki on Defining Abilities with Blocks.
+
+h2. Only for Object Attributes
+
+The block is only evaluated when an actual instance object is present. 
+It is not evaluated when checking permissions on the class (such as in the index action). 
+This means any conditions which are not dependent on the object attributes should be moved outside of the block.
+
+<pre>
+<code>
+  #don't do this
+  can :update, Project do |project|
+    user.admin? # this won't always get called
+  end
+    
+  #do this
+  can :update, Project if user.admin?
+</code>
+</pre>
+
+<hr/>
+
+What we have here really are conditions of two types: conditions outside blocks and inside blocks.
+
+I) Conditions outside blocks. They can't allow dynamic.
+
+Remember failing spec about #dynamic_rules do not react on changes of $something_dynamic (bspec spec/cantango/permit_engine/permit/permit_static_and_dynamic_rules_spec.rb)?
+
+Consider _failing_ case I created based on excerpt from Ryan's ability_spec.rb. It behaves the same way as ours failing spec.
+It is ugly but I want to show that there is no possibility to allow dynamic on conditions outside blocks:
+
+<pre>
+<code>
+  before(:each) do
+    @ability = Object.new
+    @ability.extend(CanCan::Ability)
+  end
+  
+  it "should be able to :read anything" do
+    $something = true
+    @ability.can :read, :all if $something_dynamic
+    @ability.can?(:read, :all).should be_true
+    $something = false
+    @ability.can?(:read, :all).should be_false
+  end
+</code>
+</pre>
+
+It shows us, that "can :update, Project if user.admin?" (see Ryan's code above) - is a fiction - no real dynamic!
+
+II) Conditions inside blocks.
+
+Present Ryan's #can work the following way:
+
+<pre>
+<code>
+  can :read, Article |article|
+    article.attribute ?   # article here is INSTANCE!
+  end
+</code>
+</pre>
+
+If you call @can?(:read, Article.new)@ -- inside conditions are evaluated.
+If you call @can?(:read, Article)@ -- inside conditions are SKIPPED!
+
+Review my pull request again (https://github.com/ryanb/cancan/pull/433) - 
+I did this because of I want to allow dynamic not only on instance attributes but wider - 
+on some global dynamic things like Time.now < ?
+
+
+My resume:
+
+I quickly explored a possibility to collect and call #dynamic_rules from all permits at the moment #can? was summoned and see - that 
+it is not possible with the current design we have. Making wrapping patch will be ugly here.
+
+
+Better I suggest write any dynamic we want INSIDE #can's condition blocks like
+
+<pre>
+<code>
+  can :read, Article do |article|
+    $something_dynamic == true
+  end
+</code>
+</pre>
+
+Because outside conditions don't work as I described above.
+
+If we run into this direction (inside conditions blocks) then we can expect dynamic conditions of two types:
+
+I) Instance conditions - which are based on instance attributes. CanCan's Rule deals with instances (can?(:read, Article.new)) ok now.
+
+II) (rare, but anyway needed) Some global conditions which applied to the class fx Article (not instance Article.new) as a whole. To address this case 
+I suggested my pull request #433, because Ryan's can? expect now that if we want conditions inside blocks being evaluated we should
+call can? on instances. My solution is very simple: extend usage of #can? on classes too. If we call #can? on Class then
+if block condition deals with instance attributes it'll of course raise error which we gracefully rescue and return true - 
+in fact now Rule returns conditions'true without evaluating block AT ALL if #can? is called on Class.
+
+And IF BLOCK CONTAINS some condition related not to instance but to CLASS and has REALLY SOMETHING GLOBAL/DYNAMIC NOT INSTANCE-RELATED
+then we EVALUATE inside conditions ok.
+
+This approach will lead us to completely drop "caching/static&dynamic_rules" piece because placed dynamic inside conditions, 
+WE ALREADY HAVE "CACHED" #rules, which emerge at the moment of CanTango::Ability is initialized and live unchanged 
+throughout entire CanTango::Ability lifecycle.
+
+My request to you is follow carefully all above and consider pull request #433 again.
+
+I think dynamic things I talk here about really MAKE SENSE. As for us as for extending CanCan himself.
+For now CanCan doesn't allow DYNAMIC that is NO INSTANCE-RELATED!
+
+
+UPD: See my comment on pull request #433.

data/spec/path_helper.rb

@@ -0,0 +1,9 @@
+def spec_root_path
+  File.dirname(__FILE__)
+end
+
+def dummy_root_path
+  File.join(spec_root_path, 'dummy')
+end
+
+

data/spec/simple_roles.rb

@@ -0,0 +1,46 @@
+module SimpleRoles
+  module ClassMethods 
+  
+    def is_role_in_group?(role, group)
+      raise "No group #{group} defined in User model" if !role_groups.has_key?(group)
+      role_groups[group].include?(role) 
+    end
+  
+    def role_groups
+      {:bloggers => [:editor]} 
+    end
+
+    def roles
+      [:guest, :user, :admin, :editor]
+    end
+  end
+
+  module InstanceMethods
+
+    attr_accessor :role
+    attr_accessor :role_groups_list
+
+    def has_role? rolle
+      roles_list.include? rolle
+    end
+
+    def has_any_role? roles
+      roles.include?(role.to_sym)
+    end
+
+    def roles_list
+      role.to_s.scan(/\w+/).map{|r| r.to_sym}
+    end
+
+    def is_in_group? group
+      role_groups_list.include? group
+    end
+    alias_method :in_role_group?, :is_in_group?
+
+    def role_groups_list
+      return role_groups.scan(/\w+/).map(&:to_sym) if respond_to?(:role_groups) && !role_groups.nil?
+      @role_groups_list || [] #[:bloggers]
+    end
+  end
+
+end

data/spec/spec_helper.rb

@@ -0,0 +1,22 @@
+require 'require_all'
+require 'rspec'
+require 'cancan/matchers'
+require 'cantango'
+require 'cantango/rspec'
+require 'factory_girl'
+require 'mocha'
+require 'factories'
+
+require 'cutter'
+
+# require 'moneta'
+
+#Cutter::Inspection.quiet!
+
+require 'simple_roles'
+
+CanTango.configure do |config|
+  config.permission.config_path File.dirname(__FILE__) + '/fixtures/config'
+  config.cache.set :off
+end
+#require_all File.dirname(__FILE__) + '/fixtures'

data/wiki/ability/initialize.markdown

@@ -0,0 +1,45 @@
+The **CanTango::Ability** is initialized with a candidate and an options
+hash.
+
+## Candidate
+
+The candidate is any object that can have roles and/or role groups
+behavior attached. A candidate is usually either user and in some cases
+might be a user account.
+
+## Options hash
+
+When used from a web framework such as Rails, the options hash
+is populated with essential objects such as:
+
+* Request
+* Session
+* Params
+
+These objects are then made available to the permission rules for evaluation.
+Some rules might dependen on whether the user is accessing the site
+from localhost or if the user has a given session state.
+
+## The Flow
+
+1. Use cached rules if available for user
+2. Generate rules for user
+3. Cache rules for user
+
+### Use cache rules
+
+See [[Rules cache]]
+
+### Generate rules
+
+1. Generate Permission rules from store
+2. Generate Permit rules from classes
+
+### Cache rules
+
+Generate a unique hash key for the user and marshal all the rule in a
+store with that key as identifier. If the user changes, the rules
+for the old key will be invalidated and new rules generated for the new
+key.
+
+

data/wiki/api/user/api.markdown

@@ -0,0 +1,88 @@
+Cantango comes with the following Core APIs for users:
+
+* Can API
+* Scope API
+
+The examples below assume we have the user models _User_ and _Admin_ registered as Cantango users.
+See [[Registration of User models]].
+
+## User Can API
+
+The Can API is very similar to the CanCan API but instead uses a `CanTango::Ability` for a specific kind of current user.
+The devise methods `#current_xxxx` such as current_user, current_admin etc. are wll integrated in the Can API.
+For the user models User and Admin, Cantango will provide the following API:
+
+API methods:
+
+* user_can? actions, targets
+* user_cannot? actions, targets
+* admin_can? actions, targets
+* admin_cannot? actions, targets
+
+Example use:
+
+```ruby
+if user_can? :edit, Article
+  # do sth
+end
+```
+
+```ruby
+if admin_cannot? :manage, Article
+  # do sth
+end
+```
+
+## User Scope API
+
+The Scope API is useful when you want to do several ability tests for the same kind of user.
+
+API methods:
+
+* scope_user type, options = {}, &block
+* real_user type, options = {}, &block
+
+`#scope_user` is used to define an ability scope for a specific user. The
+permission API can then operate on this ability scope directly instead
+of having to create the ability each time.
+
+Example use `#scope_user`:
+
+```ruby
+scope_user :admin do |admin|
+  if admin.can?(:edit, Article) || admin.can?(:read, Post)
+    # do stuff
+  end
+  if admin.can? :delete, Article
+    # delete link here
+  end
+end
+```
+
+### Real user
+
+The method `#real_user` is used to explicitly negate masquerading within the scope.
+Thus the permissions apply to the real user, not the masqueraded user.
+
+Assume we have an app divided into a public app and an admin app.
+
+For an Admin user it could make sense to masquerade as a Public user in
+the public part of the application, but remain as an Admin user in the
+admin app while remaining in the same session.
+
+This can be achieve using `#real_user` in the admin app.
+
+Example use `#real_user`:
+
+```ruby
+real_user :admin do |admin|
+  if admin.can?(:edit, Article) || admin.can?(:read, Post)
+    # do stuff
+  end
+  if admin.can? :delete, Article
+    # delete link here
+  end
+end
+```
+
+

data/wiki/api/user_account/api.markdown

@@ -0,0 +1,88 @@
+The User Account APIs are very similar to the [[User APIs]]
+
+* Can API
+* Scope API
+
+Assume we have the account models UserAccount and AdminAccount registered as Cantango users.
+See [[Registration of User Account models]] for details.
+
+## Account Can API
+
+The Account Can API expects methods in the form `#current_xxxx` are available for each type of user account.
+In our scenario, `#current_user_account` and `#current_admin_account` should be available.
+Cantango will provide the following API:
+
+API methods:
+
+* user_can? actions, targets
+* user_cannot? actions, targets
+* admin_can? actions, targets
+* admin_cannot? actions, targets
+
+Example use:
+
+```ruby
+if user_account_cannot? :edit, Article
+  # do sth
+end
+```
+
+```ruby
+if admin_account_can? :manage, Article
+  # do sth
+end
+```
+
+## Account Scope API
+
+The Scope API is useful when you want to do several ability tests for the same kind of user account.
+
+API methods:
+* scope_acount type, options = {}, &block
+* as_real_account type, options = {}, &block
+
+`#scope_account` is used to define an ability scope for a specific user account. The
+permission API can then operate on this ability scope directly instead
+of having to create the ability each time.
+
+Example use #scope_account:
+
+```ruby
+scope_account :admin do |account|
+  if account.can?(:edit, Article) || account.can?(:read, Post)
+    # do stuff
+  end
+  if account.can? :delete, Article
+    # delete link here
+  end
+end
+```
+
+### Real account
+
+`#real_account` is used to explicitly negate masquerading within the scope.
+Thus the permissions apply to the real account, not the masqueraded account.
+
+Assume we have an app divided into a public app and an admin app.
+
+For an Admin user it could make sense to masquerade as if he was logged
+in to the Public account in the public part of the application. 
+The admin should remain as an Admin user on the Admin account when
+accessing the admin app, while remaining in the same session.
+
+This can be achieve using `#real_account` in the admin app.
+
+Example use #real_account:
+
+```ruby
+real_account :admin do |account|
+  if account.can?(:edit, Article) || account.can?(:read, Post)
+    # do stuff
+  end
+  if account.can? :delete, Article
+    # delete link here
+  end
+end
+```
+
+