Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/neilgupta/exceptionally

Exceptionally simple Rails Exception library
https://github.com/neilgupta/exceptionally

Last synced: 19 days ago
JSON representation

Exceptionally simple Rails Exception library

Host: GitHub
URL: https://github.com/neilgupta/exceptionally
Owner: neilgupta
License: mit
Created: 2014-03-17T00:08:53.000Z (almost 11 years ago)
Default Branch: master
Last Pushed: 2023-08-31T14:27:22.000Z (over 1 year ago)
Last Synced: 2024-08-10T11:30:02.693Z (5 months ago)
Language: Ruby
Homepage: https://rubygems.org/gems/exceptionally
Size: 129 KB
Stars: 3
Watchers: 3
Forks: 2
Open Issues: 0
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: MIT-LICENSE

Awesome Lists containing this project

README

# Exceptionally

[https://www.github.com/neilgupta/exceptionally](https://www.github.com/neilgupta/exceptionally)

[![Gem Version](https://badge.fury.io/rb/exceptionally.png)](http://badge.fury.io/rb/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, backtrace, and relevant parameters to Rails.logger.

### Customizable

#### Add a custom error handler

Need to add more logging, integrate with Sentry, use [BacktraceCleaner](http://api.rubyonrails.org/classes/ActiveSupport/BacktraceCleaner.html), 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 the Exception object
# params is a hash of the parameters passed to your controller

# For example, you could:
bc = BacktraceCleaner.new
bc.add_filter { |line| line.gsub(Rails.root, '') }
bc.add_silencer { |line| line =~ /mongrel|rubygems/ }
bc.clean(error.backtrace) # will strip the Rails.root prefix and skip any lines from mongrel or rubygems from your backtrace
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(error, status)
render json: {error_message: error.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 `error`, the StandardError object that was raised, 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
* ActiveRecord::RecordNotSaved
* ActionController::ParameterMissing
* 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 SomeGem::NotAuthorizedError errors and pass them to Exceptionally
rescue_from SomeGem::NotAuthorizedError, :with => :not_authorized_error

# Tell Exceptionally you want this treated as a 401 error
def not_authorized_error(error)
pass_to_error_handler(error, 401, {caught_you: true})
end
```

`pass_to_error_handler` takes a Ruby Exception object, a status code, and an optional hash that will be returned in the json by merging it with the error message. 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::UnprocessableEntity
* 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, 422, and 500-505 are available.

**[See descriptions of all status codes](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html)**

## Why use Exceptionally?

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 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.

## Changelog

See [changelog](https://github.com/neilgupta/exceptionally/blob/master/CHANGELOG.md) to check for breaking changes between versions.

## Development

Run tests with `bundle exec rspec`

## Author

Neil Gupta [https://neil.gg](https://neil.gg)

## License