stripe 3.2.0 → 5.16.0

data/lib/stripe/api_operations/save.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module Stripe
   module APIOperations
     module Save
@@ -14,9 +16,9 @@ module Stripe
         #   object values) to be added to the request. E.g. to allow for an
         #   idempotency_key to be passed in the request headers, or for the
         #   api_key to be overwritten. See {APIOperations::Request.request}.
-        def update(id, params={}, opts={})
-          params.each do |k, v|
-            if self.protected_fields.include?(k)
+        def update(id, params = {}, opts = {})
+          params.each_key do |k|
+            if protected_fields.include?(k)
               raise ArgumentError, "Cannot update protected field: #{k}"
             end
           end
@@ -42,7 +44,7 @@ module Stripe
       #   object values) to be added to the request. E.g. to allow for an
       #   idempotency_key to be passed in the request headers, or for the
       #   api_key to be overwritten. See {APIOperations::Request.request}.
-      def save(params={}, opts={})
+      def save(params = {}, opts = {})
         # We started unintentionally (sort of) allowing attributes sent to
         # +save+ to override values used during the update. So as not to break
         # the API, this makes that official here.
@@ -51,7 +53,7 @@ module Stripe
         # Now remove any parameters that look like object attributes.
         params = params.reject { |k, _| respond_to?(k) }
 
-        values = self.serialize_params(self).merge(params)
+        values = serialize_params(self).merge(params)
 
         # note that id gets removed here our call to #url above has already
         # generated a uri for this object with an identifier baked in
@@ -62,19 +64,26 @@ module Stripe
       end
 
       def self.included(base)
+        # Set `metadata` as additive so that when it's set directly we remember
+        # to clear keys that may have been previously set by sending empty
+        # values for them.
+        #
+        # It's possible that not every object with `Save` has `metadata`, but
+        # it's a close enough heuristic, and having this option set when there
+        # is no `metadata` field is not harmful.
+        base.additive_object_param(:metadata)
+
         base.extend(ClassMethods)
       end
 
-      private
-
-      def save_url
+      private def save_url
         # This switch essentially allows us "upsert"-like functionality. If the
         # API resource doesn't have an ID set (suggesting that it's new) and
         # its class responds to .create (which comes from
         # Stripe::APIOperations::Create), then use the URL to create a new
         # resource. Otherwise, generate a URL based on the object's identifier
         # for a normal update.
-        if self[:id] == nil && self.class.respond_to?(:create)
+        if self[:id].nil? && self.class.respond_to?(:create)
           self.class.resource_url
         else
           resource_url

data/lib/stripe/api_resource.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module Stripe
   class APIResource < StripeObject
     include Stripe::APIOperations::Request
@@ -10,14 +12,18 @@ module Stripe
     attr_accessor :save_with_parent
 
     def self.class_name
-      self.name.split('::')[-1]
+      name.split("::")[-1]
     end
 
     def self.resource_url
       if self == APIResource
-        raise NotImplementedError.new('APIResource is an abstract class.  You should perform actions on its subclasses (Charge, Customer, etc.)')
+        raise NotImplementedError,
+              "APIResource is an abstract class. You should perform actions " \
+              "on its subclasses (Charge, Customer, etc.)"
       end
-      "/v1/#{CGI.escape(class_name.downcase)}s"
+      # Namespaces are separated in object names with periods (.) and in URLs
+      # with forward slashes (/), so replace the former with the latter.
+      "/v1/#{self::OBJECT_NAME.downcase.tr('.', '/')}s"
     end
 
     # A metaprogramming call that specifies that a field of a resource can be
@@ -38,17 +44,50 @@ module Stripe
         # Note that the value may be subresource, but could also be a scalar
         # (like a tokenized card's ID for example), so we check the type before
         # setting #save_with_parent here.
-        if value.is_a?(APIResource)
-          value.save_with_parent = true
-        end
+        value.save_with_parent = true if value.is_a?(APIResource)
 
         value
       end
     end
 
+    # Adds a custom method to a resource class. This is used to add support for
+    # non-CRUDL API requests, e.g. capturing charges. custom_method takes the
+    # following parameters:
+    # - name: the name of the custom method to create (as a symbol)
+    # - http_verb: the HTTP verb for the API request (:get, :post, or :delete)
+    # - http_path: the path to append to the resource's URL. If not provided,
+    #              the name is used as the path
+    #
+    # For example, this call:
+    #     custom_method :capture, http_verb: post
+    # adds a `capture` class method to the resource class that, when called,
+    # will send a POST request to `/v1/<object_name>/capture`.
+    def self.custom_method(name, http_verb:, http_path: nil)
+      unless %i[get post delete].include?(http_verb)
+        raise ArgumentError,
+              "Invalid http_verb value: #{http_verb.inspect}. Should be one " \
+              "of :get, :post or :delete."
+      end
+      http_path ||= name.to_s
+      define_singleton_method(name) do |id, params = {}, opts = {}|
+        unless id.is_a?(String)
+          raise ArgumentError,
+                "id should be a string representing the ID of an API resource"
+        end
+
+        url = "#{resource_url}/#{CGI.escape(id)}/#{CGI.escape(http_path)}"
+        resp, opts = request(http_verb, url, params, opts)
+        Util.convert_to_stripe_object(resp.data, opts)
+      end
+    end
+
     def resource_url
-      unless id = self['id']
-        raise InvalidRequestError.new("Could not determine which URL to request: #{self.class} instance has invalid ID: #{id.inspect}", 'id')
+      unless (id = self["id"])
+        raise InvalidRequestError.new(
+          "Could not determine which URL to request: #{self.class} instance " \
+          "has invalid ID: #{id.inspect}",
+          "id"
+        )
       end
       "#{self.class.resource_url}/#{CGI.escape(id)}"
     end
@@ -58,11 +97,22 @@ module Stripe
       initialize_from(resp.data, opts)
     end
 
-    def self.retrieve(id, opts={})
+    def self.retrieve(id, opts = {})
       opts = Util.normalize_opts(opts)
-      instance = self.new(id, opts)
+      instance = new(id, opts)
       instance.refresh
       instance
     end
+
+    protected def request_stripe_object(method:, path:, params:, opts: {})
+      resp, opts = request(method, path, params, opts)
+
+      # If we're getting back this thing, update; otherwise, instantiate.
+      if Util.object_name_matches_class?(resp.data[:object], self.class)
+        initialize_from(resp.data, opts)
+      else
+        Util.convert_to_stripe_object(resp.data, opts)
+      end
+    end
   end
 end

data/lib/stripe/connection_manager.rb

@@ -0,0 +1,159 @@
+# 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
+
+    def initialize
+      @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 = Stripe.open_timeout
+      connection.read_timeout = Stripe.read_timeout
+
+      connection.use_ssl = uri.scheme == "https"
+
+      if Stripe.verify_ssl_certs
+        connection.verify_mode = OpenSSL::SSL::VERIFY_PEER
+        connection.cert_store = Stripe.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 Stripe.proxy.nil?
+        [nil, nil, nil, nil]
+      else
+        u = URI.parse(Stripe.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

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module Stripe
   # StripeError is the base error from which all other more specific Stripe
   # errors derive.
@@ -8,8 +10,8 @@ module Stripe
     # about the response that conveyed the error.
     attr_accessor :response
 
-    # These fields are now available as part of #response and that usage should
-    # be preferred.
+    attr_reader :code
+    attr_reader :error
     attr_reader :http_body
     attr_reader :http_headers
     attr_reader :http_status
@@ -17,14 +19,22 @@ module Stripe
     attr_reader :request_id
 
     # Initializes a StripeError.
-    def initialize(message=nil, http_status: nil, http_body: nil, json_body: nil,
-                   http_headers: nil)
+    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 || {}
       @json_body = json_body
-      @request_id = @http_headers[:request_id]
+      @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
 
     def to_s
@@ -55,26 +65,32 @@ module Stripe
   # CardError is raised when a user enters a card that can't be charged for
   # some reason.
   class CardError < StripeError
-    attr_reader :param, :code
+    attr_reader :param
 
-    def initialize(message, param, code, http_status: nil, http_body: nil, json_body: nil,
-                   http_headers: nil)
+    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)
+                     json_body: json_body, http_headers: http_headers,
+                     code: code)
       @param = param
-      @code = code
     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)
+    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)
+                     json_body: json_body, http_headers: http_headers,
+                     code: code)
       @param = param
     end
   end
@@ -104,13 +120,17 @@ module Stripe
   module OAuth
     # OAuthError is raised when the OAuth API returns an error.
     class OAuthError < StripeError
-      attr_accessor :code
-
-      def initialize(code, description, http_status: nil, http_body: nil, json_body: nil,
-                     http_headers: nil)
+      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
+                           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
 

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