fulfil_api 0.7.0 → 0.7.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c2dd30142d140730335b3f184bc28c0fd897af19246a8794ec5d416b1a335b2a
-  data.tar.gz: b81436ad499dfdd14ea84f5651d4670395907ad8090ab4e9eed432c6195da86c
+  metadata.gz: 9a5ff8f7f8d9afe6a5130c2cf042875f2d79eabcdb53f61e7f229d03b2dc0c6e
+  data.tar.gz: 017f33c16b4562586e696724b8428f76bc27daeeaf61b0cd2d783f79a952b7e4
 SHA512:
-  metadata.gz: 6dee8c45eea430b8f6e7bfa82b03c3d737dd424cdda363c74680f4acedc9e896c28cfc3bc746e35d33035a863ffed9f995877b267a59e0afae0f2e67f7047d20
-  data.tar.gz: 5873899ac0f65bb6a9e1ecbd74aebd1f45806cee1faed5716c1649e158d83396de15139a93da9347b8b20ba080172c7e2cfa59aca36b6f89a89a4a57207e3167
+  metadata.gz: 387283adc42ad86ed86cea9c20f0c65728fb942b7ef7db70286a2dac2fcc544b0bf49a78feb520ff918faec916dabadf94067f71003bab2adb4087219fe63437
+  data.tar.gz: 8a69f8a11d5152825c8648babbe9535e533d394e13f8da819759eca069aab66bc8656517b35b5d4275ad62ffcabe4e022e93952e09f2780508bca8d90ba6830e

data/CHANGELOG.md

@@ -1,5 +1,9 @@
 ## [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.
 - Add a `connection_options` configuration option to tune the persistent connection (`max_retries`, `idle_timeout`, `pool_size`).
 - `FulfilApi.with_config` now merges the temporary options over the active configuration instead of replacing it, so a block inherits credentials and other unspecified settings rather than resetting them to their defaults.

data/README.md

@@ -149,6 +149,79 @@ line_items = FulfilApi::Resource.set(model_name: "sale.line").where(["id", "in",
 line_items = FulfilApi::Resource.set(model_name: "sale.line").find_by(["sale.id", "=", 100])
 ```
 
+### Handling Errors
+
+Whenever a request to Fulfil fails, the gem raises a `FulfilApi::HttpError`. Every HTTP status code has its own subclass, named after the status code it represents, so you can rescue the exact failure you care about:
+
+```ruby
+begin
+  FulfilApi::Resource.set(model_name: "sale.sale").find_by(["id", "=", 100])
+rescue FulfilApi::HttpError::TooManyRequests => exception
+  puts exception.message    # => "This user has exceeded an allotted request count. Try again later."
+  puts exception.status_code # => 429
+
+  sleep exception.response_headers["retry-after"].to_i
+  retry
+end
+```
+
+The message is the description reported by Fulfil. The raw response is available through `#response_body`, `#response_headers` and `#status_code`.
+
+To catch anything that went wrong, rescue the base class instead:
+
+```ruby
+rescue FulfilApi::HttpError => exception
+  Rails.logger.error("Fulfil responded with #{exception.status_code}: #{exception.message}")
+```
+
+A request that never reached Fulfil — a connection reset, a DNS failure, a timeout — has no status code to name and raises a `FulfilApi::HttpError` itself.
+
+`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/client.rb

@@ -167,15 +167,10 @@ module FulfilApi
 
     # @param exception [Faraday::Error] Any error raised by Faraday during the execution
     #   of the HTTP request to the API endpoint.
+    # @raise [FulfilApi::HttpError] The error dedicated to the HTTP status code of the
+    #   response of Fulfil.
     def handle_request_error(exception)
-      raise FulfilApi::Error.new(
-        exception.message,
-        details: {
-          response_body: exception.response_body,
-          response_headers: exception.response_headers,
-          response_status: exception.response_status
-        }
-      )
+      raise FulfilApi::HttpError.from_faraday_error(exception)
     end
 
     # @param method [Symbol, String] The HTTP verb for the HTTP request.

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

@@ -0,0 +1,193 @@
+# frozen_string_literal: true
+
+module FulfilApi
+  # The {FulfilApi::HttpError} is raised whenever a request to an API endpoint of
+  #   Fulfil fails.
+  #
+  # Every HTTP status code Fulfil can respond with has a dedicated subclass, named
+  #   after the status code it represents. A 429 response raises a
+  #   {FulfilApi::HttpError::TooManyRequests}, a 422 an
+  #   {FulfilApi::HttpError::UnprocessableEntity}, and so on. See {STATUS_CODES} for
+  #   the full list. This lets callers rescue the exact failure they care about
+  #   instead of rescuing everything and inspecting the status code themselves.
+  #
+  # Requests that never reached Fulfil — a connection reset, a DNS failure, a
+  #   timeout — have no status code to name and raise a {FulfilApi::HttpError}.
+  #
+  # @example rescuing one specific HTTP status code
+  #   begin
+  #     FulfilApi::Resource.set(model_name: "sale.sale").find_by(["id", "=", 100])
+  #   rescue FulfilApi::HttpError::TooManyRequests => exception
+  #     sleep exception.response_headers["retry-after"].to_i
+  #     retry
+  #   end
+  #
+  # @example rescuing any failed request
+  #   begin
+  #     FulfilApi::Resource.set(model_name: "sale.sale").find_by(["id", "=", 100])
+  #   rescue FulfilApi::HttpError => exception
+  #     Rails.logger.error("Fulfil responded with #{exception.status_code}: #{exception.message}")
+  #   end
+  #
+  # @note {FulfilApi::HttpError} inherits from {FulfilApi::Error}, so any code that
+  #   already rescues {FulfilApi::Error} keeps catching these exceptions.
+  class HttpError < Error
+    # The keys of an error response of Fulfil that can hold the human readable
+    #   message, in the order they're preferred.
+    #
+    # Fulfil is not consistent in how it reports failures: HTTP level errors carry a
+    #   `description`, application level errors a `message`, and a handful of
+    #   endpoints only return an `error`.
+    MESSAGE_KEYS = %w[description message error].freeze
+
+    # Maps an HTTP status code onto the name of the {FulfilApi::HttpError} subclass
+    #   representing it.
+    STATUS_CODES = {
+      400 => :BadRequest,
+      401 => :Unauthorized,
+      402 => :PaymentRequired,
+      403 => :Forbidden,
+      404 => :NotFound,
+      405 => :MethodNotAllowed,
+      406 => :NotAcceptable,
+      407 => :ProxyAuthenticationRequired,
+      408 => :RequestTimeout,
+      409 => :Conflict,
+      410 => :Gone,
+      411 => :LengthRequired,
+      412 => :PreconditionFailed,
+      413 => :PayloadTooLarge,
+      414 => :UriTooLong,
+      415 => :UnsupportedMediaType,
+      416 => :RangeNotSatisfiable,
+      417 => :ExpectationFailed,
+      418 => :ImATeapot,
+      421 => :MisdirectedRequest,
+      422 => :UnprocessableEntity,
+      423 => :Locked,
+      424 => :FailedDependency,
+      425 => :TooEarly,
+      426 => :UpgradeRequired,
+      428 => :PreconditionRequired,
+      429 => :TooManyRequests,
+      431 => :RequestHeaderFieldsTooLarge,
+      451 => :UnavailableForLegalReasons,
+      500 => :InternalServerError,
+      501 => :NotImplemented,
+      502 => :BadGateway,
+      503 => :ServiceUnavailable,
+      504 => :GatewayTimeout,
+      505 => :HttpVersionNotSupported,
+      506 => :VariantAlsoNegotiates,
+      507 => :InsufficientStorage,
+      508 => :LoopDetected,
+      510 => :NotExtended,
+      511 => :NetworkAuthenticationRequired
+    }.freeze
+
+    # Defines a dedicated exception class for every status code in {STATUS_CODES} and
+    #   indexes them by their status code, so {.for_status_code} can look one up
+    #   without going through {Module#const_get}.
+    CLASSES_BY_STATUS_CODE = STATUS_CODES.transform_values do |class_name|
+      const_set(class_name, Class.new(self))
+    end.freeze
+
+    class << self
+      # Looks up the {FulfilApi::HttpError} subclass representing the given HTTP
+      #   status code.
+      #
+      # @param status_code [Integer, nil] The HTTP status code of the response.
+      # @return [Class<FulfilApi::HttpError>] The subclass for the status code, or
+      #   {FulfilApi::HttpError} itself when the status code is unknown or absent.
+      def for_status_code(status_code)
+        CLASSES_BY_STATUS_CODE.fetch(status_code, HttpError)
+      end
+
+      # Builds the most specific {FulfilApi::HttpError} for the given Faraday exception.
+      #
+      # @param exception [Faraday::Error] Any error raised by Faraday during the
+      #   execution of the HTTP request to the API endpoint.
+      # @return [FulfilApi::HttpError]
+      def from_faraday_error(exception)
+        details = {
+          response_body: exception.response_body,
+          response_headers: exception.response_headers,
+          response_status: exception.response_status
+        }
+
+        for_status_code(exception.response_status).new(
+          message_from(exception.response_body) || exception.message, details: details
+        )
+      end
+
+      private
+
+      # Extracts the human readable error message out of the response body of Fulfil.
+      #
+      # @param response_body [String, Hash, nil] The response body of the API endpoint.
+      # @return [String, nil] The message, or nil when the body holds none. An HTML
+      #   error page and an empty body both yield nil.
+      def message_from(response_body)
+        body = parse(response_body)
+        return if body.nil?
+
+        MESSAGE_KEYS.map { |key| body[key] }.find { |message| message.is_a?(String) && message.present? }
+      end
+
+      # @param response_body [String, Hash, nil] The response body of the API endpoint.
+      # @return [ActiveSupport::HashWithIndifferentAccess, nil]
+      def parse(response_body)
+        return response_body.with_indifferent_access if response_body.is_a?(Hash)
+        return if response_body.blank?
+
+        parsed_body = JSON.parse(response_body)
+        parsed_body.with_indifferent_access if parsed_body.is_a?(Hash)
+      rescue JSON::ParserError
+        nil
+      end
+    end
+
+    # Unlike {FulfilApi::Error}, the message is returned as-is. The name of the
+    #   exception class already tells you what went wrong, so prefixing it only gets
+    #   in the way of the description reported by Fulfil.
+    #
+    # @note {StandardError#message} delegates to {StandardError#to_s}, which still
+    #   holds the message passed to the constructor.
+    #
+    # @return [String]
+    def message
+      to_s
+    end
+
+    # @return [String, Hash, nil] The raw response body of the API endpoint of Fulfil.
+    def response_body
+      details&.dig(:response_body)
+    end
+
+    # @return [Hash, nil] The response headers of the API endpoint of Fulfil.
+    def response_headers
+      details&.dig(:response_headers)
+    end
+
+    # @return [Integer, nil] The HTTP status code of the response, or nil when the
+    #   request never reached Fulfil.
+    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/relation/batchable.rb

@@ -49,7 +49,7 @@ module FulfilApi
       # @yield [FulfilApi::Relation] Yields FulfilApi::Relation
       #   objects to work with a batch of records.
       # @return [FulfilApi::Relation]
-      def in_batches(of: 500, retries: :unlimited) # rubocop:disable Metrics/MethodLength, Metrics/AbcSize
+      def in_batches(of: 500, retries: :unlimited) # rubocop:disable Metrics/MethodLength
         current_retry = 0
         current_offset = request_offset.presence || 0
         batch_size = of
@@ -64,18 +64,14 @@ module FulfilApi
 
           current_offset += 1
           current_retry = 0 # Reset the retries back to the default
-        rescue FulfilApi::Error => e
-          if e.details[:response_status] == 429
-            if retries != :unlimited && current_retry > retries
-              raise RetryLimitExceeded, "the maximum number of #{retries} retries has been reached."
-            end
-
-            current_retry += 1
-            sleep 0.25
-            retry
+        rescue FulfilApi::HttpError::TooManyRequests
+          if retries != :unlimited && current_retry > retries
+            raise RetryLimitExceeded, "the maximum number of #{retries} retries has been reached."
           end
 
-          raise e
+          current_retry += 1
+          sleep 0.25
+          retry
         end
 
         self

data/lib/fulfil_api/tpl_client.rb

@@ -182,15 +182,10 @@ module FulfilApi
 
     # @param exception [Faraday::Error] Any error raised by Faraday during the execution
     #   of the HTTP request to the API endpoint.
+    # @raise [FulfilApi::HttpError] The error dedicated to the HTTP status code of the
+    #   response of Fulfil.
     def handle_request_error(exception)
-      raise FulfilApi::Error.new(
-        exception.message,
-        details: {
-          response_body: exception.response_body,
-          response_headers: exception.response_headers,
-          response_status: exception.response_status
-        }
-      )
+      raise FulfilApi::HttpError.from_faraday_error(exception)
     end
 
     # @param method [Symbol, String] The HTTP verb for the HTTP request.

data/lib/fulfil_api/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module FulfilApi
-  VERSION = "0.7.0"
+  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,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: fulfil_api
 version: !ruby/object:Gem::Version
-  version: 0.7.0
+  version: 0.7.2
 platform: ruby
 authors:
 - Stefan Vermaas
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-06-29 00:00:00.000000000 Z
+date: 2026-08-18 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -86,6 +86,8 @@ 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
 - lib/fulfil_api/relation/countable.rb