escalate 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 367073142399930c67886a1890af1e684d767a11c62d3719fd95ecd392a4c47d
-  data.tar.gz: 368728d4e4db7d3e466571c563902e096093310685ffffc64c1906b05d95338e
+  metadata.gz: 9844b8aaae39fe3b2e23417e7b39e1ec59ff8896e5a6f8be4e3737c3ccf8ce02
+  data.tar.gz: 7e03db14d0da2ec0e6458cd03a9da89cf949fce7d2c0a34bad65b69b7ede2409
 SHA512:
-  metadata.gz: 59605b0ed9a30982a6e6dc92d37c20578b4b52c643361a8b6e7ac2876579ade371c0b528f156de8da92502f7002d66f515c467f8fe5e4a5038580d506f174d08
-  data.tar.gz: 0a24440c7988110d5cacc07bd6ec262074de501938c4076e29bea9607ee38d4d6c19f424086f81fd09ef9266e65f65a9f39b6f9ca36018fcbe9f9688041d820e
+  metadata.gz: e8eab0d9486440921db00178fa7560779976ed9e132377ca1dacea9960a9847f6eed01f964945f88719ef26583789b6bf1dad83f7dbcaef8c3625e83e8825c15
+  data.tar.gz: fa039e7c5c2c3e0c48e50840ba0831eb0f7a87d2902690b3740304f2b36b8aca91df8233c885c6e60ef9bd26fd0b4929604040082adefbdcbf0cbb14287a42ca

data/CHANGELOG.md

@@ -4,6 +4,10 @@ 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).
 
+## [0.3.0] - 2021-03-05
+### Added
+- Added `rescue_and_escalate`.
+
 ## [0.2.0] - 2021-03-02
 ### Added
 - Added support for `on_escalate(log_first: false)`. The `escalate` gem will log first before
@@ -16,5 +20,6 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Added `escalate` method for escalating rescued exceptions with default behavior of logging to `STDERR`
 - Added `Escalate.on_escalate` for registering escalation callbacks like `Honeybadger` or `Sentry`
 
+[0.3.0]: https://github.com/Invoca/escalate/compare/v0.2.0...v0.3.0
 [0.2.0]: https://github.com/Invoca/escalate/compare/v0.1.0...v0.2.0
 [0.1.0]: https://github.com/Invoca/escalate/releases/tag/v0.1.0

data/Gemfile.lock

@@ -1,8 +1,7 @@
 PATH
   remote: .
   specs:
-    escalate (0.2.0)
-      activesupport
+    escalate (0.3.0)
 
 GEM
   remote: https://rubygems.org/

data/README.md

@@ -34,6 +34,7 @@ module SomeGem
 end
 ```
 
+#### Using .escalate
 This will expose the `Escalate#escalate` method within your gem to be used instead
 of using `logger.error`.
 
@@ -46,14 +47,23 @@ module SomeGem
   end
 
   class SomeClass
-    def something_dangerous
-      # ...
-    rescue => ex
-      SomeGem.escalate(ex, "I was doing something dangerous and an exception was raised")
+    def something_dangerous(key)
+      # code here...
+    rescue => exception
+      SomeGem.escalate(exception,
+                       "Exception raised in SomeGem::SomeClass#something_dangerous",
+                       context: { key: key })
     end
   end
 end
 ```
+The following arguments are supported by `.escalate`:
+
+| argument | default | type | description |
+|------------|---|----|-----|
+| `exception` | | `Exception` | The exception to escalate. | 
+| `location_message` | | `String` | A message providing information about where and why this exception is being escalated. |
+| `context:` | `{}` | `Hash` | An optional hash of context. This will be logged with the exception. |
 
 When `SomeGem.escalate` above is triggered, it will use the logger returned by `SomeGem.logger` or
 default to a `STDERR` logger and do the following:
@@ -65,10 +75,42 @@ Step (1) is optional. It will happen if either of these is true:
  - by default if no `on_escalate_callbacks` have been registered; or
  - if any of the `on_escalate_callbacks` was registered with `on_escalate(log_first: true)`.
 
+#### Using .rescue_and_escalate
+The above pattern of `rescue` with `escalate` is very common, so a single method is provided to do both.
+This is equivalent to the code above:
+```
+class SomeClass
+  def something_dangerous(key)
+    SomeGem.rescue_and_escalate("Exception raised in SomeGem::SomeClass#something_dangerous",
+                                context: { key: key }) do
+      # code here...
+    end
+  end
+end
+```
+The following arguments are supported by `.rescue_and_escalate`:
+
+| argument | default | type | description |
+|-------------|---|----|-----|
+| `location_message` | _required_ | `String` | A message providing information about where and why this exception is being escalated. |
+| `context:` | `{}` | `Hash` | An optional hash of context. This will be logged with the exception. |
+| `exceptions:` | `StandardError` | `Class` or `Array(Class)` | The `Class` or `Array(Class)` to rescue. `Class` must be `Exception` or a sub-class. |
+| `pass_through_exceptions:` | `[SystemExit, SystemStackError, NoMemoryError, SecurityError, SignalException]` | `Class` or `Array(Class)` | The `Class` or `Array(Class)` to pass through without rescuing. `Class` must be `Exception`, or a sub-class. These take precedence over `exceptions:`.|
+
+----------------------------
+
 ### Registering an Escalate Callback
 
 If you are using an error reporting service, you can register an `on_escalate` callback to escalate exceptions.
-You have the option to handle logging yourself, or to let `escalate` log first, before calling your callback.
+You have the option to handle logging yourself, or to let `escalate` log first, before yielding to callbacks.
+
+The following arguments are supported by `.on_escalate`:
+
+| argument | default | type | description |
+|-------------|---|----|-----|
+| `name:` | `block.source_location` | `String` or `Array` | Globally unique name for this callback. |
+| `log_first:` | `true` | `Boolean` | Whether `escalate` should log the error first. `false` means the block will take care of this. |
+| `&block` | _required_ | `Proc` | The callback block to yield to from `escalate`. |
 
 #### Leave the Logging to the Escalate Gem
 Here is an example that uses the default `log_first: true` so that logging is handled by the `Escalate` gem first:

data/escalate.gemspec

@@ -26,6 +26,4 @@ Gem::Specification.new do |spec|
   end
   spec.executables   = spec.files.grep(%r{\Aexe/}) { |f| File.basename(f) }
   spec.require_paths = ["lib"]
-
-  spec.add_dependency "activesupport"
 end

data/lib/escalate.rb

@@ -11,6 +11,9 @@ module Escalate
 
   LOG_FIRST_INSTANCE_VARIABLE = :@_escalate_log_first
 
+  DEFAULT_RESCUE_EXCEPTIONS       = [StandardError].freeze
+  DEFAULT_PASS_THROUGH_EXCEPTIONS = [SystemExit, SystemStackError, NoMemoryError, SecurityError, SignalException].freeze
+
   @on_escalate_callbacks = {}
 
   class << self
@@ -29,7 +32,7 @@ module Escalate
     #
     # @param [Hash] context
     #   Any additional context to be tied to the escalation
-    def escalate(exception, location_message, logger, **context)
+    def escalate(exception, location_message, logger, context: {})
       ensure_failsafe("Exception rescued while escalating #{exception.inspect}") do
         if on_escalate_callbacks.none? || on_escalate_callbacks.values.any? { |block| block.instance_variable_get(LOG_FIRST_INSTANCE_VARIABLE) }
           logger_allows_added_context?(logger) or context_string = " (#{context.inspect})"
@@ -72,8 +75,21 @@ module Escalate
 
         attr_accessor :escalate_logger_block
 
-        def escalate(exception, location_message, **context)
-          Escalate.escalate(exception, location_message, escalate_logger, **context)
+        def escalate(exception, location_message, context: {})
+          Escalate.escalate(exception, location_message, escalate_logger, context: context)
+        end
+
+        def rescue_and_escalate(location_message, context: {},
+                                exceptions: DEFAULT_RESCUE_EXCEPTIONS,
+                                pass_through_exceptions: DEFAULT_PASS_THROUGH_EXCEPTIONS,
+                                &block)
+
+          yield
+
+        rescue *Array(pass_through_exceptions)
+          raise
+        rescue *Array(exceptions) => exception
+          escalate(exception, location_message, context: context)
         end
 
         private

data/lib/escalate/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Escalate
-  VERSION = "0.2.0"
+  VERSION = "0.3.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: escalate
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Invoca Development
@@ -9,22 +9,8 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2021-03-02 00:00:00.000000000 Z
-dependencies:
-- !ruby/object:Gem::Dependency
-  name: activesupport
-  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'
+date: 2021-03-05 00:00:00.000000000 Z
+dependencies: []
 description: A simple and lightweight gem to escalate rescued exceptions.
 email:
 - development@invoca.com