allowy 0.2.4 → 0.2.4.1

data/README.md

@@ -14,10 +14,10 @@ CanCan doesn't work very well for me when Ability definitions grow above 20 line
 
 - it becomes **really hard to track down** why something was (or not) allowed.
 - **DSL enforces** you to use ActiveRecord-like scopes or blocks. It gets harder to maintain.
-- The Ability class contains **all the definitions for everything**. Hard to test, hard to maintain unless carefully refactor it.
-- Implicit permission - CanCan tries to be very smart (and is indeed) using aliases such as `:manage` but it makes even harder to maintain.
+- The Ability class contains **all the definitions for everything**. Hard to test, hard to maintain unless you carefully refactor it.
+- Implicit permission - CanCan tries to be very smart (and is indeed) using aliases such as `:manage` but it makes even harder to understand it.
 - Implicit permission - you can use any symbol to check permissions. `:love_people` will do, even if you never defined it.
-- A little bit **tight to ORM**. When using with database such as neo4j, some smalish things don't work. So I prefer to be explicit.
+- A little bit **tight to ORM**. When using with database such as neo4j, some small-ish things don't work. So I prefer to be explicit.
 - **Testing** an ability for a single class often depends on too many others.
 - **Refacoring** of the abilities feels like rolling your own authorization library.
 
@@ -36,7 +36,7 @@ gem 'allowy'
 
 Then `bundle install`.
 
-Or use `allowy` gem any other way you are not in Rails.
+Or use `allowy` gem as usually.
 
 # Usage
 
@@ -53,7 +53,7 @@ If you want to safeguard `Page` class then define `PageAccess` class:
 class PageAccess
   include Allowy::AccessControl
 
-  # This will allow you to ask: can? :view, page
+  # This will allow you to ask: `can? :view, page`
   # The truthy result of this function will grant access, otherwise not.
   def view?(page)
     page and page.published?
@@ -64,11 +64,11 @@ class PageAccess
   end
 end
 
-# Then, in rails, you would use it:
+# Then, in rails controller/view, you would use it:
 can? :view, page
 cannot? :edit, page
 authorize! :view, page # raises Allowy::AccessDenied if can?(:view, page) returns false
-can? :love_people, page # Will raise error because `love_people` is not defined on the Access Control class
+can? :love_people, page # Will raise NoMethodError because `love_people` is not defined on the Access Control class
 ```
 
 ## Context
@@ -82,18 +82,23 @@ class PageAccess
   include Allowy::AccessControl
 
   def view?(page)
-    return true if context.params[:hiddedn_hack_for_admin]
+    return true if context.params[:hidden_hack_for_admin]
     context.user_signed_in? and page.published?
   end
 end
 ```
 
-If you want to change the context in Rails then just override it in the controller or globally in the `ApplicationController`:
+If you want to change the context in Rails then just override it in the controller or globally in the `ApplicationController`.
+The only requirement for the context is that it should mix-in the `Allowy::Context` module.
 
 ```ruby
+class CmsContext < Hash
+  include Allowy::Context
+end
+
 class PagesController < ApplicationController
   def allowy_context
-    {realy: 'anything', can_be: 'here', even: params}
+    CmsContext.new {realy: 'anything', can_be: 'here', even: params}
   end
 end
 ```
@@ -101,7 +106,7 @@ end
 ## More comprehensive example
 
 You probably have multiple classes that you want to protect.
-I recommend creating your own base class to provide common context and maybe some utility methods:
+I recommend creating your own base class or module to provide common context and maybe some utility methods:
 
 ```ruby
 class DefaultAccess
@@ -179,7 +184,11 @@ To test the access control classes you can just instantiate those passing contex
 Most of the time you will stub out the context, so the test isolation is a piece of cake.
 
 You need to `require 'allowy/rspec'`.
-It will give you RSpec matcher `be_able_to` and `ignore_authorization!` macro for controller specs.
+It will give you:
+
+- `be_able_to` RSpec matcher;
+-  `ignore_authorization!` macro for controller specs;
+-  `should_authorize_for!` macro for controller specs (can **only** be used with `ignore_authorization!`).
 
 
 ```ruby
@@ -197,17 +206,32 @@ describe PageAccess do
       subject.view?(page).should be_false
     end
 
-    context "when published" do
-      before { page.publish! }
-      it { should be_able_to :view, page }
+    context "I prefer RSpec contexts" do
+      subject { PageAccess.new(stub(:current_user: user)).view?(page) }
+
+      context "when logged in" do
+        let(:user) { stub 'User' }
+        context "and page is wiki" do
+          before { page.stub(wiki?: true) }
+          it { should be_true }
+        end
+        context "and page is not wiki" do
+          before { page.stub(wiki?: false) }
+          it { should be_false }
+        end
+      end
+
+      context "when anonim" do
+        let(:user) { nil }
+        it { should be_false }
+      end
     end
-  end
 
-  # and so on
+  end
 end
 
 
-# Example of a controller specs
+# Example of a controller spec
 describe PagesController do
   # This will always grant access, so you don't have to create too many objects
   # But make sure you test PageAccess separately as in the example above
@@ -225,25 +249,6 @@ end
 
 ```
 
-But if you don't want to stub the context because you access its `can?`, `cannot?` or `authorize!` methods
-(allwing permission delegation) then you can simply mix the `Allowy::Context` in:
-
-```ruby
-class ControllerLikeContext
-  include Alllowy::Context
-  attr_accessor :current_user
-
-  def initialize(user)
-    @current_user = user
-  end
-end
-
-# Then you can simply instantiate it to check the permissions:
-ControllerLikeContext.new(that_user).should be_able_to :edit, Blog
-ControllerLikeContext.new(this_user).should_not be_able_to :edit, Blog
-```
-
-
 # Development
 
 

data/lib/allowy/access_control.rb

@@ -1,4 +1,38 @@
 module Allowy
+  # This module provides the interface for implementing the access control actions.
+  # In order to use it, mix it into a poor Ruby class and define methods ending with `?`.
+  # For example:
+  #
+  #   @example
+  #   class PageAccess
+  #     include Allowy::AccessControl
+  #
+  #     def view?(page)
+  #       page and page.wiki? and context.user_signed_in?
+  #     end
+  #
+  # And then you can check the permissions from a controller:
+  #
+  #   @example
+  #   def show
+  #     @page = Page.find params[:id]
+  #     authorize! :view, @page
+  #   end
+  #
+  #
+  # You can also check the permissions outside of the controller, but you need a similar `Allowy::Context` class:
+  #
+  #   @example
+  #   class CucumberContext
+  #     include Allowy::Context
+  #     attr_accessor :current_user
+  #     def initialize(user)
+  #       @current_user = user
+  #     end
+  #   end
+  #
+  #   CucumberContext.new(that_user).should be_able_to :create, Blog
+  #
   module AccessControl
     extend ActiveSupport::Concern
     included do

data/lib/allowy/context.rb

@@ -1,8 +1,8 @@
 module Allowy
 
-  # This module provides the default and common context to for checking the permissions.
-  # It is mixed into the Controller in Rails by default and provides an wasy way to reuse it
-  # in other parts of the application (in RSpec or Cucumber) without needint a controller.
+  # This module provides the default and common context for checking the permissions.
+  # It is mixed into controllers in Rails by default and provides an easy way to reuse it
+  # in other parts of the application (in RSpec or Cucumber) without needing a controller.
   # For example, you can use this code in your Cucumber features:
   #
   #   @example
@@ -14,7 +14,7 @@ module Allowy
   #       @current_user = user
   #     end
   #
-  # And the you can easily check the permissions simply using something like:
+  # And the you can easily check the permissions like so:
   #
   #   @example
   #   CustomContext.new(that_user).should be_able_to :create, Blog

data/lib/allowy/version.rb

@@ -1,3 +1,3 @@
 module Allowy
-  VERSION = "0.2.4"
+  VERSION = "0.2.4.1"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: allowy
 version: !ruby/object:Gem::Version
-  version: 0.2.4
+  version: 0.2.4.1
   prerelease: 
 platform: ruby
 authors:
@@ -9,11 +9,11 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-04-18 00:00:00.000000000 Z
+date: 2012-04-19 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: i18n
-  requirement: &70247249036100 !ruby/object:Gem::Requirement
+  requirement: &70101345958680 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -21,10 +21,10 @@ dependencies:
         version: '0'
   type: :runtime
   prerelease: false
-  version_requirements: *70247249036100
+  version_requirements: *70101345958680
 - !ruby/object:Gem::Dependency
   name: activesupport
-  requirement: &70247249035480 !ruby/object:Gem::Requirement
+  requirement: &70101345957600 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ~>
@@ -32,10 +32,10 @@ dependencies:
         version: '3.2'
   type: :runtime
   prerelease: false
-  version_requirements: *70247249035480
+  version_requirements: *70101345957600
 - !ruby/object:Gem::Dependency
   name: rspec
-  requirement: &70247249034940 !ruby/object:Gem::Requirement
+  requirement: &70101345946120 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -43,10 +43,10 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *70247249034940
+  version_requirements: *70101345946120
 - !ruby/object:Gem::Dependency
   name: pry
-  requirement: &70247249034400 !ruby/object:Gem::Requirement
+  requirement: &70101345945020 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -54,10 +54,10 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *70247249034400
+  version_requirements: *70101345945020
 - !ruby/object:Gem::Dependency
   name: guard
-  requirement: &70247249033880 !ruby/object:Gem::Requirement
+  requirement: &70101345944200 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -65,10 +65,10 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *70247249033880
+  version_requirements: *70101345944200
 - !ruby/object:Gem::Dependency
   name: guard-rspec
-  requirement: &70247249023080 !ruby/object:Gem::Requirement
+  requirement: &70101345943120 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -76,7 +76,7 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *70247249023080
+  version_requirements: *70101345943120
 description: Allowy provides CanCan-like way of checking permission but doesn't enforce
   a tight DSL giving you more control
 email: