active_model_policy 0.0.1

data/.gitignore

@@ -0,0 +1,17 @@
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in active_model_policy.gemspec
+gemspec

data/LICENSE

@@ -0,0 +1,22 @@
+Copyright (c) 2012 Marty Zalega
+
+MIT License
+
+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,94 @@
+# ActiveModel::Policy
+
+The purpose of *ActiveModel::Policy* is to encapsulate the logic of checking whether an action can be performed on the given object by an actor. By abtracting the this concern into objects permission can be broken into more meaningful and managable parts.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'active_model_policy'
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install active_model_policy
+
+## Creating a Policy
+
+To create a policy object simply use the Rails generator:
+
+    $ rails generate policy *my_model_name*
+
+The file will be created in `app/policies/*my_model_name.rb*`.
+
+To manually create a policy object simply create any standard object subclassing `ActiveModel::Policy`. You should end up with something like this:
+
+```ruby
+class MyModelNamePolicy < ActiveModel::Policy
+end
+```
+
+A policy is nothing more than a series of methods which return true or false based on the state of the model, and optionally scoped. To declare a check, or in policy terms "forming a question", you simply do:
+
+```ruby
+class PostPolicy < ActiveModel::Policy
+  can :read do |context|
+    model.active?
+  end
+end
+```
+
+The `can` helper underneath simply defines the method `can_read?`. The method returns a truthy or falsy as to whether the action can be performed or not. The idea is that you are asking a question whether the action **can** be performed as the given **context**. The context is not mandatory but it is generally good to use one, even if it is `nil`.
+
+`can` accepts multiple names, so the same check can be used for multiple actions.
+
+## Using the Policy
+
+To use a policy you instantiate it as any Ruby object and pass it the model for which it is to perform checks on. ie. `PostPolicy.new post`.
+
+```ruby
+policy = PostPolicy.new post
+policy.can? :read
+```
+
+As a helper to ActiveRecord models, you can simply call `to_policy` which will look for the correct policy based on name and pass itself to the policy.
+
+```ruby
+policy = post.to_policy
+policy.can? :read
+```
+
+You can add this behaviour to your own objects by adding `include ActiveModel::PolicySupport` to your class.
+
+## Policy context
+
+A context can be anything or nothing, and are very useful to add perspective to your policy. A policy defines rules, or permissions, on what actions can be performed but this might need more context such as who or what. A context is simply passing an argument to the question which responds based on the context. In short, it adds more dimention to checking the permission.
+
+To make working with context easier, an object can be marked as a context by including the model. ie. `include ActiveModel::PolicyContext`. Then questions can be asked on the context directly:
+
+```ruby
+user.can? :read, post
+```
+
+Controllers and views have the context set by default to `current_user`, so you can use `can?` instead.
+
+## Customising context
+
+The context is given to each question asked on the policy to determine whether to grant permission. By default, this is set to `current_user` on the controller but can be changed:
+
+```ruby
+class ApplicationController < ActionController::Base
+  policy_context :current_user
+end
+```
+
+## Contributing
+
+1. Fork it
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Added some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create new Pull Request

data/Rakefile

@@ -0,0 +1,12 @@
+#!/usr/bin/env rake
+require "bundler/gem_tasks"
+require "rake/testtask"
+
+Rake::TestTask.new do |t|
+  t.libs << "lib"
+  t.libs << "test"
+  t.pattern = "test/**/*_test.rb"
+  t.verbose = true
+end
+
+task :default => "test"

data/active_model_policy.gemspec

@@ -0,0 +1,19 @@
+# -*- encoding: utf-8 -*-
+require File.expand_path('../lib/active_model/version', __FILE__)
+
+Gem::Specification.new do |gem|
+  gem.authors       = ["Marty Zalega"]
+  gem.email         = ["marty@zalega.me"]
+  gem.description   = %q{Policy implementation for rails}
+  gem.summary       = %q{Policy implementation for rails}
+  gem.homepage      = ""
+
+  gem.files         = `git ls-files`.split($\)
+  gem.executables   = gem.files.grep(%r{^bin/}).map{ |f| File.basename(f) }
+  gem.test_files    = gem.files.grep(%r{^(test|spec|features)/})
+  gem.name          = "active_model_policy"
+  gem.require_paths = ["lib"]
+  gem.version       = ActiveModel::Policy::VERSION
+
+  gem.add_development_dependency "rails", ">= 3.0"
+end

data/lib/action_controller/policy_context.rb

@@ -0,0 +1,15 @@
+module ActionController
+  module PolicyContext
+    def self.included base
+      base.class_eval do
+        include ActiveModel::PolicyContext
+        policy_context :current_user
+      end
+
+      methods = ActiveModel::PolicyContext.instance_methods
+
+      base.hide_action *methods
+      base.helper_method :can?, :cannot?
+    end
+  end
+end

data/lib/active_model/policy.rb

@@ -0,0 +1,51 @@
+module ActiveModel
+  class Policy
+    attr_reader :model
+
+    def initialize model
+      @model = model
+    end
+
+    alias_method :to_model, :model
+
+    def to_policy
+      self
+    end
+
+    def can? action, *args
+      method = "can_#{action}?"
+      respond_to?(method) && !!safe_send(method, args)
+    end
+
+    def can! action, *args
+      can?(action, *args) || raise(ActiveModel::ActionNotAllowed, action)
+    end
+
+    def cannot? *args
+      !can? *args
+    end
+
+    def cannot! action, *args
+      cannot?(action, *args) || raise(ActiveModel::ActionUnexpected, action)
+    end
+
+    def self.can *actions, &block
+      raise ArgumentError if actions.empty?
+      actions.flatten.each do |action|
+        define_method "can_#{action}?", &block
+      end
+    end
+
+  private
+
+    def safe_send method_name, args
+      method = public_method method_name
+
+      if method.arity < args.length && method.arity != -1
+        args = args.take method.arity
+      end
+
+      method.call *args
+    end
+  end
+end

data/lib/active_model/policy_context.rb

@@ -0,0 +1,44 @@
+require "active_support/core_ext/class"
+
+module ActiveModel
+  module PolicyContext
+    extend ActiveSupport::Concern
+
+    included do
+      class_attribute :_policy_context
+    end
+
+    def policy_context
+      if _policy_context && respond_to?(_policy_context)
+        send _policy_context
+      else
+        self
+      end
+    end
+
+    def can? action, object
+      return false if object.nil?
+
+      policy = object.respond_to?(:to_policy) && object.to_policy
+      !policy || policy.can?(action, policy_context)
+    end
+
+    def can! action, object
+      can?(action, object) || raise(ActiveModel::ActionNotAllowed, action)
+    end
+
+    def cannot? *args
+      !can?(*args)
+    end
+
+    def cannot! action, object
+      cannot?(action, object) || raise(ActiveModel::ActionUnexpected, action)
+    end
+
+    module ClassMethods
+      def policy_context context
+        self._policy_context = context
+      end
+    end
+  end
+end

data/lib/active_model/policy_support.rb

@@ -0,0 +1,26 @@
+require "active_support"
+require "active_support/core_ext/string/inflections"
+
+module ActiveModel::PolicySupport
+  extend ActiveSupport::Concern
+
+  def to_policy
+    @policy ||= self.class.active_model_policy.new self
+  end
+
+  module ClassMethods
+    if ''.respond_to?(:safe_constantize)
+      def active_model_policy
+        @active_model_policy ||= "#{self.name}Policy".safe_constantize
+      end
+    else
+      def active_model_policy
+        return @active_model_policy if defined? @active_model_policy
+
+        @active_model_policy = "#{self.name}Policy".constantize
+      rescue NameError
+        nil
+      end
+    end
+  end
+end

data/lib/active_model/version.rb

@@ -0,0 +1,5 @@
+module ActiveModel
+  class Policy
+    VERSION = "0.0.1"
+  end
+end

data/lib/active_model_policy.rb

@@ -0,0 +1,36 @@
+require "active_support"
+require "active_support/core_ext/string/inflections"
+
+require "active_model"
+require "active_model/policy"
+require "active_model/policy_context"
+require "active_model/policy_support"
+require "active_model/version"
+
+require "action_controller/policy_context"
+
+module ActiveModel
+  class ActionNotAllowed < StandardError; end
+  class ActionUnexpected < StandardError; end
+
+  if defined?(::Rails)
+    class Railtie < Rails::Railtie
+      generators do |app|
+        app ||= Rails.application # Rails 3.0.x does not yield `app`
+
+        ::Rails::Generators.configure!(app.config.generators)
+        ::Rails::Generators.hidden_namespaces.uniq!
+      end
+    end
+  end
+end
+
+ActiveSupport.on_load(:active_record) do
+  include ActiveModel::PolicySupport
+end
+
+ActiveSupport.on_load(:action_controller) do
+  include ActionController::PolicyContext
+end
+
+ActiveSupport.run_load_hooks(:active_model_policy, ActiveModel::Policy)

data/lib/generators/policy/policy_generator.rb

@@ -0,0 +1,22 @@
+module Rails
+  module Generators
+    class PolicyGenerator < NamedBase
+      source_root File.expand_path("../templates", __FILE__)
+      check_class_collision :suffix => "Policy"
+
+      def create_serializer_file
+        template 'policy.rb', File.join('app/policies', class_path, "#{file_name}_policy.rb")
+      end
+
+    private
+
+      def parent_class_name
+        if defined?(::ApplicationPolicy)
+          "ApplicationPolicy"
+        else
+          "ActiveModel::Policy"
+        end
+      end
+    end
+  end
+end

data/lib/generators/policy/templates/policy.rb

@@ -0,0 +1,7 @@
+<% module_namespacing do -%>
+class <%= class_name %>Policy < <%= parent_class_name %>
+  # can :read do |context|
+  #   true
+  # end
+end
+<% end -%>

data/test/controller_test.rb

@@ -0,0 +1,16 @@
+require 'test_helper'
+
+class ControllerTest < ActiveModel::TestCase
+  test "#policy_context defaults to :current_user" do
+    assert_equal :current_user, TestContextController._policy_context
+  end
+
+  test "context methods are hidden from controller actions" do
+    actions = TestContextController.actions.sort
+    assert_equal [:can!, :can?, :cannot!, :cannot?, :policy_context], actions
+  end
+
+  test "helper methods are added for view" do
+    assert_equal [:can?, :cannot?], TestContextController.methods
+  end
+end

data/test/policy_context_test.rb

@@ -0,0 +1,93 @@
+require 'test_helper'
+
+class PolicyContextTest < ActiveModel::TestCase
+  test ".policy_context sets the context" do
+    refute_equal :test, TestContext._policy_context
+    TestContext.policy_context :test
+    assert_equal :test, TestContext._policy_context
+  end
+
+  test "#policy_context calls the context" do
+    TestContext.policy_context :current_user
+    context = TestContext.new
+    assert_equal :user, context.policy_context
+  end
+
+  test "#policy_context returns itself when context is nil" do
+    TestContext.policy_context nil
+    context = TestContext.new
+    assert_equal context, context.policy_context
+  end
+
+  test "#policy_context returns itself when context is not defined" do
+    TestContext.policy_context :foobar
+    context = TestContext.new
+    refute_respond_to context, :foobar
+    assert_equal context, context.policy_context
+  end
+
+  test "#can? returns true when object doesn't have a policy" do
+    object = Object.new
+    context = TestContext.new
+    assert context.can?(:test, object)
+  end
+
+  test "#can? returns true when object has policy and permits action" do
+    model = TestModel.new
+    policy = model.to_policy
+    context = TestContext.new
+    assert context.can?(:recieve_context, model)
+    assert_equal context, policy.context
+  end
+
+  test "#can? returns false when object has policy but doesn't permit action" do
+    model = TestModel.new
+    context = TestContext.new
+    refute context.can?(:bar, model)
+  end
+
+  test "#can? returns false when object is nil" do
+    context = TestContext.new
+    refute context.can?(:foo, nil)
+  end
+
+  test "#can! raises error when object doesn't permit action" do
+    model = TestModel.new
+    context = TestContext.new
+    assert_raises ActiveModel::ActionNotAllowed do
+      context.can!(:bar, model)
+    end
+  end
+
+  test "#can! returns true when action permitted" do
+    model = TestModel.new
+    context = TestContext.new
+    assert context.can!(:foo, model)
+  end
+
+  test "#cannot? returns true when action is not allowed" do
+    model = TestModel.new
+    context = TestContext.new
+    assert context.cannot?(:bar, model)
+  end
+
+  test "#cannot? returns false when action is allowed" do
+    model = TestModel.new
+    context = TestContext.new
+    refute context.cannot?(:foo, model)
+  end
+
+  test "#cannot! raises error when action is allowed" do
+    model = TestModel.new
+    context = TestContext.new
+    assert_raises ActiveModel::ActionUnexpected do
+      context.cannot!(:foo, model)
+    end
+  end
+
+  test "#cannot! returns true when action is not allowed" do
+    model = TestModel.new
+    context = TestContext.new
+    assert context.cannot!(:bar, model)
+  end
+end

data/test/policy_support_test.rb

@@ -0,0 +1,30 @@
+require 'test_helper'
+
+class PolicySupportTest < ActiveModel::TestCase
+  class Supporter
+    include ActiveModel::PolicySupport
+  end
+
+  class SupporterPolicy < ActiveModel::Policy
+  end
+
+  class Unsupported
+    include ActiveModel::PolicySupport
+  end
+
+  test ".active_model_policy returns the policy class" do
+    assert_respond_to Supporter, :active_model_policy
+    assert_equal SupporterPolicy, Supporter.active_model_policy
+  end
+
+  test ".active_model_policy returns nil when no policy class can be found" do
+    assert_respond_to Unsupported, :active_model_policy
+    assert_nil Unsupported.active_model_policy
+  end
+
+  test "#to_policy returns the policy instance setting itself as the model" do
+    model = Supporter.new
+    policy = model.to_policy
+    assert_equal model, policy.model
+  end
+end

data/test/policy_test.rb

@@ -0,0 +1,100 @@
+require 'test_helper'
+
+class PolicyTest < ActiveModel::TestCase
+  test "#initialize sets the model" do
+    model = Object.new
+    policy = ActiveModel::Policy.new model
+
+    assert_equal model, policy.model
+  end
+
+  test "#to_policy returns itself" do
+    policy = ActiveModel::Policy.new nil
+    assert_equal policy, policy.to_policy
+  end
+
+  test "#can? returns false when method not defined" do
+    policy = ActiveModel::Policy.new nil
+    refute policy.can?(:foobar)
+  end
+
+  test "#can? returns false when method returns false" do
+    policy = TestModelPolicy.new nil
+    refute policy.can_bar?
+    refute policy.can?(:bar)
+  end
+
+  test "#can? returns true when method returns true" do
+    policy = TestModelPolicy.new nil
+    assert policy.can_foo?
+    assert policy.can?(:foo)
+  end
+
+  test "#can? passes arguments to block" do
+    policy = TestModelPolicy.new nil
+    assert_nil policy.args
+    assert policy.can?(:receive_args, :boo, :hoo)
+    assert_equal [:boo, :hoo], policy.args
+  end
+
+  test "#can? culls excessive arguments" do
+    policy = TestModelPolicy.new nil
+    assert_nil policy.args
+    assert policy.can?(:receive_args, :boo, :hoo, :abc)
+    assert_equal [:boo, :hoo], policy.args
+  end
+
+  test "#cannot? returns true when method returns false" do
+    policy = TestModelPolicy.new nil
+    refute policy.can_bar?
+    assert policy.cannot?(:bar)
+  end
+
+  test "#cannot? returns false when method returns true" do
+    policy = TestModelPolicy.new nil
+    assert policy.can_foo?
+    refute policy.cannot?(:foo)
+  end
+
+  test "#can! returns true when method returns true" do
+    policy = TestModelPolicy.new nil
+    assert policy.can_foo?
+    assert policy.can!(:foo)
+  end
+
+  test "#can! raises error when method returns false" do
+    policy = TestModelPolicy.new nil
+    refute policy.can_bar?
+    assert_raises ActiveModel::ActionNotAllowed do
+      policy.can!(:bar)
+    end
+  end
+
+  test "#cannot! returns true when method returns false" do
+    policy = TestModelPolicy.new nil
+    refute policy.can_bar?
+    assert policy.cannot!(:bar)
+  end
+
+  test "#cannot! raises error when method returns true" do
+    policy = TestModelPolicy.new nil
+    assert policy.can_foo?
+    assert_raises ActiveModel::ActionUnexpected do
+      policy.cannot!(:foo)
+    end
+  end
+
+  test ".can defines a method" do
+    refute TestModelPolicy.method_defined?(:can_foobar?)
+    TestModelPolicy.can(:foobar){ true }
+    assert TestModelPolicy.method_defined?(:can_foobar?)
+  end
+
+  test ".can defines multiple methods when given multiple arguments" do
+    refute TestModelPolicy.method_defined?(:can_boo?)
+    refute TestModelPolicy.method_defined?(:can_hoo?)
+    TestModelPolicy.can(:boo, :hoo){ true }
+    assert TestModelPolicy.method_defined?(:can_boo?)
+    assert TestModelPolicy.method_defined?(:can_hoo?)
+  end
+end

data/test/test_helper.rb

@@ -0,0 +1,8 @@
+require "rubygems"
+require "bundler/setup"
+
+require "active_model_policy"
+require "test_objects"
+require "test/unit"
+
+require "rails"

data/test/test_objects.rb

@@ -0,0 +1,52 @@
+class TestContext
+  include ActiveModel::PolicyContext
+
+  def current_user
+    :user
+  end
+end
+
+class TestModel
+  include ActiveModel::PolicySupport
+end
+
+class TestModelPolicy < ActiveModel::Policy
+  attr_reader :context, :args
+
+  def can_recieve_context? context
+    @context = context
+    true
+  end
+
+  def can_foo?
+    true
+  end
+
+  def can_bar?
+    false
+  end
+
+  def can_receive_args? arg1, arg2
+    @args = [arg1, arg2]
+    true
+  end
+end
+
+class TestContextController
+  class << self
+    attr_reader :actions, :methods
+    def hide_action *actions
+      @actions = actions
+    end
+
+    def helper_method *methods
+      @methods = methods
+    end
+  end
+
+  include ActionController::PolicyContext
+
+  def current_user
+    :user
+  end
+end

metadata

@@ -0,0 +1,87 @@
+--- !ruby/object:Gem::Specification
+name: active_model_policy
+version: !ruby/object:Gem::Version
+  prerelease: 
+  version: 0.0.1
+platform: ruby
+authors:
+- Marty Zalega
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2013-01-10 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '3.0'
+    none: false
+  name: rails
+  type: :development
+  prerelease: false
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '3.0'
+    none: false
+description: Policy implementation for rails
+email:
+- marty@zalega.me
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- .gitignore
+- Gemfile
+- LICENSE
+- README.md
+- Rakefile
+- active_model_policy.gemspec
+- lib/action_controller/policy_context.rb
+- lib/active_model/policy.rb
+- lib/active_model/policy_context.rb
+- lib/active_model/policy_support.rb
+- lib/active_model/version.rb
+- lib/active_model_policy.rb
+- lib/generators/policy/policy_generator.rb
+- lib/generators/policy/templates/policy.rb
+- test/controller_test.rb
+- test/policy_context_test.rb
+- test/policy_support_test.rb
+- test/policy_test.rb
+- test/test_helper.rb
+- test/test_objects.rb
+homepage: ''
+licenses: []
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+  none: false
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+  none: false
+requirements: []
+rubyforge_project: 
+rubygems_version: 1.8.23
+signing_key: 
+specification_version: 3
+summary: Policy implementation for rails
+test_files:
+- test/controller_test.rb
+- test/policy_context_test.rb
+- test/policy_support_test.rb
+- test/policy_test.rb
+- test/test_helper.rb
+- test/test_objects.rb