permitters 0.0.1

checksums.yaml

@@ -0,0 +1,15 @@
+---
+!binary "U0hBMQ==":
+  metadata.gz: !binary |-
+    MmY3NGJmNTczNzExZjRkYjQ3MDRiZWJiNGM3NDhjOWI5ZTYyZThlZQ==
+  data.tar.gz: !binary |-
+    NmZmYTk1MTExNDg2YmQ4OGQyM2I5YjE2OTUzNjA2MGVhZjRlMGY4YQ==
+!binary "U0hBNTEy":
+  metadata.gz: !binary |-
+    NmQ5ZGYxY2I4NTcwZDY1OTBkOTg0M2VmYzIwYWM4OTlhZjBjMjJiNGU1YzU4
+    ZmU5OTY5MTVhNTFjZGMwZGFhN2MyNWFhN2Y5ODQ4ZGIzY2I2ZWM5ZmRjMDNj
+    NzUxYTQzNWZiNjRmYTBmZjdiZGViMTdlMmY3NzI1YzJiZThmMDE=
+  data.tar.gz: !binary |-
+    OTcxMzUxMjBmNGFiNDg4MzliNDhmMTg1MzA2MTg5NTIzNjhkNWVmMzk2MTRk
+    NzUxZTczN2M5MTFlMTE0MzQwNGZmOGZlNDZhM2MwMjBiZjczNmVlZDUzMTgx
+    NGE2NGI1ZDRjZmVmMjg1YWVkMDQzNDIyNDNjOWI2NWM4NDkyMzA=

data/README.md

@@ -0,0 +1,296 @@
+[![Build Status](https://secure.travis-ci.org/permitters/permitters.png?branch=master)](http://travis-ci.org/permitters/permitters) [![Gem Version](https://badge.fury.io/rb/permitters.png)](http://badge.fury.io/rb/permitters)
+# Permitters
+
+Permitters are an object-oriented way of defining what request parameters are permitted using [Strong Parameters][strong_parameters]. It is to Strong Parameters what ActiveModel::Serializers are to as_json/to_json.
+
+Permitters also allow additional parameter authorization using an authorizing class, such as CanCan's Ability class or a custom authorizer.
+
+The original version of the Permitters framework that this was based on was provided in a [post][post] by Adam Hawkins.
+
+### Installation
+
+In your Rails app's `Gemfile`:
+
+```ruby
+gem 'permitters', '~> 0.0.1'
+```
+
+Then:
+
+```
+bundle install
+```
+
+#### Strong Parameters
+
+If you are using Rails 4.x, Strong Parameters is included and everything should be setup, so you can skip this section.
+
+If you are using Rails 3.x, you'll need [Strong Parameters][strong_parameters]:
+
+```ruby
+gem 'strong_parameters'
+```
+
+Also in Rails 3.x, you probably will want to change this to false in config:
+
+```ruby
+config.active_record.whitelist_attributes = false
+```
+
+and either put this in each model you want to use Strong Parameters with:
+
+```ruby
+include ActiveModel::ForbiddenAttributesProtection
+```
+
+Or if you'd rather use Strong Parameters with all models, just put this at the bottom of your `config/environment.rb` or an initializer:
+
+```ruby
+ActiveRecord::Base.send :include, ActiveModel::ForbiddenAttributesProtection
+```
+
+### Usage
+
+First, either put this in each controller you want to use Strong Parameters with:
+
+```ruby
+include ActionController::Permittance
+```
+
+Or if you'd rather use Permitters with all controllers, just put this at the bottom of your `config/environment.rb` or an initializer:
+
+```ruby
+ActionController::Base.send :include, ActionController::Permittance
+```
+
+Then in your controller:
+
+```ruby
+def create
+  @deal = Deal.new permitted_params
+  # ...
+end
+```
+
+Next, add a permitter for each controller that uses `ActionController::Permittance` in `/app/permitters/`.
+
+For `/app/controllers/deals_controller.rb`, you would add a `/app/permitters/deal_permitter.rb`:
+
+```ruby
+class DealPermitter < ActionController::Permitter
+  # No premissions required to set this
+  permit :name, :description, :close_by, :state
+
+  # can pass `:authorize` with a permission:
+  # This line allows user_id if the user can read the user specified
+  # by the user_id. This only happens if it's present
+  permit :user_id, :authorize => :read
+
+  # same thing but automatically handles arrays of ids as well.
+  # This line allows the attachment_ids if the user can manage all
+  # the specified attachments
+  permit :attachment_ids, :authorize => :manage
+
+  # same thing as before but scopes this it to the
+  # hash inside the line_items_attributes array
+  #
+  # line_items_attributes is permitted if every item in the array
+  # is allowed.
+  # 
+  # This also only allows line items if the user can manage the parent
+  scope :line_items_attributes, :manage => true do |line_item|
+    # So you cannot manipulate line items outside the parent
+    line_item.permit :id, :authorize => :manage 
+
+    line_item.permit :name, :quantity, :price, :currency, :notes
+    line_item.permit :product_id, :authorize => :read
+  end
+end
+```
+
+When you call `permitted_params`, this happens:
+
+```ruby
+params.require(:deal).permit(:name, :description, :close_by, :state, :line_items_attributes => [:id, :name, :quantity, :price, :currency, :notes, product_id])
+```
+
+If the controller is namespaced, the permitter should have the same namespace, e.g. `A:B:DealsController` defined in `app/controllers/a/b/deals_controller.rb` requires `A:B:DealPermitter` defined in  `/app/a/b/permitters/deal_permitter.rb`.
+
+If you need to override the argument(s) to pass into the require, use `resource` in the permitter:
+
+```ruby
+class DealPermitter < ActionController::Permitter
+  resource :deal
+  # ...
+end
+```
+
+To specify a different Permitter to use with a Controller, either provide a `permitter_class` method:
+
+```ruby
+def permitter_class
+  PersonPermitter
+end
+```
+
+Or to specify the permitter, use `permitted_params_using(PermitterClass)`, e.g.:
+
+```ruby
+def make_cotton_candy
+  @cotton_candy = CottonCandy.new(permitted_params_using(A::B::CottonCandyPermitter))
+  # ...
+end
+```
+
+### Authorizers
+
+Permitters also allow additional parameter authorization using CanCan or a custom authorizer.
+
+The authorizer class must implement `initialize(user)` and `authorize!(permission, record)` (like CanCan's Ability class).
+
+The controller class can implement a method to return an instance of the authorizer class.
+
+So, now let's add the `authorize!`:
+
+```ruby
+def create
+  authorize! :create, Deal
+  @deal = Deal.new permitted_params
+  # ...
+end
+```
+
+When you call `authorize!(:some_permission, YourModelClass)` method, that method will raise an error if `current_user` doesn't have the appropriate permissions for those attributes for which `:authorize` is specified.
+
+#### Adding a Custom Authorizer
+
+To set this up, you'll need to add one of these into your app config:
+
+```ruby
+config.action_controller.authorizer = 'SomeAuthorizer'
+```
+
+or:
+
+```ruby
+config.action_controller.current_authorizer_method = 'current_authorizer'
+```
+
+If neither is specified, then if the controller calls `authorize!(permission, record)`, nothing happens.
+
+##### Without a Controller Method
+
+Put this into your app config:
+
+```ruby
+config.action_controller.authorizer = 'SomeAuthorizer'
+```
+
+Create a class `lib/some_authorizer.rb` that has an `initialize(user)` and `authorize!(permission, record)` methods:
+
+```ruby
+class SomeAuthorizer
+
+  def initialize(user)
+    @user = user
+  end
+
+  def authorize!(permission, record)
+    raise "You must login to create deals" if permission == :create && record == Deal && @user.name == 'guest'
+  end
+end
+```
+
+##### With a Controller Method
+
+Put this into your app config:
+
+```ruby
+config.action_controller.current_authorizer_method = 'current_authorizer'
+```
+
+and in your controller or ApplicationController return an instance of an authorizer from that method:
+
+```ruby
+def current_authorizer
+  @current_ability ||= ::SomeAuthorizer.new
+end
+```
+
+Create a class `lib/some_authorizer.rb` that raises an error from `authorize!(permission, record)` if unauthorized:
+
+```ruby
+class SomeAuthorizer
+  def authorize!(permission, record)
+    raise "Deals can only be created from 8-5pm" if permission == :create && record == Deal && (Time.new.hour < 8 || Time.new.hour >= 17)
+  end
+end
+```
+
+##### CanCan
+
+[CanCan][cancan] is able to integrate with the Permitters framework as an authorizer. To use CanCan, put this into your app config:
+
+```ruby
+config.action_controller.authorizer = 'Ability'
+config.action_controller.current_authorizer_method = 'current_ability'
+```
+
+(Note: You could just define either. If you don't set current_authorizer_method, it will just try creating an instance of the authorizer using the current user. If neither are specified, nothing will happen when `authorize!(permission, record)` is called.)
+
+CanCan can integrate with [Authlogic][authlogic], [Devise][devise], etc. to return a proper logged-in user, or you can return it however you wish from the `current_user` method in your controller. Just to provide a simple example, we'll pretend the user was logged-in and return a new User instance (which means you will need a User model):
+
+```ruby
+class ApplicationController < ActionController::Base
+  protect_from_forgery
+
+  def current_user
+    User.new
+  end
+end
+```
+
+Again for simplicity, we'll write an "allow-everything" Ability in `app/models/ability.rb`:
+
+```ruby
+class Ability
+  include CanCan::Ability
+
+  def initialize(user)
+    can :manage, :all
+  end
+end
+```
+
+Then in each model you want to use CanCan with, add this into the class:
+
+```ruby
+include CanCan::ModelAdditions
+```
+
+If you'd rather use CanCan with all models, just put this at the bottom of your `config/environment.rb` or an initializer:
+
+```ruby
+ActiveRecord::Base.send :include, CanCan::ModelAdditions
+```
+
+### Release Notes
+
+See the [changelog][changelog].
+
+### Contributors
+
+* Adam Hawkins (https://github.com/twinturbo)
+* Gary Weaver (https://github.com/garysweaver)
+
+### License
+
+Copyright (c) 2013 Adam Hawkins and Gary S. Weaver, released under the [MIT license][lic].
+
+[post]: http://broadcastingadam.com/2012/07/parameter_authorization_in_rails_apis/
+[cancan]: https://github.com/ryanb/cancan
+[strong_parameters]: https://github.com/rails/strong_parameters
+[authlogic]: https://github.com/binarylogic/authlogic
+[devise]: https://github.com/plataformatec/devise
+[changelog]: https://github.com/permitters/permitters/blob/master/CHANGELOG.md
+[lic]: http://github.com/permitters/permitters/blob/master/LICENSE

data/Rakefile

@@ -0,0 +1,18 @@
+require 'bundler/setup'
+require 'bundler/gem_tasks'
+require 'appraisal'
+
+require 'rspec/core/rake_task'
+RSpec::Core::RakeTask.new(:spec)
+
+task :default do |t|
+  if ENV['BUNDLE_GEMFILE'] =~ /gemfiles/
+    exec 'rake spec'
+  else
+    exec 'rake appraise'
+  end
+end
+
+task :appraise => ['appraisal:install'] do |t|
+  exec 'rake appraisal'
+end

data/lib/action_controller/permittance.rb

@@ -0,0 +1,41 @@
+module ActionController
+  module Permittance
+    extend ActiveSupport::Concern
+
+    def permitted_params
+      get_permitted_params_using(permitter)
+    end
+
+    def permitted_params_using(pclass)
+      get_permitted_params_using(permitter(pclass))
+    end
+
+    # Returns a new instance of the permitter by initializing it with params, current_user, current_ability.
+    def permitter(pclass = permitter_class)
+      pinstance = (@permitter_class_to_permitter ||= {})[pclass]
+      return pinstance if pinstance
+      current_authorizer_method = ActionController::Permitter.current_authorizer_method ? ActionController::Permitter.current_authorizer_method.to_sym : nil
+      @permitter_class_to_permitter[pclass] = pclass.new(params, current_user, current_authorizer_method && defined?(current_authorizer_method) ? __send__(current_authorizer_method) : nil)
+    end
+
+    # Returns the permitter class corresponding to the controller by matching everything in the controller class name
+    # other than "Controller" and singularizing the part after any namespace before tacking on Permitter to the name.
+    #
+    # e.g. if self.class.name is "A:B:StatusesController", it would return A::B::StatusPermitter
+    def permitter_class
+      # Permitters should be in the same namespace as the controller, like ActiveModel::Serializers are in the same namespace as the model.
+      name = self.class.name
+      # in Rails 3.2+ could do:
+      # namespace = name.deconstantize; "#{namespace}#{namespace.blank? ? '' : '::'}#{name.demodulize.chomp('Controller').singularize}Permitter".constantize
+      # Rails < 3.2
+      last_index = name.rindex('::')
+      "#{last_index ? "#{name[0...(last_index || 0)]}::" : ''}#{(last_index ? name[(last_index+2)..-1] : name).chomp('Controller').singularize}Permitter".constantize
+    end
+
+    private
+
+    def get_permitted_params_using(pinstance)
+      (@permitter_to_permitted_params ||= {})[pinstance] ||= pinstance.permitted_params
+    end
+  end
+end

data/lib/action_controller/permitter.rb

@@ -0,0 +1,101 @@
+module ActionController
+  class PermitterAttribute < Struct.new(:name, :options); end
+  class Permitter
+
+    # Application-wide configuration
+    cattr_accessor :authorizer, :instance_accessor => false
+    cattr_accessor :current_authorizer_method, :instance_accessor => false
+
+    class << self
+      # When Permitter is inherited, it sets the resource (the symbol for params.require(some_sym)) to the unnamespaced model class that corresponds
+      # to the Permitter's classname, e.g. by default A::B::ApplesController will use A::B::ApplePermitter which will do params.permit(:apple).
+      # To change this value, use the `resource` class method.
+      def inherited(subclass)
+        subclass.class_eval do
+          class_attribute :permitted_attributes
+          class_attribute :resource_name
+
+          self.permitted_attributes = []
+          name = self.name
+
+          # in Rails 3.2+ could do:
+          # name.demodulize.chomp('Permitter').underscore.to_sym
+          # Rails < 3.2
+          last_index = name.rindex('::')
+          self.resource_name = (last_index ? name[(last_index+2)..-1] : name).chomp('Permitter').underscore.to_sym
+        end
+      end
+
+      def permit(*args)
+        options = args.extract_options!
+
+        args.each do |name|
+          self.permitted_attributes += [ActionController::PermitterAttribute.new(name, options)]
+        end
+      end
+
+      def scope(name)
+        with_options :scope => name do |nested|
+          yield nested
+        end
+      end
+
+      def resource(name)
+        self.resource_name = name
+      end
+    end
+
+    def initialize(params, user, authorizer = nil)
+      @params, @user, @authorizer = params, user, authorizer
+    end
+
+    def permitted_params
+      scopes = {}
+      unscoped_attributes = []
+
+      permitted_attributes.each do |attribute|
+        scope_name = attribute.options[:scope]
+        (scope_name ? (scopes[scope_name] ||= []) : unscoped_attributes) << attribute.name
+      end
+
+      # class_attribute creates an instance method called resource_name, which we'll allow overriding of in the permitter definition, if desired for some odd reason.
+      @filtered_params ||= params.require(resource_name).permit(*unscoped_attributes, scopes)
+
+      permitted_attributes.select {|a| a.options[:authorize]}.each do |attribute|
+        scope_name = attribute.options[:scope]
+        values = scope_name ? Array.wrap(@filtered_params[scope_name]).collect {|hash| hash[attribute.name]}.compact : Array.wrap(@filtered_params[attribute.name])
+        klass = (attribute.options[:as].try(:to_s) || attribute.name.to_s.split(/(.+)_ids?/)[1]).classify.constantize
+
+        values.each do |record_id|
+          record = klass.find record_id
+          permission = attribute.options[:authorize].to_sym || :read
+          authorize! permission, record
+        end
+      end
+
+      @filtered_params
+    end
+
+    def authorize!(*args, &block)
+      # implementing here is clearer than doing a delegate :authorize!, :to => :authorizer, imo.
+      authorizer ? authorizer.__send__(:authorize!, *args, &block) : nil
+    end
+
+
+  private
+
+    def params
+      @params
+    end
+
+    def user
+      @user
+    end
+
+    def authorizer
+      # e.g. if ActionController::Permitter.authorizer = Ability
+      # then this returns Ability.new(user)
+      @authorizer ||= (ActionController::Permitter.authorizer.is_a?(String) ? ActionController::Permitter.authorizer.constantize : ActionController::Permitter.authorizer).try(:new, user)
+    end
+  end
+end

data/lib/permitters.rb

@@ -0,0 +1,4 @@
+require 'permitters/version'
+require 'action_controller/permittance'
+require 'action_controller/permitter'
+require 'permitters/railtie' if defined? ::Rails::Railtie

data/lib/permitters/railtie.rb

@@ -0,0 +1,15 @@
+require 'rails/railtie'
+
+module Permitters
+  class Railtie < ::Rails::Railtie
+    initializer "permitters.config", :before => "action_controller.set_configs" do |app|
+      ActionController::Permitter.authorizer = app.config.action_controller.delete(:authorizer)
+      ActionController::Permitter.current_authorizer_method = app.config.action_controller.delete(:current_authorizer_method)
+    end
+
+    initializer "permitters.set_autoload_path", after: :load_config_initializers do
+      permitters_path = "#{Rails.root}/app/permitters"
+      ActiveSupport::Dependencies.autoload_paths << permitters_path unless ActiveSupport::Dependencies.autoload_paths.include?(permitters_path)
+    end
+  end
+end

data/lib/permitters/version.rb

@@ -0,0 +1,3 @@
+module Permitters
+  VERSION = '0.0.1'
+end

metadata

@@ -0,0 +1,55 @@
+--- !ruby/object:Gem::Specification
+name: permitters
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+platform: ruby
+authors:
+- Adam Hawkins
+- Gary S. Weaver
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2013-04-27 00:00:00.000000000 Z
+dependencies: []
+description: Permitters are an object-oriented way of defining what request parameters
+  are permitted. using Strong Parameters. It is to Strong Parameters what ActiveModel::Serializers
+  are to as_json/to_json, but supports CanCan and similar authorization frameworks.
+email:
+- me@broadcastingadam.com
+- garysweaver@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- lib/action_controller/permittance.rb
+- lib/action_controller/permitter.rb
+- lib/permitters/railtie.rb
+- lib/permitters/version.rb
+- lib/permitters.rb
+- Rakefile
+- README.md
+homepage: https://github.com/permitters/permitters
+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.0.3
+signing_key: 
+specification_version: 4
+summary: Object-oriented parameter authorization with Strong Parameters
+test_files: []