exception_transformer 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: d7ed6231e5c5ec775142f9bcbefbf8e5611491f11ca8210d97bd883a3f91f494
+  data.tar.gz: 8e676ba345439a39b6b36cf1139e2554127d4f1d8842982c115f7aa0ec85f982
+SHA512:
+  metadata.gz: 495784ad163c57718c3d7ea4891937a5e2f909fefe4d9d6c6396da0663ec160d63570999e4adfb9447ec39bb9a0112d8b9f9c9dcbfc990a6994a72cf01136ff3
+  data.tar.gz: 4e2fabcfccd2915c81ece88e93aa20b6f9eb70fc20541d3597762bcc28307707b21276f3042d35bd95e5e9a7323d46d52ffee4580a532c4075d3c1ab8b9fbb9c

data/lib/exception_transformer/reportable.rb

@@ -0,0 +1,102 @@
+module ExceptionTransformer
+  # Include this module when declaring an exception class to add
+  # the `reportable?` flag to individual exceptions. The presence
+  # of this flag can then be checked when capturing exceptions to
+  # send to a crash reporter.
+  #
+  # @example Conditionally reporting exceptions
+  #   class MyError < StandardError
+  #     include ExceptionTransformer::ReportableException
+  #   end
+  #
+  #   begin
+  #     # do something that may fail
+  #   rescue MyError => e
+  #     CrashReport.new(e) if e.reportable?
+  #   end
+  #
+  # This flag can be set at the instance level with `mark_reportable!`.
+  # Alternatively, the class method `as_reportable` returns a subclass
+  # for which `reportable?` is true when raised.
+  module Reportable
+    def self.included(base)
+      raise TypeError, "#{base} is not a type of Exception" unless base <= Exception
+      base.extend ClassMethods
+    end
+
+    module ClassMethods
+      # Returns a subclass 'Reportable_<name>' of the current class that
+      # includes `Reportable`. This subclass is created the first time
+      # time this method is called and reused for subsequent invocations.
+      def as_reportable
+        return self if self <= ReportableException
+
+        name = reportable_name
+        mod  = parent
+
+        mod.const_defined?(name) ? mod.const_get(name) : mod.const_set(name, build_reportable)
+      end
+
+      def unload_reportable
+        name = reportable_name
+        mod  = parent
+
+        mod.send(:remove_const, name) if mod.const_defined?(name)
+      end
+
+      def reported_class
+        @reported_class ||= self
+      end
+
+      def reported_class=(klass)
+        @reported_class = klass
+      end
+
+      private
+
+      def build_reportable
+        super_class = self
+        Class.new(super_class) do
+          include ReportableException
+          self.reported_class = super_class
+        end
+      end
+
+      def reportable_name
+        [ReportableException.name, self.name].map(&:demodulize).join("_")
+      end
+    end
+
+    def reportable?
+      @reportable ||= false
+    end
+
+    def mark_reportable!
+      @reportable = true
+    end
+  end
+
+  # Every `Reportable` that includes `ReportableException` will be
+  # raised with the `reportable?` flag set to true.
+  module ReportableException
+    def self.included(base)
+      base.include(Reportable) unless base <= Reportable
+      base.extend ClassMethods
+    end
+
+    module ClassMethods
+      def exception(*args)
+        if reported_class == self
+          super.tap(&:mark_reportable!)
+        else
+          reported_class.exception(*args).tap(&:mark_reportable!)
+        end
+      end
+    end
+
+    def exception(*args)
+      mark_reportable!
+      super
+    end
+  end
+end

data/lib/exception_transformer/transformer.rb

@@ -0,0 +1,92 @@
+class ExceptionTransformer::Transformer
+  attr_accessor :strategy, :validator, :delegate, :mappings
+
+  MAX_MESSAGE_SIZE = 100
+
+  def initialize(strategy)
+    self.strategy = strategy
+    self.mappings = {}
+  end
+
+  def register_target(target, exceptions)
+    case strategy
+    when :validate
+      self.validator = target
+    when :delegate
+      self.delegate  = target
+    when :rewrite, :regex
+      exceptions.each do |klass|
+        self.mappings[klass] = target
+      end
+    end
+  end
+
+  def after_rescue(obj, e, calling_method, except: [], use_default: true, opts: {})
+    with_reporting do
+      case strategy
+      when :delegate
+        obj.instance_exec(e, calling_method, opts, &delegate)
+      when :rewrite, :regex
+        exception, message = find_target(e, except, use_default)
+      end
+
+      if exception.present?
+        raise exception, message.first(MAX_MESSAGE_SIZE), e.backtrace
+      else
+        # Couldn't transform the exception to a defined mapping.
+        raise e
+      end
+    end
+  end
+
+  def after_yield(obj, result, calling_method, except: [], use_default: true, opts: {})
+    with_reporting do
+      case strategy
+      when :validate
+        obj.instance_exec(result, calling_method, opts, &validator)
+      end
+    end
+  end
+
+  private
+
+  # @return [Array] `[exception, message]`
+  def find_target(e, exclude, use_default_match)
+    case strategy
+    when :rewrite
+      exception = find_mapping(e, exclude)
+      message   = e.message
+    when :regex
+      patterns  = find_mapping(e, exclude) || {}
+
+      pattern = patterns.keys.find { |re| re.is_a?(Regexp) && e.message =~ re }
+      pattern ||= :default if use_default_match
+
+      exception = patterns[pattern]
+      message   = e.message.length <= MAX_MESSAGE_SIZE ? e.message : pattern.inspect.gsub(/([^\w\s]|i\z)*/, '')
+    end
+
+    [exception, message]
+  end
+
+  # @return [StandardError, Hash]
+  def find_mapping(e, exclude)
+    mappings
+      .select  { |klass| e.is_a?(klass) && !exclude.include?(klass) }
+      .sort_by { |klass, _| klass.ancestors.count }
+      .last.try(:[], 1)
+  end
+
+  # Report all exceptions that occur except those
+  # with the `reportable?` flag set to false.
+  def with_reporting
+    yield
+  rescue => e
+    unless e.respond_to?(:reportable?) && !e.reportable?
+      # @examples
+      #   Raven.capture_exception(e)
+    end
+
+    raise
+  end
+end

data/lib/exception_transformer/version.rb

@@ -0,0 +1,3 @@
+module ExceptionTransformer
+  VERSION = "0.1.0"
+end

data/lib/exception_transformer.rb

@@ -0,0 +1,82 @@
+require 'exception_transformer/version'
+require 'exception_transformer/transformer'
+
+require 'active_support'
+require 'active_support/core_ext'
+
+require 'byebug'
+
+module ExceptionTransformer
+  def self.included base
+    base.send :include, InstanceMethods
+    base.extend ClassMethods
+  end
+
+  module ClassMethods
+    # Add exceptions to be transformed in `handle_exceptions` block.
+    # @examples
+    #   1. Transform several errors to a single error:
+    #
+    #        transform_exceptions FooError, BazError, to: BarError
+    #
+    #   2. Transform a single error based on it's message:
+    #
+    #        transform_exceptions FooError, where: {
+    #          /Invalid API key/i => BarError,
+    #          :default => RuntimeError
+    #        }
+    #
+    #      To prevent *all* errors being caught via the `:default` branch,
+    #      pass `use_default: false` to `handle_exceptions`.
+    #
+    #   3. Validate a response with a Proc that takes two parameters. The
+    #      first parameter is the response, and the second is the calling method.
+    #
+    #         transform_exceptions validate: proc { |response, action| ... }
+    #
+    #   4. Inspect an error with a Proc that takes two parameters. The
+    #      first parameter is the error, and the second is the calling method.
+    #
+    #         transform_exceptions with: proc { |err, action| ... }
+    def transform_exceptions(*exceptions, group: :default, to: nil, where: nil, with: nil, validate: nil)
+      strategies = { validate: validate, delegate: with, rewrite: to, regex: where }
+
+      strategy = strategies.keys.find { |s| strategies[s].present? }
+      target   = strategies[strategy]
+
+      transformer = find_or_create_exception_transformer(group, strategy)
+      transformer.register_target(target, exceptions)
+    end
+
+    def find_exception_transformer(group)
+      exception_transformers[group]
+    end
+
+    def find_or_create_exception_transformer(group, strategy)
+      exception_transformers[group] ||= Transformer.new(strategy)
+    end
+
+    private
+
+    def exception_transformers
+      @exception_transformers ||= {}
+    end
+  end
+
+  module InstanceMethods
+    def handle_exceptions(group = :default, **opts)
+      # NOTE: `base_label` returns the label of this frame without decoration,
+      # i.e. if `label` was 'block in test', then `base_label` would be `test`.
+      calling_method = caller_locations(1, 1)[0].base_label
+      transformer    = self.class.find_exception_transformer(group)
+
+      result = yield
+
+      transformer.after_yield(self, result, calling_method, opts)
+
+      result
+    rescue => e
+      transformer.after_rescue(self, e, calling_method, opts)
+    end
+  end
+end

data/spec/exception_transformer/reportable_spec.rb

@@ -0,0 +1,106 @@
+require 'exception_transformer/reportable'
+require 'helpers/class_helpers'
+
+describe ExceptionTransformer::Reportable do
+  include ClassHelpers
+
+  context 'when included' do
+    context 'in a class that is not an Exception' do
+      before(:each) { build_class :NotAnException }
+
+      it 'raises TypeError' do
+        expect { NotAnException.include ExceptionTransformer::Reportable }
+          .to raise_error(TypeError)
+      end
+    end
+
+    context 'in an Exception' do
+      before(:each) { build_class :MyException, Exception }
+
+      it 'it should extend it with class methods' do
+        expect { MyException.include ExceptionTransformer::Reportable }
+          .to change { MyException.singleton_class.ancestors }
+          .to include(ExceptionTransformer::Reportable::ClassMethods)
+      end
+    end
+  end
+
+  shared_context :reportable, define_reportable: true do
+    before(:each) do
+      build_class :MyException, Exception do
+        include ExceptionTransformer::Reportable
+      end
+    end
+
+    after(:each) { MyException.unload_reportable }
+  end
+
+  describe '::as_reportable', define_reportable: true do
+    it 'returns a subclass of ReportableException' do
+      expect(MyException.as_reportable).to be < ExceptionTransformer::ReportableException
+    end
+
+    it 'is idempotent' do
+      reportable_exception = MyException.as_reportable
+      expect(reportable_exception).to equal(reportable_exception.as_reportable)
+    end
+
+    describe 'the return value' do
+      it 'is a subclass of the caller' do
+        expect(MyException.as_reportable).to be < MyException
+      end
+
+      it 'is a constant' do
+        expect(MyException.as_reportable.name).not_to be_nil
+      end
+
+      context 'when raised' do
+        it 'is reportable' do
+          expect { raise MyException.as_reportable, 'oops!' }.to raise_error(be_reportable, 'oops!')
+        end
+      end
+    end
+  end
+
+  describe '::unload_reportable', define_reportable: true do
+    context 'when the reportable exception is defined' do
+      it 'removes the constant' do
+        reportable_exception = MyException.as_reportable
+        MyException.unload_reportable
+        expect(Object.const_defined?(reportable_exception.name)).to be false
+      end
+
+      it 'returns it' do
+        reportable_exception = MyException.as_reportable
+        expect(MyException.unload_reportable).to equal(reportable_exception)
+      end
+    end
+
+    context 'when the reportable exception is not defined' do
+      it 'returns nil' do
+        expect(MyException.unload_reportable).to be_nil
+      end
+    end
+  end
+
+  describe '#reportable?', define_reportable: true do
+    context 'when ReportableException is not included' do
+      context 'when the exception is raised' do
+        it 'is false' do
+          # assert !MyException.include?(ExceptionTransformer::ReportableException)
+          expect { raise MyException.new }.to raise_error do |e|
+            expect(e).not_to be_reportable
+          end
+        end
+      end
+    end
+  end
+
+  describe '#mark_reportable!', define_reportable: true do
+    it 'marks the exception as reportable' do
+      exception = MyException.new
+      expect { exception.mark_reportable! }
+        .to change { exception.reportable? }.from(false).to(true)
+    end
+  end
+end

data/spec/exception_transformer_spec.rb

@@ -0,0 +1,291 @@
+require 'exception_transformer'
+
+describe ExceptionTransformer do
+  class FooError < StandardError; end
+  class BarError < StandardError; end
+
+  class BazError < StandardError; end
+  class QuxError < StandardError; end
+
+  class ClassWithExceptionTransformer
+    include ExceptionTransformer
+  end
+
+  def build_obj(&block)
+    Class.new(ClassWithExceptionTransformer, &block).new
+  end
+
+  it 'returns the result if there are no errors' do
+    obj = build_obj do
+      transform_exceptions FooError, to: BarError
+      def task; :task end
+    end
+
+    expect(obj.task).to be(:task)
+  end
+
+  it 'should preserve exception messages' do
+    obj = build_obj do
+      transform_exceptions FooError, to: BarError
+
+      def task; handle_exceptions { raise FooError, 'oops' } end
+    end
+
+    expect{obj.task}.to raise_error(BarError, 'oops')
+  end
+
+  context 'when using :validate strategy' do
+    it 'transforms exceptions' do
+      obj = build_obj do
+        transform_exceptions validate: proc { |res, action|
+          unless res == :success
+            fail FooError
+          end
+        }
+
+        def task1; handle_exceptions { :success } end
+        def task2; handle_exceptions { :failure } end
+      end
+
+      expect{obj.task1}.not_to raise_error
+      expect{obj.task2}.to raise_error(FooError)
+    end
+
+    it 'executes the proc in instance context' do
+      obj = build_obj do
+        transform_exceptions validate: proc { |res, action|
+          raise FooError unless @foo
+        }
+
+        def task1; handle_exceptions { @foo = :foo } end
+        def task2; handle_exceptions { @foo = nil  } end
+      end
+
+      expect{obj.task1}.not_to raise_error
+      expect{obj.task2}.to raise_error(FooError)
+    end
+  end
+
+  context 'when using :delegate strategy' do
+    it 'transforms exceptions' do
+      obj = build_obj do
+        transform_exceptions with: proc { |e, action|
+          next unless e.is_a? FooError
+          raise BazError
+        }
+
+        def task1; handle_exceptions { raise FooError } end
+        def task2; handle_exceptions { raise BarError } end
+      end
+
+      expect{obj.task1}.to raise_error(BazError)
+      expect{obj.task2}.to raise_error(BarError)
+    end
+
+    it 'executes the proc in instance context' do
+      obj = build_obj do
+        transform_exceptions with: proc { |err, action|
+          if @foo
+            raise FooError
+          else
+            raise BarError
+          end
+        }
+
+        def task1
+          handle_exceptions do
+            @foo = :foo
+            raise
+          end
+        end
+
+        def task2
+          handle_exceptions do
+            @foo = nil
+            raise
+          end
+        end
+      end
+
+      expect{obj.task1}.to raise_error(FooError)
+      expect{obj.task2}.to raise_error(BarError)
+    end
+
+    it 'doesnt decorate the caller_location label' do
+      obj = build_obj do
+        transform_exceptions with: proc { |res, action|
+          raise action
+        }
+
+        def task1
+          handle_exceptions { raise }
+        end
+
+        def task2
+          [:foo, :bar].each do |sym|
+            handle_exceptions { raise }
+          end
+        end
+      end
+
+      expect{obj.task1}.to raise_error('task1')
+      expect{obj.task2}.to raise_error('task2')
+    end
+  end
+
+  it 'should limit exception messages to certain length' do
+    obj = build_obj do
+      transform_exceptions FooError, to: BarError
+
+      def task; handle_exceptions { raise FooError, 'oops' * 50 } end
+    end
+
+    begin
+      obj.task
+    rescue BarError => e
+      expect(e.message.length).to be <= ExceptionTransformer::Transformer::MAX_MESSAGE_SIZE
+    end
+  end
+
+  context 'when using :rewrite strategy' do
+    it 'transforms exceptions' do
+      obj = build_obj do
+        transform_exceptions FooError, to: BarError
+
+        def task; handle_exceptions { raise FooError } end
+      end
+
+      expect{obj.task}.to raise_error(BarError)
+    end
+
+    it 'transforms exceptions by inheritance order' do
+      obj = build_obj do
+        transform_exceptions FooError, to: BarError
+        transform_exceptions StandardError, to: QuxError
+
+        def task1; handle_exceptions { raise FooError } end
+        def task2; handle_exceptions { raise ArgumentError} end
+      end
+
+      expect{obj.task1}.to raise_error(BarError)
+      expect{obj.task2}.to raise_error(QuxError)
+    end
+
+    it 'doesnt transform exceptions to be skipped' do
+      obj = build_obj do
+        transform_exceptions FooError, to: BarError
+
+        def task; handle_exceptions(except: [FooError]) { raise FooError, 'oops' } end
+      end
+
+      expect{obj.task}.to raise_error(FooError)
+    end
+  end
+
+  context 'when using :regex strategy' do
+    it 'is able to transform exceptions' do
+      obj = build_obj do
+        transform_exceptions FooError, where: {
+                               /oops/ => BarError,
+                               :default  => StandardError
+                             }
+
+        def task1; handle_exceptions { raise FooError, 'oops' } end
+        def task2; handle_exceptions { raise FooError } end
+      end
+
+      expect{obj.task1}.to raise_error(BarError)
+      expect{obj.task2}.to raise_error(StandardError)
+    end
+
+    it 'should fallback to the default transformation unless specified' do
+      obj = build_obj do
+        transform_exceptions FooError, where: {
+                               /oops/ => BarError,
+                               :default  => StandardError
+                             }
+
+        def task1; handle_exceptions { raise FooError, 'oops' } end
+
+        def task2
+          handle_exceptions use_default: false do
+            raise FooError
+          end
+        end
+      end
+
+      expect{obj.task1}.to raise_error(BarError)
+      expect{obj.task2}.to raise_error(FooError)
+    end
+
+    it 'should keep the exception message if < 100 characters' do
+      obj = build_obj do
+        transform_exceptions FooError, where: {
+          /oops/ => BarError,
+          :default  => StandardError
+        }
+
+        def task1; handle_exceptions { raise FooError, 'oops it broke' } end
+      end
+
+      begin
+        obj.task1
+      rescue BarError => e
+        expect(e.message).to eq('oops it broke')
+      end
+    end
+
+    it 'should use a readable version of the regex if message > 100 characters' do
+      obj = build_obj do
+        transform_exceptions FooError, where: {
+          /oops/ => BarError,
+          :default  => StandardError
+        }
+
+        def task1; handle_exceptions { raise FooError, 'oops' + ((0..9).to_a.join * 10) } end
+      end
+
+      begin
+        obj.task1
+      rescue BarError => e
+        expect(e.message).to eq('oops')
+      end
+    end
+  end
+
+  describe '::find_exception_transformer' do
+    let!(:obj) do
+      build_obj do
+        transform_exceptions FooError, to: BarError, group: :a
+        transform_exceptions FooError, to: BazError, group: :b
+      end
+    end
+
+    it 'returns the transformer defined for the given group' do
+      transformer = obj.class.find_exception_transformer(:a)
+
+      expect(transformer).to be
+      expect(transformer.mappings).to eq(FooError => BarError)
+    end
+  end
+
+  describe '#handle_exceptions' do
+    context 'when a group is provided' do
+      let!(:obj) do
+        build_obj do
+          transform_exceptions FooError, to: BarError, group: :a
+          transform_exceptions FooError, to: BazError, group: :b
+
+          def task(group)
+            handle_exceptions(group) { raise FooError }
+          end
+        end
+      end
+
+      it 'should use the transformer defined for the given group' do
+        expect { obj.task(:a) }.to raise_error(BarError)
+        expect { obj.task(:b) }.to raise_error(BazError)
+      end
+    end
+  end
+end

data/spec/helpers/class_helpers.rb

@@ -0,0 +1,13 @@
+module ClassHelpers
+  # Defines a named class, descending from `super_class`.
+  # The constant assigned to the the class will be restored
+  # to it's original state when an example completes.
+  #
+  # @param name [Symbol, String] the constant name
+  # @param super_class [Class] the class the return value inherits from
+  # @yield [] block passed to `Class.new`
+  # @return [Class]
+  def build_class(name, super_class = Object, &block)
+    stub_const(name.to_s, Class.new(super_class, &block))
+  end
+end

data/spec/spec_helper.rb

@@ -0,0 +1,16 @@
+require "bundler/setup"
+require "exception_transformer"
+
+RSpec.configure do |config|
+  # Enable flags like --only-failures and --next-failure
+  config.example_status_persistence_file_path = ".rspec_status"
+
+  # Disable RSpec exposing methods globally on `Module` and `main`
+  config.disable_monkey_patching!
+
+  config.expect_with :rspec do |c|
+    c.syntax = :expect
+  end
+
+  config.expose_dsl_globally = true
+end

metadata

@@ -0,0 +1,124 @@
+--- !ruby/object:Gem::Specification
+name: exception_transformer
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Patrick McLaren
+- Allina Dolor
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2019-01-29 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.17'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.17'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: byebug
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+description: Add exceptions to be transformed.
+email:
+- patrick@privy.com
+- allina@privy.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- lib/exception_transformer.rb
+- lib/exception_transformer/reportable.rb
+- lib/exception_transformer/transformer.rb
+- lib/exception_transformer/version.rb
+- spec/exception_transformer/reportable_spec.rb
+- spec/exception_transformer_spec.rb
+- spec/helpers/class_helpers.rb
+- spec/spec_helper.rb
+homepage: https://github.com/Privy/exception-transformer
+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.7.6
+signing_key: 
+specification_version: 4
+summary: Error Handling
+test_files: []