crows 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 45a31cd6e8c73b9a5ea6b587986da193074bc2d6
+  data.tar.gz: e51b2f94197a437e4dec56e166c99eec206bfa88
+SHA512:
+  metadata.gz: 9cac3c422c581712a967212b6a3516bd7fa915766fe62c4737ae38c69dfcd3bd6721eac17a993a48d72d1be5dede1172e424a826379c10e9ab4681660bb887fb
+  data.tar.gz: 1d24ab84eaa80027896b71cf58d54e3d65577b4b38602eb0c03c858efabe7d5189149375ca1b13d33bb47f8c2d1f98fcc9a7e7a23099a58368debdc7e404c70f

data/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2015 Julio Lopez
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,149 @@
+# Crows
+
+Inspired by [Pundit](https://github.com/elabs/pundit), Crows is a micro framework-agnostic library for authorization in Ruby classes.
+
+A set of crows to authorized your users, because the night is dark and full of terrors...
+
+Crows provide you with a few helpers to check if `current_user` can make operations into some records. This gives you the freedom to build your own plain Ruby classes to make authorization works easily, without the painful of bigs DSLs or something like that.
+
+## Installation
+
+Installing Crows is as simple as running:
+
+```
+$ gem install crows
+```
+
+Include Crows in your Gemfile with gem 'crows' or require it with require 'crows'.
+
+Usage
+-----
+
+Include Crows in your main class, can be your controller, your API class, etc.
+
+``` ruby
+class ApplicationController < ActionController::Base
+  include Crows
+end
+```
+
+Crows exist around the notion of Crow classes.
+
+``` ruby
+class PostCrow
+  attr_reader :user, :post
+
+  def initialize(user, post)
+    @user = user
+    @post = post
+  end
+
+  def destroy?
+    user.admin? and post.draft?
+  end
+end
+```
+
+In the above example:
+
+-  We define a Crow class, its name is composed by a name of a class whose authorization you want to check, plus the suffix "Crow".
+- In its `initialize` the class receive as first argument the user(captured by your method `current_user`) and as second argument your instance of the class for which was created the current crow.
+- Finally the Crow class implements methods to check if user can be authorized to do a particular action.
+
+Lastly, you have the `authorize` method for use your Crow class.
+
+``` ruby
+authorize @post, :destroy?
+```
+
+The above line will check your PostCrow class to authorize if current user can destroy the @post
+
+Raising an exception if is not true the result of `destroy?`
+
+``` ruby
+Crows::NotAuthorizedError: not allowed to destroy? this #<Post:0x007fd1831adc48>
+```
+
+Also, you have a method `crow` to receive the instance of your Crow class for handle the checks manually, useful in the views:
+
+``` erb
+<% if crow(@post).destroy? %>
+  <%= link_to "Delete post", post_path(@post), method: :delete %>
+<% end %>
+```
+
+## Scopes
+
+You can also declare a Scope in your Crow class, use it when you need to check if the user can access to a list of records, looks like this:
+
+``` ruby
+class PostCrow
+  class Scope
+    attr_reader :user, :scope
+
+    def initialize(user, scope)
+      @user = user
+      @scope = scope
+    end
+
+    def resolve
+      if user.admin?
+        scope.all
+      else
+        scope.select{|post| post.published }
+      end
+    end
+  end
+end
+```
+
+To make the Scope class works: 
+- You need to create it nested in your Crow class.
+- In its `initialize` the class Scope receive as first argument the `current_user`(similar as works the Crow classes) and as second argument the scope(a class name) that you'll pass later to the `authorize` method
+- And you need to declare the `resolve` method, which should check the authorization and return something that can be iterated(that's why is called scope, isn't it?)
+
+Now, you can use your scopes like this:
+
+``` erb
+<% crow_scope(Post).each do |post| %>
+  <p><%= link_to post.title, post_path(post) %></p>
+<% end %>
+```
+
+This example will return all the posts if the user is admin, if not it will return just the published posts, as we indicated in the `resolve` method.
+
+## Customize your current user
+
+Sometimes, you'll need to authorize users outside your main class(your controller, API class, etc), in that case you simply need to Crows call other method than `current_user` and we give you for that, the option of define the `crow_user`
+
+```ruby
+def crow_user
+  #grab here the user that you want to check his authorization
+  User.find(params[:user_id])
+end
+```
+
+## Get and Set Crows
+
+For other purposes you can get the hash of all crows and scopes defined with `crows` and `crows_scope` methods (use them in the class where you include Crows)
+
+Following the previous examples:
+
+```ruby
+class ApplicationController
+  puts crows
+  #=>{<Post:instance> => <PostCrow:instance>}
+
+  puts crows_scope
+  #=>{Post => #result of PostCrow::Scope.resolve}
+end
+```
+
+And you can set manually the crows with a hash syntax:
+
+```ruby
+class ApplicationController
+  crows[@post] = crow(@post)
+  crows_scope[Post] = crow_scope(Post)
+end
+```

data/crows.gemspec

@@ -0,0 +1,20 @@
+require "./lib/crows"
+
+Gem::Specification.new do |s|
+  s.name              = "crows"
+  s.version           = Crows::VERSION
+  s.summary           = "Micro library for authorization in Ruby classes."
+  s.description       = "Crows is a micro framework-agnostic library for authorization in Ruby classes. A set of crows to authorized your users, because the night is dark and full of terrors... Crows provide you with a few helpers to check if `current_user` can make operations into some records. This gives you the freedom to build your own plain Ruby classes to make authorization works easily, without the painful of bigs DSLs or something like that."
+  s.authors           = ["Julio Lopez"]
+  s.email             = ["ljuliom@gmail.com"]
+  s.homepage          = "http://github.com/TheBlasfem/crows"
+  s.files = Dir[
+    "LICENSE",
+    "README.md",
+    "lib/**/*.rb",
+    "*.gemspec",
+    "test/**/*.rb"
+  ]
+  s.license           = "MIT"
+  s.add_development_dependency "cutest", "1.1.3"
+end

data/lib/crows.rb

@@ -0,0 +1,76 @@
+# Copyright (c) 2015 Julio Lopez
+
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+
+# The above copyright notice and this permission notice shall be included in all
+# copies or substantial portions of the Software.
+
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+# SOFTWARE.
+module Crows
+  VERSION = "0.1.0"
+  SUFFIX = "Crow"
+
+  class NotDefinedError < StandardError; end
+  class NotAuthorizedError < StandardError
+    def initialize(options = {})
+      query  = options[:query]
+      record = options[:record]
+      message = "not allowed to #{query} this #{record.inspect}"
+      super(message)
+    end
+  end
+
+  def crow(record)
+    instance = find_crowclass(record).new(crow_user, record)
+    crows[record] = instance unless record.is_a? Class
+    instance
+  end
+
+  def crow_scope(klass)
+    crows_scope[klass] = crow(klass)
+    crows_scope[klass].resolve
+  end
+
+  def authorize(record, query)
+    crow = crow(record)
+    unless crow.public_send(query)
+      raise NotAuthorizedError.new(query: query, record: record)
+    end
+    true
+  end
+
+  def crow_user
+    current_user
+  end
+
+  def crows
+    @crows ||= {}
+  end
+
+  def crows_scope
+    @crows_scope ||= {}
+  end
+
+  private
+
+  def find_crowclass(record)
+    klass = if record.is_a? Class
+      Object.const_get(record.to_s + SUFFIX)::Scope
+    else
+      Object.const_get(record.class.to_s + SUFFIX)
+    end
+  rescue NameError
+    raise NotDefinedError, "unable to find crow #{klass} for #{record.inspect}"
+  end
+end

data/test/test_crows.rb

@@ -0,0 +1,121 @@
+require File.expand_path("../lib/crows", File.dirname(__FILE__))
+
+scope do
+  class User; end
+
+  class Post
+    def self.all
+      ['post 1', 'post 2']
+    end
+  end
+
+  class PostCrow
+    attr_reader :user, :post
+
+    def initialize(user, post)
+      @user = user
+      @post = post
+    end
+
+    def update?
+      true
+    end
+
+    def destroy?
+      false
+    end
+
+    class Scope
+      attr_reader :user, :scope
+
+      def initialize(user, scope)
+        @user = user
+        @scope = scope
+      end
+
+      def resolve
+        if true
+          scope.all
+        end
+      end
+    end
+  end
+
+  class Controller
+    include Crows
+    attr_reader :current_user
+    def initialize(user)
+      @current_user = user
+    end
+  end
+
+  @user = User.new
+  @controller = Controller.new @user
+  @post = Post.new
+
+  test "return true if authorization passes" do
+    action = @controller.authorize(@post, :update?)
+    assert_equal action, true
+  end
+
+  test "throw an exception if authorization fails" do
+    assert_raise(Crows::NotAuthorizedError) do
+      @controller.authorize(@post, :destroy?)
+    end
+  end
+
+  test "throws an exception when a crow class cannot be found" do
+    assert_raise(Crows::NotDefinedError) do
+      @controller.authorize(@user, :update?)
+    end
+  end
+
+  test "returns an instantiated crow" do
+    crow = @controller.crow(@post)
+    assert_equal crow.post, @post
+  end
+
+  test "throws an exception when a crow class cannot be found in #crow" do
+    assert_raise(Crows::NotDefinedError) do
+      @controller.crow(@user)
+    end
+  end
+
+  test "save the crow" do
+    assert_equal @controller.crows[Post.new], nil
+    crow = @controller.crow(@post)
+    assert_equal @controller.crows[@post], crow
+  end
+
+  test "allow crow to be injected" do
+    crow = @controller.crow(@post)
+    @controller.crows[@post] = crow
+    assert_equal @controller.crows[@post], crow
+  end
+
+  test "returns an instantiated crow scope" do
+    scope = @controller.crow_scope(Post)
+    assert_equal scope, ['post 1', 'post 2']
+  end
+
+  test "throws an exception when a crow scope class cannot be found" do
+    assert_raise(Crows::NotDefinedError) do
+      @controller.crow_scope(User)
+    end
+  end
+
+  test "save the crow scope" do
+    scope = @controller.crow_scope(Post)
+    assert_equal @controller.crows_scope[Post].resolve, scope
+  end
+
+  test "allow crow scope to be injected" do
+    scope = @controller.crow_scope(Post)
+    @controller.crows_scope[Post] = scope
+    assert_equal @controller.crows_scope[Post], scope
+  end
+
+  test "crow_user return the same current_user of controller" do
+    assert_equal @controller.crow_user, @controller.current_user
+  end
+end

metadata

@@ -0,0 +1,68 @@
+--- !ruby/object:Gem::Specification
+name: crows
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Julio Lopez
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2015-06-18 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: cutest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 1.1.3
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 1.1.3
+description: Crows is a micro framework-agnostic library for authorization in Ruby
+  classes. A set of crows to authorized your users, because the night is dark and
+  full of terrors... Crows provide you with a few helpers to check if `current_user`
+  can make operations into some records. This gives you the freedom to build your
+  own plain Ruby classes to make authorization works easily, without the painful of
+  bigs DSLs or something like that.
+email:
+- ljuliom@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- crows.gemspec
+- lib/crows.rb
+- test/test_crows.rb
+homepage: http://github.com/TheBlasfem/crows
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.4.6
+signing_key: 
+specification_version: 4
+summary: Micro library for authorization in Ruby classes.
+test_files: []