stripe 1.27.2 → 5.33.0

data/lib/stripe/connection_manager.rb

@@ -0,0 +1,164 @@
+# frozen_string_literal: true
+
+module Stripe
+  # Manages connections across multiple hosts which is useful because the
+  # library may connect to multiple hosts during a typical session (main API,
+  # Connect, Uploads). Ruby doesn't provide an easy way to make this happen
+  # easily, so this class is designed to track what we're connected to and
+  # manage the lifecycle of those connections.
+  #
+  # Note that this class in itself is *not* thread safe. We expect it to be
+  # instantiated once per thread.
+  class ConnectionManager
+    # Timestamp (in seconds procured from the system's monotonic clock)
+    # indicating when the connection manager last made a request. This is used
+    # by `StripeClient` to determine whether a connection manager should be
+    # garbage collected or not.
+    attr_reader :last_used
+    attr_reader :config
+
+    def initialize(config = Stripe.config)
+      @config = config
+      @active_connections = {}
+      @last_used = Util.monotonic_time
+
+      # A connection manager may be accessed across threads as one thread makes
+      # requests on it while another is trying to clear it (either because it's
+      # trying to garbage collect the manager or trying to clear it because a
+      # configuration setting has changed). That's probably thread-safe already
+      # because of Ruby's GIL, but just in case the library's running on JRuby
+      # or the like, use a mutex to synchronize access in this connection
+      # manager.
+      @mutex = Mutex.new
+    end
+
+    # Finishes any active connections by closing their TCP connection and
+    # clears them from internal tracking.
+    def clear
+      @mutex.synchronize do
+        @active_connections.each do |_, connection|
+          connection.finish
+        end
+        @active_connections = {}
+      end
+    end
+
+    # Gets a connection for a given URI. This is for internal use only as it's
+    # subject to change (we've moved between HTTP client schemes in the past
+    # and may do it again).
+    #
+    # `uri` is expected to be a string.
+    def connection_for(uri)
+      @mutex.synchronize do
+        u = URI.parse(uri)
+        connection = @active_connections[[u.host, u.port]]
+
+        if connection.nil?
+          connection = create_connection(u)
+          connection.start
+
+          @active_connections[[u.host, u.port]] = connection
+        end
+
+        connection
+      end
+    end
+
+    # Executes an HTTP request to the given URI with the given method. Also
+    # allows a request body, headers, and query string to be specified.
+    def execute_request(method, uri, body: nil, headers: nil, query: nil)
+      # Perform some basic argument validation because it's easy to get
+      # confused between strings and hashes for things like body and query
+      # parameters.
+      raise ArgumentError, "method should be a symbol" \
+        unless method.is_a?(Symbol)
+      raise ArgumentError, "uri should be a string" \
+        unless uri.is_a?(String)
+      raise ArgumentError, "body should be a string" \
+        if body && !body.is_a?(String)
+      raise ArgumentError, "headers should be a hash" \
+        if headers && !headers.is_a?(Hash)
+      raise ArgumentError, "query should be a string" \
+        if query && !query.is_a?(String)
+
+      @last_used = Util.monotonic_time
+
+      connection = connection_for(uri)
+
+      u = URI.parse(uri)
+      path = if query
+               u.path + "?" + query
+             else
+               u.path
+             end
+
+      @mutex.synchronize do
+        connection.send_request(method.to_s.upcase, path, body, headers)
+      end
+    end
+
+    #
+    # private
+    #
+
+    # `uri` should be a parsed `URI` object.
+    private def create_connection(uri)
+      # These all come back as `nil` if no proxy is configured.
+      proxy_host, proxy_port, proxy_user, proxy_pass = proxy_parts
+
+      connection = Net::HTTP.new(uri.host, uri.port,
+                                 proxy_host, proxy_port,
+                                 proxy_user, proxy_pass)
+
+      # Time in seconds within which Net::HTTP will try to reuse an already
+      # open connection when issuing a new operation. Outside this window, Ruby
+      # will transparently close and re-open the connection without trying to
+      # reuse it.
+      #
+      # Ruby's default of 2 seconds is almost certainly too short. Here I've
+      # reused Go's default for `DefaultTransport`.
+      connection.keep_alive_timeout = 30
+
+      connection.open_timeout = config.open_timeout
+      connection.read_timeout = config.read_timeout
+      if connection.respond_to?(:write_timeout=)
+        connection.write_timeout = config.write_timeout
+      end
+
+      connection.use_ssl = uri.scheme == "https"
+
+      if config.verify_ssl_certs
+        connection.verify_mode = OpenSSL::SSL::VERIFY_PEER
+        connection.cert_store = config.ca_store
+      else
+        connection.verify_mode = OpenSSL::SSL::VERIFY_NONE
+        warn_ssl_verify_none
+      end
+
+      connection
+    end
+
+    # `Net::HTTP` somewhat awkwardly requires each component of a proxy URI
+    # (host, port, etc.) rather than the URI itself. This method simply parses
+    # out those pieces to make passing them into a new connection a little less
+    # ugly.
+    private def proxy_parts
+      if config.proxy.nil?
+        [nil, nil, nil, nil]
+      else
+        u = URI.parse(config.proxy)
+        [u.host, u.port, u.user, u.password]
+      end
+    end
+
+    private def warn_ssl_verify_none
+      return if @verify_ssl_warned
+
+      @verify_ssl_warned = true
+      warn("WARNING: Running without SSL cert verification. " \
+        "You should never do this in production. " \
+        "Execute `Stripe.verify_ssl_certs = true` to enable " \
+        "verification.")
+    end
+  end
+end

data/lib/stripe/error_object.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+module Stripe
+  # Represents an error object as returned by the API.
+  #
+  # @see https://stripe.com/docs/api/errors
+  class ErrorObject < StripeObject
+    # Unlike other objects, we explicitly declare getter methods here. This
+    # is because the API doesn't return `null` values for fields on this
+    # object, rather the fields are omitted entirely. Not declaring the getter
+    # methods would cause users to run into `NoMethodError` exceptions and
+    # get in the way of generic error handling.
+
+    # For card errors, the ID of the failed charge.
+    def charge
+      @values[:charge]
+    end
+
+    # For some errors that could be handled programmatically, a short string
+    # indicating the error code reported.
+    def code
+      @values[:code]
+    end
+
+    # For card errors resulting from a card issuer decline, a short string
+    # indicating the card issuer's reason for the decline if they provide one.
+    def decline_code
+      @values[:decline_code]
+    end
+
+    # A URL to more information about the error code reported.
+    def doc_url
+      @values[:doc_url]
+    end
+
+    # A human-readable message providing more details about the error. For card
+    # errors, these messages can be shown to your users.
+    def message
+      @values[:message]
+    end
+
+    # If the error is parameter-specific, the parameter related to the error.
+    # For example, you can use this to display a message near the correct form
+    # field.
+    def param
+      @values[:param]
+    end
+
+    # The PaymentIntent object for errors returned on a request involving a
+    # PaymentIntent.
+    def payment_intent
+      @values[:payment_intent]
+    end
+
+    # The PaymentMethod object for errors returned on a request involving a
+    # PaymentMethod.
+    def payment_method
+      @values[:payment_method]
+    end
+
+    # The SetupIntent object for errors returned on a request involving a
+    # SetupIntent.
+    def setup_intent
+      @values[:setup_intent]
+    end
+
+    # The source object for errors returned on a request involving a source.
+    def source
+      @values[:source]
+    end
+
+    # The type of error returned. One of `api_connection_error`, `api_error`,
+    # `authentication_error`, `card_error`, `idempotency_error`,
+    # `invalid_request_error`, or `rate_limit_error`.
+    def type
+      @values[:type]
+    end
+  end
+
+  # Represents on OAuth error returned by the OAuth API.
+  #
+  # @see https://stripe.com/docs/connect/oauth-reference#post-token-errors
+  class OAuthErrorObject < StripeObject
+    # A unique error code per error type.
+    def error
+      @values[:error]
+    end
+
+    # A human readable description of the error.
+    def error_description
+      @values[:error_description]
+    end
+  end
+end

data/lib/stripe/errors.rb

@@ -0,0 +1,177 @@
+# frozen_string_literal: true
+
+module Stripe
+  # StripeError is the base error from which all other more specific Stripe
+  # errors derive.
+  class StripeError < StandardError
+    attr_reader :message
+
+    # Response contains a StripeResponse object that has some basic information
+    # about the response that conveyed the error.
+    attr_accessor :response
+
+    attr_reader :code
+    attr_reader :error
+    attr_reader :http_body
+    attr_reader :http_headers
+    attr_reader :http_status
+    attr_reader :json_body # equivalent to #data
+    attr_reader :request_id
+
+    # Initializes a StripeError.
+    def initialize(message = nil, http_status: nil, http_body: nil,
+                   json_body: nil, http_headers: nil, code: nil)
+      @message = message
+      @http_status = http_status
+      @http_body = http_body
+      @http_headers = http_headers || {}
+      @idempotent_replayed = @http_headers["idempotent-replayed"] == "true"
+      @json_body = json_body
+      @code = code
+      @request_id = @http_headers["request-id"]
+      @error = construct_error_object
+    end
+
+    def construct_error_object
+      return nil if @json_body.nil? || !@json_body.key?(:error)
+
+      ErrorObject.construct_from(@json_body[:error])
+    end
+
+    # Whether the error was the result of an idempotent replay, meaning that it
+    # originally occurred on a previous request and is being replayed back
+    # because the user sent the same idempotency key for this one.
+    def idempotent_replayed?
+      @idempotent_replayed
+    end
+
+    def to_s
+      status_string = @http_status.nil? ? "" : "(Status #{@http_status}) "
+      id_string = @request_id.nil? ? "" : "(Request #{@request_id}) "
+      "#{status_string}#{id_string}#{@message}"
+    end
+  end
+
+  # AuthenticationError is raised when invalid credentials are used to connect
+  # to Stripe's servers.
+  class AuthenticationError < StripeError
+  end
+
+  # APIConnectionError is raised in the event that the SDK can't connect to
+  # Stripe's servers. That can be for a variety of different reasons from a
+  # downed network to a bad TLS certificate.
+  class APIConnectionError < StripeError
+  end
+
+  # APIError is a generic error that may be raised in cases where none of the
+  # other named errors cover the problem. It could also be raised in the case
+  # that a new error has been introduced in the API, but this version of the
+  # Ruby SDK doesn't know how to handle it.
+  class APIError < StripeError
+  end
+
+  # CardError is raised when a user enters a card that can't be charged for
+  # some reason.
+  class CardError < StripeError
+    attr_reader :param
+
+    def initialize(message, param, code: nil, http_status: nil, http_body: nil,
+                   json_body: nil, http_headers: nil)
+      super(message, http_status: http_status, http_body: http_body,
+                     json_body: json_body, http_headers: http_headers,
+                     code: code)
+      @param = param
+    end
+  end
+
+  # IdempotencyError is raised in cases where an idempotency key was used
+  # improperly.
+  class IdempotencyError < StripeError
+  end
+
+  # InvalidRequestError is raised when a request is initiated with invalid
+  # parameters.
+  class InvalidRequestError < StripeError
+    attr_accessor :param
+
+    def initialize(message, param, http_status: nil, http_body: nil,
+                   json_body: nil, http_headers: nil, code: nil)
+      super(message, http_status: http_status, http_body: http_body,
+                     json_body: json_body, http_headers: http_headers,
+                     code: code)
+      @param = param
+    end
+  end
+
+  # PermissionError is raised in cases where access was attempted on a resource
+  # that wasn't allowed.
+  class PermissionError < StripeError
+  end
+
+  # RateLimitError is raised in cases where an account is putting too much load
+  # on Stripe's API servers (usually by performing too many requests). Please
+  # back off on request rate.
+  class RateLimitError < StripeError
+  end
+
+  # SignatureVerificationError is raised when the signature verification for a
+  # webhook fails
+  class SignatureVerificationError < StripeError
+    attr_accessor :sig_header
+
+    def initialize(message, sig_header, http_body: nil)
+      super(message, http_body: http_body)
+      @sig_header = sig_header
+    end
+  end
+
+  module OAuth
+    # OAuthError is raised when the OAuth API returns an error.
+    class OAuthError < StripeError
+      def initialize(code, description, http_status: nil, http_body: nil,
+                     json_body: nil, http_headers: nil)
+        super(description, http_status: http_status, http_body: http_body,
+                           json_body: json_body, http_headers: http_headers,
+                           code: code)
+      end
+
+      def construct_error_object
+        return nil if @json_body.nil?
+
+        OAuthErrorObject.construct_from(@json_body)
+      end
+    end
+
+    # InvalidClientError is raised when the client doesn't belong to you, or
+    # the API key mode (live or test) doesn't match the client mode. Or the
+    # stripe_user_id doesn't exist or isn't connected to your application.
+    class InvalidClientError < OAuthError
+    end
+
+    # InvalidGrantError is raised when a specified code doesn't exist, is
+    # expired, has been used, or doesn't belong to you; a refresh token doesn't
+    # exist, or doesn't belong to you; or if an API key's mode (live or test)
+    # doesn't match the mode of a code or refresh token.
+    class InvalidGrantError < OAuthError
+    end
+
+    # InvalidRequestError is raised when a code, refresh token, or grant type
+    # parameter is not provided, but was required.
+    class InvalidRequestError < OAuthError
+    end
+
+    # InvalidScopeError is raised when an invalid scope parameter is provided.
+    class InvalidScopeError < OAuthError
+    end
+
+    # UnsupportedGrantTypeError is raised when an unuspported grant type
+    # parameter is specified.
+    class UnsupportedGrantTypeError < OAuthError
+    end
+
+    # UnsupportedResponseTypeError is raised when an unsupported response type
+    # parameter is specified.
+    class UnsupportedResponseTypeError < OAuthError
+    end
+  end
+end

data/lib/stripe/instrumentation.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+module Stripe
+  class Instrumentation
+    # Event emitted on `request_begin` callback.
+    class RequestBeginEvent
+      attr_reader :method
+      attr_reader :path
+
+      # Arbitrary user-provided data in the form of a Ruby hash that's passed
+      # from subscribers on `request_begin` to subscribers on `request_end`.
+      # `request_begin` subscribers can set keys which will then be available
+      # in `request_end`.
+      #
+      # Note that all subscribers of `request_begin` share the same object, so
+      # they must be careful to set unique keys so as to not conflict with data
+      # set by other subscribers.
+      attr_reader :user_data
+
+      def initialize(method:, path:, user_data:)
+        @method = method
+        @path = path
+        @user_data = user_data
+        freeze
+      end
+    end
+
+    # Event emitted on `request_end` callback.
+    class RequestEndEvent
+      attr_reader :duration
+      attr_reader :http_status
+      attr_reader :method
+      attr_reader :num_retries
+      attr_reader :path
+
+      # Arbitrary user-provided data in the form of a Ruby hash that's passed
+      # from subscribers on `request_begin` to subscribers on `request_end`.
+      # `request_begin` subscribers can set keys which will then be available
+      # in `request_end`.
+      attr_reader :user_data
+
+      def initialize(duration:, http_status:, method:, num_retries:, path:,
+                     user_data: nil)
+        @duration = duration
+        @http_status = http_status
+        @method = method
+        @num_retries = num_retries
+        @path = path
+        @user_data = user_data
+        freeze
+      end
+    end
+
+    # This class was renamed for consistency. This alias is here for backwards
+    # compatibility.
+    RequestEvent = RequestEndEvent
+
+    # Returns true if there are a non-zero number of subscribers on the given
+    # topic, and false otherwise.
+    def self.any_subscribers?(topic)
+      !subscribers[topic].empty?
+    end
+
+    def self.subscribe(topic, name = rand, &block)
+      subscribers[topic][name] = block
+      name
+    end
+
+    def self.unsubscribe(topic, name)
+      subscribers[topic].delete(name)
+    end
+
+    def self.notify(topic, event)
+      subscribers[topic].each_value { |subscriber| subscriber.call(event) }
+    end
+
+    def self.subscribers
+      @subscribers ||= Hash.new { |hash, key| hash[key] = {} }
+    end
+    private_class_method :subscribers
+  end
+end