allowy 0.1.0 → 0.1.1

data/README.md

@@ -3,21 +3,23 @@
 Allowy is the authorization library that doesn't enforce tight DSL on you.
 It is very simple yet powerful.
 
-If you have any questions please contact me [@dnagir](http://www.ApproachE.com).
-
 ## Why another one?
 
 I've been using really great [cancan](https://github.com/ryanb/cancan) gem by Ryan Bates for a long time.
 It does its job amazingly well.
 
+Allowy is basically the result of refactoring the CanCan Ability class. I then extracted it into a gem.
+
 CanCan doesn't work very well for me when Ability definitions grow above 20 lines or so:
 
-- it becomes **really** hard to track down why something was (or not) allowed.
-- DSL enforces you to use ActiveRecord-like scopes or block to fall back. Those grow and it gets hard to maintain.
-- The Ability class contains all the definitions for everything. Hard to test, hard to maintain.
+- 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.
 - 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 smalish 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.
 
 So I decided to put up allowy to solve those issue for me.
 
@@ -65,8 +67,8 @@ end
 # Then, in rails, you would use it:
 can? :view, page
 cannot? :edit, page
-authorize! :view, page # raises Allowy::AccessDenied if can?(:view, page) return false
-can? :love_people, page # Will fail because `love_people` is not defined on the Access Control class
+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
 ```
 
 ## Context
@@ -80,19 +82,19 @@ class PageAccess
   include Allowy::AccessControl
 
   def view?(page)
+    return true if context.params[:hiddedn_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 on a single controller or globally on the `ApplicationController`:
+If you want to change the context in Rails then just override it in the controller or globally in the `ApplicationController`:
 
 ```ruby
-class DefaultAccess
-  include Allowy::AccessControl
-  # This will give you methods without the need to go to context object
-  delegate :current_user,    :to => :context
-  delegate :current_company, :to => :context
+class PagesController < ApplicationController
+  def allowy_context
+    {realy: 'anything', can_be: 'here', event: params}
+  end
 end
 ```
 
@@ -104,16 +106,22 @@ I recommend creating your own base class to provide common context and maybe som
 ```ruby
 class DefaultAccess
   include Allowy::AccessControl
+  delegate :current_user,    :to => :context
+  delegate :current_company, :to => :context
+
+  def domain_name
+    context.request.host
+  end
 end
 ```
 
-Then you can create multiple access control classes much easier:
+Then you can create multiple access control classes:
 
 ```ruby
 class PageAccess < DefaultAccess
   # can? :view, page
   def view?(page)
-    page and page.published?
+    page and page.published? and domain_name =~ /^www\./i
   end
 
   # can? :edit, page
@@ -124,6 +132,7 @@ class PageAccess < DefaultAccess
   # can? :create, WikiPage
   def create?(page_class)
     # We can do something with WikiPage here if we need to
+    return false if page_class.count >= 2 # only 2 wiki pages allowed
     # but can just ignore it and authorize based on current context only
     current_user and current_user.admin?
   end
@@ -136,13 +145,40 @@ class PageAccess < DefaultAccess
 end
 ```
 
+In your controller:
+
+```ruby
+class PagesController < ApplicationController
+  def show
+    @page = Page.find(params[:id])
+    authorize! :view, @page # It will raise if declined
+    # can?, cannot? can be used too
+  end
+
+  # Add this to the ApplicationController to handle it globally
+  rescue_from Allowy::AccessDenied do |exception|
+    logger.debug "Access denied on #{exception.action} #{exception.subject.inspect}"
+    redirect_to new_user_session_url, :alert => exception.message
+  end
+end
+```
+
+In your views:
+
+```haml
+# app/views/pages/show.html.haml
+
+%h1= @page.name
+= link_to "Edit", edit_page_path if can? :edit, @page
+```
+
 
 # Testing with RSpec
 
 To test the access control classes you can just instantiate those passing context as a parameter.
-Most of the times you will stub out the context, so more isolated is a piece of cake.
+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'` to enable the RSpec matchers and Rails controller extensions.
+You need to `require 'allowy/rspec'`.
 It will give you RSpec matcher `be_able_to` and `ignore_authorization!` macro for controller specs.
 
 
@@ -156,6 +192,11 @@ describe PageAccess do
   describe "#view" do
     it { should_not be_able_to :view, page }
 
+    # Or without the matcher
+    it "should not allow" do
+      subject.view?(page).should be_false
+    end
+
     context "when published" do
       before { page.publish! }
       it { should be_able_to :view, page }

data/lib/allowy/version.rb

@@ -1,3 +1,3 @@
 module Allowy
-  VERSION = "0.1.0"
+  VERSION = "0.1.1"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: allowy
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.1
   prerelease: 
 platform: ruby
 authors:
@@ -9,11 +9,11 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-01-07 00:00:00.000000000 Z
+date: 2012-01-10 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
-  requirement: &70137337531820 !ruby/object:Gem::Requirement
+  requirement: &70173734581140 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -21,10 +21,10 @@ dependencies:
         version: '0'
   type: :runtime
   prerelease: false
-  version_requirements: *70137337531820
+  version_requirements: *70173734581140
 - !ruby/object:Gem::Dependency
   name: rspec
-  requirement: &70137337531300 !ruby/object:Gem::Requirement
+  requirement: &70173734580640 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -32,10 +32,10 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *70137337531300
+  version_requirements: *70173734580640
 - !ruby/object:Gem::Dependency
   name: pry
-  requirement: &70137337530860 !ruby/object:Gem::Requirement
+  requirement: &70173734579780 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -43,10 +43,10 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *70137337530860
+  version_requirements: *70173734579780
 - !ruby/object:Gem::Dependency
   name: guard
-  requirement: &70137337530240 !ruby/object:Gem::Requirement
+  requirement: &70173734578960 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -54,10 +54,10 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *70137337530240
+  version_requirements: *70173734578960
 - !ruby/object:Gem::Dependency
   name: guard-rspec
-  requirement: &70137337529580 !ruby/object:Gem::Requirement
+  requirement: &70173734578340 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -65,7 +65,7 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *70137337529580
+  version_requirements: *70173734578340
 description: Allowy provides CanCan-like way of checking permission but doesn't enforce
   a tight DSL giving you more control
 email: