customs 1.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 4f7d1115e1d61873619f4bab8f5eee93db18d59d
+  data.tar.gz: e3a3b2c4954b7f009fcbfdcab5b45ac505a4e7b8
+SHA512:
+  metadata.gz: 6cb37e479f2d906090756750d72355485b0cc54d396b2e2b5d19e25a6f3a56fe2f0d53c170449fabebb3402923def6ddb8d048e7331dbe8ddb6bdfb65ece2890
+  data.tar.gz: 10d4143ff33e16680a0db8a3f4c42f8c744f04f7e3952553d50a56cd26cb660e7d0a93ba32e4174af23b1531975f23f5c34e0cfd1b63bef202a77cc28daa6198

data/Gemfile

@@ -0,0 +1,19 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in customs.gemspec
+gemspec
+
+case ENV['RAILS_VERSION'] || 'default'
+when 'default'
+  gem 'rails'
+when 'master'
+  gem 'rails', github: 'rails/rails'
+when %r{\A3\.}
+  gem 'rails', "~> #{ENV['RAILS_VERSION']}"
+else
+  gem 'rails', "~> #{ENV['RAILS_VERSION']}"
+end
+
+gem 'rspec'
+gem 'rspec-rails'
+gem 'awesome_print'

data/LICENSE

@@ -0,0 +1,22 @@
+Copyright (c) 2012 Savater Sebastien
+
+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,229 @@
+<img src="http://upload.wikimedia.org/wikipedia/commons/3/36/Aiga_customs_inv.gif" alt="Customs Icon" align="right" width="120" />
+
+# Customs
+
+<img src="https://travis-ci.org/plataformatec/devise.svg?branch=master">
+
+
+**Customs** uses the power of [cancancan](https://github.com/CanCanCommunity/cancancan) (formerly known as [cancan](http://github.com/ryanb/cancan/)) to control the flow of your controllers.
+
+It adds some magic in your rails controllers, through the cancan magic formula : ```load_and_authorize_resource```, and let you customize the flow.
+
+**Customs** provides you:
+
+* default cruds methods
+* full control on controllers methods, steps by steps
+* methods for HTTP statuses
+* common errors rescue
+
+```
+class DrogsController < ApplicationController
+  control_and_rescue_traffic
+  respond_to :html, :json
+
+  load_and_authorize_resource :drog
+end
+```
+
+In the given examples, we do not endorse in any way the traffic of illegal products.
+Customs is watching you!
+
+
+## Requirements:
+
+* Ruby 1.9.3
+* Rails 3.2.18 and higher
+* Cancancan
+
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'customs'
+
+Or install it yourself as:
+
+    $ gem install customs
+
+Then, take a beer.
+
+## Usage
+
+Two methods available:
+
+* ``control_traffic``
+* ``rescue_traffic``
+
+Or only one to bind them:
+
+* ``control_and_rescue_traffic``
+
+
+#### Example
+
+```
+class DrogsController < ApplicationController
+  load_and_authorize_resource :drog
+  control_and_rescue_traffic
+  respond_to :html, :json
+end
+```
+
+
+#### Control traffic
+
+`control_traffic` provides you default methods to list, create, update & delete resources, depending on the cancan `load_resource` arguments.
+
+It uses exception to control the flow of data, such as:
+
+  * ActiveRecord::RecordNotFound or Mongoid::Errors::DocumentNotFound
+  * ActiveRecord::RecordInvalid or Mongoid::Errors::Validations
+  * CanCan::AccessDenied
+
+
+#### Rescue traffic
+
+`rescue_traffic` provides methods for specific HTTP statuses & routes the flow exceptions to the most appropriate one.
+
+  * 401 - `unauthorized`
+  * 403 - `forbidden`
+  * 404 - `not_found`
+  * 422 - `unprocessable`
+
+
+#### Callbacks
+
+Callbacks are working like rails filters :
+
+  * `before_save    :make_something`
+  * `before_save    :make_something_else, only: :create`
+  * `before_destroy :make_nothing`
+
+```
+class BaggagesController < ApplicationController
+  load_and_authorize_resource :baggage
+  before_save   :add_illegal_content
+  after_save    :report_to_autorithies
+  after_destroy :analyse_scraps
+end
+```
+
+Maybe you prefer to pass a block to `create`, `update` or `destroy` ?
+In this case, the block is called after the `save!` method.
+
+```
+class BaggagesController < ApplicationController
+  load_and_authorize_resource :baggage
+
+  def create
+    super do
+      control_content && report_to_autorithies
+    end
+  end
+end
+```
+
+
+#### Flow customization
+
+You can customize the controller flow by overriding any following methods:
+
+  * `resource_params` - parameters attributes, which will be used to create/update resources
+  * `success_response` - what happened after successfull action
+  * `resource_location` - where redirect on a success response (depending on the `action_name`)
+
+For a better understanding, you have to keep in mind that `control_traffic` apply these methods with the following schema:
+
+
+```
+class DrogsController < ApplicationController
+
+  def create
+    resource.assign_attributes resource_params
+    resource.save!
+    success_response
+  end
+
+  def update
+    resource.assign_attributes resource_params
+    resource.save!
+    success_response
+  end
+
+  def destroy
+    resource.destroy
+    success_response
+  end
+
+protected
+
+  def resource_params
+    params[resource_name]
+  end
+
+  def success_response
+    respond_with resource, :location => resource_location
+  end
+
+  def resource_location
+    case action_name
+    when 'create'  then resource
+    when 'update'  then resource
+    when 'destroy' then resource_name.to_s.pluralize.to_sym
+    end
+  end
+end
+```
+
+
+##### Mass assignment
+
+I highly recommend overriding the `resource_params` method with [Strong Parameters](http://github.com/rails/strong_parameters):
+
+```
+class SmugglersController < ApplicationController
+  load_and_authorize_resource :smuggler
+
+protected
+
+  def resource_params
+    params.require(:smuggler).permit(:name, :skills)
+  end
+end
+```
+
+
+#### Trace errors
+
+With `rescue_traffic`, rescued errors will output something like that in you logs:
+
+```
+[Customs] Rescuing from ActionView::MissingTemplate with :not_found
+```
+
+If you need to trace the error, you just have to override the `rescue_exception_with` method:
+
+```
+def rescue_exception_with exception, method
+  logger.error "Rescuing from #{ exception.class } with :#{ method }"
+  exception.backtrace[0..10].each {|line| logger.error line }
+  send method
+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
+
+
+#### Credits
+
+- The gem has been cutted over [cancan](https://github.com/ryanb/cancan).
+- The icon has been stolen to [wikimedia.org](http://wikimedia.org).
+

data/Rakefile

@@ -0,0 +1,7 @@
+#!/usr/bin/env rake
+require 'bundler/gem_tasks'
+require 'rspec/core/rake_task'
+
+RSpec::Core::RakeTask.new('spec')
+
+task default: :spec

data/app/views/customs/401.html.haml

@@ -0,0 +1,3 @@
+.dialog
+  %h1= I18n.t 'customs.401.title'
+  %p= I18n.t 'customs.401.content'

data/app/views/customs/403.html.haml

@@ -0,0 +1,3 @@
+.dialog
+  %h1= I18n.t 'customs.403.title'
+  %p= I18n.t 'customs.403.content'

data/app/views/customs/404.html.haml

@@ -0,0 +1,3 @@
+.dialog
+  %h1= I18n.t 'customs.404.title'
+  %p= I18n.t 'customs.404.content'

data/app/views/customs/406.html.haml

@@ -0,0 +1,3 @@
+.dialog
+  %h1= I18n.t 'customs.406.title'
+  %p= I18n.t 'customs.406.content'

data/config/locales/en.yml

@@ -0,0 +1,14 @@
+en:
+  customs:
+    "401":
+      title:    You cannot access to this page.
+      content:  You first need to authenticate to access this page.
+    "403":
+      title:    You cannot access to this page.
+      content:  You do not have sufficient permissions to access this page.
+    "404":
+      title:    The page you were looking for doesn't exist.
+      content:  You may have mistyped the address or the page may have moved.
+    "406":
+      title:    The resource you have requested cannot be returned.
+      content:  An appropriate representation of the requested resource could not be rendered.

data/lib/customs/control_flow.rb

@@ -0,0 +1,106 @@
+require 'cancan'
+
+module Customs
+  module ControlFlow
+
+    # GET actions
+
+    def index
+      respond_with resource_collection
+    end
+
+    [:new, :show, :edit].each do |name|
+      define_method name do
+        respond_with resource
+      end
+    end
+
+    # Other actions
+
+    def create
+      save_resource
+      success_response
+    end
+
+    def update
+      save_resource
+      success_response
+    end
+
+    def destroy
+      destroy_resource
+      success_response
+    end
+
+
+  protected
+
+    # Resource naming
+
+    def resource_name
+      @resource_name ||= resource_name_from_controller
+    end
+
+    def resource_name_from_controller
+      params[:controller].sub("Controller", "").underscore.split('/').last.singularize
+    end
+
+    def resource_class
+      @resource_class ||= resource_name.to_s.classify.constantize
+    end
+
+    def resource_params
+      params[resource_name]
+    end
+
+    # Resources
+
+    def resource_collection
+      instance_variable_get "@#{resource_name.to_s.pluralize}"
+    end
+
+    def resource
+      instance_variable_get "@#{resource_name.to_s}"
+    end
+
+    # Resource actions
+
+    def save_resource
+      resource.assign_attributes resource_params
+
+      args = [:save]
+      args << action_name unless ::Rails.version.to_f >= 4.0
+
+      run_callbacks *args do
+        resource.save!
+      end
+    end
+
+    def destroy_resource
+      args = [:destroy]
+      args << action_name unless ::Rails.version.to_f >= 4.0
+
+      run_callbacks *args do
+        if resource.respond_to? :destroy!
+          resource.destroy!
+        else
+          resource.destroy
+        end
+      end
+    end
+
+    # Response
+
+    def success_response
+      respond_with resource, :location => resource_location
+    end
+
+    def resource_location
+      case action_name
+      when 'create'  then resource
+      when 'update'  then resource
+      when 'destroy' then resource_name.to_s.pluralize.to_sym
+      end
+    end
+  end
+end

data/lib/customs/control_traffic.rb

@@ -0,0 +1,60 @@
+require 'cancan'
+
+module Customs
+
+  # Override CanCan::ControllerResource
+
+  class ControllerResource < CanCan::ControllerResource
+    def initialize *args
+      super
+      @controller.resource_name   = instance_name
+      @controller.resource_class  = resource_class
+    end
+
+    def build_resource
+      resource = resource_base.new
+      assign_attributes(resource)
+    end
+  end
+
+  module ControlTraffic
+
+    def self.included base
+      base.send :extend, ClassMethods
+
+      base.class_attribute :controller_resource_class, :instance_reader => false
+      base.controller_resource_class = ControllerResource
+
+      base.class_attribute :resource_name,  :instance_reader => false
+      base.class_attribute :resource_class, :instance_reader => false
+
+      base.define_callbacks :save, :destroy
+    end
+
+    module ClassMethods
+      def cancan_resource_class
+        if ancestors.map(&:to_s).include? "InheritedResources::Actions"
+          super
+        else
+          self.controller_resource_class
+        end
+      end
+
+
+      [:before, :after, :around].each do |callback|
+
+        define_method "#{callback}_save" do |*names, &blk|
+          _insert_callbacks(names, blk) do |name, options|
+            set_callback :save, callback, name, options
+          end
+        end
+
+        define_method "#{callback}_destroy" do |*names, &blk|
+          _insert_callbacks(names, blk) do |name, options|
+            set_callback :destroy, callback, name, options
+          end
+        end
+      end
+    end
+  end
+end

data/lib/customs/engine.rb

@@ -0,0 +1,28 @@
+require 'rails/engine'
+
+module Customs
+  class Engine < Rails::Engine
+
+    initializer 'traffic.configure' do
+      ActiveSupport.on_load(:action_controller) do
+        ActionController::Base.send :extend, Customs::ControllerAdditions
+      end
+    end
+  end
+
+  module ControllerAdditions
+    def control_and_rescue_traffic
+      control_traffic && rescue_traffic
+    end
+
+    def control_traffic
+      include Customs::ControlTraffic
+      include Customs::ControlFlow
+    end
+
+    def rescue_traffic
+      include Customs::Statuses
+      include Customs::RescueTraffic
+    end
+  end
+end

data/lib/customs/rescue_traffic.rb

@@ -0,0 +1,24 @@
+module Customs
+  module RescueTraffic
+
+    def self.included base
+      base.rescue_from CanCan::AccessDenied, with: proc{|e| rescue_exception_with e, :access_denied }
+
+      base.rescue_from ActionController::UnknownFormat, with: proc{|e| rescue_exception_with e, :not_acceptable } if defined? ActionController::UnknownFormat
+
+      base.rescue_from ActiveRecord::RecordNotFound, with: proc{|e| rescue_exception_with e, :not_found }     if defined? ActiveRecord::RecordNotFound
+      base.rescue_from ActiveRecord::RecordInvalid , with: proc{|e| rescue_exception_with e, :unprocessable } if defined? ActiveRecord::RecordInvalid
+
+      base.rescue_from Mongoid::Errors::DocumentNotFound, with: proc{|e| rescue_exception_with e, :not_found }     if defined? Mongoid::Errors
+      base.rescue_from Mongoid::Errors::Validations     , with: proc{|e| rescue_exception_with e, :unprocessable } if defined? Mongoid::Errors
+    end
+
+    def rescue_exception_with exception, status_method
+      if respond_to?(:logger) && logger
+        logger.info "[Customs] Rescuing from #{ exception.class } with :#{ status_method }"
+      end
+
+      send status_method
+    end
+  end
+end

data/lib/customs/statuses.rb

@@ -0,0 +1,53 @@
+module Customs
+  module Statuses
+
+    def self.included base
+      base.class_attribute :navigational_formats
+      base.navigational_formats = [:html]
+    end
+
+    { :unauthorized   => 401,
+      :forbidden      => 403,
+      :not_found      => 404,
+      :not_acceptable => 406,
+      :unprocessable  => 422
+    }.each do |method, code|
+      define_method method do
+        render options_for_status_code(code)
+        false
+      end
+    end
+
+    def access_denied
+      return unauthorized if self.respond_to?(:current_user) && !current_user
+      forbidden
+    end
+
+    def unprocessable *args
+      options = args.extract_options!
+
+      respond_to do |format|
+        format.any *navigational_formats do
+          action = options.delete(:action)
+          action ||= case params[:action]
+            when 'update' then 'edit'
+            when 'create' then 'new'
+            else raise "Unknown unprocessable action"
+          end
+
+          render :status => 422, :action => action
+        end
+
+        format.all { render :status => 422 }
+      end
+    end
+
+    def options_for_status_code code
+      { :status => code, :template => template_for_status_code(code) }
+    end
+
+    def template_for_status_code code
+      "customs/#{code}"
+    end
+  end
+end

data/lib/customs/version.rb

@@ -0,0 +1,3 @@
+module Customs
+  VERSION = '1.1.0'
+end

data/lib/customs.rb

@@ -0,0 +1,6 @@
+require 'customs/statuses'
+require 'customs/rescue_traffic'
+require 'customs/control_traffic'
+require 'customs/control_flow'
+require 'customs/engine'
+require 'customs/version'

metadata

@@ -0,0 +1,129 @@
+--- !ruby/object:Gem::Specification
+name: customs
+version: !ruby/object:Gem::Version
+  version: 1.1.0
+platform: ruby
+authors:
+- Savater
+- Sebastien
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2014-05-16 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 3.2.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 3.2.0
+- !ruby/object:Gem::Dependency
+  name: sqlite3
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: railties
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 3.2.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 3.2.0
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 3.2.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 3.2.0
+- !ruby/object:Gem::Dependency
+  name: cancancan
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: Use the power of Cancan to control the flow of your controllers.
+email: savater.sebastien@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- Gemfile
+- LICENSE
+- README.md
+- Rakefile
+- app/views/customs/401.html.haml
+- app/views/customs/403.html.haml
+- app/views/customs/404.html.haml
+- app/views/customs/406.html.haml
+- config/locales/en.yml
+- lib/customs.rb
+- lib/customs/control_flow.rb
+- lib/customs/control_traffic.rb
+- lib/customs/engine.rb
+- lib/customs/rescue_traffic.rb
+- lib/customs/statuses.rb
+- lib/customs/version.rb
+homepage: http://github.com/inkstak/customs
+licenses: []
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 1.9.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.2.2
+signing_key: 
+specification_version: 4
+summary: Control the traffic of your rails controllers.
+test_files: []