temescal 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 668a0e9c9bb3d5400a4b9b28302607767828bc0c
+  data.tar.gz: 1f1a62d3e48d5db8cd32b853a06ea116be8a3b69
+SHA512:
+  metadata.gz: 614f71816ca80c27852abe47a8aef37702fc8eced6143613ed25735dd1bc3bc051a7e9d4f4dd1eefb1709aedc6537191354abaab13a837cc57bbc70469f91564
+  data.tar.gz: 1bf5f51abe2f31d8e2cd7b8595f97c4d6a86083f99d34f1d800e7e96495de41bae2017b62ec1bb6b7f1ced4a8ccf4fd04062b7c7ea7edde87484a2fd3c0799e9

data/LICENSE

@@ -0,0 +1,20 @@
+The MIT License (MIT)
+
+Copyright (c) 2013-2014 Todd Bealmear
+
+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,53 @@
+temescal
+========
+
+[![Build Status](https://travis-ci.org/todd/temescal.png?branch=master)](https://travis-ci.org/todd/temescal) [![Coverage Status](https://coveralls.io/repos/todd/temescal/badge.png?branch=master)](https://coveralls.io/r/todd/temescal?branch=master) [![Code Climate](https://codeclimate.com/github/todd/temescal.png)](https://codeclimate.com/github/todd/temescal) [![Dependency Status](https://gemnasium.com/todd/temescal.png)](https://gemnasium.com/todd/temescal)
+
+Temescal is Rack middleware that will automatically rescue exceptions for JSON APIs and render a nice, clean JSON response with the error information. No need to write custom error handling logic for your apps - Temescal will take care of it for you!
+## Getting Started
+Add the gem to your Gemfile and run `bundle install`:
+```
+gem 'temescal'
+```
+Since Temescal is just Rack middleware, adding it to your application is super easy. For Rails, add an initializer:
+```ruby
+Rails.application.config.middleware.use Temescal::Middleware do |config|
+  config.monitors = :airbrake, :new_relic
+  config.default_message = "Oops! Something went kablooey!"
+end
+```
+For Sinatra:
+```ruby
+use Temescal::Middleware do |config|
+  config.monitors = :airbrake, :new_relic
+  config.default_message = "Oops! Something went kablooey!"
+end
+```
+## Default Behavior
+By default, Temescal will render a JSON response formatted as such (using StandardError with a message of "Foobar" as an example):
+```json
+{
+  meta: {
+    status: 500,
+    error: "StandardError",
+    message: "Foobar"
+  }
+}
+```
+Temescal will also log the error for you through STDERR.
+## Monitors
+Though Temescal will log an error for you, it won't necessarily be picked up by your monitoring solution of choice in a production environment. Luckily, Temescal provides integration with popular monitoring services. At the moment, only two (Airbrake, New Relic) are supported, but more will be added if there's a need. If you use a different monitoring service that you'd like to see supported, pull requests are more than welcome!
+
+Note that you'll need the gem for your monitor installed and configured for your application in order for Temescal to properly work with it.
+
+## Configuration
+Temescal provides several configuration options for you. You can set these options when configuring the middleware for your application.
+
+`monitors` to set the monitors you'd like to use with Temescal. It takes symbols of monitor names (currently `:airbrake` and `:new_relic`).
+
+`raise_errors` to set whether you'd like to override Temescal and raise all errors without rendering a Temescal response. Set to `true` to enable.
+
+`default_message` to set an all-encompasing message to use in responses instead of the exception's message. Takes a string.
+
+## License
+Copyright 2013-2014 Todd Bealmear. See LICENSE for details.

data/Rakefile

@@ -0,0 +1,5 @@
+require 'rspec/core/rake_task'
+
+RSpec::Core::RakeTask.new(:spec)
+
+task :default => :spec

data/lib/temescal.rb

@@ -0,0 +1,6 @@
+module Temescal
+  require 'temescal/configuration'
+  require 'temescal/middleware'
+  require 'temescal/monitors'
+  require 'temescal/response'
+end

data/lib/temescal/configuration.rb

@@ -0,0 +1,54 @@
+module Temescal
+  class Configuration
+
+    # Public: Getter for monitors array.
+    attr_reader :monitors
+
+    # Public: Setter for raise_errors option.
+    attr_writer :raise_errors
+
+    # Public: Getter/Setter for default JSON message.
+    attr_accessor :default_message
+
+    # Public: Initializes configuration and monitors option.
+    #
+    # Returns a new Configuration object.
+    def initialize
+      @monitors = []
+    end
+
+    # Public: Setter for monitors option.
+    #
+    # monitors - Zero or more Symbols representing monitoring services
+    #            supported by Temescal.
+    #
+    # Raises NameError if a monitor Symbol is invalid.
+    def monitors=(*monitors)
+      monitors.flatten.each do |monitor|
+        monitor = camelize_symbol(monitor)
+        @monitors << Temescal::Monitors.const_get(monitor)
+      end
+
+    rescue NameError => exception
+      strategy = exception.message.split(" ").last
+      raise NameError.new("#{strategy} is not a valid monitoring strategy")
+    end
+
+    # Public: Getter for raise_errors.
+    #
+    # Returns true if raise_errors is configured to true or the application is
+    # running in a test environment, false otherwise.
+    def raise_errors?
+      @raise_errors == true || ENV["RACK_ENV"] == "test"
+    end
+
+    private
+
+    # Private: Converts a snake cased Symbol to a camel cased String.
+    #
+    # Returns the converted String.
+    def camelize_symbol(symbol)
+      symbol.to_s.split(/_/).map { |word| word.capitalize }.join
+    end
+  end
+end

data/lib/temescal/middleware.rb

@@ -0,0 +1,55 @@
+module Temescal
+  class Middleware
+
+    # Public: Initializes the middleware.
+    #
+    # app   - The Rack application.
+    # block - Optional block for configuring the middleware.
+    #
+    # Returns an instance of the middleware.
+    def initialize(app, &block)
+      @app = app
+      yield(configuration) if block
+    end
+
+    # Public: call method for Rack application. Rescues from an exception and
+    # does the following: 1) Logs the error 2) Reports error to configured
+    # monitoring services 3) Generates a JSON response with error information.
+    #
+    # env - The environment of the request.
+    #
+    # Returns an array of response data for Rack.
+    def call(env)
+      begin
+        @status, @headers, @response = @app.call(env)
+      rescue => error
+        raise if configuration.raise_errors?
+
+        @error  = error
+        message = configuration.default_message || @error.message
+
+        $stderr.print formatted_error
+        configuration.monitors.each { |monitor| monitor.report(@error) }
+
+        @status   = @error.respond_to?(:http_status) ? @error.http_status : 500
+        @response = Response.build(@status, @error, message)
+        @headers  = { "Content-Type"   => "application/json" }
+      end
+      [@status, @headers, @response]
+    end
+
+    private
+
+    # Private: Getter for middleware configuration.
+    def configuration
+      @_configuration ||= Configuration.new
+    end
+
+    # Private: Formats the exception for logging.
+    def formatted_error
+      message = "\n#{@error.class}: #{@error.message}\n  "
+      message << @error.backtrace.join("\n  ")
+      message << "\n\n"
+    end
+  end
+end

data/lib/temescal/monitors.rb

@@ -0,0 +1,35 @@
+module Temescal
+
+  # Public: Collection of reporting strategies for different monitoring
+  # services.
+  module Monitors
+
+    # Public: Abstract strategy for monitor reporting strategies.
+    class MonitorsStrategy
+      # Raises NotImplementedError
+      def self.report(exception)
+        raise NotImplementedError
+      end
+    end
+
+    # Public: Reporting strategy for Airbrake.
+    class Airbrake < MonitorsStrategy
+      # Public: Reports an exception to Airbrake.
+      #
+      # exception - The caught exception.
+      def self.report(exception)
+        ::Airbrake.notify exception
+      end
+    end
+
+    # Public: Reporting strategy for New Relic.
+    class NewRelic < MonitorsStrategy
+      # Public: Reports an exception to New Relic.
+      #
+      # exception - The caught exception.
+      def self.report(exception)
+        ::NewRelic::Agent.notice_error exception
+      end
+    end
+  end
+end

data/lib/temescal/response.rb

@@ -0,0 +1,25 @@
+require 'json'
+
+module Temescal
+  module Response
+
+    # Public: Builds a response body for the Rack response.
+    #
+    # status    - The HTTP status code of the response.
+    # exception - The caught exception.
+    # message   - The error message.
+    #
+    # Returns an Array containing a JSON string as the response body.
+    def self.build(status, exception, message)
+      [
+        {
+          meta: {
+            status:  status,
+            error:   exception.class.to_s,
+            message: message
+          }
+        }.to_json
+      ]
+    end
+  end
+end

data/lib/temescal/version.rb

@@ -0,0 +1,3 @@
+module Temescal
+  VERSION = '0.1.0'
+end

data/spec/lib/temescal/configuration_spec.rb

@@ -0,0 +1,25 @@
+require "spec_helper"
+
+class Temescal::Monitors::Monitor;     end
+class Temescal::Monitors::FakeMonitor; end
+class Temescal::Monitors::FooMonitor;  end
+
+describe Temescal::Configuration do
+  let(:config) { Temescal::Configuration.new }
+
+  context "#monitors=" do
+    it "should add a list of valid monitor classes to the monitors array from snake-cased arguments" do
+      config.monitors = :monitor, :fake_monitor, :foo_monitor
+
+      expect(config.monitors).to eq [
+                                      Temescal::Monitors::Monitor,
+                                      Temescal::Monitors::FakeMonitor,
+                                      Temescal::Monitors::FooMonitor
+                                    ]
+    end
+
+    it "should raise an error if a monitor strategy is invalid" do
+      expect { config.monitors = :foo }.to raise_error(NameError, /Foo is not a valid monitoring strategy/)
+    end
+  end
+end

data/spec/lib/temescal/middleware_spec.rb

@@ -0,0 +1,112 @@
+require "spec_helper"
+
+describe Temescal::Middleware do
+  context "Ok response" do
+    let(:app) { ->(env) { [200, env, "app" ] } }
+
+    let(:middleware) do
+      Temescal::Middleware.new(app)
+    end
+
+    it "should render the application's response" do
+      code, _, _ = middleware.call env_for('http://foobar.com')
+
+      expect(code).to eq 200
+    end
+  end
+
+  context "Bad response" do
+    before do
+      Temescal::Monitors::NewRelic.stub(:report)
+      $stderr.stub(:print)
+
+      # Travis automatically sets RACK_ENV=test
+      # Need to override for tests to run correctly.
+      ENV["RACK_ENV"] = nil
+    end
+
+    let(:app) { ->(env) { raise StandardError.new("Foobar") } }
+
+    let(:middleware) do
+      Temescal::Middleware.new(app) do |config|
+        config.monitors = :new_relic
+      end
+    end
+
+    it "should respond with a 500 if the exception does not have a http_status attribute" do
+      code, _, _ = middleware.call env_for("http://foobar.com")
+
+      expect(code).to eq 500
+    end
+
+    it "should respond with the appropriate status if the exception has a http_status attribute" do
+      StandardError.any_instance.stub(:http_status).and_return(403)
+
+      code, _, _ = middleware.call env_for("http://foobar.com")
+
+      expect(code).to eq 403
+    end
+
+    it "should set the correct content type header" do
+      _, headers, _ = middleware.call env_for("http://foobar.com")
+
+      expect(headers["Content-Type"]).to eq "application/json"
+    end
+
+    it "should render a JSON response for the error" do
+      _, _, response = middleware.call env_for("http://foobar.com")
+
+      json = JSON.parse(response.first)["meta"]
+      expect(json["status"]).to  eq 500
+      expect(json["error"]).to   eq "StandardError"
+      expect(json["message"]).to eq "Foobar"
+    end
+
+    it "should log the error" do
+      expect($stderr).to receive(:print).with(an_instance_of String)
+
+      middleware.call env_for("http://foobar.com")
+    end
+
+    it "should report the error to the specified monitors" do
+      expect(Temescal::Monitors::NewRelic).to receive(:report).with(an_instance_of StandardError)
+
+      middleware.call env_for("http://foobar.com")
+    end
+
+    context "with default_message set" do
+      it "should build a response with the specified message instead of the exception message" do
+        middleware = Temescal::Middleware.new(app) do |config|
+          config.default_message = "An error has occured - we'll get on it right away!"
+        end
+
+        _, _, response = middleware.call env_for("http://foobar.com")
+
+        json = JSON.parse(response.first)["meta"]
+        expect(json["message"]).to eq "An error has occured - we'll get on it right away!"
+      end
+    end
+  end
+
+  context "Override middleware to raise exception" do
+    before do
+      $stderr.stub(:print)
+    end
+
+    let(:app) { ->(env) { raise StandardError.new("Foobar") } }
+
+    let(:middleware) do
+      Temescal::Middleware.new(app) do |config|
+        config.raise_errors = true
+      end
+    end
+
+    it "should raise the error" do
+      expect { middleware.call env_for("http://foobar.com") }.to raise_error StandardError
+    end
+  end
+
+  def env_for url, opts={}
+    Rack::MockRequest.env_for(url, opts)
+  end
+end

data/spec/lib/temescal/monitors_spec.rb

@@ -0,0 +1,29 @@
+require "spec_helper"
+
+describe Temescal::Monitors do
+  let(:exception) { StandardError.new }
+
+  context "MonitorsStrategy" do
+    it "should raise an error when the report method is called" do
+      expect { Temescal::Monitors::MonitorsStrategy.report(exception) }.to raise_error(NotImplementedError)
+    end
+  end
+
+  context "Airbrake" do
+    it "should send the exception to Airbrake when report is called" do
+      Airbrake.stub(:send_notice)
+
+      expect(Airbrake).to receive(:notify).with(exception)
+
+      Temescal::Monitors::Airbrake.report exception
+    end
+  end
+
+  context "NewRelic" do
+    it "should send the exception to New Relic when report is called" do
+      expect(NewRelic::Agent).to receive(:notice_error).with(exception)
+
+      Temescal::Monitors::NewRelic.report exception
+    end
+  end
+end

data/spec/spec_helper.rb

@@ -0,0 +1,29 @@
+if ENV['CI']
+  require 'coveralls'
+  Coveralls.wear!
+else
+  require 'awesome_print'
+  require 'pry-debugger'
+
+  require 'simplecov'
+  SimpleCov.start
+end
+
+require 'rack'
+
+require 'airbrake'
+require 'newrelic_rpm'
+
+require 'temescal'
+
+RSpec.configure do |config|
+  config.treat_symbols_as_metadata_keys_with_true_values = true
+  config.run_all_when_everything_filtered = true
+  config.filter_run :focus
+
+  # Run specs in random order to surface order dependencies. If you find an
+  # order dependency and want to debug it, you can fix the order by providing
+  # the seed, which is printed after each run.
+  #     --seed 1234
+  config.order = 'random'
+end

data/temescal.gemspec

@@ -0,0 +1,22 @@
+# encoding: utf-8
+
+$:.unshift File.expand_path('../lib', __FILE__)
+require 'temescal/version'
+
+Gem::Specification.new do |spec|
+  spec.add_dependency 'rack'
+  spec.add_development_dependency 'bundler'
+
+  spec.authors       = ['Todd Bealmear']
+  spec.description   = %q{Rack Middleware for gracefully handling exceptions for JSON APIs.}
+  spec.email         = ['todd@t0dd.io']
+  spec.files         = %w(LICENSE README.md Rakefile temescal.gemspec)
+  spec.files        += Dir.glob('lib/**/*.rb')
+  spec.files        += Dir.glob('spec/**/*')
+  spec.homepage      = 'https://github.com/todd/temescal'
+  spec.licenses      = ['MIT']
+  spec.name          = 'temescal'
+  spec.require_paths = ['lib']
+  spec.summary       = spec.description
+  spec.version       = Temescal::VERSION
+end

metadata

@@ -0,0 +1,86 @@
+--- !ruby/object:Gem::Specification
+name: temescal
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Todd Bealmear
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2014-01-13 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rack
+  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'
+- !ruby/object:Gem::Dependency
+  name: bundler
+  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'
+description: Rack Middleware for gracefully handling exceptions for JSON APIs.
+email:
+- todd@t0dd.io
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- Rakefile
+- temescal.gemspec
+- lib/temescal/configuration.rb
+- lib/temescal/middleware.rb
+- lib/temescal/monitors.rb
+- lib/temescal/response.rb
+- lib/temescal/version.rb
+- lib/temescal.rb
+- spec/lib/temescal/configuration_spec.rb
+- spec/lib/temescal/middleware_spec.rb
+- spec/lib/temescal/monitors_spec.rb
+- spec/spec_helper.rb
+homepage: https://github.com/todd/temescal
+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.1.10
+signing_key: 
+specification_version: 4
+summary: Rack Middleware for gracefully handling exceptions for JSON APIs.
+test_files: []