stripe 5.1.0 → 5.55.0

data/lib/stripe/api_operations/delete.rb

@@ -15,15 +15,19 @@ 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 delete(id, params = {}, opts = {})
-          resp, opts = request(:delete, "#{resource_url}/#{id}", params, opts)
+          resp, opts = execute_resource_request(:delete,
+                                                "#{resource_url}/#{id}",
+                                                params, opts)
           Util.convert_to_stripe_object(resp.data, opts)
         end
       end
 
       def delete(params = {}, opts = {})
-        resp, opts = request(:delete, resource_url, params, opts)
+        resp, opts = execute_resource_request(:delete, resource_url,
+                                              params, opts)
         initialize_from(resp.data, opts)
       end
 

data/lib/stripe/api_operations/list.rb

@@ -6,17 +6,12 @@ module Stripe
       def list(filters = {}, opts = {})
         opts = Util.normalize_opts(opts)
 
-        resp, opts = request(:get, resource_url, filters, opts)
+        resp, opts = execute_resource_request(:get, resource_url, filters, opts)
         obj = ListObject.construct_from(resp.data, opts)
 
         # set filters so that we can fetch the same limit, expansions, and
         # predicates when accessing the next and previous pages
-        #
-        # just for general cleanliness, remove any paging options
         obj.filters = filters.dup
-        obj.filters.delete(:ending_before)
-        obj.filters.delete(:starting_after)
-
         obj
       end
     end

data/lib/stripe/api_operations/nested_resource.rb

@@ -6,7 +6,7 @@ module Stripe
     # that it's possible to do so from a static context (i.e. without a
     # pre-existing collection of subresources on the parent).
     #
-    # For examle, a transfer gains the static methods for reversals so that the
+    # For example, a transfer gains the static methods for reversals so that the
     # methods `.create_reversal`, `.retrieve_reversal`, `.update_reversal`,
     # etc. all become available.
     module NestedResource
@@ -14,9 +14,11 @@ module Stripe
                                         resource_plural: nil)
         resource_plural ||= "#{resource}s"
         path ||= resource_plural
+
         raise ArgumentError, "operations array required" if operations.nil?
 
         resource_url_method = :"#{resource}s_url"
+
         define_singleton_method(resource_url_method) do |id, nested_id = nil|
           url = "#{resource_url}/#{CGI.escape(id)}/#{CGI.escape(path)}"
           url += "/#{CGI.escape(nested_id)}" unless nested_id.nil?
@@ -27,39 +29,40 @@ module Stripe
           case operation
           when :create
             define_singleton_method(:"create_#{resource}") \
-                do |id, params = {}, opts = {}|
-              url = send(resource_url_method, id)
-              resp, opts = request(:post, url, params, opts)
-              Util.convert_to_stripe_object(resp.data, opts)
-            end
+              do |id, params = {}, opts = {}|
+                url = send(resource_url_method, id)
+                resp, opts = execute_resource_request(:post, url, params, opts)
+                Util.convert_to_stripe_object(resp.data, opts)
+              end
           when :retrieve
             define_singleton_method(:"retrieve_#{resource}") \
-                do |id, nested_id, opts = {}|
-              url = send(resource_url_method, id, nested_id)
-              resp, opts = request(:get, url, {}, opts)
-              Util.convert_to_stripe_object(resp.data, opts)
-            end
+              do |id, nested_id, opts = {}|
+                url = send(resource_url_method, id, nested_id)
+                resp, opts = execute_resource_request(:get, url, {}, opts)
+                Util.convert_to_stripe_object(resp.data, opts)
+              end
           when :update
             define_singleton_method(:"update_#{resource}") \
-                do |id, nested_id, params = {}, opts = {}|
-              url = send(resource_url_method, id, nested_id)
-              resp, opts = request(:post, url, params, opts)
-              Util.convert_to_stripe_object(resp.data, opts)
-            end
+              do |id, nested_id, params = {}, opts = {}|
+                url = send(resource_url_method, id, nested_id)
+                resp, opts = execute_resource_request(:post, url, params, opts)
+                Util.convert_to_stripe_object(resp.data, opts)
+              end
           when :delete
             define_singleton_method(:"delete_#{resource}") \
-                do |id, nested_id, params = {}, opts = {}|
-              url = send(resource_url_method, id, nested_id)
-              resp, opts = request(:delete, url, params, opts)
-              Util.convert_to_stripe_object(resp.data, opts)
-            end
+              do |id, nested_id, params = {}, opts = {}|
+                url = send(resource_url_method, id, nested_id)
+                resp, opts = execute_resource_request(:delete, url, params,
+                                                      opts)
+                Util.convert_to_stripe_object(resp.data, opts)
+              end
           when :list
             define_singleton_method(:"list_#{resource_plural}") \
-                do |id, params = {}, opts = {}|
-              url = send(resource_url_method, id)
-              resp, opts = request(:get, url, params, opts)
-              Util.convert_to_stripe_object(resp.data, opts)
-            end
+              do |id, params = {}, opts = {}|
+                url = send(resource_url_method, id)
+                resp, opts = execute_resource_request(:get, url, params, opts)
+                Util.convert_to_stripe_object(resp.data, opts)
+              end
           else
             raise ArgumentError, "Unknown operation: #{operation.inspect}"
           end

data/lib/stripe/api_operations/request.rb

@@ -4,10 +4,38 @@ module Stripe
   module APIOperations
     module Request
       module ClassMethods
-        def request(method, url, params = {}, opts = {})
+        def execute_resource_request(method, url,
+                                     params = {}, opts = {})
+          execute_resource_request_internal(
+            :execute_request, method, url, params, opts
+          )
+        end
+
+        def execute_resource_request_stream(method, url,
+                                            params = {}, opts = {},
+                                            &read_body_chunk_block)
+          execute_resource_request_internal(
+            :execute_request_stream,
+            method,
+            url,
+            params,
+            opts,
+            &read_body_chunk_block
+          )
+        end
+
+        private def execute_resource_request_internal(client_request_method_sym,
+                                                      method, url,
+                                                      params, opts,
+                                                      &read_body_chunk_block)
+          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
@@ -16,10 +44,12 @@ module Stripe
           client = headers.delete(:client)
           # Assume all remaining opts must be headers
 
-          resp, opts[:api_key] = client.execute_request(
+          resp, opts[:api_key] = client.send(
+            client_request_method_sym,
             method, url,
             api_base: api_base, api_key: api_key,
-            headers: headers, params: params
+            headers: headers, params: params,
+            &read_body_chunk_block
           )
 
           # Hash#select returns an array before 1.9
@@ -31,10 +61,43 @@ module Stripe
           [resp, opts_to_persist]
         end
 
+        # 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
+
+        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)
-              warn("WARNING: #{opt} should be in opts instead of params.")
+              warn("WARNING: '#{opt}' should be in opts instead of params.")
             end
           end
         end
@@ -44,10 +107,23 @@ 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
+
+      protected def execute_resource_request_stream(method, url,
+                                                    params = {}, opts = {},
+                                                    &read_body_chunk_block)
+        opts = @opts.merge(Util.normalize_opts(opts))
+        self.class.execute_resource_request_stream(
+          method, url, params, opts, &read_body_chunk_block
+        )
+      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
 

data/lib/stripe/api_operations/search.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Stripe
+  module APIOperations
+    module Search
+      def _search(search_url, filters = {}, opts = {})
+        opts = Util.normalize_opts(opts)
+
+        resp, opts = execute_resource_request(:get, search_url, filters, opts)
+        obj = SearchResultObject.construct_from(resp.data, opts)
+
+        # set filters so that we can fetch the same limit and query
+        # when accessing the next page
+        obj.filters = filters.dup
+        obj
+      end
+    end
+  end
+end

data/lib/stripe/api_resource.rb

@@ -63,22 +63,7 @@ module Stripe
     # 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
+      Util.custom_method self, self, name, http_verb, http_path
     end
 
     def resource_url
@@ -93,7 +78,8 @@ module Stripe
     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
 
@@ -104,8 +90,8 @@ module Stripe
       instance
     end
 
-    protected def request_stripe_object(method:, path:, params:, opts: {})
-      resp, opts = request(method, path, params, opts)
+    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)
@@ -114,5 +100,13 @@ module Stripe
         Util.convert_to_stripe_object(resp.data, opts)
       end
     end
+
+    protected def request_stream(method:, path:, params:, opts: {},
+                                 &read_body_chunk_block)
+      resp, = execute_resource_request_stream(
+        method, path, params, opts, &read_body_chunk_block
+      )
+      resp
+    end
   end
 end

data/lib/stripe/api_resource_test_helpers.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module Stripe
+  # The base class for nested TestHelpers classes in resource objects.
+  # The APIResourceTestHelpers handles URL generation and custom method
+  # support for test-helper methods.
+  #
+  #  class MyAPIResource < APIResource
+  #    class TestHelpers < APIResourceTestHelpers
+  class APIResourceTestHelpers
+    def initialize(resource)
+      @resource = resource
+    end
+
+    # Adds a custom method to a test helper. 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)
+      Util.custom_method self::RESOURCE_CLASS, self, name, http_verb, http_path
+    end
+
+    def self.resource_url
+      "/v1/test_helpers/"\
+      "#{self::RESOURCE_CLASS::OBJECT_NAME.downcase.tr('.', '/')}s"
+    end
+
+    def resource_url
+      unless (id = @resource["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
+  end
+end

data/lib/stripe/connection_manager.rb

@@ -9,24 +9,38 @@ module Stripe
   #
   # Note that this class in itself is *not* thread safe. We expect it to be
   # instantiated once per thread.
-  #
-  # Note also that this class doesn't currently clean up after itself because
-  # it expects to only ever have a few connections (unless `.clear` is called
-  # manually). It'd be possible to tank memory by constantly changing the value
-  # of `Stripe.api_base` or the like. A possible improvement might be to detect
-  # and prune old connections whenever a request is executed.
   class ConnectionManager
-    def initialize
+    # 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
-      @active_connections.each do |_, connection|
-        connection.finish
+      @mutex.synchronize do
+        @active_connections.each do |_, connection|
+          connection.finish
+        end
+        @active_connections = {}
       end
-      @active_connections = {}
     end
 
     # Gets a connection for a given URI. This is for internal use only as it's
@@ -35,22 +49,25 @@ module Stripe
     #
     # `uri` is expected to be a string.
     def connection_for(uri)
-      u = URI.parse(uri)
-      connection = @active_connections[[u.host, u.port]]
+      @mutex.synchronize do
+        u = URI.parse(uri)
+        connection = @active_connections[[u.host, u.port]]
 
-      if connection.nil?
-        connection = create_connection(u)
-        connection.start
+        if connection.nil?
+          connection = create_connection(u)
+          connection.start
 
-        @active_connections[[u.host, u.port]] = connection
-      end
+          @active_connections[[u.host, u.port]] = connection
+        end
 
-      connection
+        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)
+    def execute_request(method, uri, body: nil, headers: nil, query: nil,
+                        &block)
       # Perform some basic argument validation because it's easy to get
       # confused between strings and hashes for things like body and query
       # parameters.
@@ -65,6 +82,8 @@ module Stripe
       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)
@@ -74,7 +93,44 @@ module Stripe
                u.path
              end
 
-      connection.send_request(method.to_s.upcase, path, body, headers)
+      method_name = method.to_s.upcase
+      has_response_body = method_name != "HEAD"
+      request = Net::HTTPGenericRequest.new(
+        method_name,
+        (body ? true : false),
+        has_response_body,
+        path,
+        headers
+      )
+
+      Util.log_debug("ConnectionManager starting request",
+                     method_name: method_name,
+                     path: path,
+                     process_id: Process.pid,
+                     thread_object_id: Thread.current.object_id,
+                     connection_manager_object_id: object_id,
+                     connection_object_id: connection.object_id,
+                     log_timestamp: Util.monotonic_time)
+
+      resp = @mutex.synchronize do
+        # The block parameter is special here. If a block is provided, the block
+        # is invoked with the Net::HTTPResponse. However, the body will not have
+        # been read yet in the block, and can be streamed by calling
+        # HTTPResponse#read_body.
+        connection.request(request, body, &block)
+      end
+
+      Util.log_debug("ConnectionManager request complete",
+                     method_name: method_name,
+                     path: path,
+                     process_id: Process.pid,
+                     thread_object_id: Thread.current.object_id,
+                     connection_manager_object_id: object_id,
+                     connection_object_id: connection.object_id,
+                     response_object_id: resp.object_id,
+                     log_timestamp: Util.monotonic_time)
+
+      resp
     end
 
     #
@@ -99,14 +155,17 @@ module Stripe
       # reused Go's default for `DefaultTransport`.
       connection.keep_alive_timeout = 30
 
-      connection.open_timeout = Stripe.open_timeout
-      connection.read_timeout = Stripe.read_timeout
+      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 Stripe.verify_ssl_certs
+      if config.verify_ssl_certs
         connection.verify_mode = OpenSSL::SSL::VERIFY_PEER
-        connection.cert_store = Stripe.ca_store
+        connection.cert_store = config.ca_store
       else
         connection.verify_mode = OpenSSL::SSL::VERIFY_NONE
         warn_ssl_verify_none
@@ -120,10 +179,10 @@ module Stripe
     # out those pieces to make passing them into a new connection a little less
     # ugly.
     private def proxy_parts
-      if Stripe.proxy.nil?
+      if config.proxy.nil?
         [nil, nil, nil, nil]
       else
-        u = URI.parse(Stripe.proxy)
+        u = URI.parse(config.proxy)
         [u.host, u.port, u.user, u.password]
       end
     end

data/lib/stripe/error_object.rb

@@ -69,9 +69,8 @@ module Stripe
       @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`.
+    # The type of error returned. One of `api_error`, `card_error`,
+    # `idempotency_error`, or `invalid_request_error`.
     def type
       @values[:type]
     end

data/lib/stripe/errors.rb

@@ -25,9 +25,10 @@ module Stripe
       @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]
+      @request_id = @http_headers["request-id"]
       @error = construct_error_object
     end
 
@@ -37,6 +38,13 @@ module Stripe
       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}) "