sp_api_clients 2.0.0

data/lib/amazon_sp_clients/v2/credentials.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+require 'amazon_sp_clients/v2/errors'
+require 'amazon_sp_clients/v2/token'
+
+module AmazonSpClients
+  module V2
+    # Where the client gets the access token for each request. Every
+    # kind answers one message, +access_token+, and returns the value to
+    # the caller: the token is never parked on a shared object and read
+    # back in a second step, so a request cannot carry another thread's
+    # token.
+    module Credentials
+      # Asks a block for the current token before every request. This
+      # is the production path: the host refreshes tokens out of band
+      # and the block returns whatever it holds now, so a client that
+      # runs for hours keeps sending fresh tokens.
+      #
+      #   Credentials::Callback.new { store.access_token }
+      #
+      # The block's value goes on the wire as it is; a missing token
+      # surfaces as Amazon's own 401 or 403.
+      class Callback
+        # @yieldreturn [String] the current access token
+        def initialize(&block)
+          raise ArgumentError, 'a block returning the access token is required' unless block
+
+          @block = block
+        end
+
+        # @return [String]
+        def access_token = @block.call
+      end
+
+      # Exchanges a refresh token with LWA and caches the result until it
+      # expires. One exchange per expiry, even when many threads ask at
+      # once: the expiry check runs again under the lock.
+      class RefreshToken
+        # @param lwa [LWA] anything answering +exchange(refresh_token:)+ with a Token
+        # @param refresh_token [String] the refresh token to start from
+        def initialize(lwa, refresh_token)
+          @lwa = lwa
+          @initial_refresh_token = refresh_token
+          @token = nil
+          @mutex = Mutex.new
+        end
+
+        # @return [String] a fresh access token, exchanging when needed
+        def access_token
+          token = @token
+          return token.access_token if token && !token.expired?
+
+          @mutex.synchronize do
+            token = @token
+            return token.access_token if token && !token.expired?
+
+            token = exchange
+            @token = token
+            token.access_token
+          end
+        end
+
+        # The refresh token the next exchange will send: the latest one
+        # LWA returned, else the initial one. Persist it if it changes.
+        #
+        # @return [String]
+        def refresh_token
+          @token&.refresh_token || @initial_refresh_token
+        end
+
+        # Refresh tokens stay out of consoles and error trackers.
+        #
+        # @return [String]
+        def inspect
+          "#<#{self.class.name} refresh_token=#{FILTERED} token=#{@token.inspect}>"
+        end
+
+        private
+
+        # LWA may leave refresh_token out of the response; keep the one
+        # we have, so the stored Token always knows what to send next.
+        def exchange
+          token = @lwa.exchange(refresh_token: refresh_token)
+          return token if token.refresh_token
+
+          token.with(refresh_token: refresh_token)
+        end
+      end
+    end
+  end
+end

data/lib/amazon_sp_clients/v2/documents.rb

@@ -0,0 +1,115 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'zlib'
+require 'faraday'
+require 'multi_xml'
+require 'amazon_sp_clients/adapter_loader'
+require 'amazon_sp_clients/v2/config'
+require 'amazon_sp_clients/v2/errors'
+require 'amazon_sp_clients/v2/error_mapper'
+
+module AmazonSpClients
+  module V2
+    # Feed and report documents live on presigned S3 urls: outside the
+    # SP-API host, without the access token. A feed goes out in three
+    # steps (create the document, PUT the content to its url, create the
+    # feed); feed results and reports come back by GET, gzipped when the
+    # document says so.
+    #
+    # Every +document+ argument is the payload Hash the Feeds or Reports
+    # API returned for it (+:url+, +:compressionAlgorithm+).
+    class Documents
+      # Value of +compressionAlgorithm+ for gzipped documents.
+      GZIP = 'GZIP'
+      # Set on uploads; read on downloads to pick the parser.
+      CONTENT_TYPE_HEADER = 'Content-Type'
+      # Content types parsed as JSON; anything else is parsed as XML.
+      JSON_TYPES = /json/i
+
+      # @param config [Config] timeouts and user agent
+      def initialize(config)
+        @config = config
+        @errors = ErrorMapper.new(:documents)
+        @conn = build_connection
+      end
+
+      # @param document [Hash] payload of createFeedDocument
+      # @param content_type [String] the one given to createFeedDocument
+      # @param body [String] feed content
+      # @return [nil]
+      # @raise [DocumentError, ConnectionError]
+      def upload(document, content_type, body)
+        send_request(:put, url_of(document), body, CONTENT_TYPE_HEADER => content_type)
+
+        nil
+      end
+
+      # @param document [Hash] payload of getFeedDocument
+      # @return [Hash] the processing report, string-keyed; JSON or XML by content type
+      # @raise [DocumentError, ConnectionError]
+      def download_feed_result(document)
+        response = fetch(document)
+
+        parse(inflate(response.body, document), response.headers[CONTENT_TYPE_HEADER])
+      end
+
+      # @param document [Hash] payload of getReportDocument
+      # @return [String] the report; UTF-8 tagged when it was gzipped,
+      #   otherwise as delivered
+      # @raise [DocumentError, ConnectionError]
+      def download_report_document(document)
+        inflate(fetch(document).body, document)
+      end
+
+      private
+
+      def build_connection
+        options = { timeout: @config.timeout, open_timeout: @config.open_timeout }
+        headers = { 'User-Agent' => @config.user_agent }
+
+        Faraday.new(request: options, headers: headers) do |conn|
+          conn.adapter Faraday::Adapter::HTTPClient
+        end
+      end
+
+      def fetch(document)
+        send_request(:get, url_of(document), nil, {})
+      end
+
+      # The payload of createFeedDocument, getFeedDocument or
+      # getReportDocument as ApiResponse#payload returns it: symbol keys.
+      def url_of(document)
+        document.fetch(:url) do
+          keys = document.keys.inspect
+          raise ArgumentError, "document payload without a :url key (keys: #{keys})"
+        end
+      end
+
+      def send_request(method, url, body, headers)
+        response = @conn.run_request(method, url, body, headers)
+
+        @errors.check!(response)
+      rescue *ErrorMapper::TRANSPORT_ERRORS => e
+        raise @errors.transport_error(e, method: method, url: url)
+      end
+
+      # Zlib.gunzip returns binary; the documents are text.
+      def inflate(body, document)
+        return body unless document[:compressionAlgorithm].to_s.casecmp?(GZIP)
+
+        Zlib.gunzip(body).force_encoding(Encoding::UTF_8)
+      rescue Zlib::Error => e
+        raise DocumentError, "could not inflate the document: #{e.message}"
+      end
+
+      def parse(body, content_type)
+        return JSON.parse(body) if content_type.to_s.match?(JSON_TYPES)
+
+        MultiXml.parse(body)
+      rescue JSON::ParserError, MultiXml::ParseError => e
+        raise DocumentError, "could not parse the document: #{e.message}"
+      end
+    end
+  end
+end

data/lib/amazon_sp_clients/v2/error_mapper.rb

@@ -0,0 +1,235 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'uri'
+require 'faraday'
+require 'httpclient'
+require 'amazon_sp_clients/api_error'
+require 'amazon_sp_clients/v2/errors'
+
+module AmazonSpClients
+  module V2
+    # Turns a Faraday response or a transport exception into the V2
+    # error for it. One mapper per service, because the three services
+    # V2 talks to fail in different shapes:
+    #
+    #   :api        SP-API; body {"errors": [{code, message, details}]}
+    #   :lwa        token endpoint; body {"error", "error_description"}
+    #   :documents  presigned S3 urls; the url carries the credential
+    class ErrorMapper
+      # The three services V2 talks to.
+      SERVICES = %i[api lwa documents].freeze
+
+      # Exceptions the HTTPClient adapter lets out of a request: Faraday's
+      # own, plus the ones it re-raises untouched. Nothing else is
+      # wrapped, so an exception delivered by Thread#raise passes through.
+      TRANSPORT_ERRORS = [
+        Faraday::Error, HTTPClient::KeepAliveDisconnected, SystemCallError, IOError, SocketError
+      ].freeze
+
+      # Too Many Requests; also what LWA answers when the token endpoint
+      # is called too often.
+      THROTTLED_STATUS = 429
+      # SP-API statuses with their own error class; other 4xx and 5xx
+      # fall to ClientError and ServerError.
+      STATUS_ERRORS = {
+        400 => BadRequestError,
+        401 => UnauthorizedError,
+        403 => ForbiddenError,
+        404 => NotFoundError,
+        THROTTLED_STATUS => ThrottledError
+      }.freeze
+      # Statuses mapped to ClientError when not in STATUS_ERRORS.
+      CLIENT_ERROR_STATUSES = (400...500)
+      # Statuses mapped to ServerError.
+      SERVER_ERROR_STATUSES = (500...600)
+
+      # LWA error codes with their own class; other codes raise AuthError.
+      LWA_ERRORS = {
+        'invalid_grant' => InvalidGrantError,
+        'invalid_client' => InvalidClientError
+      }.freeze
+
+      # Response header carrying Amazon's request id.
+      REQUEST_ID_HEADER = 'x-amzn-RequestId'
+      # Response header carrying the usage plan rate, in requests per second.
+      RATE_LIMIT_HEADER = 'x-amzn-RateLimit-Limit'
+
+      # The error ends up in consumer logs; keep secrets out of it.
+      FILTERED = V2::FILTERED
+      # Request headers replaced by FILTERED on the error.
+      SENSITIVE_HEADERS = %w[authorization x-amz-access-token x-amz-security-token].freeze
+
+      # @param service [Symbol] one of SERVICES
+      # @raise [ArgumentError] on an unknown service
+      def initialize(service)
+        raise ArgumentError, "unknown service #{service.inspect}" unless SERVICES.include?(service)
+
+        @service = service
+      end
+
+      # @param response [Faraday::Response]
+      # @return [Faraday::Response] the same response, when it is a 2xx
+      # @raise [Error] the mapped error otherwise
+      def check!(response)
+        env = response.env
+        raise ConnectionError.new('no status in response', **context(env)) if env.status.nil?
+        return response if response.success?
+
+        raise error_for(env)
+      end
+
+      # A 2xx response whose body could not be used, with the same
+      # redacted context every other error carries.
+      #
+      # @param message [String]
+      # @param response [Faraday::Response]
+      # @return [ParseError]
+      def parse_error(message, response)
+        ParseError.new(message, **context(response.env))
+      end
+
+      # Wraps an exception raised by the transport. Call it inside the
+      # rescue, so Ruby records the original exception as +cause+.
+      #
+      # @param exception [Exception]
+      # @param method [Symbol] HTTP method of the failed request
+      # @param url [String] full url of the failed request
+      # @return [ConnectionError]
+      def transport_error(exception, method:, url:)
+        klass = exception.is_a?(Faraday::TimeoutError) ? TimeoutError : ConnectionError
+
+        klass.new("#{exception.class}: #{exception.message}",
+                  request: { method: method, url: redacted_url(url), path: URI(url).path })
+      end
+
+      private
+
+      def error_for(env)
+        case @service
+        when :api then api_error(env)
+        when :lwa then lwa_error(env)
+        else document_error(env)
+        end
+      end
+
+      def api_error(env)
+        parsed = parse_json(env.body)
+        errors = api_errors(parsed)
+        messages = parsed && api_messages(parsed, errors)
+        klass = STATUS_ERRORS.fetch(env.status) { generic_class(env.status) }
+
+        klass.new("#{env.status} #{summary(env.body, messages)}",
+                  errors: errors, rate_limit: rate_limit(env), **context(env))
+      end
+
+      # The documented shape is {errors: [{code, message, details}]}; this
+      # is the last line of defence, so anything else yields no errors
+      # rather than an exception.
+      def api_errors(parsed)
+        list = parsed.is_a?(Hash) ? parsed[:errors] : parsed
+        return [] unless list.is_a?(Array)
+
+        ApiError.new(list.grep(Hash)).errors
+      end
+
+      # The documented errors, or the one-line body API Gateway sends when
+      # a request never reaches SP-API, e.g. {"message":"Forbidden"}.
+      def api_messages(parsed, errors)
+        return errors.map { |e| describe(e) } if errors.any?
+
+        message = parsed[:message] if parsed.is_a?(Hash)
+        message.to_s.empty? ? [] : [message.to_s]
+      end
+
+      def lwa_error(env)
+        parsed = parse_json(env.body)
+        parsed = nil unless parsed.is_a?(Hash)
+        code = parsed&.fetch(:error, nil)
+        description = parsed&.fetch(:error_description, nil)
+        messages = parsed && [[code, description].compact.join(': ')].reject(&:empty?)
+        message = "#{env.status} #{summary(env.body, messages)}"
+        return ServerError.new(message, **context(env)) if SERVER_ERROR_STATUSES.cover?(env.status)
+        return ThrottledError.new(message, **context(env)) if env.status == THROTTLED_STATUS
+
+        LWA_ERRORS.fetch(code, AuthError)
+                  .new(message, code: code, description: description, **context(env))
+      end
+
+      def document_error(env)
+        DocumentError.new("#{env.status} #{env.reason_phrase}".strip, **context(env))
+      end
+
+      # Status text: the parsed error messages, or why there are none.
+      # +messages+ is nil when the body was not JSON.
+      def summary(body, messages)
+        return '(no body)' if body.nil? || body.empty?
+        return '(body is not JSON)' if messages.nil?
+        return '(no error details)' if messages.empty?
+
+        messages.join('; ')
+      end
+
+      def describe(error)
+        text = "#{error.code}: #{error.message}"
+        return text if error.details.to_s.empty?
+
+        "#{text} (#{error.details})"
+      end
+
+      def generic_class(status)
+        return ClientError if CLIENT_ERROR_STATUSES.cover?(status)
+        return ServerError if SERVER_ERROR_STATUSES.cover?(status)
+
+        ResponseError
+      end
+
+      def parse_json(body)
+        return nil if body.nil? || body.empty?
+
+        JSON.parse(body, symbolize_names: true)
+      rescue JSON::ParserError
+        nil
+      end
+
+      def context(env)
+        {
+          status: env.status,
+          request_id: env.response_headers&.[](REQUEST_ID_HEADER),
+          request: request_details(env),
+          response: { status: env.status, headers: env.response_headers, body: env.body }
+        }
+      end
+
+      def request_details(env)
+        {
+          method: env.method,
+          url: redacted_url(env.url.to_s),
+          path: env.url.path,
+          headers: redacted_headers(env.request_headers),
+          body: @service == :lwa ? FILTERED : env.request_body
+        }
+      end
+
+      # A copy that keeps Faraday's case-insensitive lookup.
+      def redacted_headers(headers)
+        redacted = Faraday::Utils::Headers.new(headers || {})
+        SENSITIVE_HEADERS.each do |name|
+          redacted[name] = FILTERED unless redacted[name].nil?
+        end
+        redacted
+      end
+
+      # Presigned S3 urls carry their credential in the query string.
+      def redacted_url(url)
+        return url unless @service == :documents
+
+        URI(url).tap { |uri| uri.query = nil }.to_s
+      end
+
+      def rate_limit(env)
+        env.response_headers&.[](RATE_LIMIT_HEADER)&.to_f
+      end
+    end
+  end
+end

data/lib/amazon_sp_clients/v2/errors.rb

@@ -0,0 +1,117 @@
+# frozen_string_literal: true
+
+module AmazonSpClients
+  module V2
+    # Replaces a secret wherever V2 renders one: error payloads and
+    # inspect output.
+    FILTERED = '[FILTERED]'
+
+    # Base class of every error V2 raises.
+    #
+    # Match on the class and on +code+, never on the message. Rescue
+    # subclasses before their parents: ThrottledError, UnauthorizedError,
+    # ForbiddenError and NotFoundError before ClientError; TimeoutError
+    # before ConnectionError. The exception that caused a transport
+    # error is available as +cause+.
+    class Error < StandardError
+      # @return [Integer, nil] HTTP status, when a response was received
+      attr_reader :status
+      # @return [String, nil] Amazon's request id (x-amzn-RequestId)
+      attr_reader :request_id
+      # @return [Hash, nil] method, url, path, headers and body of the
+      #   request; secrets redacted
+      attr_reader :request
+      # @return [Hash, nil] status, headers and body of the response
+      attr_reader :response
+
+      # @param message [String, nil]
+      def initialize(message = nil, status: nil, request_id: nil, request: nil, response: nil)
+        super(message)
+        @status = status
+        @request_id = request_id
+        @request = request
+        @response = response
+      end
+    end
+
+    # The request got no usable response: connection refused, DNS or
+    # SSL failure, a dropped keep-alive socket, a malformed response, a
+    # response without status.
+    class ConnectionError < Error; end
+
+    # The request timed out while connecting, reading or writing.
+    class TimeoutError < ConnectionError; end
+
+    # A 2xx response whose body is not valid JSON.
+    class ParseError < Error; end
+
+    # The LWA token endpoint rejected the request (4xx).
+    class AuthError < Error
+      # @return [String, nil] LWA error code, e.g. 'invalid_grant'
+      attr_reader :code
+      # @return [String, nil] LWA error description
+      attr_reader :description
+
+      # @param message [String, nil]
+      # @param code [String, nil]
+      # @param description [String, nil]
+      def initialize(message = nil, code: nil, description: nil, **context)
+        super(message, **context)
+        @code = code
+        @description = description
+      end
+    end
+
+    # The refresh token is revoked or invalid (LWA +invalid_grant+).
+    class InvalidGrantError < AuthError; end
+
+    # The app credentials are wrong (LWA +invalid_client+).
+    class InvalidClientError < AuthError; end
+
+    # SP-API answered with a non-2xx status.
+    class ResponseError < Error
+      # @return [Array<AmazonSpClients::ApiError::Error>] parsed SP-API
+      #   errors (code, message, details); empty when the body had none
+      attr_reader :errors
+      # @return [Float, nil] x-amzn-RateLimit-Limit header, when present
+      attr_reader :rate_limit
+
+      # @param message [String, nil]
+      # @param errors [Array<AmazonSpClients::ApiError::Error>]
+      # @param rate_limit [Float, nil]
+      def initialize(message = nil, errors: [], rate_limit: nil, **context)
+        super(message, **context)
+        @errors = errors
+        @rate_limit = rate_limit
+      end
+
+      # @return [String, nil] code of the first SP-API error
+      def code = errors.first&.code
+    end
+
+    # 429: the request was throttled. Kept out of ClientError on
+    # purpose, so a +rescue ClientError+ cannot swallow it.
+    class ThrottledError < ResponseError; end
+
+    # Any 4xx other than 429.
+    class ClientError < ResponseError; end
+
+    # 400.
+    class BadRequestError < ClientError; end
+
+    # 401.
+    class UnauthorizedError < ClientError; end
+
+    # 403.
+    class ForbiddenError < ClientError; end
+
+    # 404.
+    class NotFoundError < ClientError; end
+
+    # 5xx.
+    class ServerError < ResponseError; end
+
+    # A presigned S3 upload or download failed.
+    class DocumentError < Error; end
+  end
+end

data/lib/amazon_sp_clients/v2/lwa.rb

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'faraday'
+require 'amazon_sp_clients/adapter_loader'
+require 'amazon_sp_clients/v2/config'
+require 'amazon_sp_clients/v2/errors'
+require 'amazon_sp_clients/v2/error_mapper'
+require 'amazon_sp_clients/v2/token'
+
+module AmazonSpClients
+  module V2
+    # Login with Amazon: exchanges a refresh token for an access token.
+    #
+    #   token = LWA.new(config).exchange(refresh_token: stored_refresh_token)
+    #   token.access_token   # => "Atza|..."
+    #   token.expires_at     # => Time
+    #
+    # Needs the app credentials on the config. Consumers that keep their
+    # own token store call this directly; RefreshToken credentials call
+    # it for the client.
+    class LWA
+      # Login with Amazon lives outside the SP-API hosts.
+      TOKEN_HOST = 'https://api.amazon.com'
+      # The OAuth 2 token endpoint.
+      TOKEN_PATH = '/auth/o2/token'
+      # The grant type V2 uses; grantless (client_credentials) has no consumer.
+      REFRESH_GRANT = 'refresh_token'
+
+      # @param config [Config] with client_id and client_secret set
+      # @raise [ArgumentError] when the app credentials are missing
+      def initialize(config)
+        if config.client_id.nil? || config.client_secret.nil?
+          raise ArgumentError, 'config needs client_id and client_secret'
+        end
+
+        @config = config
+        @errors = ErrorMapper.new(:lwa)
+        @conn = build_connection
+      end
+
+      # @param refresh_token [String]
+      # @return [Token]
+      # @raise [AuthError] when LWA rejects the grant (e.g. InvalidGrantError)
+      # @raise [ConnectionError, ParseError, ServerError]
+      def exchange(refresh_token:)
+        form = {
+          grant_type: REFRESH_GRANT,
+          client_id: @config.client_id,
+          client_secret: @config.client_secret,
+          refresh_token: refresh_token
+        }
+
+        build_token(post(form))
+      end
+
+      private
+
+      def build_connection
+        options = { timeout: @config.timeout, open_timeout: @config.open_timeout }
+        headers = { 'User-Agent' => @config.user_agent }
+
+        Faraday.new(url: TOKEN_HOST, request: options, headers: headers) do |conn|
+          conn.request :url_encoded
+          conn.adapter Faraday::Adapter::HTTPClient
+        end
+      end
+
+      def post(form)
+        response = @conn.post(TOKEN_PATH, form)
+
+        @errors.check!(response)
+      rescue *ErrorMapper::TRANSPORT_ERRORS => e
+        raise @errors.transport_error(e, method: :post, url: "#{TOKEN_HOST}#{TOKEN_PATH}")
+      end
+
+      def build_token(response)
+        body = parse(response)
+        expires_in = body[:expires_in]
+
+        Token.new(
+          access_token: body[:access_token],
+          token_type: body[:token_type],
+          expires_in: expires_in,
+          expires_at: expires_in && (Time.now.utc + expires_in),
+          refresh_token: body[:refresh_token]
+        )
+      end
+
+      def parse(response)
+        body = JSON.parse(response.body, symbolize_names: true)
+        return body if body.is_a?(Hash) && body[:access_token]
+
+        raise @errors.parse_error('LWA response has no access_token', response)
+      rescue JSON::ParserError => e
+        raise @errors.parse_error("LWA response is not JSON: #{e.message}", response)
+      end
+    end
+  end
+end