stripe 5.28.0 → 5.38.0

data/lib/stripe/stripe_client.rb

@@ -9,19 +9,36 @@ module Stripe
   class StripeClient
     # A set of all known thread contexts across all threads and a mutex to
     # synchronize global access to them.
-    @thread_contexts_with_connection_managers = []
+    @thread_contexts_with_connection_managers = Set.new
     @thread_contexts_with_connection_managers_mutex = Mutex.new
     @last_connection_manager_gc = Util.monotonic_time
 
-    # Initializes a new `StripeClient`.
-    #
-    # Takes a connection manager object for backwards compatibility only, and
-    # that use is DEPRECATED.
-    def initialize(_connection_manager = nil)
+    # Initializes a new StripeClient
+    def initialize(config_arg = {})
       @system_profiler = SystemProfiler.new
       @last_request_metrics = nil
+
+      @config = case config_arg
+                when Hash
+                  Stripe.config.reverse_duplicate_merge(config_arg)
+                when Stripe::ConnectionManager
+                  # Supports accepting a connection manager object for backwards
+                  # compatibility only, and that use is DEPRECATED.
+                  Stripe.config.dup
+                when Stripe::StripeConfiguration
+                  config_arg
+                when String
+                  Stripe.config.reverse_duplicate_merge(
+                    { api_key: config_arg }
+                  )
+                else
+                  raise ArgumentError, "Can't handle argument: #{config_arg}"
+                end
     end
 
+    attr_reader :config
+    attr_reader :options
+
     # Gets a currently active `StripeClient`. Set for the current thread when
     # `StripeClient#request` is being run so that API operations being executed
     # inside of that block can find the currently active client. It's reset to
@@ -37,36 +54,51 @@ module Stripe
     # clears them from internal tracking in all connection managers across all
     # threads.
     #
+    # If passed a `config` object, only clear connection managers for that
+    # particular configuration.
+    #
     # For internal use only. Does not provide a stable API and may be broken
     # with future non-major changes.
-    def self.clear_all_connection_managers
+    def self.clear_all_connection_managers(config: nil)
       # Just a quick path for when configuration is being set for the first
       # time before any connections have been opened. There is technically some
       # potential for thread raciness here, but not in a practical sense.
       return if @thread_contexts_with_connection_managers.empty?
 
       @thread_contexts_with_connection_managers_mutex.synchronize do
+        pruned_contexts = Set.new
+
         @thread_contexts_with_connection_managers.each do |thread_context|
           # Note that the thread context itself is not destroyed, but we clear
           # its connection manager and remove our reference to it. If it ever
           # makes a new request we'll give it a new connection manager and
           # it'll go back into `@thread_contexts_with_connection_managers`.
-          thread_context.default_connection_manager.clear
-          thread_context.default_connection_manager = nil
+          thread_context.default_connection_managers.reject! do |cm_config, cm|
+            if config.nil? || config.key == cm_config
+              cm.clear
+              true
+            end
+          end
+
+          if thread_context.default_connection_managers.empty?
+            pruned_contexts << thread_context
+          end
         end
-        @thread_contexts_with_connection_managers.clear
+
+        @thread_contexts_with_connection_managers.subtract(pruned_contexts)
       end
     end
 
     # A default client for the current thread.
     def self.default_client
-      current_thread_context.default_client ||= StripeClient.new
+      current_thread_context.default_client ||= StripeClient.new(Stripe.config)
     end
 
-    # A default connection manager for the current thread.
-    def self.default_connection_manager
-      current_thread_context.default_connection_manager ||= begin
-        connection_manager = ConnectionManager.new
+    # A default connection manager for the current thread scoped to the
+    # configuration object that may be provided.
+    def self.default_connection_manager(config = Stripe.config)
+      current_thread_context.default_connection_managers[config.key] ||= begin
+        connection_manager = ConnectionManager.new(config)
 
         @thread_contexts_with_connection_managers_mutex.synchronize do
           maybe_gc_connection_managers
@@ -80,8 +112,9 @@ module Stripe
     # Checks if an error is a problem that we should retry on. This includes
     # both socket errors that may represent an intermittent problem and some
     # special HTTP statuses.
-    def self.should_retry?(error, method:, num_retries:)
-      return false if num_retries >= Stripe.max_network_retries
+    def self.should_retry?(error,
+                           method:, num_retries:, config: Stripe.config)
+      return false if num_retries >= config.max_network_retries
 
       case error
       when Net::OpenTimeout, Net::ReadTimeout
@@ -127,13 +160,13 @@ module Stripe
       end
     end
 
-    def self.sleep_time(num_retries)
+    def self.sleep_time(num_retries, config: Stripe.config)
       # Apply exponential backoff with initial_network_retry_delay on the
       # number of num_retries so far as inputs. Do not allow the number to
       # exceed max_network_retry_delay.
       sleep_seconds = [
-        Stripe.initial_network_retry_delay * (2**(num_retries - 1)),
-        Stripe.max_network_retry_delay,
+        config.initial_network_retry_delay * (2**(num_retries - 1)),
+        config.max_network_retry_delay,
       ].min
 
       # Apply some jitter by randomizing the value in the range of
@@ -141,9 +174,7 @@ module Stripe
       sleep_seconds *= (0.5 * (1 + rand))
 
       # But never sleep less than the base sleep seconds.
-      sleep_seconds = [Stripe.initial_network_retry_delay, sleep_seconds].max
-
-      sleep_seconds
+      [config.initial_network_retry_delay, sleep_seconds].max
     end
 
     # Gets the connection manager in use for the current `StripeClient`.
@@ -182,60 +213,9 @@ module Stripe
 
     def execute_request(method, path,
                         api_base: nil, api_key: nil, headers: {}, params: {})
-      raise ArgumentError, "method should be a symbol" \
-        unless method.is_a?(Symbol)
-      raise ArgumentError, "path should be a string" \
-        unless path.is_a?(String)
-
-      api_base ||= Stripe.api_base
-      api_key ||= Stripe.api_key
-      params = Util.objects_to_ids(params)
-
-      check_api_key!(api_key)
-
-      body_params = nil
-      query_params = nil
-      case method
-      when :get, :head, :delete
-        query_params = params
-      else
-        body_params = params
-      end
-
-      query_params, path = merge_query_params(query_params, path)
-
-      headers = request_headers(api_key, method)
-                .update(Util.normalize_headers(headers))
-      url = api_url(path, api_base)
-
-      # Merge given query parameters with any already encoded in the path.
-      query = query_params ? Util.encode_parameters(query_params) : nil
-
-      # Encoding body parameters is a little more complex because we may have
-      # to send a multipart-encoded body. `body_log` is produced separately as
-      # a log-friendly variant of the encoded form. File objects are displayed
-      # as such instead of as their file contents.
-      body, body_log =
-        body_params ? encode_body(body_params, headers) : [nil, nil]
-
-      # stores information on the request we're about to make so that we don't
-      # have to pass as many parameters around for logging.
-      context = RequestLogContext.new
-      context.account         = headers["Stripe-Account"]
-      context.api_key         = api_key
-      context.api_version     = headers["Stripe-Version"]
-      context.body            = body_log
-      context.idempotency_key = headers["Idempotency-Key"]
-      context.method          = method
-      context.path            = path
-      context.query           = query
-
-      http_resp = execute_request_with_rescues(method, api_base, context) do
-        self.class.default_connection_manager.execute_request(method, url,
-                                                              body: body,
-                                                              headers: headers,
-                                                              query: query)
-      end
+      http_resp, api_key = execute_request_internal(
+        method, path, api_base, api_key, headers, params
+      )
 
       begin
         resp = StripeResponse.from_net_http(http_resp)
@@ -246,13 +226,53 @@ module Stripe
       # If being called from `StripeClient#request`, put the last response in
       # thread-local memory so that it can be returned to the user. Don't store
       # anything otherwise so that we don't leak memory.
-      if self.class.current_thread_context.last_responses&.key?(object_id)
-        self.class.current_thread_context.last_responses[object_id] = resp
+      store_last_response(object_id, resp)
+
+      [resp, api_key]
+    end
+
+    # Executes a request and returns the body as a stream instead of converting
+    # it to a StripeObject. This should be used for any request where we expect
+    # an arbitrary binary response.
+    #
+    # A `read_body_chunk` block can be passed, which will be called repeatedly
+    # with the body chunks read from the socket.
+    #
+    # If a block is passed, a StripeHeadersOnlyResponse is returned as the
+    # block is expected to do all the necessary body processing. If no block is
+    # passed, then a StripeStreamResponse is returned containing an IO stream
+    # with the response body.
+    def execute_request_stream(method, path,
+                               api_base: nil, api_key: nil,
+                               headers: {}, params: {},
+                               &read_body_chunk_block)
+      unless block_given?
+        raise ArgumentError,
+              "execute_request_stream requires a read_body_chunk_block"
       end
 
+      http_resp, api_key = execute_request_internal(
+        method, path, api_base, api_key, headers, params, &read_body_chunk_block
+      )
+
+      # When the read_body_chunk_block is given, we no longer have access to the
+      # response body at this point and so return a response object containing
+      # only the headers. This is because the body was consumed by the block.
+      resp = StripeHeadersOnlyResponse.from_net_http(http_resp)
+
       [resp, api_key]
     end
 
+    def store_last_response(object_id, resp)
+      return unless last_response_has_key?(object_id)
+
+      self.class.current_thread_context.last_responses[object_id] = resp
+    end
+
+    def last_response_has_key?(object_id)
+      self.class.current_thread_context.last_responses&.key?(object_id)
+    end
+
     #
     # private
     #
@@ -328,11 +348,6 @@ module Stripe
       # the user hasn't specified their own.
       attr_accessor :default_client
 
-      # A default `ConnectionManager` for the thread. Normally shared between
-      # all `StripeClient` objects on a particular thread, and created so as to
-      # minimize the number of open connections that an application needs.
-      attr_accessor :default_connection_manager
-
       # A temporary map of object IDs to responses from last executed API
       # calls. Used to return a responses from calls to `StripeClient#request`.
       #
@@ -345,6 +360,17 @@ module Stripe
       # because that's wrapped in an `ensure` block, they should never leave
       # garbage in `Thread.current`.
       attr_accessor :last_responses
+
+      # A map of connection mangers for the thread. Normally shared between
+      # all `StripeClient` objects on a particular thread, and created so as to
+      # minimize the number of open connections that an application needs.
+      def default_connection_managers
+        @default_connection_managers ||= {}
+      end
+
+      def reset_connection_managers
+        @default_connection_managers = {}
+      end
     end
 
     # Access data stored for `StripeClient` within the thread's current
@@ -380,24 +406,109 @@ module Stripe
       last_used_threshold =
         Util.monotonic_time - CONNECTION_MANAGER_GC_LAST_USED_EXPIRY
 
-      pruned_thread_contexts = []
+      pruned_contexts = []
       @thread_contexts_with_connection_managers.each do |thread_context|
-        connection_manager = thread_context.default_connection_manager
-        next if connection_manager.last_used > last_used_threshold
+        thread_context
+          .default_connection_managers
+          .each do |config_key, connection_manager|
+            next if connection_manager.last_used > last_used_threshold
 
-        connection_manager.clear
-        thread_context.default_connection_manager = nil
-        pruned_thread_contexts << thread_context
+            connection_manager.clear
+            thread_context.default_connection_managers.delete(config_key)
+          end
       end
 
-      @thread_contexts_with_connection_managers -= pruned_thread_contexts
+      @thread_contexts_with_connection_managers.each do |thread_context|
+        next unless thread_context.default_connection_managers.empty?
+
+        pruned_contexts << thread_context
+      end
+
+      @thread_contexts_with_connection_managers -= pruned_contexts
       @last_connection_manager_gc = Util.monotonic_time
 
-      pruned_thread_contexts.count
+      pruned_contexts.count
+    end
+
+    private def execute_request_internal(method, path,
+                                         api_base, api_key, headers, params,
+                                         &read_body_chunk_block)
+      raise ArgumentError, "method should be a symbol" \
+      unless method.is_a?(Symbol)
+      raise ArgumentError, "path should be a string" \
+      unless path.is_a?(String)
+
+      api_base ||= config.api_base
+      api_key ||= config.api_key
+      params = Util.objects_to_ids(params)
+
+      check_api_key!(api_key)
+
+      body_params = nil
+      query_params = nil
+      case method
+      when :get, :head, :delete
+        query_params = params
+      else
+        body_params = params
+      end
+
+      query_params, path = merge_query_params(query_params, path)
+
+      headers = request_headers(api_key, method)
+                .update(Util.normalize_headers(headers))
+      url = api_url(path, api_base)
+
+      # Merge given query parameters with any already encoded in the path.
+      query = query_params ? Util.encode_parameters(query_params) : nil
+
+      # Encoding body parameters is a little more complex because we may have
+      # to send a multipart-encoded body. `body_log` is produced separately as
+      # a log-friendly variant of the encoded form. File objects are displayed
+      # as such instead of as their file contents.
+      body, body_log =
+        body_params ? encode_body(body_params, headers) : [nil, nil]
+
+      # stores information on the request we're about to make so that we don't
+      # have to pass as many parameters around for logging.
+      context = RequestLogContext.new
+      context.account         = headers["Stripe-Account"]
+      context.api_key         = api_key
+      context.api_version     = headers["Stripe-Version"]
+      context.body            = body_log
+      context.idempotency_key = headers["Idempotency-Key"]
+      context.method          = method
+      context.path            = path
+      context.query           = query
+
+      # A block can be passed in to read the content directly from the response.
+      # We want to execute this block only when the response was actually
+      # successful. When it wasn't, we defer to the standard error handling as
+      # we have to read the body and parse the error JSON.
+      response_block =
+        if block_given?
+          lambda do |response|
+            unless should_handle_as_error(response.code.to_i)
+              response.read_body(&read_body_chunk_block)
+            end
+          end
+        end
+
+      http_resp = execute_request_with_rescues(method, api_base, context) do
+        self.class
+            .default_connection_manager(config)
+            .execute_request(method, url,
+                             body: body,
+                             headers: headers,
+                             query: query,
+                             &response_block)
+      end
+
+      [http_resp, api_key]
     end
 
     private def api_url(url = "", api_base = nil)
-      (api_base || Stripe.api_base) + url
+      (api_base || config.api_base) + url
     end
 
     private def check_api_key!(api_key)
@@ -435,6 +546,7 @@ module Stripe
         # that's more condusive to logging.
         flattened_params =
           flattened_params.map { |k, v| [k, v.is_a?(String) ? v : v.to_s] }.to_h
+
       else
         body = Util.encode_parameters(body_params)
       end
@@ -448,6 +560,10 @@ module Stripe
       [body, body_log]
     end
 
+    private def should_handle_as_error(http_status)
+      http_status >= 400
+    end
+
     private def execute_request_with_rescues(method, api_base, context)
       num_retries = 0
 
@@ -465,13 +581,15 @@ module Stripe
         http_status = resp.code.to_i
         context = context.dup_from_response_headers(resp)
 
-        handle_error_response(resp, context) if http_status >= 400
+        if should_handle_as_error(http_status)
+          handle_error_response(resp, context)
+        end
 
         log_response(context, request_start, http_status, resp.body)
         notify_request_end(context, request_duration, http_status,
                            num_retries, user_data)
 
-        if Stripe.enable_telemetry? && context.request_id
+        if config.enable_telemetry? && context.request_id
           request_duration_ms = (request_duration * 1000).to_i
           @last_request_metrics =
             StripeRequestMetrics.new(context.request_id, request_duration_ms)
@@ -498,9 +616,12 @@ module Stripe
         notify_request_end(context, request_duration, http_status, num_retries,
                            user_data)
 
-        if self.class.should_retry?(e, method: method, num_retries: num_retries)
+        if self.class.should_retry?(e,
+                                    method: method,
+                                    num_retries: num_retries,
+                                    config: config)
           num_retries += 1
-          sleep self.class.sleep_time(num_retries)
+          sleep self.class.sleep_time(num_retries, config: config)
           retry
         end
 
@@ -546,6 +667,7 @@ module Stripe
         method: context.method,
         num_retries: num_retries,
         path: context.path,
+        request_id: context.request_id,
         user_data: user_data || {}
       )
       Stripe::Instrumentation.notify(:request_end, event)
@@ -622,7 +744,8 @@ module Stripe
                      error_param: error_data[:param],
                      error_type: error_data[:type],
                      idempotency_key: context.idempotency_key,
-                     request_id: context.request_id)
+                     request_id: context.request_id,
+                     config: config)
 
       # The standard set of arguments that can be used to initialize most of
       # the exceptions.
@@ -671,7 +794,8 @@ module Stripe
                      error_code: error_code,
                      error_description: description,
                      idempotency_key: context.idempotency_key,
-                     request_id: context.request_id)
+                     request_id: context.request_id,
+                     config: config)
 
       args = {
         http_status: resp.http_status, http_body: resp.http_body,
@@ -703,7 +827,8 @@ module Stripe
       Util.log_error("Stripe network error",
                      error_message: error.message,
                      idempotency_key: context.idempotency_key,
-                     request_id: context.request_id)
+                     request_id: context.request_id,
+                     config: config)
 
       errors, message = NETWORK_ERROR_MESSAGES_MAP.detect do |(e, _)|
         error.is_a?(e)
@@ -714,7 +839,7 @@ module Stripe
           "with Stripe. Please let us know at support@stripe.com."
       end
 
-      api_base ||= Stripe.api_base
+      api_base ||= config.api_base
       message = message % api_base
 
       message += " Request was retried #{num_retries} times." if num_retries > 0
@@ -735,7 +860,7 @@ module Stripe
         "Content-Type" => "application/x-www-form-urlencoded",
       }
 
-      if Stripe.enable_telemetry? && !@last_request_metrics.nil?
+      if config.enable_telemetry? && !@last_request_metrics.nil?
         headers["X-Stripe-Client-Telemetry"] = JSON.generate(
           last_request_metrics: @last_request_metrics.payload
         )
@@ -743,12 +868,12 @@ module Stripe
 
       # It is only safe to retry network failures on post and delete
       # requests if we add an Idempotency-Key header
-      if %i[post delete].include?(method) && Stripe.max_network_retries > 0
+      if %i[post delete].include?(method) && config.max_network_retries > 0
         headers["Idempotency-Key"] ||= SecureRandom.uuid
       end
 
-      headers["Stripe-Version"] = Stripe.api_version if Stripe.api_version
-      headers["Stripe-Account"] = Stripe.stripe_account if Stripe.stripe_account
+      headers["Stripe-Version"] = config.api_version if config.api_version
+      headers["Stripe-Account"] = config.stripe_account if config.stripe_account
 
       user_agent = @system_profiler.user_agent
       begin
@@ -772,11 +897,13 @@ module Stripe
                     idempotency_key: context.idempotency_key,
                     method: context.method,
                     num_retries: num_retries,
-                    path: context.path)
+                    path: context.path,
+                    config: config)
       Util.log_debug("Request details",
                      body: context.body,
                      idempotency_key: context.idempotency_key,
-                     query: context.query)
+                     query: context.query,
+                     config: config)
     end
 
     private def log_response(context, request_start, status, body)
@@ -788,11 +915,13 @@ module Stripe
                     method: context.method,
                     path: context.path,
                     request_id: context.request_id,
-                    status: status)
+                    status: status,
+                    config: config)
       Util.log_debug("Response details",
                      body: body,
                      idempotency_key: context.idempotency_key,
-                     request_id: context.request_id)
+                     request_id: context.request_id,
+                     config: config)
 
       return unless context.request_id
 
@@ -800,7 +929,8 @@ module Stripe
                      idempotency_key: context.idempotency_key,
                      request_id: context.request_id,
                      url: Util.request_id_dashboard_url(context.request_id,
-                                                        context.api_key))
+                                                        context.api_key),
+                     config: config)
     end
 
     private def log_response_error(context, request_start, error)
@@ -810,7 +940,8 @@ module Stripe
                      error_message: error.message,
                      idempotency_key: context.idempotency_key,
                      method: context.method,
-                     path: context.path)
+                     path: context.path,
+                     config: config)
     end
 
     # RequestLogContext stores information about a request that's begin made so

data/lib/stripe/stripe_configuration.rb

@@ -101,14 +101,22 @@ module Stripe
       @max_network_retries = val.to_i
     end
 
+    def max_network_retry_delay=(val)
+      @max_network_retry_delay = val.to_i
+    end
+
+    def initial_network_retry_delay=(val)
+      @initial_network_retry_delay = val.to_i
+    end
+
     def open_timeout=(open_timeout)
       @open_timeout = open_timeout
-      StripeClient.clear_all_connection_managers
+      StripeClient.clear_all_connection_managers(config: self)
     end
 
     def read_timeout=(read_timeout)
       @read_timeout = read_timeout
-      StripeClient.clear_all_connection_managers
+      StripeClient.clear_all_connection_managers(config: self)
     end
 
     def write_timeout=(write_timeout)
@@ -117,32 +125,32 @@ module Stripe
       end
 
       @write_timeout = write_timeout
-      StripeClient.clear_all_connection_managers
+      StripeClient.clear_all_connection_managers(config: self)
     end
 
     def proxy=(proxy)
       @proxy = proxy
-      StripeClient.clear_all_connection_managers
+      StripeClient.clear_all_connection_managers(config: self)
     end
 
     def verify_ssl_certs=(verify_ssl_certs)
       @verify_ssl_certs = verify_ssl_certs
-      StripeClient.clear_all_connection_managers
+      StripeClient.clear_all_connection_managers(config: self)
     end
 
     def uploads_base=(uploads_base)
       @uploads_base = uploads_base
-      StripeClient.clear_all_connection_managers
+      StripeClient.clear_all_connection_managers(config: self)
     end
 
     def connect_base=(connect_base)
       @connect_base = connect_base
-      StripeClient.clear_all_connection_managers
+      StripeClient.clear_all_connection_managers(config: self)
     end
 
     def api_base=(api_base)
       @api_base = api_base
-      StripeClient.clear_all_connection_managers
+      StripeClient.clear_all_connection_managers(config: self)
     end
 
     def ca_bundle_path=(path)
@@ -151,7 +159,7 @@ module Stripe
       # empty this field so a new store is initialized
       @ca_store = nil
 
-      StripeClient.clear_all_connection_managers
+      StripeClient.clear_all_connection_managers(config: self)
     end
 
     # A certificate store initialized from the the bundle in #ca_bundle_path and
@@ -174,5 +182,13 @@ module Stripe
     def enable_telemetry?
       enable_telemetry
     end
+
+    # Generates a deterministic key to identify configuration objects with
+    # identical configuration values.
+    def key
+      instance_variables
+        .collect { |variable| instance_variable_get(variable) }
+        .join
+    end
   end
 end