action_policy 0.0.1 → 0.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: 17194a757a9567d4499a4477fa4cc35257283ebb
-  data.tar.gz: ce45f2edd96504a8e438cec24fd30df415f1f8e0
+SHA256:
+  metadata.gz: a039b5a6e9cdfa9821dfc8ac42d0e78f52239379d532e75e64e9a136123971f1
+  data.tar.gz: b756862f053a8ab07cc957813231988a8447dce8d2655a8d1f0171dda47ab957
 SHA512:
-  metadata.gz: 58086abbb1a2ec4d91350bd478a7e12049ed89196439cf7c6019a0740ea4c63eb7621f6d41f770704eb8e641f28e3741c0a9b298cef474367d1445d0b34bc4bf
-  data.tar.gz: 3a46de4ef1f3b50e2ea77306e6a289e5542aa8d6f7cd10f7a7a52660f9878f6131326addb9d40d0a622407741972526392c93ceaca43e1a7372a90d8840ead04
+  metadata.gz: f6855bd1057d2153300d0cc2d92fc7091bab8a49c6ac4d67fd805372e0fdb0caabb6dd38fc30f28f4bcc74d83b8e37d3dfc96e0410e7616f8e7ada2949c69d6e
+  data.tar.gz: b5ee9d56785412b634f405954b7bd456536d1564d31d8c0927926d045068ef67125e42b0674cdda574f6fefc366f30c94fb798e4f641235e95a31aa2c4f9a65c

data/.rubocop.yml

@@ -0,0 +1,85 @@
+require:
+  - rubocop-md
+
+AllCops:
+  Include:
+    - 'lib/**/*.rb'
+    - 'lib/**/*.rake'
+    - 'test/**/*.rb'
+  Exclude:
+    - 'bin/**/*'
+    - 'gemfiles/**/*'
+    - 'test/dummy/**/*'
+    - 'vendor/**/*'
+    - 'tmp/**/*'
+  DisplayCopNames: true
+  StyleGuideCopsOnly: false
+  TargetRubyVersion: 2.3
+
+Rails:
+  Enabled: false
+
+Bundler/OrderedGems:
+  Enabled: false
+
+Lint/Void:
+  Exclude:
+    - '**/*.md'
+
+Lint/DuplicateMethods:
+  Exclude:
+    - '**/*.md'
+
+Naming/FileName:
+  Exclude:
+   - 'Rakefile'
+   - 'Gemfile'
+   - '**/*.md'
+
+Naming/UncommunicativeMethodParamName:
+  Enabled: false
+
+Naming/VariableNumber:
+  Exclude:
+    - 'test/**/*.rb'
+
+Style/SymbolArray:
+  Enabled: false
+
+Style/Documentation:
+  Exclude:
+    - 'test/**/*.rb'
+    - '**/*.md'
+
+Style/StringLiterals:
+  EnforcedStyle: double_quotes
+
+Style/RegexpLiteral:
+  Enabled: false
+
+Style/NumericPredicate:
+  Enabled: false
+
+Style/Lambda:
+  Enabled: false
+
+Layout/SpaceInsideStringInterpolation:
+  EnforcedStyle: no_space
+
+Lint/AmbiguousRegexpLiteral:
+  Enabled: false
+
+Metrics/LineLength:
+  Max: 100
+
+Metrics/AbcSize:
+  Exclude:
+    - 'test/**/*.rb'
+
+Metrics/BlockLength:
+  Exclude:
+    - 'spec/**/*.rb'
+
+Metrics/MethodLength:
+  Exclude:
+    - 'test/**/*.rb'

data/.travis.yml

@@ -1,5 +1,28 @@
 sudo: false
 language: ruby
 rvm:
-  - 2.4.2
-before_install: gem install bundler -v 1.15.4
+  - 2.5.0
+
+notifications:
+  email: false
+
+matrix:
+  fast_finish: true
+  include:
+    - rvm: ruby-head
+      gemfile: gemfiles/railsmaster.gemfile
+    - rvm: jruby-9.1.0.0
+      gemfile: gemfiles/jruby.gemfile
+    - rvm: 2.5.0
+      gemfile: Gemfile
+    - rvm: 2.4.3
+      gemfile: Gemfile
+    - rvm: 2.3.1
+      gemfile: gemfiles/rails42.gemfile
+  allow_failures:
+    - rvm: 2.3.1
+      gemfile: gemfiles/rails42.gemfile
+    - rvm: ruby-head
+      gemfile: gemfiles/railsmaster.gemfile
+    - rvm: jruby-9.1.0.0
+      gemfile: gemfiles/jruby.gemfile

data/CHANGELOG.md

@@ -0,0 +1,7 @@
+## master
+
+## 0.1.0 (2018-04-17)
+
+- Initial pre-release version. ([@palkan][])
+
+[@palkan]: https://github.com/palkan

data/Gemfile

@@ -1,6 +1,15 @@
-source "https://rubygems.org"
+# frozen_string_literal: true
 
-git_source(:github) {|repo_name| "https://github.com/#{repo_name}" }
+source "https://rubygems.org"
 
-# Specify your gem's dependencies in action_policy.gemspec
 gemspec
+
+gem "pry-byebug", platform: :mri
+
+local_gemfile = File.join(__dir__, "Gemfile.local")
+
+if File.exist?(local_gemfile)
+  eval(File.read(local_gemfile)) # rubocop:disable Security/Eval
+else
+  gem "rails", "~> 5.0"
+end

data/README.md

@@ -1,39 +1,98 @@
+[![Gem Version](https://badge.fury.io/rb/action_policy.svg)](https://badge.fury.io/rb/action_policy)
+[![Build Status](https://travis-ci.org/palkan/action_policy.svg?branch=master)](https://travis-ci.org/palkan/action_policy)
+[![Documentation](https://img.shields.io/badge/docs-link-brightgreen.svg)](http://actionpolicy.evilmartians.io)
+
 # ActionPolicy
 
-Welcome to your new gem! In this directory, you'll find the files you need to be able to package up your Ruby library into a gem. Put your Ruby code in the file `lib/action_policy`. To experiment with that code, run `bin/console` for an interactive prompt.
+Action Policy is an authorization framework for Ruby and Rails applications.
+
+📑 [Documentation][]
 
-TODO: Delete this and the text above, and describe your gem
+<a href="https://evilmartians.com/?utm_source=action_policy">
+<img src="https://evilmartians.com/badges/sponsored-by-evil-martians.svg" alt="Sponsored by Evil Martians" width="236" height="54"></a>
 
 ## Installation
 
-Add this line to your application's Gemfile:
+Add this line to your application's `Gemfile`:
 
 ```ruby
-gem 'action_policy'
+gem "action_policy"
 ```
 
 And then execute:
 
     $ bundle
 
-Or install it yourself as:
+## Usage
 
-    $ gem install action_policy
+Action Policy relies on resource-specific policy classes (just like [Pundit](https://github.com/varvet/pundit)).
 
-## Usage
+First, add an application-specific `ApplicationPolicy` with some global configuration to inherit from:
 
-TODO: Write usage instructions here
+```ruby
+class ApplicationPolicy < ActionPolicy::Base
+end
+```
 
-## Development
+Then write a policy for a resource. For example:
 
-After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+```ruby
+class PostPolicy < ApplicationPolicy
+  # everyone can see any post
+  def show?
+    true
+  end
+
+  def update?
+    # `user` is a performing subject,
+    # `record` is a target object (post we want to update)
+    user.admin? || (user.id == record.user_id)
+  end
+end
+```
 
-To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+Now you can easily add authorization to your Rails\* controller:
+
+```ruby
+class PostsController < ApplicationController
+  def update
+    @post = Post.find(params[:id])
+    authorize! @post
+
+    if @post.update(post_params)
+      redirect_to @post
+    else
+      render :edit
+    end
+  end
+end
+```
+
+\* See [Non-Rails Usage](docs/non_rails.md) on how to add `authorize!` to any Ruby project.
+
+
+When authorization is successful (i.e., the corresponding rule returns `true`), nothing happens, but in case of authorization failure `ActionPolicy::Unauthorized` error is raised.
+
+There is also an `allowed_to?` method which returns `true` or `false`, and could be used, in views, for example:
+
+```erb
+<% @posts.each do |post| %>
+  <li><%= post.title %>
+    <% if allowed_to?(:edit?, post) %>
+      = link_to post, "Edit"
+    <% end %>
+  </li>
+<% end %>
+```
+
+Read more in our [Documentation][].
 
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/action_policy.
+Bug reports and pull requests are welcome on GitHub at https://github.com/palkan/action_policy.
 
 ## License
 
 The gem is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT).
+
+[Documentation]: http://actionpolicy.evilmartians.io

data/Rakefile

@@ -1,5 +1,13 @@
+# frozen_string_literal: true
+
 require "bundler/gem_tasks"
 require "rake/testtask"
+require "rubocop/rake_task"
+require "rspec/core/rake_task"
+
+RuboCop::RakeTask.new
+
+RSpec::Core::RakeTask.new(:spec)
 
 Rake::TestTask.new(:test) do |t|
   t.libs << "test"
@@ -7,4 +15,4 @@ Rake::TestTask.new(:test) do |t|
   t.test_files = FileList["test/**/*_test.rb"]
 end
 
-task :default => :test
+task default: [:rubocop, :test, :spec]

data/action_policy.gemspec

@@ -1,5 +1,6 @@
-# coding: utf-8
-lib = File.expand_path("../lib", __FILE__)
+# frozen_string_literal: true
+
+lib = File.expand_path("lib", __dir__)
 $LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
 require "action_policy/version"
 
@@ -9,8 +10,8 @@ Gem::Specification.new do |spec|
   spec.authors       = ["Vladimir Dementyev"]
   spec.email         = ["dementiev.vm@gmail.com"]
 
-  spec.summary       = "WIP: Authorization framework"
-  spec.description   = "WIP: Authorization framework"
+  spec.summary       = "Authorization framework for Ruby/Rails application"
+  spec.description   = "Authorization framework for Ruby/Rails application"
   spec.homepage      = "https://github.com/palkan/action-policy"
   spec.license       = "MIT"
 
@@ -20,7 +21,12 @@ Gem::Specification.new do |spec|
 
   spec.require_paths = ["lib"]
 
+  spec.required_ruby_version = ">= 2.3.0"
+
   spec.add_development_dependency "bundler", "~> 1.15"
-  spec.add_development_dependency "rake", "~> 10.0"
   spec.add_development_dependency "minitest", "~> 5.0"
+  spec.add_development_dependency "rake", "~> 10.0"
+  spec.add_development_dependency "rspec", "~> 3.3"
+  spec.add_development_dependency "rubocop", "~> 0.51"
+  spec.add_development_dependency "rubocop-md", "~> 0.2"
 end

data/docs/CNAME

@@ -0,0 +1 @@
+actionpolicy.evilmartians.io

data/docs/README.md

@@ -0,0 +1,46 @@
+[![Gem Version](https://badge.fury.io/rb/action_policy.svg)](https://badge.fury.io/rb/action_policy)
+[![Build Status](https://travis-ci.org/palkan/action_policy.svg?branch=master)](https://travis-ci.org/palkan/action_policy)
+
+## Action Policy
+
+> Action Policy is an authorization framework for Ruby and Rails applications.
+
+## What is it?
+
+_Authorization_ is an act of giving **someone** official
+permission to **do something** (to not be confused with [_authentication_](https://en.wikipedia.org/wiki/Authentication)).
+
+Action Policy provides flexible tools to build an _authorization layer_ for your application.
+
+<div class="chart-container">
+  <img src="assets/images/layer.svg" alt="Authorization layer" width="80%">
+</div>
+
+**NOTE:** Action Policy does not force you to use a specific authorization model (i.e., roles, permissions, etc.) and does not provide one. It only answers a single question: **How to verify access?**
+
+## History
+
+Action Policy gem is an _extraction_-kind of a library. Most of the code has been used in production for several years in different [Evil Martians][] projects.
+
+We have decided to collect all our authorization techniques and pack them into a standalone gem–and that is how Action Policy was born!
+
+## What about the existing solutions?
+
+Why did we decide to build our own authorization gem instead of using the existing solutions, such as [Pundit][] and [CanCanCan][]?
+
+**TL;DR they didn't solve all of our problems.**
+
+[Pundit][] has been our framework of choice for a long time. Being too _dead-simple_, it required a lot of hacking to fulfill business logic requirements.
+
+These _hacks_ later become into Action Policy (initially, we even called it "Pundit, re-visited").
+
+We also took a few ideas from [CanCanCan][]—such as default rules and rule aliases.
+
+It is also worth noting that Action Policy (despite from a _Railsy_ name) is designed to be **Rails-free**. On the other hand, it contains some Rails-specific extensions and seamlessly integrates into the framework.
+
+<a href="https://evilmartians.com/?utm_source=action_policy">
+<img src="https://evilmartians.com/badges/sponsored-by-evil-martians.svg" alt="Sponsored by Evil Martians" width="236" height="54"></a>
+
+[CanCanCan]: https://github.com/CanCanCommunity/cancancan
+[Pundit]: https://github.com/varvet/pundit
+[Evil Martians]: https://evilmartians.com

data/docs/_sidebar.md

@@ -0,0 +1,19 @@
+* Getting Started
+  * [Quick Start](quick_start.md)
+  * [Writing Policies](writing_policies.md)
+  * [Rails Integration](rails.md)
+  * [Non-Rails Usage](non_rails.md)
+  * [Testing](testing.md)
+* Features
+  * [Policy Lookup](lookup_chain.md)
+  * [Authorization Context](authorization_context.md)
+  * [Aliases](aliases.md)
+  * [Pre-Checks](pre_checks.md)
+  * [Caching](caching.md)
+  * [Namespaces](namespaces.md)
+  * [Failure Reasons](reasons.md)
+  * [Instrumentation](instrumentation.md)
+  * [I18n Support](i18n.md)
+* Customize
+  * [Base Policy](custom_policy.md)
+  * [Lookup Chain](custom_lookup_chain.md)

data/docs/aliases.md

@@ -0,0 +1,54 @@
+# Rule Aliases
+
+Action Policy allows you to add rule aliases. It is useful when you rely on _implicit_ rules in controllers. For example:
+
+```ruby
+class PostsController < ApplicationController
+  before_action :load_post, only: [:edit, :update, :destroy]
+
+  private
+
+  def load_post
+    @post = Post.find(params[:id])
+    # depending on action, an `edit?`, `update?` or `destroy?`
+    # rule would be applied
+    authorize! @post
+  end
+end
+```
+
+In your policy, you can create aliases to avoid duplication:
+
+```ruby
+class PostPolicy < ApplicationPolicy
+  alias_rule :edit?, :destroy?, to: :update?
+end
+```
+
+**NOTE**: `alias_rule` is available only if you inherit from `ActionPolicy::Base` or include `ActionPolicy::Policy::Aliases` into your `ApplicationPolicy`.
+
+**Why not just use Ruby's `alias`?**
+
+An alias created with `alias_rule` is resolved at _authorization time_ (during an `authorize!` or `allowed_to?` call), and it does not add an alias method to the class.
+
+That allows us to write tests easier, as we should only test the rule, not the alias–and to leverage [caching](caching.md) better.
+
+By default, `ActionPolicy::Base` adds one alias: `alias_rule :new?, to: :create?`.
+
+## Default rule
+
+You can add a _default_ rule–the rule that would be applied if the rule specified during authorization is missing (like a "wildcard" alias):
+
+```ruby
+class PostPolicy < ApplicationPolicy
+  default_rule :manage?
+
+  def manage?
+    # ...
+  end
+end
+```
+
+Now when you call `authorize! post` with any rule not explicitly defined in policy class, the `manage?` rule is applied.
+
+By default, `ActionPolicy::Base` sets `manage?` as a default rule.