escalate 0.2.0.pre.1 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2a0dc76f8fb9f09d141c117b3b746b143078712c8d14687e9a413f9e0db0eee4
-  data.tar.gz: 0a8861399988e40db304ff5bed43a5a3c6359eb2f0853f162515c5883e74c613
+  metadata.gz: 9844b8aaae39fe3b2e23417e7b39e1ec59ff8896e5a6f8be4e3737c3ccf8ce02
+  data.tar.gz: 7e03db14d0da2ec0e6458cd03a9da89cf949fce7d2c0a34bad65b69b7ede2409
 SHA512:
-  metadata.gz: 95f0fd83333e4245756cee9c5fff725255a8b81e954102ad22e8d0d2c0f49bf27050c15154a00a309d4c0bce8f9edd7e5247aba3dfdc8b2f9b1fa64cbf281ab8
-  data.tar.gz: 62f87cc4801ff0a5187c251ec2fe0e47433d52ab4bdc89558af29a57f6bbf50ee912c9e92127c4a152a5008cf1d7e3110735b8082ec540b6aac9e7d95bf2fa18
+  metadata.gz: e8eab0d9486440921db00178fa7560779976ed9e132377ca1dacea9960a9847f6eed01f964945f88719ef26583789b6bf1dad83f7dbcaef8c3625e83e8825c15
+  data.tar.gz: fa039e7c5c2c3e0c48e50840ba0831eb0f7a87d2902690b3740304f2b36b8aca91df8233c885c6e60ef9bd26fd0b4929604040082adefbdcbf0cbb14287a42ca

data/CHANGELOG.md

@@ -4,7 +4,11 @@ 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.2.0] - Unreleased
+## [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
   escalating if either of these is true: there are no `on_escalate` blocks registered, or
@@ -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.pre.1)
-      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,20 +47,97 @@ 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:
 
-1. Log an error containing the exception and any additional information about the current environment that is specified
-2. Trigger any `escalation_callbacks` configured on the `Escalate` gem
+1. [optional] Log an error containing the exception, location_message, and context hash
+2. Trigger any `on_escalate_callbacks` configured on the `Escalate` gem
+
+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 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:
+```
+Escalate.on_escalate do |exception, location_message, **context|
+  # send exception, location_message, **context to the error reporting service here
+end
+```
+
+#### Callback Uniqueness
+Each callback may be named with the `name:` keyword argument.
+If a callback with the same name has been registered before, it will be overwritten with the new one.
+```
+Escalate.on_escalate(name: 'abc gem') do |exception, location_message, **context|
+  # send exception, location_message, **context to the error reporting service here
+end
+```
+If not given, the `name:` defaults to the `.source_location` property of the passed-in block.
+
+#### Handle the Logging in the `on_escalate` Callback
+Here is an example that handles logging itself with `log_first: false`:
+```
+Escalate.on_escalate(log_first: false) do |exception, location_message, **context|
+  # log here first
+  # send exception, location_message, **context to the error reporting service here
+end
+```
 ## Development
 
 After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.

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

@@ -9,7 +9,16 @@ require_relative "escalate/mixin"
 module Escalate
   class Error < StandardError; end
 
+  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
+    attr_reader :on_escalate_callbacks
+
     # Logs and escalated an exception
     #
     # @param [Exception] exception
@@ -23,23 +32,24 @@ 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_blocks.any? || on_escalate_no_log_first_blocks.none?
+        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})"
           error_message = <<~EOS
-            [Escalate] #{location_message} (#{context.inspect})
+            [Escalate] #{location_message}#{context_string}
             #{exception.class.name}: #{exception.message}
             #{exception.backtrace.join("\n")}
           EOS
 
-          if logger_allows_added_context?(logger)
-            logger.error(error_message, **context)
-          else
+          if context_string
             logger.error(error_message)
+          else
+            logger.error(error_message, **context)
           end
         end
 
-        all_on_escalate_blocks.each do |block|
+        on_escalate_callbacks.values.each do |block|
           ensure_failsafe("Exception rescued while escalating #{exception.inspect} to #{block.inspect}") do
             block.call(exception, location_message, **context)
           end
@@ -65,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
@@ -81,22 +104,21 @@ module Escalate
       end
     end
 
-    # Registers an escalation callback to be executed when `escalate`
-    # is invoked.
+    # Registers an escalation callback to be executed when `escalate` is invoked.
     #
     # @param [boolean] log_first: true
     #   whether escalate should log first before escalating, or leave the logging to the escalate block
-    def on_escalate(log_first: true, &block)
-      if log_first
-        on_escalate_blocks.add(block)
-      else
-        on_escalate_no_log_first_blocks.add(block)
-      end
+    # @param [string | Array] name:
+    #   unique name for this callback block
+    #   any previously-registered block with the same name will be discarded
+    #   if not provided, name defaults to `block.source_location`
+    def on_escalate(log_first: true, name: nil, &block)
+      block.instance_variable_set(LOG_FIRST_INSTANCE_VARIABLE, log_first)
+      on_escalate_callbacks[name || block.source_location] = block
     end
 
-    def clear_all_on_escalate_blocks
-      on_escalate_blocks.clear
-      on_escalate_no_log_first_blocks.clear
+    def clear_on_escalate_callbacks
+      on_escalate_callbacks.clear
     end
 
     private
@@ -111,17 +133,5 @@ module Escalate
       defined?(ContextualLogger::LoggerMixin) &&
         logger.is_a?(ContextualLogger::LoggerMixin)
     end
-
-    def on_escalate_blocks
-      @on_escalate_blocks ||= Set.new
-    end
-
-    def on_escalate_no_log_first_blocks
-      @on_escalate_no_log_first_blocks ||= Set.new
-    end
-
-    def all_on_escalate_blocks
-      on_escalate_blocks + on_escalate_no_log_first_blocks
-    end
   end
 end

data/lib/escalate/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Escalate
-  VERSION = "0.2.0.pre.1"
+  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.pre.1
+  version: 0.3.0
 platform: ruby
 authors:
 - Invoca Development
@@ -9,22 +9,8 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2021-02-25 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
@@ -67,9 +53,9 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: 2.4.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
-  - - ">"
+  - - ">="
     - !ruby/object:Gem::Version
-      version: 1.3.1
+      version: '0'
 requirements: []
 rubygems_version: 3.1.2
 signing_key: