fulfil_api 0.7.1 → 0.7.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2971bc621921930210bce77c057d6da8ce549cfe476fb1fc29d72f10c4447303
-  data.tar.gz: 97658bf767d8909e359ad66441de0f81108982c6383070778eb04d3386c2fb3d
+  metadata.gz: 9a5ff8f7f8d9afe6a5130c2cf042875f2d79eabcdb53f61e7f229d03b2dc0c6e
+  data.tar.gz: 017f33c16b4562586e696724b8428f76bc27daeeaf61b0cd2d783f79a952b7e4
 SHA512:
-  metadata.gz: 020e57b3a676a3c56f2d2b76e5b269010764d3a95f41ef19848f0477e4f77ac9db9871252c68efe77fe35af1fbd6f319d8283f43b578caf7e09e8de4651120a9
-  data.tar.gz: 51af4a10179668acf8977fca9dccfc133bbb25516c7464cb87bd05f9abf0a5926b1631620cf9265a9637b7b0ffa8c7b9a6618bf9ee7b75912005eb3f1722e1a3
+  metadata.gz: 387283adc42ad86ed86cea9c20f0c65728fb942b7ef7db70286a2dac2fcc544b0bf49a78feb520ff918faec916dabadf94067f71003bab2adb4087219fe63437
+  data.tar.gz: 8a69f8a11d5152825c8648babbe9535e533d394e13f8da819759eca069aab66bc8656517b35b5d4275ad62ffcabe4e022e93952e09f2780508bca8d90ba6830e

data/CHANGELOG.md

@@ -1,5 +1,7 @@
 ## [Unreleased]
 
+- Publish an `ActiveSupport::Notifications` event named `error.fulfil_api` whenever a `FulfilApi::Error` is raised, so an application can report failures of the Fulfil API to its APM without rescuing every call into the gem. Subscribe with `FulfilApi.on_error { |error| ... }`, or through `ActiveSupport::Notifications` directly to also reach the status code, response body and response headers of a `FulfilApi::HttpError`.
+
 - Raise a `FulfilApi::HttpError` instead of a generic `FulfilApi::Error` when a request to Fulfil fails, with a dedicated subclass per HTTP status code (e.g. `FulfilApi::HttpError::TooManyRequests` for a 429). The exception message is now the description reported by Fulfil rather than its serialized response body, and the status code, body and headers are available through `#status_code`, `#response_body` and `#response_headers`. `FulfilApi::HttpError` inherits from `FulfilApi::Error`, so existing rescues keep working.
 
 - Re-enable Ruby's built-in retry for idempotent requests on the persistent connection, which the `net_http_persistent` adapter disables by forcing `max_retries` to `0`. This recovers stale keep-alive sockets transparently instead of surfacing them as read timeouts.

data/README.md

@@ -178,6 +178,50 @@ A request that never reached Fulfil — a connection reset, a DNS failure, a tim
 
 `FulfilApi::HttpError` inherits from `FulfilApi::Error`, the base class of every error in this gem, so code that already rescues `FulfilApi::Error` keeps working unchanged.
 
+### Subscribing to Errors
+
+Rescuing tells you about the one call you wrapped. To report *every* failure of the Fulfil API — to count rate limit hits in your APM, to page on authentication failures, to log what Fulfil actually said — subscribe once instead.
+
+Every `FulfilApi::Error` publishes an `ActiveSupport::Notifications` event named `error.fulfil_api` when it is raised. `FulfilApi.on_error` is the shorthand for listening to it:
+
+```ruby
+# config/initializers/fulfil_api.rb
+
+FulfilApi.on_error do |error|
+  Appsignal.increment_counter("fulfil_api_errors", 1, error: error.class.name)
+end
+```
+
+Because every error carries its own class, you can report only the failures you care about:
+
+```ruby
+FulfilApi.on_error do |error|
+  next unless error.is_a?(FulfilApi::HttpError::TooManyRequests)
+
+  Appsignal.increment_counter("fulfil_api_rate_limit_exceeded")
+end
+```
+
+Subscribing through `ActiveSupport::Notifications` directly gives you the full payload, which carries the HTTP details of a `FulfilApi::HttpError` as separate keys — handy as metric dimensions:
+
+```ruby
+ActiveSupport::Notifications.subscribe(FulfilApi::Error::EVENT_NAME) do |event|
+  event.payload[:exception]        # => ["FulfilApi::HttpError::TooManyRequests", "Try again later."]
+  event.payload[:exception_object] # => the FulfilApi::HttpError::TooManyRequests instance
+  event.payload[:status_code]      # => 429
+  event.payload[:response_headers] # => { "retry-after" => "5", ... }
+  event.payload[:response_body]    # => the raw response of Fulfil
+end
+```
+
+Both methods return the subscriber, so you can stop listening again with `ActiveSupport::Notifications.unsubscribe(subscriber)`.
+
+A few things worth knowing:
+
+- The event is published when an error is **raised**, not when it is built. Rescuing it afterwards does not suppress the notification, and retrying a request publishes one event per attempt — which is exactly what you want when counting rate limit hits.
+- The subscriber runs on the thread that raised the error, while the error travels up the stack. Keep it cheap and hand anything slow to a background job.
+- A subscriber cannot change the behaviour of your application. If it raises, the exception is swallowed and reported on `$stderr` rather than replacing the `FulfilApi::Error` on its way up.
+
 ### Using the 3PL (TPL) Client
 
 The gem also includes a client for Fulfil's [3PL Integration API](https://fulfil-3pl-integration-api.readme.io/reference/getting-started-with-your-api). This is a separate API that allows third-party logistics providers to interact with Fulfil on behalf of a merchant.

data/lib/fulfil_api/error/notifiable.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+module FulfilApi
+  class Error
+    # The {FulfilApi::Error::Notifiable} publishes an {ActiveSupport::Notifications}
+    #   event every time a {FulfilApi::Error} is raised. It gives an application a
+    #   single place to report a failure of the Fulfil API to its APM — a counter of
+    #   rate limit hits, an error tracker, a log line — without having to wrap every
+    #   call into the gem in a `begin`/`rescue`.
+    #
+    # Ruby routes every form of `raise` through {Exception.exception} (when raising a
+    #   class) or {Exception#exception} (when raising an instance), which makes those
+    #   two methods the hook for "an error is on its way up the stack". Building an
+    #   error without raising it — {FulfilApi::HttpError.from_faraday_error}, for
+    #   example — publishes nothing.
+    #
+    # @example counting the errors of Fulfil in an APM
+    #   # config/initializers/fulfil_api.rb
+    #   FulfilApi.on_error do |error|
+    #     Appsignal.increment_counter("fulfil_api_errors", 1, error: error.class.name)
+    #   end
+    #
+    # @example subscribing through ActiveSupport directly, for the full payload
+    #   ActiveSupport::Notifications.subscribe(FulfilApi::Error::EVENT_NAME) do |event|
+    #     Rails.logger.warn("Fulfil responded with #{event.payload[:status_code]}")
+    #   end
+    #
+    # @note A subscriber must not change the behaviour of the application it observes.
+    #   An exception raised by a subscriber is therefore swallowed and reported on
+    #   `$stderr` rather than allowed to replace the {FulfilApi::Error} on its way up.
+    module Notifiable
+      extend ActiveSupport::Concern
+
+      # The name of the published event. It follows the `<action>.<library>` naming
+      #   convention of Rails, so an APM that subscribes to a whole library through a
+      #   `/\.fulfil_api\z/` regexp picks it up along with everything the gem may
+      #   instrument in the future.
+      EVENT_NAME = "error.fulfil_api"
+
+      # The key of the fiber local flag guarding against infinite recursion. A
+      #   subscriber that itself raises a {FulfilApi::Error} — one calling back into
+      #   Fulfil, for instance — would otherwise publish an event from within the
+      #   publication of an event, without end.
+      REENTRANCY_KEY = :fulfil_api_notifying_error
+
+      class_methods do
+        # Publishes {EVENT_NAME} for `raise SomeError` and `raise SomeError, "message"`.
+        #
+        # @return [FulfilApi::Error] The error being raised.
+        def exception(*, **)
+          super.tap(&:notify)
+        end
+      end
+
+      # Publishes {EVENT_NAME} for `raise error` and `raise error, "message"`.
+      #
+      # @return [FulfilApi::Error] The error being raised.
+      def exception(*)
+        super.tap(&:notify)
+      end
+
+      # Publishes {EVENT_NAME} for the receiver.
+      #
+      # @return [void]
+      def notify
+        return if Thread.current[REENTRANCY_KEY]
+
+        Thread.current[REENTRANCY_KEY] = true
+        ActiveSupport::Notifications.instrument(EVENT_NAME, notification_payload)
+      rescue StandardError => e
+        warn "[FulfilApi] a subscriber of #{EVENT_NAME} raised #{e.class}: #{e.message}"
+      ensure
+        Thread.current[REENTRANCY_KEY] = nil
+      end
+
+      private
+
+      # The payload published alongside {EVENT_NAME}.
+      #
+      # `:exception` and `:exception_object` follow the convention Rails uses for its
+      #   own instrumentation, which is what an APM looks for to attribute an event to
+      #   a failure.
+      #
+      # @return [Hash]
+      def notification_payload
+        { exception: [self.class.name, message], exception_object: self }
+      end
+    end
+  end
+end

data/lib/fulfil_api/error.rb

@@ -3,7 +3,13 @@
 module FulfilApi
   # The {FulfilApi::Error} is the base class for all FulfilApi errors, also used
   #   for generic or unexpected errors.
+  #
+  # Raising any of them publishes an {ActiveSupport::Notifications} event, so an
+  #   application can report the failure to its APM without rescuing every call into
+  #   the gem. See {FulfilApi::Error::Notifiable} and {FulfilApi.on_error}.
   class Error < StandardError
+    include Notifiable
+
     attr_reader :details
 
     # @param message [String] The displayable error message for the receiver.
@@ -32,4 +38,36 @@ module FulfilApi
       nil
     end
   end
+
+  # Subscribes to every {FulfilApi::Error} raised by the gem.
+  #
+  # This is the shorthand for the common case: reporting the failure somewhere. To
+  #   reach the HTTP status code, response body and response headers of a
+  #   {FulfilApi::HttpError} as well, subscribe to {FulfilApi::Error::EVENT_NAME}
+  #   through {ActiveSupport::Notifications} directly.
+  #
+  # @example incrementing a counter of an APM
+  #   # config/initializers/fulfil_api.rb
+  #   FulfilApi.on_error do |error|
+  #     Appsignal.increment_counter("fulfil_api_errors", 1, error: error.class.name)
+  #   end
+  #
+  # @example reporting only the rate limit hits
+  #   FulfilApi.on_error do |error|
+  #     next unless error.is_a?(FulfilApi::HttpError::TooManyRequests)
+  #
+  #     Appsignal.increment_counter("fulfil_api_rate_limit_exceeded")
+  #   end
+  #
+  # @note The block runs while the error travels up the stack, on the thread that
+  #   raised it. Keep it cheap, and hand anything slow to a background job.
+  #
+  # @yieldparam error [FulfilApi::Error] The error being raised.
+  # @return [Object] The subscriber, to hand back to
+  #   `ActiveSupport::Notifications.unsubscribe` to stop listening.
+  def self.on_error
+    ActiveSupport::Notifications.subscribe(Error::EVENT_NAME) do |event|
+      yield(event.payload[:exception_object])
+    end
+  end
 end

data/lib/fulfil_api/http_error.rb

@@ -174,5 +174,20 @@ module FulfilApi
     def status_code
       details&.dig(:response_status)
     end
+
+    private
+
+    # Enriches the payload published by {FulfilApi::Error::Notifiable} with what
+    #   Fulfil reported, so a subscriber can tag its metrics by status code without
+    #   having to unpack the exception itself.
+    #
+    # @return [Hash]
+    def notification_payload
+      super.merge(
+        response_body: response_body,
+        response_headers: response_headers,
+        status_code: status_code
+      )
+    end
   end
 end

data/lib/fulfil_api/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module FulfilApi
-  VERSION = "0.7.1"
+  VERSION = "0.7.2"
 end

data/lib/fulfil_api.rb

@@ -12,6 +12,7 @@ require "active_support/core_ext/hash/deep_merge"
 require "active_support/core_ext/hash/indifferent_access"
 require "active_support/core_ext/module/delegation"
 require "active_support/core_ext/object/blank"
+require "active_support/notifications"
 
 module FulfilApi
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: fulfil_api
 version: !ruby/object:Gem::Version
-  version: 0.7.1
+  version: 0.7.2
 platform: ruby
 authors:
 - Stefan Vermaas
@@ -86,6 +86,7 @@ files:
 - lib/fulfil_api/configuration.rb
 - lib/fulfil_api/customer_shipment.rb
 - lib/fulfil_api/error.rb
+- lib/fulfil_api/error/notifiable.rb
 - lib/fulfil_api/http_error.rb
 - lib/fulfil_api/relation.rb
 - lib/fulfil_api/relation/batchable.rb