fulfil_api 0.7.1 → 0.8.0

data/app/models/fulfil_api/installation.rb

@@ -0,0 +1,145 @@
+# frozen_string_literal: true
+
+module FulfilApi
+  # An {FulfilApi::Installation} records that the OAuth app was installed on a
+  #   merchant's Fulfil workspace, and holds the access token that came out of
+  #   it.
+  #
+  # An installation without an owner is the application-wide installation, which
+  #   is what a Rails application built for a single merchant needs. Assigning an
+  #   owner scopes the installation to a record instead, which is what an
+  #   application serving many merchants needs — see {FulfilApi::Installable}.
+  #
+  # An owner has at most one installation, so a record is always tied to a single
+  #   Fulfil workspace. The same holds for the application-wide installation.
+  class Installation < ActiveRecord::Base
+    belongs_to :owner, polymorphic: true, optional: true
+
+    encrypts :access_token
+    encrypts :offline_access_token
+
+    normalizes :merchant_id, with: ->(merchant_id) { FulfilApi::OAuth::Authorization.normalize(merchant_id) }
+
+    validates :merchant_id, presence: true
+    validates :owner_id, uniqueness: { message: "is already connected to a Fulfil workspace", scope: :owner_type }
+
+    # Which of the two tokens is granted depends on the access mode, so neither
+    #   column can be required on its own. An installation carrying neither is
+    #   not an installation: it authenticates nothing, and {#usable?} would send
+    #   the user back through the flow forever.
+    validates :access_token, presence: { message: "or an offline access token has to be present" }, unless: :offline?
+
+    scope :global, -> { where(owner: nil) }
+
+    serialize :scopes, coder: JSON, type: Array
+
+    # Records the outcome of a completed authorization flow.
+    #
+    # Installing replaces whatever the owner was connected to before, rather than
+    #   leaving it connected to two Fulfil workspaces at once.
+    #
+    # @param token [FulfilApi::OAuth::Token] The granted access token.
+    # @param merchant_id [String] The workspace the app was installed on.
+    # @param owner [ActiveRecord::Base, nil] The record the installation belongs
+    #   to, or `nil` for the application-wide installation.
+    # @return [FulfilApi::Installation]
+    def self.install(token, merchant_id:, owner: nil)
+      installation = find_or_initialize_by(owner: owner)
+      installation.merchant_id = merchant_id
+
+      # A token granted by one workspace is worthless on another, so moving the
+      #   owner to a different workspace drops what the previous one granted.
+      installation.offline_access_token = nil if installation.merchant_id_changed?
+
+      installation.assign_token(token)
+      installation.save!
+      installation
+    end
+
+    # Looks up the installation to authenticate a Fulfil API request with.
+    #
+    # @param owner [ActiveRecord::Base, nil] The record the installation belongs to.
+    # @param merchant_id [String, nil] The workspace to find the installation for.
+    # @return [FulfilApi::Installation, nil]
+    def self.installed_on(merchant_id: FulfilApi.configuration.merchant_id, owner: nil)
+      return if merchant_id.blank?
+
+      find_by(owner: owner, merchant_id: merchant_id)
+    end
+
+    # Copies the granted token onto the installation.
+    #
+    # Re-authorizing in `user_session` mode does not return an
+    #   `offline_access_token`, so an already granted permanent token is kept
+    #   rather than wiped.
+    #
+    # @param token [FulfilApi::OAuth::Token] The granted access token.
+    # @return [void]
+    def assign_token(token)
+      assign_attributes(
+        access_token: token.access_token,
+        expires_at: token.expires_at,
+        scopes: token.scopes,
+        token_type: token.token_type
+      )
+
+      assign_associated_user(token.associated_user)
+      self.offline_access_token = token.offline_access_token if token.offline?
+    end
+
+    # Whether the short-lived token has passed its expiry. It says nothing about
+    #   the permanent token, which is only revoked by uninstalling the app.
+    #
+    # @return [true, false]
+    def expired?
+      expires_at.present? && expires_at <= Time.current
+    end
+
+    # @return [true, false] Whether a permanent token was granted.
+    def offline?
+      offline_access_token.present?
+    end
+
+    # @return [FulfilApi::AccessToken]
+    def to_access_token
+      FulfilApi::AccessToken.new(offline_access_token.presence || access_token, type: :oauth)
+    end
+
+    # Whether the installation can still authenticate requests, or whether the
+    #   user has to walk through the authorization flow again.
+    #
+    # @return [true, false]
+    def usable?
+      return true if offline?
+
+      access_token.present? && !expired?
+    end
+
+    # Runs a block against the Fulfil API as this installation.
+    #
+    # @example
+    #   installation.with_config do |client|
+    #     client.get("model/sale.sale")
+    #   end
+    #
+    # @yieldparam [FulfilApi::Client] client A client authenticated as this installation.
+    # @return [void]
+    def with_config
+      FulfilApi.with_config(access_token: to_access_token, merchant_id: merchant_id) do
+        yield(FulfilApi.client)
+      end
+    end
+
+    private
+
+    # @param user [Hash] The user who walked through the authorization flow.
+    # @return [void]
+    def assign_associated_user(user)
+      assign_attributes(
+        associated_user_email: user[:email],
+        associated_user_id: user[:id],
+        associated_user_name: user[:name]
+      )
+    end
+  end
+end

data/config/routes.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+FulfilApi::Engine.routes.draw do
+  resource :installation, only: %i[new]
+
+  # Fulfil sends the user back with a `GET`, so the installation cannot be
+  #   created through the resourceful `POST /installation` route.
+  get "callback", to: "installations#create", as: :callback
+end

data/lib/fulfil_api/circuit_open.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module FulfilApi
+  # The {FulfilApi::CircuitOpen} is raised instead of sending a request while the
+  #   circuit breaker has the Fulfil instance marked as failing.
+  #
+  # @see FulfilApi::Middleware::CircuitBreaker
+  class CircuitOpen < Error; end
+end

data/lib/fulfil_api/client.rb

@@ -113,6 +113,9 @@ module FulfilApi
           configure_persistent_connection(http)
         end
 
+        # Retries and other safeguards wrap every request, so they're added first
+        FulfilApi::Middleware.apply(connection, configuration)
+
         # Configuration of the request middleware
         connection.request :json
 
@@ -136,11 +139,9 @@ module FulfilApi
     # Tunes the underlying Net::HTTP::Persistent connection.
     #
     # The `net_http_persistent` adapter forces `max_retries` to 0 on every
-    #   request, which disables Ruby's built-in retry for idempotent requests.
-    #   Restoring it lets a stale keep-alive socket — one the server has already
-    #   closed — be retried transparently on a fresh socket instead of surfacing
-    #   as a read timeout. The config block runs after the adapter zeroes the
-    #   value, so this takes effect.
+    #   request. Retries are handled by {FulfilApi::Middleware::Retry} instead, so
+    #   `max_retries` is only restored when it's configured explicitly. The config
+    #   block runs after the adapter zeroes the value, so this takes effect.
     #
     # @param http [Net::HTTP::Persistent] The live persistent connection.
     # @return [void]
@@ -155,7 +156,10 @@ module FulfilApi
 
     # @return [Array] The cache key identifying a unique connection.
     def connection_cache_key
-      [configuration.merchant_id, configuration.request_options, configuration.connection_options]
+      [
+        configuration.merchant_id, configuration.request_options, configuration.connection_options,
+        configuration.retry_options, configuration.circuit_breaker
+      ]
     end
 
     # @param relative_path [String] The relative path to the API endpoint.

data/lib/fulfil_api/configuration.rb

@@ -7,22 +7,43 @@ module FulfilApi
   #   to these settings.
   class Configuration
     attr_accessor :access_token, :api_version, :merchant_id, :request_options, :tpl
-    attr_reader :connection_options
+    attr_reader :connection_options, :oauth, :retry_options
+
+    # @!attribute [rw] circuit_breaker
+    #   @return [Faulty, nil] The Faulty instance that runs every request through a
+    #     circuit per Fulfil instance, or nil to turn the circuit breaker off. See
+    #     {FulfilApi::Middleware::CircuitBreaker}.
+    attr_accessor :circuit_breaker
 
     DEFAULT_API_VERSION = "v2"
     DEFAULT_REQUEST_OPTIONS = { open_timeout: 1, read_timeout: 5, write_timeout: 5, timeout: 5 }.freeze
 
     # Tuning for the persistent (keep-alive) HTTP connection.
     #
-    # `max_retries` re-enables Ruby's built-in retry for idempotent requests
-    #   (GET/HEAD/PUT/DELETE/OPTIONS). The `net_http_persistent` adapter forces
-    #   it to 0, which means a keep-alive socket the server has already dropped
-    #   surfaces as a read timeout instead of being transparently retried on a
-    #   fresh socket. POST is never auto-retried, so this is side-effect safe.
-    #
     # `idle_timeout` and `pool_size` are passed through to the underlying
     #   Net::HTTP::Persistent connection when set.
-    DEFAULT_CONNECTION_OPTIONS = { max_retries: 1 }.freeze
+    #
+    # `max_retries` re-enables Ruby's built-in retry, which retries every request
+    #   Net::HTTP considers idempotent (GET/HEAD/PUT/DELETE/OPTIONS) whatever its
+    #   endpoint. Fulfil writes through PUT too, so it is off by default in favour
+    #   of the endpoint scoped {#retry_options}.
+    DEFAULT_CONNECTION_OPTIONS = {}.freeze
+
+    # Retries for requests that failed before Fulfil could answer them: a dropped
+    #   keep-alive socket, a refused connection or a timeout.
+    #
+    # `max_retries` caps the number of retries per request. `requests` maps an
+    #   HTTP verb onto the endpoints that are safe to retry, either `true` for every
+    #   endpoint or a list of patterns matched against the request path. Reads in
+    #   Fulfil go out as PUT requests to `search_read` and `search_count`, so those
+    #   are retried; every other PUT may write and is not.
+    DEFAULT_RETRY_OPTIONS = {
+      max_retries: 1,
+      requests: {
+        get: true,
+        put: [%r{/search_read\z}, %r{/search_count\z}]
+      }
+    }.freeze
 
     # Initializes the configuration with optional settings.
     #
@@ -48,8 +69,49 @@ module FulfilApi
       @connection_options = DEFAULT_CONNECTION_OPTIONS.merge(options || {})
     end
 
+    # Assigns the credentials of the OAuth app that was registered in Fulfil's
+    #   authentication dashboard. Assigning `nil` resets to the defaults.
+    #
+    # @param options [Hash, FulfilApi::OAuth::Configuration, nil] The OAuth options to apply.
+    # @return [void]
+    def oauth=(options)
+      @oauth =
+        case options
+        when OAuth::Configuration then options
+        when Hash, NilClass then OAuth::Configuration.new(options)
+        else raise ArgumentError, "Expected Hash or FulfilApi::OAuth::Configuration, got #{options.class} instead"
+        end
+    end
+
+    # Merges the provided retry options over the defaults. Assigning `nil` resets
+    #   to the defaults.
+    #
+    # @example retrying reads three times, and one write endpoint as well
+    #   config.retry_options = {
+    #     max_retries: 3,
+    #     requests: { get: true, put: [%r{/search_read\z}, %r{/stock.shipment.out/hold\z}] }
+    #   }
+    #
+    # @param options [Hash, nil] The retry options to apply.
+    # @return [void]
+    def retry_options=(options)
+      @retry_options = DEFAULT_RETRY_OPTIONS.merge(options || {})
+    end
+
     private
 
+    # {FulfilApi.with_config} duplicates the active configuration, which would
+    #   otherwise share the very same OAuth configuration object with the copy.
+    #   A block that changes an OAuth option would then leak that change into
+    #   the configuration it was supposed to be reverted to.
+    #
+    # @param source [FulfilApi::Configuration] The configuration being copied.
+    # @return [void]
+    def initialize_copy(source)
+      super
+      @oauth = source.oauth.dup
+    end
+
     # Sets the default options for the gem configuration.
     #
     # This method is called during initialization to ensure all configuration
@@ -60,6 +122,8 @@ module FulfilApi
       self.api_version = DEFAULT_API_VERSION if api_version.nil?
       self.request_options = DEFAULT_REQUEST_OPTIONS if request_options.nil?
       self.connection_options = nil if connection_options.nil?
+      self.oauth = nil if oauth.nil?
+      self.retry_options = nil if retry_options.nil?
     end
   end
 

data/lib/fulfil_api/engine.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+require "rails/engine"
+
+module FulfilApi
+  # Ships the OAuth flow as a mountable engine, so a Rails application only has
+  #   to mount it and point Fulfil's whitelisted redirect URL at its callback.
+  #
+  # @example config/routes.rb
+  #   mount FulfilApi::Engine => "/fulfil"
+  class Engine < ::Rails::Engine
+    isolate_namespace FulfilApi
+  end
+end

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/middleware/circuit_breaker.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module FulfilApi
+  module Middleware
+    # The {FulfilApi::Middleware::CircuitBreaker} runs every request through a
+    #   [Faulty](https://github.com/ParentSquare/faulty) circuit, so a Fulfil instance
+    #   that keeps failing is skipped for a while instead of tying up the threads of an
+    #   application that talks to several of them.
+    #
+    # Each Fulfil instance gets its own circuit, shared by the {FulfilApi::Client} and
+    #   the {FulfilApi::TplClient}. The thresholds and the storage come from the
+    #   configured Faulty instance.
+    #
+    # It wraps the retries, so a request that failed after retrying counts as one
+    #   failure. A response with a 4xx status code is an answer, and doesn't count.
+    class CircuitBreaker < Faraday::Middleware
+      # The errors that count as a failure of the Fulfil instance.
+      FAILURES = [Faraday::ConnectionFailed, Faraday::ServerError, Faraday::TimeoutError].freeze
+
+      # Faulty wraps the error of a failed request into one of its own. Raising the
+      #   original error instead keeps the gem's errors the same with or without a
+      #   circuit breaker. Only an open circuit, which has no original error, raises
+      #   a {FulfilApi::CircuitOpen}.
+      ERROR_MAPPER = lambda do |_error_name, cause, circuit|
+        cause || FulfilApi::CircuitOpen.new("#{circuit.name} is open after repeated failures", details: {})
+      end
+
+      # @param env [Faraday::Env] The environment of the request.
+      # @raise [FulfilApi::CircuitOpen] When the circuit of the Fulfil instance is open.
+      # @return [Faraday::Response]
+      def call(env)
+        circuit_for(env).run { @app.call(env) }
+      end
+
+      private
+
+      # @param env [Faraday::Env] The environment of the request.
+      # @return [Faulty::Circuit]
+      def circuit_for(env)
+        options[:faulty].circuit("fulfil_api:#{env.url.host}", errors: FAILURES, error_mapper: ERROR_MAPPER)
+      end
+    end
+  end
+end

data/lib/fulfil_api/middleware.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module FulfilApi
+  # The {FulfilApi::Middleware} sets up the Faraday middleware that both the
+  #   {FulfilApi::Client} and the {FulfilApi::TplClient} run their requests through.
+  module Middleware
+    # The errors raised when a request never got an answer from Fulfil. An HTTP
+    #   error response is an answer, and is never retried.
+    RETRYABLE_ERRORS = [Faraday::ConnectionFailed, Faraday::TimeoutError].freeze
+
+    class << self
+      # Adds the gem's middleware to a Faraday connection. Middleware runs in the
+      #   order it's added, so the first one wraps everything after it.
+      #
+      # @param connection [Faraday::Connection] The connection being built.
+      # @param configuration [FulfilApi::Configuration] The configuration of the client.
+      # @return [void]
+      def apply(connection, configuration)
+        connection.use CircuitBreaker, faulty: configuration.circuit_breaker if configuration.circuit_breaker
+        connection.request :retry, retry_middleware_options(configuration.retry_options)
+      end
+
+      private
+
+      # Translates the {FulfilApi::Configuration#retry_options} into the options of
+      #   the `faraday-retry` middleware.
+      #
+      # Ruby's built-in retry, and `faraday-retry` by default, treat every PUT as
+      #   idempotent, while Fulfil uses PUT both to read (`search_read`,
+      #   `search_count`) and to write (updating a record, holding a shipment).
+      #   Retrying a write that timed out could apply it twice, so no HTTP verb is
+      #   retried wholesale and every request is matched against the configured
+      #   endpoints instead.
+      #
+      # @param options [Hash] The retry options of the configuration.
+      # @return [Hash]
+      def retry_middleware_options(options)
+        requests = options.fetch(:requests, {})
+
+        {
+          max: options.fetch(:max_retries, 0),
+          methods: [],
+          exceptions: RETRYABLE_ERRORS,
+          retry_if: ->(env, _exception) { retryable_request?(env, requests) }
+        }
+      end
+
+      # @param env [Faraday::Env] The environment of the request.
+      # @param requests [Hash] The HTTP verbs mapped onto their retryable endpoints.
+      # @return [true, false] Whether the endpoint of the request is safe to retry.
+      def retryable_request?(env, requests)
+        patterns = requests[env.method]
+        return true if patterns == true
+
+        Array(patterns).any? { |pattern| pattern.match?(env.url.path) }
+      end
+    end
+  end
+end