escalate 0.1.0.pre.2 → 0.2.0.pre.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: a3e33eb654953f4c511b2207a89df47f6db4865c
-  data.tar.gz: 4b245b1e402c24a933eae6ba6ac6eb9be362e5f1
+SHA256:
+  metadata.gz: fc6bd15f68b37624979732a8c7b2c55d323c407c397c01ac59d8b8df54e90504
+  data.tar.gz: 144d6a67f62d9ca4ce7d740a26285dae283372450fd1149b74da59ab5411c982
 SHA512:
-  metadata.gz: 28a1ecb9c22129c0b68c62ac6c5bd00eb5b41580bae1763dfdc9e0d9e732dfd22b7acc37ec84f353d4a3f7f35c18334ae92a78a5677c5e9e6453c4ccfb074767
-  data.tar.gz: dc2271ab38903b2c8f874adc0b21f26c3851a759f5ed1db34482d447573d3d8f13d8b8d1b5565b9106b73bde766dee65260aeb6c645d402b9326371536d3dce0
+  metadata.gz: 1490795a292d531715525872a8bc06d1d27330222a24a436ad22ea62aa1d5fbc2e80b8a36b382cec86ef6281173bd5bddcbaffe9aa35c7f5bc641f6ac3611380
+  data.tar.gz: e2e7f3d6fd1be1e679bc6286c7fb892cef56fe64b57bbd55fedf649aa681c6e1d26f2f4f4aadbe8db3d0c327a378da65c46baee8fd20d137a6d6f1e2d40257d0

data/CHANGELOG.md

@@ -4,6 +4,17 @@ 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.1.0] - Unreleased
+## [0.2.0] - Unreleased
+### 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
+  there are some and at least one of them passed `log_first: false`.
 
+## [0.1.0] - 2021-02-03
+### Added
+- Added `Escalate.mixin` interface for mixing in `Escalate` with your module for easy escalation of rescued exceptions
+- 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.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,7 +1,7 @@
 PATH
   remote: .
   specs:
-    escalate (0.1.0.pre.2)
+    escalate (0.2.0.pre.4)
       activesupport
 
 GEM
@@ -49,6 +49,7 @@ GEM
       thread_safe (~> 0.1)
 
 PLATFORMS
+  ruby
   x86_64-darwin-19
 
 DEPENDENCIES

data/README.md

@@ -58,8 +58,44 @@ end
 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)`.
+
+### 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.
+
+#### 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/lib/escalate.rb

@@ -9,37 +9,46 @@ require_relative "escalate/mixin"
 module Escalate
   class Error < StandardError; end
 
+  LOG_FIRST_INSTANCE_VARIABLE = :@_escalate_log_first
+
+  @on_escalate_callbacks = {}
+
   class << self
+    attr_reader :on_escalate_callbacks
+
     # Logs and escalated an exception
     #
     # @param [Exception] exception
-    #   The exception that was raised and needs to be escalated
+    #   The exception that was rescued and needs to be escalated
     #
-    # @param [String] message
-    #   An additional message about what was happening at the time of the exception
+    # @param [String] location_message
+    #   An additional message giving an indication of where in the code this exception was rescued
     #
     # @param [Logger] logger
     #   The logger object to use when logging the exception
     #
     # @param [Hash] context
     #   Any additional context to be tied to the escalation
-    def escalate(exception, message, logger, **context)
+    def escalate(exception, location_message, logger, **context)
       ensure_failsafe("Exception rescued while escalating #{exception.inspect}") do
-        error_message = <<~EOS
-          [Escalate] #{message} (#{context.inspect})
+        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_string}
             #{exception.class.name}: #{exception.message}
             #{exception.backtrace.join("\n")}
-        EOS
+          EOS
 
-        if logger_allows_added_context?(logger)
-          logger.error(error_message, **context)
-        else
-          logger.error(error_message)
+          if context_string
+            logger.error(error_message)
+          else
+            logger.error(error_message, **context)
+          end
         end
 
-        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, message, **context)
+            block.call(exception, location_message, **context)
           end
         end
       end
@@ -57,16 +66,43 @@ module Escalate
 
       Module.new do
         def self.included(base)
-          base.extend Escalate::Mixin
+          base.extend self
           base.escalate_logger_block = Thread.current[:escalate_logger_block] || -> { base.try(:logger) }
         end
+
+        attr_accessor :escalate_logger_block
+
+        def escalate(exception, location_message, **context)
+          Escalate.escalate(exception, location_message, escalate_logger, **context)
+        end
+
+        private
+
+        def escalate_logger
+          escalate_logger_block&.call || default_escalate_logger
+        end
+
+        def default_escalate_logger
+          @default_escalate_logger ||= Logger.new(STDERR)
+        end
       end
     end
 
-    # Registers an escalation callback to be executed when `escalate`
-    # is invoked.
-    def on_escalate(&block)
-      on_escalate_blocks.add(block)
+    # 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
+    # @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_on_escalate_callbacks
+      on_escalate_callbacks.clear
     end
 
     private
@@ -81,9 +117,5 @@ module Escalate
       defined?(ContextualLogger::LoggerMixin) &&
         logger.is_a?(ContextualLogger::LoggerMixin)
     end
-
-    def on_escalate_blocks
-      @on_escalate_blocks ||= Set.new
-    end
   end
 end

data/lib/escalate/mixin.rb

@@ -4,24 +4,8 @@ module Escalate
   module Mixin
     class << self
       def included(base)
-        raise 'instead of `include Escalator::Mixin`, you should `include Escalator.mixin`'
+        raise 'instead of `include Escalate::Mixin`, you should `include Escalate.mixin`'
       end
     end
-
-    attr_accessor :escalate_logger_block
-
-    def escalate(exception, message, **context)
-      Escalate.escalate(exception, message, escalate_logger, **context)
-    end
-
-    private
-
-    def escalate_logger
-      escalate_logger_block.try(:call) || default_escalate_logger
-    end
-
-    def default_escalate_logger
-      @default_escalate_logger ||= Logger.new(STDERR)
-    end
   end
 end

data/lib/escalate/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Escalate
-  VERSION = "0.1.0.pre.2"
+  VERSION = "0.2.0.pre.4"
 end

metadata

@@ -1,15 +1,15 @@
 --- !ruby/object:Gem::Specification
 name: escalate
 version: !ruby/object:Gem::Version
-  version: 0.1.0.pre.2
+  version: 0.2.0.pre.4
 platform: ruby
 authors:
 - Invoca Development
 - Octothorp
-autorequire:
+autorequire: 
 bindir: bin
 cert_chain: []
-date: 2021-02-02 00:00:00.000000000 Z
+date: 2021-03-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -56,7 +56,7 @@ metadata:
   allowed_push_host: https://rubygems.org
   homepage_uri: https://github.com/invoca/escalate
   changelog_uri: https://github.com/invoca/escalate/blob/main/CHANGELOG.md
-post_install_message:
+post_install_message: 
 rdoc_options: []
 require_paths:
 - lib
@@ -71,9 +71,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: 1.3.1
 requirements: []
-rubyforge_project:
-rubygems_version: 2.6.13
-signing_key:
+rubygems_version: 3.1.2
+signing_key: 
 specification_version: 4
 summary: A simple and lightweight gem to escalate rescued exceptions.
 test_files: []