permission_policy 0.0.2 → 0.0.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: e282b311b9a97875e9918d7fe57f6c1c19150d81
-  data.tar.gz: 24241e62b1a2355be883b2d3edec11f141c2d250
+  metadata.gz: 4adb1909f5453d105d3633ea38aa354558021cb8
+  data.tar.gz: 7eb77cfdb035b30524c96980f06976e13bef429a
 SHA512:
-  metadata.gz: 7049c534d01ebaa7e4472c57e6a12dd56973d9eb4d22d3e2c18da977adde0472ce1a09c9d0516b353b0d7b50ef6e9ba9e6cd1c1ab97485880609cc5cb358b4aa
-  data.tar.gz: b7b4be9758970112f4c462aee6328ddecc667e7d7d99430976c5f4bdedf9fe1a510bddb415e25620b6ac636a293d17899c5fdb43cf9f3f00e9464a04fefb0b80
+  metadata.gz: 6ba9089daca35610777ec2fb6727e2e2d746bb6df99c3ccaaa3daacdca05027a01652447b79678b25ca722b502484ccc83a7f75df648b56708e4693e98975e42
+  data.tar.gz: e70165676e16169bef09c5545f600894ed931ecff03e90b28b19614389ca7fb5bb3296c3542b0a9dcb94960387c3586321debc6fcd0fe5270a8e2a852b74a1b4

data/CHANGELOG.md

@@ -0,0 +1,5 @@
+
+# 0.0.3
+
+  * [ENHANCEMENT] *some* documentation
+  * [ENHANCEMENT] config option for debug output

data/README.md

@@ -1,6 +1,10 @@
 # PermissionPolicy
 
-TODO: Write a gem description
+* some description
+* travis
+* codeaclimate
+* dependencies
+
 
 ## Installation
 
@@ -18,7 +22,93 @@ Or install it yourself as:
 
 ## Usage
 
-TODO: Write usage instructions here
+You might want to configure which objects are needed for your permission handling.
+
+In a Rails App you can configure the gem with simple initializer file under `config/initializers/permission_policy.rb`.
+
+```
+  PermissionPolicy.configure do |c|
+    # c.precondition_attributes = [:current_user] # => default
+    c.debug_logger = true # => useful for debugging which strategy matched
+    c.strategy_order = [
+      :SuperAdminStrategy,
+      :FeatureStrategy,
+      :RuleStrategy,
+      :UnknownStrategy
+    ]
+  end
+```
+
+The main idea is that strategies decide if they are responsible for authorization.
+A "base strategy" defines the object API for all strategies which can be
+used for permission checks. Each strategy should inherit from it and
+implement `#match?` and `#allowed?`. But more on this under *customization*.
+
+The permission_polciy is available in the controller layer of the application.
+The public API is reduced to basicaly two methods:
+
+* **#allowed?**
+
+  Use it to receive a boolean response, whether the current user is allowed to
+  access the requested feature in the current context.
+  Usually, you would use it to check access in views and decorators.
+
+  The first argument is the action you want to perform (either :view or :manage).
+  As a second argument you can pass either a subject or a feature name:
+
+  * ``` allowed? :view, subject: @entity```
+    Would check if the user is allowed to perform action on the provided entity
+  * ``` allowed? :view, feature: 'report' ```
+    Would check if the user  is allowed to access the provided feature.
+
+
+* **#authorize!**
+
+  Same interface like ```#allowed?```, but instead of returning a boolean,
+  it would raise an error if access is denied. Use it in your controllers,
+  as the exception is rescued globally and would redirect user to root
+  and display an access denied message.
+
+  Example for subject based check:
+
+  ```
+        class EntityController < ApplicationController
+          def edit
+            @entity = current_user.entities.find(params[:id])
+            authorize! :manage, subject: @entity
+          end
+        end
+  ```
+
+  Example for feature check:
+
+  ```
+        class ReportsController < ApplicationController
+          before_action { authorize! :view, feature: 'report' }
+
+          def index
+            @report = current_user.report
+          end
+        end
+  ```
+
+---
+### Authorization Customization
+
+Each subject has it's own set of rules, described as a plain old ruby object,
+which will be found by the policy when it responds to a common interface.
+If an action is allowed will be decided either by a strategy directly or a separate class.
+
+Rules should / can be placed under `models/permission_policy/rules/` and will
+be called by the rules strategy defined in `strategies/rule_strategy.rb`.
+At the moment you need to define one by yourself.
+
+You can extend the permission policy by:
+
+ - adding new actions to your rule classes
+ - implement new rule classes for new subjects (entities)
+ - implement new permission strategies, which help the policy to find the 'decider'
+
 
 ## Contributing
 

data/lib/permission_policy/authorization.rb

@@ -39,7 +39,11 @@ module PermissionPolicy
 
     # Finds the matching strategy which can decide if the action is allowed by lazy checking
     def strategy_for(*args)
-      PermissionPolicy.strategies.lazy.map { |klass| Strategies.const_get(klass).new(self, *args) }.find(&:match?)
+      PermissionPolicy.strategies.lazy.map { |klass| Strategies.const_get(klass).new(self, *args) }.find do |s|
+        s.match?.tap do |match|
+          PermissionPolicy.log "#{s.class.name} #{match ? 'matched' : 'not matched'}"
+        end
+      end
     end
 
     def set!(var, value)

data/lib/permission_policy/configuration.rb

@@ -7,13 +7,21 @@ module PermissionPolicy
     def strategies
       strategy_order || [:UnknownStrategy]
     end
+
+    def log(message)
+      logging.debug(message) && !!debug_logger
+    end
+
+    def logging
+      logger || Logger.new(STDOUT)
+    end
   end
 
   class << self
     attr_accessor :configuration
 
     extend Forwardable
-    delegate [:preconditions, :strategies] => :config
+    delegate [:preconditions, :strategies, :log] => :config
 
     def configure
       yield(config)

data/lib/permission_policy/version.rb

@@ -1,3 +1,3 @@
 module PermissionPolicy
-  VERSION = '0.0.2'
+  VERSION = '0.0.3'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: permission_policy
 version: !ruby/object:Gem::Version
-  version: 0.0.2
+  version: 0.0.3
 platform: ruby
 authors:
 - Marco Schaden
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2015-01-21 00:00:00.000000000 Z
+date: 2015-01-22 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -134,6 +134,7 @@ files:
 - ".gitignore"
 - ".rspec"
 - ".rubocop.yml"
+- CHANGELOG.md
 - Gemfile
 - Guardfile
 - LICENSE.txt