stripe 4.9.0 → 5.28.0

data/lib/stripe/api_operations/request.rb

@@ -4,10 +4,16 @@ module Stripe
   module APIOperations
     module Request
       module ClassMethods
-        def request(method, url, params = {}, opts = {})
+        def execute_resource_request(method, url,
+                                     params = {}, opts = {})
+          params ||= {}
+
+          error_on_invalid_params(params)
           warn_on_opts_in_params(params)
 
           opts = Util.normalize_opts(opts)
+          error_on_non_string_user_opts(opts)
+
           opts[:client] ||= StripeClient.active_client
 
           headers = opts.clone
@@ -31,12 +37,43 @@ module Stripe
           [resp, opts_to_persist]
         end
 
-        private
+        # This method used to be called `request`, but it's such a short name
+        # that it eventually conflicted with the name of a field on an API
+        # resource (specifically, `Event#request`), so it was renamed to
+        # something more unique.
+        #
+        # The former name had been around for just about forever though, and
+        # although all internal uses have been renamed, I've left this alias in
+        # place for backwards compatibility. Consider removing it on the next
+        # major.
+        alias request execute_resource_request
 
-        def warn_on_opts_in_params(params)
+        private def error_on_non_string_user_opts(opts)
+          Util::OPTS_USER_SPECIFIED.each do |opt|
+            next unless opts.key?(opt)
+
+            val = opts[opt]
+            next if val.nil?
+            next if val.is_a?(String)
+
+            raise ArgumentError,
+                  "request option '#{opt}' should be a string value " \
+                    "(was a #{val.class})"
+          end
+        end
+
+        private def error_on_invalid_params(params)
+          return if params.nil? || params.is_a?(Hash)
+
+          raise ArgumentError,
+                "request params should be either a Hash or nil " \
+                  "(was a #{params.class})"
+        end
+
+        private def warn_on_opts_in_params(params)
           Util::OPTS_USER_SPECIFIED.each do |opt|
             if params.key?(opt)
-              $stderr.puts("WARNING: #{opt} should be in opts instead of params.")
+              warn("WARNING: '#{opt}' should be in opts instead of params.")
             end
           end
         end
@@ -46,12 +83,14 @@ module Stripe
         base.extend(ClassMethods)
       end
 
-      protected
-
-      def request(method, url, params = {}, opts = {})
+      protected def execute_resource_request(method, url,
+                                             params = {}, opts = {})
         opts = @opts.merge(Util.normalize_opts(opts))
-        self.class.request(method, url, params, opts)
+        self.class.execute_resource_request(method, url, params, opts)
       end
+
+      # See notes on `alias` above.
+      alias request execute_resource_request
     end
   end
 end

data/lib/stripe/api_operations/save.rb

@@ -15,7 +15,8 @@ module Stripe
         # * +opts+ - A Hash of additional options (separate from the params /
         #   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}.
+        #   api_key to be overwritten. See
+        #   {APIOperations::Request.execute_resource_request}.
         def update(id, params = {}, opts = {})
           params.each_key do |k|
             if protected_fields.include?(k)
@@ -23,7 +24,8 @@ module Stripe
             end
           end
 
-          resp, opts = request(:post, "#{resource_url}/#{id}", params, opts)
+          resp, opts = execute_resource_request(:post, "#{resource_url}/#{id}",
+                                                params, opts)
           Util.convert_to_stripe_object(resp.data, opts)
         end
       end
@@ -43,7 +45,8 @@ module Stripe
       # * +opts+ - A Hash of additional options (separate from the params /
       #   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}.
+      #   api_key to be overwritten. See
+      #   {APIOperations::Request.execute_resource_request}.
       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
@@ -59,7 +62,7 @@ module Stripe
         # generated a uri for this object with an identifier baked in
         values.delete(:id)
 
-        resp, opts = request(:post, save_url, values, opts)
+        resp, opts = execute_resource_request(:post, save_url, values, opts)
         initialize_from(resp.data, opts)
       end
 
@@ -76,9 +79,7 @@ module Stripe
         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

data/lib/stripe/api_resource.rb

@@ -17,7 +17,9 @@ module Stripe
 
     def self.resource_url
       if self == APIResource
-        raise NotImplementedError, "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
       # Namespaces are separated in object names with periods (.) and in URLs
       # with forward slashes (/), so replace the former with the latter.
@@ -48,15 +50,51 @@ module Stripe
       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 = execute_resource_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")
+        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
 
     def refresh
-      resp, opts = request(:get, resource_url, @retrieve_params)
+      resp, opts = execute_resource_request(:get, resource_url,
+                                            @retrieve_params)
       initialize_from(resp.data, opts)
     end
 
@@ -66,5 +104,16 @@ module Stripe
       instance.refresh
       instance
     end
+
+    protected def request_stripe_object(method:, path:, params:, opts: {})
+      resp, opts = execute_resource_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,162 @@
+# 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
+      if connection.respond_to?(:write_timeout=)
+        connection.write_timeout = Stripe.write_timeout
+      end
+
+      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