rescue_registry 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 528eb94a1296262f6cb1d20d7b8209072147c72e392dabb468fdbb0d2e4d9f43
+  data.tar.gz: 296ea4a7f1a08fa3fbd981c1ec08e35e528befc17b4167a51b5cdcd480783229
+SHA512:
+  metadata.gz: 076d737ba7c477015a3b984e34d2c3782b56688d039db35b27d9cf8d89b682755e1a01c0cae34996ab63ed1fdf2a6e20c8b945d8f1b84c1a5a196f002b060b6c
+  data.tar.gz: 46c7d35672ecb8d4f04b5d2cad6f4d9844ef3d6d5600c6ba2eaa090a638c2bce77f180163523c5bda7ca646db6355f172ce70da996bc9fbc5b9f6d9b4bcf7191

data/CHANGELOG.md

@@ -0,0 +1,10 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+---
+
+No releases means no changes...

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright 2019 Peter Wagenet
+
+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,75 @@
+# RescueRegistry
+
+RescueRegistry improves error handling with Rails while still hewing as close to the defaults as possible.
+
+
+
+## Features
+
+### Better than `rescue_from`
+`rescue_from` works fine, but it it's a big hammer. Using it completely bypasses Rail's built-in exception handling middlewares,
+which actually do some nice things for us (e.g. automatically handling different data formats). RescueRegistry allows the built-in
+middleware to handle the exceptions but with our custom handlers.
+
+### Better default exception handling
+Rails also has some built-in support for assigning different exception classes to status types (See `config.action_dispatch.rescue_responses`).
+Unfortunately, all this allows you to do is assign a status code. If you want more complex error handling, or to use different codes in
+different controllers, you're out of luck. With RescueRegistry you can register and exception with a custom handler or with different status
+codes in different controllers.
+
+## In Action
+
+### graphiti-rails
+The [graphiti-rails gem](https://github.com/wagenet/graphiti-rails) uses RescueRegistry to facilitate better JSON:API error handling, since
+Rails' out-of-the-box behavior doesn't adhere to the JSON:API spec.
+
+## Usage
+
+Example usages:
+
+```ruby
+class MyController < ActionController::Base
+  class CustomStatusError < StandardError; end
+  class CustomTitleError < StandardError; end
+  class DetailExceptionError < StandardError; end
+  class DetailProcError < StandardError; end
+  class DetailStringError < StandardError; end
+  class MetaProcError < StandardError; end
+  class LogFalseError < StandardError; end
+  class CustomHandlerError < StandardError; end
+  class RailsError < StandardError; end
+  class SubclassedError < CustomStatusError; end
+
+  class CustomErrorHandler < RescueRegistry::ExceptionHandler
+    def self.default_status
+      302
+    end
+
+    def title
+      "Custom Title"
+    end
+  end
+
+  register_exception CustomStatusError, status: 401
+  register_exception CustomTitleError, title: "My Title"
+  register_exception DetailExceptionError, detail: :exception
+  register_exception DetailProcError, detail: -> (e) { e.class.name.upcase }
+  register_exception DetailStringError, detail: "Custom Detail"
+  register_exception MetaProcError, meta: -> (e) { { class_name: e.class.name.upcase } }
+  register_exception CustomHandlerError, handler: CustomErrorHandler
+  register_exception RailsError, status: 403, handler: RescueRegistry::RailsExceptionHandler
+end
+```
+
+## Installation
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'rescue_registry'
+```
+
+## Contributing
+We'd love to have your help improving rescue_registry, send a PR!
+
+## License
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,20 @@
+begin
+  require 'bundler/setup'
+rescue LoadError
+  puts 'You must `gem install bundler` and `bundle install` to run rake tasks'
+end
+
+require 'yard'
+require 'rspec/core/rake_task'
+require 'bundler/gem_tasks'
+
+YARD::Rake::YardocTask.new
+
+RSpec::Core::RakeTask.new(:spec) do |t|
+  t.rspec_opts = "--order random"
+end
+
+APP_RAKEFILE = File.expand_path("spec/dummy/Rakefile", __dir__)
+load "rails/tasks/engine.rake"
+
+task default: :spec

data/lib/rescue_registry.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+require 'active_support'
+
+module RescueRegistry
+  autoload :Controller,            "rescue_registry/controller"
+  autoload :ExceptionsApp,         "rescue_registry/exceptions_app"
+  autoload :ExceptionHandler,      "rescue_registry/exception_handler"
+  autoload :RailsExceptionHandler, "rescue_registry/exception_handler"
+  autoload :Registry,              "rescue_registry/registry"
+
+  class HandlerNotFound < StandardError; end
+
+  def self.context
+    Thread.current[:rescue_registry_context]
+  end
+
+  def self.context=(value)
+    Thread.current[:rescue_registry_context] = value
+  end
+
+  def self.with_context(value)
+    original = context
+    self.context = value
+    yield
+  ensure
+    self.context = original
+  end
+
+  REGISTRY_METHODS = %i[
+    handler_for_exception
+    handles_exception?
+    status_code_for_exception
+    response_for_debugging
+    response_for_public
+  ]
+
+  REGISTRY_METHODS.each do |method|
+    define_singleton_method(method) do |*args|
+      return unless context.respond_to?(:rescue_registry)
+      context.rescue_registry.public_send(method, *args)
+    end
+  end
+end
+
+ActiveSupport.on_load(:action_controller) do
+  include RescueRegistry::Controller
+end
+
+require 'rescue_registry/action_dispatch'
+require 'rescue_registry/railtie'

data/lib/rescue_registry/action_dispatch.rb

@@ -0,0 +1,71 @@
+require 'action_dispatch'
+
+ActionDispatch::ExceptionWrapper.class_eval do
+  class << self
+    alias_method :status_code_for_exception_without_rescue_registry, :status_code_for_exception
+    def status_code_for_exception(class_name)
+      RescueRegistry.status_code_for_exception(class_name) ||
+        status_code_for_exception_without_rescue_registry(class_name)
+    end
+  end
+end
+
+# Since this is for debugging only it's less critical to make changes here. The main area that matters is
+# returning the correct status code. Since all this code relies upon the ExceptionWrapper which we've monkeypatched,
+# it should work correctly without changes. However, we can provide more details in some areas so we hook in for that.
+ActionDispatch::DebugExceptions.class_eval do
+  private
+
+  # `#log_error`
+  # TODO: We may be able to add more information, though the details remain to be determined
+
+  # `#render_for_browser_request`
+  # TODO: We may be able to add more information, though the details remain to be determined
+
+  # This would work without changes, but the formatting would be incorrect. Since it's for debugging only,
+  # we could choose to ignore it, but the detailed information would definitely be useful.
+  alias_method :render_for_api_request_without_rescue_registry, :render_for_api_request
+  def render_for_api_request(content_type, wrapper)
+    response = nil
+
+    if RescueRegistry.handles_exception?(wrapper.exception)
+      # Ideally `render_for_api_request` would be split up so we could avoid some duplication in RescueRegistry
+      begin
+        response = RescueRegistry.response_for_debugging(content_type, wrapper.exception, traces: wrapper.traces)
+      rescue Exception => e
+        # Replace the original exception (still available via `cause`) and let it get handled with default handlers
+        wrapper = ActionDispatch::ExceptionWrapper.new(wrapper.backtrace_cleaner, e)
+      end
+    end
+
+    if response
+      render(*response)
+    else
+      # One of the following is true:
+      # - No handler for the exception
+      # - No response for content_type
+      # - An exception while generating the response
+      # In any case, we go with the default here.
+      render_for_api_request_without_rescue_registry(content_type, wrapper)
+    end
+  end
+end
+
+ActionDispatch::ShowExceptions.class_eval do
+  # @private
+  alias_method :initialize_without_rescue_registry, :initialize
+
+  # @private
+  def initialize(*args)
+    initialize_without_rescue_registry(*args)
+    @exceptions_app = RescueRegistry::ExceptionsApp.new(@exceptions_app)
+  end
+
+  alias_method :call_without_rescue_registry, :call
+  def call(*args)
+    warn "Didn't expect RescueRegistry context to be set in middleware" if RescueRegistry.context
+    call_without_rescue_registry(*args)
+  ensure
+    RescueRegistry.context = nil
+  end
+end

data/lib/rescue_registry/controller.rb

@@ -0,0 +1,48 @@
+module RescueRegistry
+  module Controller
+    extend ActiveSupport::Concern
+
+    included do
+      cattr_accessor :rescue_registry
+      self.rescue_registry = Registry.new(self)
+
+      class << self
+        delegate :register_exception, to: :rescue_registry
+      end
+    end
+
+    def rescue_registry
+      self.class.rescue_registry
+    end
+
+    def process_action(*args)
+      if RescueRegistry.context
+        # Controller logger isn't yet available
+        Rails.logger.warn "Didn't expect RescueRegistry context to be set in controller"
+        Rails.logger.debug caller.join("\n")
+      end
+
+      # Setting something globally is not very nice, but it allows us to access it without
+      # having to change a whole lot of internal Rails APIs. This especially matters when
+      # getting the status code via ExceptionWrapper.
+      # We don't unset here so that it is available to middleware
+      # Unsetting happens in ActionDispatch::ShowExceptions. This _should_ be ok since we shouldn't
+      # be processing multiple requests in the same thread.
+      RescueRegistry.context = self
+
+      super
+    end
+
+    class_methods do
+      def inherited(subklass)
+        super
+        subklass.rescue_registry = rescue_registry.dup
+        subklass.rescue_registry.owner = subklass
+      end
+
+      def default_exception_handler
+        ExceptionHandler
+      end
+    end
+  end
+end

data/lib/rescue_registry/exception_handler.rb

@@ -0,0 +1,148 @@
+module RescueRegistry
+  class ExceptionHandler
+    def self.default_status
+      500
+    end
+
+    # Use a glob for options so that unknown values won't throw errors. Also, this list could get long...
+    def initialize(exception, **options)
+      @exception = exception
+
+      status = options[:status]
+      if status == :passthrough
+        status = ActionDispatch::ExceptionWrapper.status_code_for_exception_without_rescue_registry(exception.class.name)
+      end
+      @status = status
+
+      @title = options[:title]
+
+      @detail = options[:detail]
+      if options[:message] && @detail.nil?
+        # Deprecated, from GraphitiErrors
+        @detail = (options[:message] == true) ? :exception : options[:message]
+      end
+
+      @meta = options[:meta]
+
+      # TODO: Warn about unrecognized options
+    end
+
+    attr_reader :exception, :status
+    alias_method :status_code, :status
+
+    def error_code
+      error_code_from_status
+    end
+
+    def title
+      @title || title_from_status
+    end
+
+    def detail
+      detail =
+        case @detail
+        when :exception
+          exception.message
+        when Proc
+          @detail.call(exception)
+        else
+          @detail.try(:to_s)
+        end
+
+      detail.presence || default_detail_for_status
+    end
+
+    def meta
+      if @meta.is_a?(Proc)
+        @meta.call(exception)
+      else
+        { }
+      end
+    end
+
+    def build_payload(show_details: false, traces: nil)
+      payload_meta = meta
+
+      if show_details
+        payload_meta = payload_meta.merge(
+          __details__: {
+            exception: exception.inspect,
+            traces: traces || [exception.backtrace]
+          }
+        )
+      end
+
+      {
+        errors: [
+          code: error_code,
+          status: status_code.to_s,
+          title: title,
+          detail: detail,
+          meta: payload_meta
+        ]
+      }
+    end
+
+    def formatted_response(content_type, fallback: :json, **options)
+      body = build_payload(**options)
+
+      # TODO: Maybe make a helper to register these types?
+      to_format = content_type == :jsonapi ? "to_json" : "to_#{content_type.to_sym}"
+
+      if content_type && body.respond_to?(to_format)
+        formatted_body = body.public_send(to_format)
+        format = content_type
+      else
+        if fallback == :json
+          formatted_body = body.to_json
+          format = Mime[:json]
+        elsif fallback == :none
+          return nil
+        else
+          raise ArgumentError, "unknown fallback=#{fallback}"
+        end
+      end
+
+      [status_code, formatted_body, format]
+    end
+
+    private
+
+    def error_code_from_status
+      code_to_symbol = Rack::Utils::SYMBOL_TO_STATUS_CODE.invert
+      code_to_symbol.fetch(status_code, code_to_symbol[500])
+    end
+
+    def title_from_status
+      Rack::Utils::HTTP_STATUS_CODES.fetch(
+        status_code,
+        Rack::Utils::HTTP_STATUS_CODES[500]
+      )
+    end
+
+    def default_detail_for_status
+      if status_code >= 500
+        "We've notified our engineers and hope to address this issue shortly."
+      end
+    end
+  end
+
+  # Builds a payload in the style of the Rails default handling for compatibility
+  class RailsExceptionHandler < ExceptionHandler
+    def build_payload(show_details: false, traces: nil)
+      body = {
+        status: status_code,
+        error:  title
+      }
+
+      if show_details
+        body[:exception] = exception.inspect
+        if traces
+          body[:traces] = traces
+        end
+      end
+
+      body
+    end
+  end
+end

data/lib/rescue_registry/exceptions_app.rb

@@ -0,0 +1,36 @@
+module RescueRegistry
+  class ExceptionsApp
+    def initialize(app)
+      @app = app
+    end
+
+    def call(env)
+      request = ActionDispatch::Request.new(env)
+      exception = request.get_header "action_dispatch.exception"
+
+      if RescueRegistry.handles_exception?(exception)
+        begin
+          content_type = request.formats.first
+        rescue Mime::Type::InvalidMimeType
+          content_type = Mime[:text]
+        end
+
+        if (response = RescueRegistry.response_for_public(content_type, exception))
+          status, body, format = response
+
+          if request.path_info != "/#{status}"
+            warn "status mismatch; path_info=#{request.path_info}; status=#{status}"
+          end
+
+          [status, { "Content-Type" => "#{format}; charset=#{ActionDispatch::Response.default_charset}",
+            "Content-Length" => body.bytesize.to_s }, [body]]
+        else
+          # If we have no response, it means we couldn't render for the content_type, use the default handler instead
+          @app.call(env)
+        end
+      else
+        @app.call(env)
+      end
+    end
+  end
+end

data/lib/rescue_registry/railtie.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require 'rails/railtie'
+
+module RescueRegistry
+  class Railtie < Rails::Railtie
+  end
+end

data/lib/rescue_registry/registry.rb

@@ -0,0 +1,100 @@
+module RescueRegistry
+  class Registry
+    attr_accessor :owner
+
+    def initialize(owner)
+      @owner = self
+      @handlers = { }
+    end
+
+    def initialize_dup(_other)
+      @handlers = @handlers.dup
+    end
+
+    # TODO: Support a shorthand for handler
+    def register_exception(exception_class, handler: nil, **options)
+      raise ArgumentError, "#{exception_class} is not an Exception" unless exception_class <= Exception
+
+      handler ||= owner.try(:default_exception_handler)
+      raise ArgumentError, "handler must be provided" unless handler
+
+      status = options[:status] ||= handler.default_status
+      raise ArgumentError, "status must be provided" unless status
+      raise ArgumentError, "invalid status: #{status}" unless status.is_a?(Integer) || status == :passthrough
+
+      # TODO: Validate options here
+
+      # We assign the status here as a default when looking up by class (and not instance)
+      @handlers[exception_class] = [handler, options]
+    end
+
+    def handler_for_exception(exception)
+      handler_info = handler_info_for_exception(exception)
+      raise HandlerNotFound, "no handler found for #{exception.class}" unless handler_info
+
+      handler_class, handler_options = handler_info
+      handler_class.new(exception, **handler_options)
+    end
+
+    def handles_exception?(exception)
+      handler_info_for_exception(exception).present?
+    end
+
+    def status_code_for_exception(exception)
+      _, options = handler_info_for_exception(exception)
+      return unless options
+
+      # Return no code for passthrough.
+      # Alternatively we could handle this explicitly in the ExceptionWrapper monkeypatch.
+      options[:status] == :passthrough ? nil : options[:status]
+    end
+
+    def build_response(content_type, exception, **options)
+      handler = handler_for_exception(exception)
+      handler.formatted_response(content_type, **options)
+    end
+
+    def response_for_debugging(content_type, exception, traces: nil)
+      build_response(content_type, exception, show_details: true, traces: traces)
+    end
+
+    def response_for_public(content_type, exception)
+      build_response(content_type, exception, fallback: :none)
+    end
+
+    private
+
+    def handler_info_for_exception(exception)
+      exception_class =
+        case exception
+        when String
+          exception.safe_constantize
+        when Class
+          exception
+        else
+          exception.class
+        end
+
+      return unless exception_class
+
+      raise ArgumentError, "#{exception_class} is not an Exception" unless exception_class <= Exception
+
+      # Reverse so most recently defined takes precedence
+      registry = @handlers.to_a.reverse
+
+      # Look for an exact class, then for the superclass and so on.
+      # There might be a more efficient way to do this, but this is pretty readable
+      match_class = exception_class
+      loop do
+        if (found = registry.find { |(klass, _)| klass == match_class })
+          return found.last
+        elsif match_class == Exception
+          # We've exhausted our options
+          return nil
+        end
+
+        match_class = match_class.superclass
+      end
+    end
+  end
+end

data/lib/rescue_registry/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module RescueRegistry
+  VERSION = "0.1.0"
+end

data/lib/tasks/rescue_registry_tasks.rake

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

metadata

@@ -0,0 +1,163 @@
+--- !ruby/object:Gem::Specification
+name: rescue_registry
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Peter Wagenet
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2019-05-15 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '5.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '7.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '5.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '7.0'
+- !ruby/object:Gem::Dependency
+  name: appraisal
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.2'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.2'
+- !ruby/object:Gem::Dependency
+  name: kramdown-parser-gfm
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+- !ruby/object:Gem::Dependency
+  name: rouge
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.3'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.3'
+- !ruby/object:Gem::Dependency
+  name: rspec-rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.8'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.8'
+- !ruby/object:Gem::Dependency
+  name: sqlite3
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.3'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.3'
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+description: 
+email:
+- peter.wagenet@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- MIT-LICENSE
+- README.md
+- Rakefile
+- lib/rescue_registry.rb
+- lib/rescue_registry/action_dispatch.rb
+- lib/rescue_registry/controller.rb
+- lib/rescue_registry/exception_handler.rb
+- lib/rescue_registry/exceptions_app.rb
+- lib/rescue_registry/railtie.rb
+- lib/rescue_registry/registry.rb
+- lib/rescue_registry/version.rb
+- lib/tasks/rescue_registry_tasks.rake
+homepage: https://github.com/wagenet/rescue_registry
+licenses:
+- MIT
+metadata:
+  bug_tracker_uri: https://github.com/wagenet/rescue_registry/issues
+  changelog_uri: https://github.com/wagenet/rescue_registry/CHANGELOG.md
+  source_code_uri: https://github.com/wagenet/rescue_registry
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - "~>"
+    - !ruby/object:Gem::Version
+      version: '2.4'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.0.3
+signing_key: 
+specification_version: 4
+summary: Registry for Rails Exceptions
+test_files: []