authorize_if 0.0.1 → 0.0.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: fea95712c0006a402eef0bff57366a89a7b6cb67
-  data.tar.gz: b667cf8c07496f7fa6b1970107e5de1e44b53db2
+  metadata.gz: 57156e1bc123cd5c21ac7d8b0103a8eb32fbde03
+  data.tar.gz: f13d7d247b7a517f016e1a469f9856f033a2ed4b
 SHA512:
-  metadata.gz: 34aff8dfa5ddeeea9ca00539a375c3e97c719b11d86b0367b2bbfdfcbc8d0cd0d58038040ba42f5b108cd4c96fe4e20524779962366e61bae31096840f999d08
-  data.tar.gz: 761953381f50d9842b22183bbe2582ea680a8650d28848a0dc37bbf2f54eabc0f4c16afa5f58316c700e4e2e3458fe1dcd0aac7d916ca64e82c0a40acac736f4
+  metadata.gz: 1990ed7061f41529ab1994cb713605ec0221c2ff7b59b0a9605236feeea26682612490549affd8fd98e208276400eebcb7b3e8a8007f12d3a4e4b246a2fa4936
+  data.tar.gz: ccdd44c902ecec0df0b154511ed2074262d6f5954ad9832e1af59eeb64e2ccd393ebdfc357c5eaa969710193094a6178497e228716914e32a24aceb57a53168d

data/README.md

@@ -1,33 +1,33 @@
-# authorize_if
+# authorize_if [![Gem Version](https://badge.fury.io/rb/authorize_if.svg)](https://badge.fury.io/rb/authorize_if) [![Build Status](https://travis-ci.org/vrybas/authorize_if.svg?branch=master)](https://travis-ci.org/vrybas/authorize_if) [![Code Climate](https://codeclimate.com/github/vrybas/authorize_if/badges/gpa.svg)](https://codeclimate.com/github/vrybas/authorize_if)
 
 Minimalistic authorization library for Ruby on Rails applications. It
-defines controller methods `authorize` and `authorize_if`, which accept
-authorization rules and raise exception if rule evaluates to `false`.
+defines controller methods `authorize_if` and `authorize`, which accept
+inline or pre-defined authorization rules and raise exception if rule
+evaluates to `false`.
 
-And that's it.
+## API documentation
 
-## Installation
+#### Contents:
 
-Add gem to your application's `Gemfile`:
+##### [`authorize_if`](#authorize_if) - inline authorization
+* [Exception handling](#exception-handling)
+* [Customization of an exception object](#customization-of-an-exception-object)
 
-    gem 'authorize_if'
+##### [`authorize`](#authorize) - authorization using pre-defined authorization rules
+* [Organizing authorization rules](#organizing-authorization-rules)
 
-And then execute:
+##### [`Installation`](#installation)
 
-    $ bundle
+##### [`Contributing`](#contributing)
 
-Or install it yourself as:
+##### [`License`](#license)
 
-    $ gem install authorize_if
-
-## Usage
-
-#### `authorize_if`
+## `authorize_if`
 
 Accepts any `truthy` or `falsey` Ruby object.
 
 ```ruby
-class ArticlesController
+class ArticlesController < ActionController::Base
   def index
     authorize_if current_user
     # ...
@@ -37,7 +37,7 @@ class ArticlesController
     article = Article.find(params[:id])
 
     authorize_if article.authored_by?(current_user) ||
-                 article.group.members.include?(current_user)
+                 article.published?
     # ...
   end
 
@@ -56,11 +56,13 @@ class ArticlesController
 end
 ```
 
+### Exception handling
+
 It raises `AuthorizeIf::NotAuthorizedError` exception, which you can
-rescue right in the controller method
+rescue right in the controller action
 
 ```ruby
-class ArticlesController
+class ArticlesController < ApplicationController
   def index
     authorize_if current_user
     # ...
@@ -76,38 +78,61 @@ or with `rescue_from` in `ApplicaitonController`:
 
 ```ruby
 class ApplicationController < ActionController::Base
-  rescue_from "AuthorizeIf::NotAuthorizedError" do |exception|
+  rescue_from AuthorizeIf::NotAuthorizedError do |exception|
     head 403
   end
 end
 ```
 
-You can set custom error message by using configuration block
+### Customization of an exception object
+
+If block is given, `authorize_if` yields the block with an exception
+object. This allows to set custom error message, which is going to be
+used when exception is raised.
+
+Also you can use key-value store(plain Ruby hash), `context`, to store
+any data, and access it in the exception handling block.
 
 ```ruby
-class ArticlesController
+class ArticlesController < ApplicationController
   def index
-    authorize_if(current_user) do |config|
-      config.error_message = "You are not authorized!"
+    authorize_if(current_user) do |exception|
+      exception.message = "You are not authorized!"
+
+      exception.context[:request_ip] = "192.168.1.1"
+      exception.context[:user_agent] = "Gecko"
     end
     # ...
   end
 end
+```
 
+```ruby
 class ApplicationController < ActionController::Base
-  rescue_from "AuthorizeIf::NotAuthorizedError" do |exception|
-    render text: exception.message, status: 403
+  rescue_from AuthorizeIf::NotAuthorizedError do |exception|
+    exception.message
+    # => "You are not authorized!"
+
+    exception.context[:request_ip]
+    # => "192.168.1.1"
+
+    exception.context[:user_agent]
+    # => "Gecko"
   end
 end
 ```
 
-#### `authorize`
+## `authorize`
+
+You can define authorization rules for controller actions like this
+
+##### `"authorize_#{action_name}?"`
 
-This method helps to extract authorization rules out of controller. It
-expects corresponding authorization rule to exist.
+And then call `authorize`, which is going to find and evaluate
+corresponding authorization rule.
 
 ```ruby
-class ArticlesController
+class ArticlesController < ActionController::Base
   def index
     authorize
 
@@ -122,32 +147,11 @@ class ArticlesController
 end
 ```
 
-You can extract those rules into a module and include them to the
-controller.
-
-```ruby
-module AuthorizationRules
-  def authorize_index?
-    current_user.present?
-  end
-end
-
-class ArticlesController
-  include AuthorizationRules
-
-  def index
-    authorize
-
-    # ...
-  end
-end
-```
-
-`authorize` accepts any parameters and passes them to authorization
+`authorize` accepts any arguments and passes them to authorization
 rule.
 
 ```ruby
-class ArticlesController
+class ArticlesController < ActionController::Base
   def edit
     article = Article.find(params[:id])
 
@@ -164,18 +168,24 @@ class ArticlesController
 end
 ```
 
-It can also be customized by using configuration block.
+It also accepts customization block, and yields an exception object:
 
 ```ruby
-class ArticlesController
+class ArticlesController < ActionController::Base
   def edit
     article = Article.find(params[:id])
 
-    authorize(article) do |config|
-      config.error_message = "You are not authorized!"
+    authorize(article) do |exception|
+      exception.message = "You are not authorized!"
+      exception.context[:request_ip] = "192.168.1.1"
     end
 
-    # ...
+  rescue AuthorizeIf::NotAuthorizedError => e
+    e.message
+    # => "You are not authorized!"
+
+    e.context[:request_ip]
+    # => "192.168.1.1"
   end
 
   private
@@ -186,6 +196,52 @@ class ArticlesController
 end
 ```
 
+### Organizing authorization rules
+
+You can extract rules into a module and include it to the
+controller.
+
+```ruby
+class ArticlesController < ActionController::Base
+  include AuthorizationRules
+
+  def index
+    authorize
+
+    # ...
+  end
+end
+```
+
+```ruby
+class ArticlesController
+  module AuthorizationRules
+    def authorize_index?
+      current_user.present?
+    end
+  end
+end
+```
+
+## Usage outside of controllers
+
+Include `AuthorizeIf` module to any class and you'll get `authorize` and
+`authorize_if` methods.
+
+## Installation
+
+Add gem to your application's `Gemfile`:
+
+    gem 'authorize_if'
+
+And then execute:
+
+    $ bundle
+
+Or install it manually:
+
+    $ gem install authorize_if
+
 ## Contributing
 
 1. Fork it ( https://github.com/vrybas/authorize_if/fork )

data/lib/authorize_if.rb

@@ -1,30 +1,29 @@
+require "authorize_if/version"
+require "authorize_if/errors"
+
 # Provides a set of methods to handle authorization scenarios.
 # It is included to ActionController::Base on load.
 #
 module AuthorizeIf
-  NotAuthorizedError            = Class.new(StandardError)
-  MissingAuthorizationRuleError = Class.new(StandardError)
-
-  Configuration = Class.new do
-    attr_accessor :error_message
-  end
-
   # Evaluates given object as boolean. Returns 'true' if object
   # evaluates to 'true'. Raises `AuthorizeIf::NotAuthorizedError`
   # if object evaluates to 'false'.
   #
-  # Also accepts block and calls it with `AuthorizeIf::Configuration`
-  # object as parameter. Behavior can be customized by calling methods
-  # on configuraiton object.
+  # Also accepts block and yields it with `AuthorizeIf::NotAuthorizedError`
+  # exception object. Behavior can be customized by calling methods
+  # on exception object.
   #
   # @param [Object] rule
   #   The authorization rule. Any "truthy" or "falsey" Ruby object.
   #
   # @param [Proc] block
-  #   The configuration block. Supported configuration:
-  #     `error_message=()` - custom error message, which will be raised
-  #                          along with `AuthorizeIf::NotAuthorizedError`
-  #                          exception.
+  #   The customization block. Supported customization methods:
+  #     `message=` - error message, which will be raisedalong
+  #                  with `AuthorizeIf::NotAuthorizedError` exception.
+  #
+  #     `context` - a key-value store(plain Ruby hash), which will be
+  #                  passed along with `AuthorizeIf::NotAuthorizedError`
+  #                  exception object, as an object attribute.
   #
   # @example
   #     class ArticlesController
@@ -38,16 +37,25 @@ module AuthorizeIf
   #       def edit
   #         @article = Article.find(params[:id])
   #
-  #         authorize_if @article.authors.include?(current_user) do |config|
-  #           config.error_message = "You are not authorized!"
+  #         authorize_if @article.authors.include?(current_user) do |exception|
+  #           exception.message = "You are not authorized!"
+  #           exception.context[:request_ip] = "192.168.1.1"
+  #           exception.context[:user_agent] = "Gecko"
   #         end
   #         # => AuthorizeIf::NotAuthorizedError: You are not authorized!
   #
-  #         ...
+  #       rescue AuthorizeIf::NotAuthorizedError => e
+  #         e.message
+  #         # => "You are not authorized!"
+  #
+  #         e.context[:request_ip]
+  #         # => "192.168.1.1"
+  #
+  #         e.context[:user_agent]
+  #         # => "Gecko"
   #       end
   #     end
   #
-  #
   # @return [Boolean]
   #   Returns 'true' if given object evaluates to 'true'.
   #
@@ -55,10 +63,11 @@ module AuthorizeIf
   #   Raised if given object evaluates to 'false'.
   #
   def authorize_if(rule, &block)
-    config = Configuration.new
-    block.call(config) if block
+    return true if !!rule
 
-    !!rule || raise(NotAuthorizedError, config.error_message)
+    exception = NotAuthorizedError.exception
+    yield(exception) if block
+    raise(exception, exception.instance_variable_get(:@message))
   end
 
   # Accepts any arguments and configuration block. Calls corresponding
@@ -72,8 +81,8 @@ module AuthorizeIf
   #   authorization rule.
   #
   # @param [Proc] block
-  #   The configuration block. See `#authorize_if` for complete list of
-  #   configuration options.
+  #   The exception customization block. See `#authorize_if` for complete list of
+  #   customization methods.
   #
   # @example
   #     class ArticlesController
@@ -87,12 +96,22 @@ module AuthorizeIf
   #       def edit
   #         @article = Article.find(params[:id])
   #
-  #         authorize(@article) do |config|
-  #           config.error_message = "You are not authorized!"
+  #         authorize(@article) do |exception|
+  #           exception.message = "You are not authorized!"
+  #           exception.context[:request_ip] = "192.168.1.1"
+  #           exception.context[:user_agent] = "Gecko"
   #         end
   #         # => AuthorizeIf::NotAuthorizedError: You are not authorized!
   #
-  #         ...
+  #       rescue AuthorizeIf::NotAuthorizedError => e
+  #         e.message
+  #         # => "You are not authorized!"
+  #
+  #         e.context[:request_ip]
+  #         # => "192.168.1.1"
+  #
+  #         e.context[:user_agent]
+  #         # => "Gecko"
   #       end
   #
   #       def destroy

data/lib/authorize_if/errors.rb

@@ -0,0 +1,19 @@
+module AuthorizeIf
+  class NotAuthorizedError < StandardError
+    attr_reader :context
+
+    def initialize(*)
+      @message = nil
+      @context = {}
+
+      super
+    end
+
+    def message=(msg)
+      @message = msg
+    end
+  end
+
+  class MissingAuthorizationRuleError < StandardError
+  end
+end

data/lib/authorize_if/version.rb

@@ -1,3 +1,3 @@
 module AuthorizeIf
-  VERSION = "0.0.1"
+  VERSION = "0.0.2"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: authorize_if
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 0.0.2
 platform: ruby
 authors:
 - Vladimir Rybas
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2016-03-02 00:00:00.000000000 Z
+date: 2016-06-12 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -25,19 +25,19 @@ dependencies:
       - !ruby/object:Gem::Version
         version: 4.2.5
 - !ruby/object:Gem::Dependency
-  name: m
+  name: rspec-rails
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 1.3.1
+        version: '3'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 1.3.1
+        version: '3'
 - !ruby/object:Gem::Dependency
   name: byebug
   requirement: !ruby/object:Gem::Requirement
@@ -63,47 +63,8 @@ files:
 - README.md
 - Rakefile
 - lib/authorize_if.rb
+- lib/authorize_if/errors.rb
 - lib/authorize_if/version.rb
-- lib/tasks/authorize_if_tasks.rake
-- test/dummy/README.rdoc
-- test/dummy/Rakefile
-- test/dummy/app/assets/javascripts/application.js
-- test/dummy/app/assets/stylesheets/application.css
-- test/dummy/app/controllers/application_controller.rb
-- test/dummy/app/controllers/articles_controller.rb
-- test/dummy/app/helpers/application_helper.rb
-- test/dummy/app/views/layouts/application.html.erb
-- test/dummy/bin/bundle
-- test/dummy/bin/rails
-- test/dummy/bin/rake
-- test/dummy/bin/setup
-- test/dummy/config.ru
-- test/dummy/config/application.rb
-- test/dummy/config/boot.rb
-- test/dummy/config/environment.rb
-- test/dummy/config/environments/development.rb
-- test/dummy/config/environments/production.rb
-- test/dummy/config/environments/test.rb
-- test/dummy/config/initializers/assets.rb
-- test/dummy/config/initializers/backtrace_silencers.rb
-- test/dummy/config/initializers/cookies_serializer.rb
-- test/dummy/config/initializers/filter_parameter_logging.rb
-- test/dummy/config/initializers/inflections.rb
-- test/dummy/config/initializers/mime_types.rb
-- test/dummy/config/initializers/session_store.rb
-- test/dummy/config/initializers/wrap_parameters.rb
-- test/dummy/config/locales/en.yml
-- test/dummy/config/routes.rb
-- test/dummy/config/secrets.yml
-- test/dummy/db/test.sqlite3
-- test/dummy/log/test.log
-- test/dummy/public/404.html
-- test/dummy/public/422.html
-- test/dummy/public/500.html
-- test/dummy/public/favicon.ico
-- test/integration/authorize_if_integration_test.rb
-- test/test_helper.rb
-- test/unit/authorize_if_unit_test.rb
 homepage: https://github.com/vrybas/authorize_if
 licenses:
 - MIT
@@ -128,43 +89,4 @@ rubygems_version: 2.5.1
 signing_key: 
 specification_version: 4
 summary: Minimalistic authorization library for Ruby on Rails applications.
-test_files:
-- test/dummy/app/assets/javascripts/application.js
-- test/dummy/app/assets/stylesheets/application.css
-- test/dummy/app/controllers/application_controller.rb
-- test/dummy/app/controllers/articles_controller.rb
-- test/dummy/app/helpers/application_helper.rb
-- test/dummy/app/views/layouts/application.html.erb
-- test/dummy/bin/bundle
-- test/dummy/bin/rails
-- test/dummy/bin/rake
-- test/dummy/bin/setup
-- test/dummy/config/application.rb
-- test/dummy/config/boot.rb
-- test/dummy/config/environment.rb
-- test/dummy/config/environments/development.rb
-- test/dummy/config/environments/production.rb
-- test/dummy/config/environments/test.rb
-- test/dummy/config/initializers/assets.rb
-- test/dummy/config/initializers/backtrace_silencers.rb
-- test/dummy/config/initializers/cookies_serializer.rb
-- test/dummy/config/initializers/filter_parameter_logging.rb
-- test/dummy/config/initializers/inflections.rb
-- test/dummy/config/initializers/mime_types.rb
-- test/dummy/config/initializers/session_store.rb
-- test/dummy/config/initializers/wrap_parameters.rb
-- test/dummy/config/locales/en.yml
-- test/dummy/config/routes.rb
-- test/dummy/config/secrets.yml
-- test/dummy/config.ru
-- test/dummy/db/test.sqlite3
-- test/dummy/log/test.log
-- test/dummy/public/404.html
-- test/dummy/public/422.html
-- test/dummy/public/500.html
-- test/dummy/public/favicon.ico
-- test/dummy/Rakefile
-- test/dummy/README.rdoc
-- test/integration/authorize_if_integration_test.rb
-- test/test_helper.rb
-- test/unit/authorize_if_unit_test.rb
+test_files: []