exceptionally 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 021bc161718c3f6759f35966d9d833adfcd9b700
+  data.tar.gz: c77c028c2e5aefaa9d424910b1898e141b350f63
+SHA512:
+  metadata.gz: ab99856b766aecb5504bdbbb8fb033f868a40bfca10f751ea3f1d2f420206b68bf92b5bbe1b8a5538c41765f870cdc758d40d34748420e8cbeab42a83eddec31
+  data.tar.gz: d75cc2385e01a7280fa3602063c92101d174ea375d399df523f41f4394c72cfed30f6168257b0b0f3971ec439d9fee9b9195665c4ae5e7839b5745b9ce44dd5c

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright 2014 Neil Gupta
+
+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,138 @@
+# Exceptionally
+
+[https://www.github.com/neilgupta/exceptionally](https://www.github.com/neilgupta/exceptionally)
+
+Exceptionally abstracts your exception logic to make raising and returning meaningful errors in Ruby on Rails easier. It is primarily designed for API-only applications that need to return descriptive JSON error messages, rather than static HTML error pages.
+
+Just raise the appropriate exception anywhere in your code and Exceptionally will handle the rest.
+
+```ruby
+raise Exceptionally::Unauthorized.new("Incorrect token")
+```
+
+will return the following JSON response to the client with a 401 status code: 
+
+```javascript
+{"error": "Incorrect token"}
+```
+
+It's that easy!
+
+## Installation
+
+To get started with Exceptionally, just add the following to your `Gemfile`:
+
+```ruby
+gem 'exceptionally'
+```
+
+Exceptionally has only been tested with Rails 4, but it should work with Rails 3+ in theory ;)
+
+## Features
+
+In addition to seamlessly abstracting your exception logic and returning clean JSON responses to your users, Exceptionally also offers the following benefits.
+
+### Logging
+
+If you raise a 500-level error, Exceptionally will log the error, stacktrace, and relevant parameters to Rails.logger. Additionally, Exceptionally supports [Airbrake](http://airbrake.io) and [New Relic](http://newrelic.com) by default, and will notify those services if you have their gems set up.
+
+### Customizable
+
+#### Add a custom error handler
+
+Need to run your own logging code or do something else with the errors before they're returned to the user? Just add the following to `config/initializers/exceptionally.rb`:
+
+```ruby
+Exceptionally::Handler.before_render do |message, status, error, params|
+  # Place your custom code here
+  # message is a string description of what went wrong
+  # status is an integer of the HTTP status code
+  # error is a Ruby Exception object
+  # params is a hash of the parameters passed to your controller
+end
+```
+
+#### Override output formatting
+
+You can also override the returned response by adding a `render_error` method to your controller. For example, if you want to include the HTTP status code in the returned JSON, you can do:
+
+```ruby
+def render_error(message, status)
+  render json: {error_message: message, error_status: status}, status: status
+end
+```
+
+You could also return HTML, XML, or whatever other format is relevant to your application.
+
+`render_error` must accept `message`, a string description of the error, and `status`, an integer HTTP status code.
+
+#### Add custom errors
+
+Exceptionally will handle the following errors by default:
+
+* generic Exceptions
+* ArgumentErrors
+* ActiveRecord::RecordNotFound
+* ActiveRecord::RecordInvalid
+* Apipie::ParamMissing (if using [Apipie](https://github.com/Apipie/apipie-rails))
+* Apipie::ParamInvalid (if using [Apipie](https://github.com/Apipie/apipie-rails))
+* Exceptionally errors (see below for available errors)
+
+If there are additional errors that you want to assign status codes to and pass to Exceptionally, you can add the following to the top of your `application_controller.rb`:
+
+```ruby
+# Catch MyCustomModule::BadRequestException errors and pass them to Exceptionally
+rescue_from MyCustomModule::BadRequestException, :with => :custom_400_error
+
+# Tell Exceptionally you want this treated as a 400 error
+def custom_400_error(error)
+  pass_to_error_handler(error, 400)
+end
+```
+
+`pass_to_error_handler` takes a Ruby Exception object and an optional status code. If no status code is provided, it will default to 500.
+
+## Available Errors
+
+You can raise the following HTTP errors. All of them accept an optional string that is passed to the user instead of the generic message (eg. "Invalid token" instead of "Unauthorized"):
+
+* Exceptionally::BadRequest
+* Exceptionally::Unauthorized
+* Exceptionally::PaymentRequired
+* Exceptionally::Forbidden
+* Exceptionally::NotFound
+* Exceptionally::NotAllowed
+* Exceptionally::NotAcceptable
+* Exceptionally::ProxyAuthRequired
+* Exceptionally::Timeout
+* Exceptionally::Conflict
+* Exceptionally::Gone
+* Exceptionally::LengthRequired
+* Exceptionally::PreconditionFailed
+* Exceptionally::TooLarge
+* Exceptionally::TooLong
+* Exceptionally::UnsupportedMedia
+* Exceptionally::RangeNotSatisfiable
+* Exceptionally::ExpectationFailed
+* Exceptionally::Error
+* Exceptionally::NotImplemented
+* Exceptionally::BadGateway
+* Exceptionally::ServiceUnavailable
+* Exceptionally::GatewayTimeout
+* Exceptionally::HttpVersionNotSupported
+
+You can also raise an error with just the HTTP status code by using `Exceptionally::Http404`. Status codes 400-417 and 500-505 are available.
+
+**[See descriptions of all status codes](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html)**
+
+## Why use Exceptionally instead of the built-in Rails `render`?
+
+By abstracting all of the exception handling logic, Exceptionally DRY's up your code and makes it easier to read. If you later decide to change the format of your error responses, you just need to edit `render_error` in one place. Exceptionally also transparently handles ActiveRecord, Apipie, and other generic exceptions for you, so that your app is less likely to crash. Additionally, you get a bunch of logging and error reporting functionality for free.
+
+## Author
+
+Neil Gupta [http://metamorphium.com](http://metamorphium.com)
+
+## License
+
+The MIT License (MIT) Copyright (c) 2014 Neil Gupta. See [MIT-LICENSE](https://raw.github.com/neilgupta/exceptionally/master/MIT-LICENSE)

data/Rakefile

@@ -0,0 +1,32 @@
+begin
+  require 'bundler/setup'
+rescue LoadError
+  puts 'You must `gem install bundler` and `bundle install` to run rake tasks'
+end
+
+require 'rdoc/task'
+
+RDoc::Task.new(:rdoc) do |rdoc|
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title    = 'Exceptionally'
+  rdoc.options << '--line-numbers'
+  rdoc.rdoc_files.include('README.rdoc')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end
+
+
+
+
+Bundler::GemHelper.install_tasks
+
+require 'rake/testtask'
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << 'lib'
+  t.libs << 'test'
+  t.pattern = 'test/**/*_test.rb'
+  t.verbose = false
+end
+
+
+task default: :test

data/lib/exceptionally/controller.rb

@@ -0,0 +1,50 @@
+require "active_record/validations.rb"
+
+module Exceptionally
+  module Controller
+    extend ActiveSupport::Concern
+
+    included do
+      rescue_from Exception, :with => :exceptionally_handler
+      rescue_from ArgumentError, :with => :exceptionally_handler
+      rescue_from Exceptionally::Error, :with => :exceptionally_handler
+      rescue_from ActiveRecord::RecordNotFound, :with => :missing_record_handler
+      rescue_from ActiveRecord::RecordInvalid, :with => :record_invalid_handler
+      if defined?(Apipie)
+        rescue_from Apipie::ParamMissing, :with => :missing_param
+        rescue_from Apipie::ParamInvalid, :with => :missing_param
+      end
+    end
+
+    # Raise custom error
+    def exceptionally_handler(error)
+      pass_to_error_handler(error)
+    end
+
+    # Raise 400 error
+    def missing_param(error)
+      pass_to_error_handler(error, 400)
+    end
+
+    # Raise 404 error
+    def missing_record_handler(error)
+      pass_to_error_handler(error, 404)
+    end
+
+    # Raise 409 error
+    def record_invalid_handler(error)
+      pass_to_error_handler(error, 409)
+    end
+
+    def pass_to_error_handler(error, status = nil)
+      status ||= error.try(:status) || 500
+      Exceptionally::Handler.new(error.message, status, error, params)
+      render_error(error.message, status)
+    end
+
+    def render_error(message, status)
+      render json: {error: message}, status: status
+    end
+
+  end
+end

data/lib/exceptionally/exceptions.rb

@@ -0,0 +1,182 @@
+module Exceptionally
+  class Error < StandardError
+    attr_reader :status
+
+    def initialize(message = nil, status = nil, default = nil)
+      @message = message
+      @status = status || 500
+      @default = default || "Internal Server Error"
+    end
+
+    def message
+      @message || @default
+    end
+
+    def to_s
+      "#{@status} #{@default}#{@message ? ": #{@message}" : ''}"
+    end
+  end
+
+  class BadRequest < Error
+    def initialize(message = nil)
+      super(message, 400, "Bad Request")
+    end
+  end
+
+  class Unauthorized < Error
+    def initialize(message = nil)
+      super(message, 401, "Unauthorized")
+    end
+  end
+
+  class PaymentRequired < Error
+    def initialize(message = nil)
+      super(message, 402, "Payment Required")
+    end
+  end
+
+  class Forbidden < Error
+    def initialize(message = nil)
+      super(message, 403, "Forbidden")
+    end
+  end
+
+  class NotFound < Error
+    def initialize(message = nil)
+      super(message, 404, "Not Found")
+    end
+  end
+
+  class NotAllowed < Error
+    def initialize(message = nil)
+      super(message, 405, "Method Not Allowed")
+    end
+  end
+
+  class NotAcceptable < Error
+    def initialize(message = nil)
+      super(message, 406, "Not Acceptable")
+    end
+  end
+
+  class ProxyAuthRequired < Error
+    def initialize(message = nil)
+      super(message, 407, "Proxy Authentication Required")
+    end
+  end
+
+  class Timeout < Error
+    def initialize(message = nil)
+      super(message, 408, "Request Timeout")
+    end
+  end
+
+  class Conflict < Error
+    def initialize(message = nil)
+      super(message, 409, "Conflict")
+    end
+  end
+
+  class Gone < Error
+    def initialize(message = nil)
+      super(message, 410, "Gone")
+    end
+  end
+
+  class LengthRequired < Error
+    def initialize(message = nil)
+      super(message, 411, "Length Required")
+    end
+  end
+
+  class PreconditionFailed < Error
+    def initialize(message = nil)
+      super(message, 412, "Precondition Failed")
+    end
+  end
+
+  class TooLarge < Error
+    def initialize(message = nil)
+      super(message, 413, "Request Entity Too Large")
+    end
+  end
+
+  class TooLong < Error
+    def initialize(message = nil)
+      super(message, 414, "Request-URI Too Long")
+    end
+  end
+
+  class UnsupportedMedia < Error
+    def initialize(message = nil)
+      super(message, 415, "Unsupported Media Type")
+    end
+  end
+
+  class RangeNotSatisfiable < Error
+    def initialize(message = nil)
+      super(message, 416, "Requested Range Not Satisfiable")
+    end
+  end
+
+  class ExpectationFailed < Error
+    def initialize(message = nil)
+      super(message, 417, "Expectation Failed")
+    end
+  end
+
+  class NotImplemented < Error
+    def initialize(message = nil)
+      super(message, 501, "Not Implemented")
+    end
+  end
+
+  class BadGateway < Error
+    def initialize(message = nil)
+      super(message, 502, "Bad Gateway")
+    end
+  end
+
+  class ServiceUnavailable < Error
+    def initialize(message = nil)
+      super(message, 503, "Service Unavailable")
+    end
+  end
+
+  class GatewayTimeout < Error
+    def initialize(message = nil)
+      super(message, 504, "Gateway Timeout")
+    end
+  end
+
+  class HttpVersionNotSupported < Error
+    def initialize(message = nil)
+      super(message, 505, "HTTP Version Not Supported")
+    end
+  end
+
+  class Http400 < BadRequest; end
+  class Http401 < Unauthorized; end
+  class Http402 < PaymentRequired; end
+  class Http403 < Forbidden; end
+  class Http404 < NotFound; end
+  class Http405 < NotAllowed; end
+  class Http406 < NotAcceptable; end
+  class Http407 < ProxyAuthRequired; end
+  class Http408 < Timeout; end
+  class Http409 < Conflict; end
+  class Http410 < Gone; end
+  class Http411 < LengthRequired; end
+  class Http412 < PreconditionFailed; end
+  class Http413 < TooLarge; end
+  class Http414 < TooLong; end
+  class Http415 < UnsupportedMedia; end
+  class Http416 < RangeNotSatisfiable; end
+  class Http417 < ExpectationFailed; end
+  class Http500 < Error; end
+  class Http501 < NotImplemented; end
+  class Http502 < BadGateway; end
+  class Http503 < ServiceUnavailable; end
+  class Http504 < GatewayTimeout; end
+  class Http505 < HttpVersionNotSupported; end
+end

data/lib/exceptionally/handler.rb

@@ -0,0 +1,30 @@
+module Exceptionally
+  class Handler
+    def initialize(message = nil, status = nil, e = nil, params = nil)
+      @message = message
+      @status = status || 500
+      @error = e
+      @params = params || {}
+
+      @@callback.call(@message, @status, @error, @params) if defined?(@@callback) && @@callback.respond_to?(:call)
+      log
+    end
+
+    def self.before_render(&block)
+      @@callback = Proc.new(&block)
+    end
+
+    def log
+      # Log 5xx errors
+      if @status >= 500 && @error
+        # Support Airbrake and New Relic out of box
+        Airbrake.notify(@error, :parameters => @params) if defined?(Airbrake) && Airbrake.respond_to?(:notify) && Rails.env.production?
+        NewRelic::Agent.notice_error(@error) if defined?(NewRelic) && defined?(NewRelic::Agent) && NewRelic::Agent.respond_to?(:notice_error) && Rails.env.production?
+
+        Rails.logger.error(@error.to_s)
+        Rails.logger.error("Parameters: #{@params.to_s}") unless @params.blank?
+        Rails.logger.error(@error.backtrace.join("\n")) unless @error.backtrace.blank?
+      end
+    end
+  end  
+end

data/lib/exceptionally/railtie.rb

@@ -0,0 +1,9 @@
+module Exceptionally
+  class Railtie < Rails::Railtie
+    initializer "exceptionally.action_controller" do
+      ActiveSupport.on_load(:action_controller) do
+        include Exceptionally::Controller
+      end
+    end
+  end
+end

data/lib/exceptionally/version.rb

@@ -0,0 +1,3 @@
+module Exceptionally
+  VERSION = "1.0.0"
+end

data/lib/exceptionally.rb

@@ -0,0 +1,7 @@
+require 'exceptionally/controller'
+require 'exceptionally/exceptions'
+require 'exceptionally/handler'
+require 'exceptionally/railtie'
+
+module Exceptionally
+end

data/lib/tasks/exceptionally_tasks.rake

@@ -0,0 +1,4 @@
+# desc "Explaining what the task does"
+# task :exceptionally do
+#   # Task goes here
+# end

data/test/dummy/README.rdoc

@@ -0,0 +1,28 @@
+== README
+
+This README would normally document whatever steps are necessary to get the
+application up and running.
+
+Things you may want to cover:
+
+* Ruby version
+
+* System dependencies
+
+* Configuration
+
+* Database creation
+
+* Database initialization
+
+* How to run the test suite
+
+* Services (job queues, cache servers, search engines, etc.)
+
+* Deployment instructions
+
+* ...
+
+
+Please feel free to use a different markup language if you do not plan to run
+<tt>rake doc:app</tt>.

data/test/dummy/Rakefile

@@ -0,0 +1,6 @@
+# Add your own tasks in files placed in lib/tasks ending in .rake,
+# for example lib/tasks/capistrano.rake, and they will automatically be available to Rake.
+
+require File.expand_path('../config/application', __FILE__)
+
+Dummy::Application.load_tasks

data/test/dummy/app/assets/javascripts/application.js

@@ -0,0 +1,13 @@
+// This is a manifest file that'll be compiled into application.js, which will include all the files
+// listed below.
+//
+// Any JavaScript/Coffee file within this directory, lib/assets/javascripts, vendor/assets/javascripts,
+// or vendor/assets/javascripts of plugins, if any, can be referenced here using a relative path.
+//
+// It's not advisable to add code directly here, but if you do, it'll appear at the bottom of the
+// compiled file.
+//
+// Read Sprockets README (https://github.com/sstephenson/sprockets#sprockets-directives) for details
+// about supported directives.
+//
+//= require_tree .

data/test/dummy/app/assets/stylesheets/application.css

@@ -0,0 +1,13 @@
+/*
+ * This is a manifest file that'll be compiled into application.css, which will include all the files
+ * listed below.
+ *
+ * Any CSS and SCSS file within this directory, lib/assets/stylesheets, vendor/assets/stylesheets,
+ * or vendor/assets/stylesheets of plugins, if any, can be referenced here using a relative path.
+ *
+ * You're free to add application-wide styles to this file and they'll appear at the top of the
+ * compiled file, but it's generally better to create a new file per style scope.
+ *
+ *= require_self
+ *= require_tree .
+ */

data/test/dummy/app/controllers/application_controller.rb

@@ -0,0 +1,5 @@
+class ApplicationController < ActionController::Base
+  # Prevent CSRF attacks by raising an exception.
+  # For APIs, you may want to use :null_session instead.
+  protect_from_forgery with: :exception
+end

data/test/dummy/app/helpers/application_helper.rb

@@ -0,0 +1,2 @@
+module ApplicationHelper
+end

data/test/dummy/app/views/layouts/application.html.erb

@@ -0,0 +1,14 @@
+<!DOCTYPE html>
+<html>
+<head>
+  <title>Dummy</title>
+  <%= stylesheet_link_tag    "application", media: "all", "data-turbolinks-track" => true %>
+  <%= javascript_include_tag "application", "data-turbolinks-track" => true %>
+  <%= csrf_meta_tags %>
+</head>
+<body>
+
+<%= yield %>
+
+</body>
+</html>

data/test/dummy/bin/bundle

@@ -0,0 +1,3 @@
+#!/usr/bin/env ruby
+ENV['BUNDLE_GEMFILE'] ||= File.expand_path('../../Gemfile', __FILE__)
+load Gem.bin_path('bundler', 'bundle')

data/test/dummy/bin/rails

@@ -0,0 +1,4 @@
+#!/usr/bin/env ruby
+APP_PATH = File.expand_path('../../config/application',  __FILE__)
+require_relative '../config/boot'
+require 'rails/commands'

data/test/dummy/bin/rake

@@ -0,0 +1,4 @@
+#!/usr/bin/env ruby
+require_relative '../config/boot'
+require 'rake'
+Rake.application.run

data/test/dummy/config/application.rb

@@ -0,0 +1,23 @@
+require File.expand_path('../boot', __FILE__)
+
+require 'rails/all'
+
+Bundler.require(*Rails.groups)
+require "exceptionally"
+
+module Dummy
+  class Application < Rails::Application
+    # Settings in config/environments/* take precedence over those specified here.
+    # Application configuration should go into files in config/initializers
+    # -- all .rb files in that directory are automatically loaded.
+
+    # Set Time.zone default to the specified zone and make Active Record auto-convert to this zone.
+    # Run "rake -D time" for a list of tasks for finding time zone names. Default is UTC.
+    # config.time_zone = 'Central Time (US & Canada)'
+
+    # The default locale is :en and all translations from config/locales/*.rb,yml are auto loaded.
+    # config.i18n.load_path += Dir[Rails.root.join('my', 'locales', '*.{rb,yml}').to_s]
+    # config.i18n.default_locale = :de
+  end
+end
+

data/test/dummy/config/boot.rb

@@ -0,0 +1,5 @@
+# Set up gems listed in the Gemfile.
+ENV['BUNDLE_GEMFILE'] ||= File.expand_path('../../../../Gemfile', __FILE__)
+
+require 'bundler/setup' if File.exists?(ENV['BUNDLE_GEMFILE'])
+$LOAD_PATH.unshift File.expand_path('../../../../lib', __FILE__)

data/test/dummy/config/database.yml

@@ -0,0 +1,25 @@
+# SQLite version 3.x
+#   gem install sqlite3
+#
+#   Ensure the SQLite 3 gem is defined in your Gemfile
+#   gem 'sqlite3'
+development:
+  adapter: sqlite3
+  database: db/development.sqlite3
+  pool: 5
+  timeout: 5000
+
+# Warning: The database defined as "test" will be erased and
+# re-generated from your development database when you run "rake".
+# Do not set this db to the same as development or production.
+test:
+  adapter: sqlite3
+  database: db/test.sqlite3
+  pool: 5
+  timeout: 5000
+
+production:
+  adapter: sqlite3
+  database: db/production.sqlite3
+  pool: 5
+  timeout: 5000

data/test/dummy/config/environment.rb

@@ -0,0 +1,5 @@
+# Load the Rails application.
+require File.expand_path('../application', __FILE__)
+
+# Initialize the Rails application.
+Dummy::Application.initialize!