stripe 4.10.0 → 5.55.0

data/lib/stripe/stripe_configuration.rb

@@ -0,0 +1,194 @@
+# frozen_string_literal: true
+
+module Stripe
+  # Configurable options:
+  #
+  # =ca_bundle_path=
+  # The location of a file containing a bundle of CA certificates. By default
+  # the library will use an included bundle that can successfully validate
+  # Stripe certificates.
+  #
+  # =log_level=
+  # When set prompts the library to log some extra information to $stdout and
+  # $stderr about what it's doing. For example, it'll produce information about
+  # requests, responses, and errors that are received. Valid log levels are
+  # `debug` and `info`, with `debug` being a little more verbose in places.
+  #
+  # Use of this configuration is only useful when `.logger` is _not_ set. When
+  # it is, the decision what levels to print is entirely deferred to the logger.
+  #
+  # =logger=
+  # The logger should support the same interface as the `Logger` class that's
+  # part of Ruby's standard library (hint, anything in `Rails.logger` will
+  # likely be suitable).
+  #
+  # If `.logger` is set, the value of `.log_level` is ignored. The decision on
+  # what levels to print is entirely deferred to the logger.
+  class StripeConfiguration
+    attr_accessor :api_key
+    attr_accessor :api_version
+    attr_accessor :client_id
+    attr_accessor :enable_telemetry
+    attr_accessor :logger
+    attr_accessor :stripe_account
+
+    attr_reader :api_base
+    attr_reader :uploads_base
+    attr_reader :connect_base
+    attr_reader :ca_bundle_path
+    attr_reader :log_level
+    attr_reader :initial_network_retry_delay
+    attr_reader :max_network_retries
+    attr_reader :max_network_retry_delay
+    attr_reader :open_timeout
+    attr_reader :read_timeout
+    attr_reader :write_timeout
+    attr_reader :proxy
+    attr_reader :verify_ssl_certs
+
+    def self.setup
+      new.tap do |instance|
+        yield(instance) if block_given?
+      end
+    end
+
+    # Create a new config based off an existing one. This is useful when the
+    # caller wants to override the global configuration
+    def reverse_duplicate_merge(hash)
+      dup.tap do |instance|
+        hash.each do |option, value|
+          instance.public_send("#{option}=", value)
+        end
+      end
+    end
+
+    def initialize
+      @ca_bundle_path = Stripe::DEFAULT_CA_BUNDLE_PATH
+      @enable_telemetry = true
+      @verify_ssl_certs = true
+
+      @max_network_retries = 0
+      @initial_network_retry_delay = 0.5
+      @max_network_retry_delay = 2
+
+      @open_timeout = 30
+      @read_timeout = 80
+      @write_timeout = 30
+
+      @api_base = "https://api.stripe.com"
+      @connect_base = "https://connect.stripe.com"
+      @uploads_base = "https://files.stripe.com"
+    end
+
+    def log_level=(val)
+      # Backwards compatibility for values that we briefly allowed
+      if val == "debug"
+        val = Stripe::LEVEL_DEBUG
+      elsif val == "info"
+        val = Stripe::LEVEL_INFO
+      end
+
+      levels = [Stripe::LEVEL_INFO, Stripe::LEVEL_DEBUG, Stripe::LEVEL_ERROR]
+
+      if !val.nil? && !levels.include?(val)
+        raise ArgumentError,
+              "log_level should only be set to `nil`, `debug` or `info`"
+      end
+      @log_level = val
+    end
+
+    def max_network_retries=(val)
+      @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(config: self)
+    end
+
+    def read_timeout=(read_timeout)
+      @read_timeout = read_timeout
+      StripeClient.clear_all_connection_managers(config: self)
+    end
+
+    def write_timeout=(write_timeout)
+      unless Net::HTTP.instance_methods.include?(:write_timeout=)
+        raise NotImplementedError
+      end
+
+      @write_timeout = write_timeout
+      StripeClient.clear_all_connection_managers(config: self)
+    end
+
+    def proxy=(proxy)
+      @proxy = proxy
+      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(config: self)
+    end
+
+    def uploads_base=(uploads_base)
+      @uploads_base = uploads_base
+      StripeClient.clear_all_connection_managers(config: self)
+    end
+
+    def connect_base=(connect_base)
+      @connect_base = connect_base
+      StripeClient.clear_all_connection_managers(config: self)
+    end
+
+    def api_base=(api_base)
+      @api_base = api_base
+      StripeClient.clear_all_connection_managers(config: self)
+    end
+
+    def ca_bundle_path=(path)
+      @ca_bundle_path = path
+
+      # empty this field so a new store is initialized
+      @ca_store = nil
+
+      StripeClient.clear_all_connection_managers(config: self)
+    end
+
+    # A certificate store initialized from the the bundle in #ca_bundle_path and
+    # which is used to validate TLS on every request.
+    #
+    # This was added to the give the gem "pseudo thread safety" in that it seems
+    # when initiating many parallel requests marshaling the certificate store is
+    # the most likely point of failure (see issue #382). Any program attempting
+    # to leverage this pseudo safety should make a call to this method (i.e.
+    # `Stripe.ca_store`) in their initialization code because it marshals lazily
+    # and is itself not thread safe.
+    def ca_store
+      @ca_store ||= begin
+                      store = OpenSSL::X509::Store.new
+                      store.add_file(ca_bundle_path)
+                      store
+                    end
+    end
+
+    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

data/lib/stripe/stripe_object.rb

@@ -4,7 +4,7 @@ module Stripe
   class StripeObject
     include Enumerable
 
-    @@permanent_attributes = Set.new([:id])
+    @@permanent_attributes = Set.new([:id]) # rubocop:disable Style/ClassVars
 
     # The default :id method is deprecated and isn't useful to us
     undef :id if method_defined?(:id)
@@ -93,10 +93,12 @@ module Stripe
     # considered to be equal if they have the same set of values and each one
     # of those values is the same.
     def ==(other)
-      other.is_a?(StripeObject) && @values == other.instance_variable_get(:@values)
+      other.is_a?(StripeObject) &&
+        @values == other.instance_variable_get(:@values)
     end
 
-    # Hash equality. As with `#==`, we consider two equivalent Stripe objects equal.
+    # Hash equality. As with `#==`, we consider two equivalent Stripe objects
+    # equal.
     def eql?(other)
       # Defer to the implementation on `#==`.
       self == other
@@ -121,21 +123,10 @@ module Stripe
 
     def inspect
       id_string = respond_to?(:id) && !id.nil? ? " id=#{id}" : ""
-      "#<#{self.class}:0x#{object_id.to_s(16)}#{id_string}> JSON: " + JSON.pretty_generate(@values)
+      "#<#{self.class}:0x#{object_id.to_s(16)}#{id_string}> JSON: " +
+        JSON.pretty_generate(@values)
     end
 
-    # Re-initializes the object based on a hash of values (usually one that's
-    # come back from an API call). Adds or removes value accessors as necessary
-    # and updates the state of internal data.
-    #
-    # Please don't use this method. If you're trying to do mass assignment, try
-    # #initialize_from instead.
-    def refresh_from(values, opts, partial = false)
-      initialize_from(values, opts, partial)
-    end
-    extend Gem::Deprecate
-    deprecate :refresh_from, "#update_attributes", 2016, 1
-
     # Mass assigns attributes on the model.
     #
     # This is a version of +update_attributes+ that takes some extra options
@@ -144,7 +135,8 @@ module Stripe
     # ==== Attributes
     #
     # * +values+ - Hash of values to use to update the current attributes of
-    #   the object.
+    #   the object. If you are on ruby 2.7 or higher make sure to wrap in curly
+    #   braces to be ruby 3 compatible.
     # * +opts+ - Options for +StripeObject+ like an API key that will be reused
     #   on subsequent API calls.
     #
@@ -162,12 +154,12 @@ module Stripe
       end
     end
 
-    def [](k)
-      @values[k.to_sym]
+    def [](key)
+      @values[key.to_sym]
     end
 
-    def []=(k, v)
-      send(:"#{k}=", v)
+    def []=(key, value)
+      send(:"#{key}=", value)
     end
 
     def keys
@@ -178,17 +170,20 @@ module Stripe
       @values.values
     end
 
-    def to_json(*_a)
+    def to_json(*_opts)
+      # TODO: pass opts to JSON.generate?
       JSON.generate(@values)
     end
 
-    def as_json(*a)
-      @values.as_json(*a)
+    def as_json(*opts)
+      @values.as_json(*opts)
     end
 
     def to_hash
       maybe_to_hash = lambda do |value|
-        value && value.respond_to?(:to_hash) ? value.to_hash : value
+        return nil if value.nil?
+
+        value.respond_to?(:to_hash) ? value.to_hash : value
       end
 
       @values.each_with_object({}) do |(key, value), acc|
@@ -251,10 +246,11 @@ module Stripe
         #      values within in that its parent StripeObject doesn't know about.
         #
         unsaved = @unsaved_values.include?(k)
-        if options[:force] || unsaved || v.is_a?(StripeObject)
-          update_hash[k.to_sym] =
-            serialize_params_value(@values[k], @original_values[k], unsaved, options[:force], key: k)
-        end
+        next unless options[:force] || unsaved || v.is_a?(StripeObject)
+
+        update_hash[k.to_sym] = serialize_params_value(
+          @values[k], @original_values[k], unsaved, options[:force], key: k
+        )
       end
 
       # a `nil` that makes it out of `#serialize_params_value` signals an empty
@@ -264,16 +260,6 @@ module Stripe
       update_hash
     end
 
-    class << self
-      # This class method has been deprecated in favor of the instance method
-      # of the same name.
-      def serialize_params(obj, options = {})
-        obj.serialize_params(options)
-      end
-      extend Gem::Deprecate
-      deprecate :serialize_params, "#serialize_params", 2016, 9
-    end
-
     # A protected field is one that doesn't get an accessor assigned to it
     # (i.e. `obj.public = ...`) and one which is not allowed to be updated via
     # the class level `Model.update(id, { ... })`.
@@ -281,18 +267,38 @@ module Stripe
       []
     end
 
-    protected
-
-    def metaclass
+    # When designing APIs, we now make a conscious effort server-side to avoid
+    # naming fields after important built-ins in various languages (e.g. class,
+    # method, etc.).
+    #
+    # However, a long time ago we made the mistake (either consciously or by
+    # accident) of initializing our `metadata` fields as instances of
+    # `StripeObject`, and metadata can have a wide range of different keys
+    # defined in it. This is somewhat a convenient in that it allows users to
+    # access data like `obj.metadata.my_field`, but is almost certainly not
+    # worth the cost.
+    #
+    # Naming metadata fields bad things like `class` causes `initialize_from`
+    # to produce strange results, so we ban known offenders here.
+    #
+    # In a future major version we should consider leaving `metadata` as a hash
+    # and forcing people to access it with `obj.metadata[:my_field]` because
+    # the potential for trouble is just too high. For now, reserve names.
+    RESERVED_FIELD_NAMES = [
+      :class,
+    ].freeze
+
+    protected def metaclass
       class << self; self; end
     end
 
-    def remove_accessors(keys)
+    protected def remove_accessors(keys)
       # not available in the #instance_eval below
       protected_fields = self.class.protected_fields
 
       metaclass.instance_eval do
         keys.each do |k|
+          next if RESERVED_FIELD_NAMES.include?(k)
           next if protected_fields.include?(k)
           next if @@permanent_attributes.include?(k)
 
@@ -313,7 +319,7 @@ module Stripe
               #
               # Here we swallow that error and issue a warning so at least
               # the program doesn't crash.
-              $stderr.puts("WARNING: Unable to remove method `#{method_name}`; " \
+              warn("WARNING: Unable to remove method `#{method_name}`; " \
                 "if custom, please consider renaming to a name that doesn't " \
                 "collide with an API property name.")
             end
@@ -322,12 +328,13 @@ module Stripe
       end
     end
 
-    def add_accessors(keys, values)
+    protected def add_accessors(keys, values)
       # not available in the #instance_eval below
       protected_fields = self.class.protected_fields
 
       metaclass.instance_eval do
         keys.each do |k|
+          next if RESERVED_FIELD_NAMES.include?(k)
           next if protected_fields.include?(k)
           next if @@permanent_attributes.include?(k)
 
@@ -359,7 +366,11 @@ module Stripe
       end
     end
 
-    def method_missing(name, *args)
+    # Disabling the cop because it's confused by the fact that the methods are
+    # protected, but we do define `#respond_to_missing?` just below. Hopefully
+    # this is fixed in more recent Rubocop versions.
+    # rubocop:disable Style/MissingRespondToMissing
+    protected def method_missing(name, *args)
       # TODO: only allow setting in updateable classes.
       if name.to_s.end_with?("=")
         attr = name.to_s[0...-1].to_sym
@@ -375,7 +386,9 @@ module Stripe
         begin
           mth = method(name)
         rescue NameError
-          raise NoMethodError, "Cannot set #{attr} on this object. HINT: you can't set: #{@@permanent_attributes.to_a.join(', ')}"
+          raise NoMethodError,
+                "Cannot set #{attr} on this object. HINT: you can't set: " \
+                "#{@@permanent_attributes.to_a.join(', ')}"
         end
         return mth.call(args[0])
       elsif @values.key?(name)
@@ -385,16 +398,22 @@ module Stripe
       begin
         super
       rescue NoMethodError => e
-        # If we notice the accessed name if our set of transient values we can
+        # If we notice the accessed name of our set of transient values we can
         # give the user a slightly more helpful error message. If not, just
         # raise right away.
         raise unless @transient_values.include?(name)
 
-        raise NoMethodError, e.message + ".  HINT: The '#{name}' attribute was set in the past, however.  It was then wiped when refreshing the object with the result returned by Stripe's API, probably as a result of a save().  The attributes currently available on this object are: #{@values.keys.join(', ')}"
+        raise NoMethodError,
+              e.message + ".  HINT: The '#{name}' attribute was set in the " \
+              "past, however.  It was then wiped when refreshing the object " \
+              "with the result returned by Stripe's API, probably as a " \
+              "result of a save().  The attributes currently available on " \
+              "this object are: #{@values.keys.join(', ')}"
       end
     end
+    # rubocop:enable Style/MissingRespondToMissing
 
-    def respond_to_missing?(symbol, include_private = false)
+    protected def respond_to_missing?(symbol, include_private = false)
       @values && @values.key?(symbol) || super
     end
 
@@ -410,7 +429,7 @@ module Stripe
     # * +:opts:+ Options for StripeObject like an API key.
     # * +:partial:+ Indicates that the re-initialization should not attempt to
     #   remove accessors.
-    def initialize_from(values, opts, partial = false)
+    protected def initialize_from(values, opts, partial = false)
       @opts = Util.normalize_opts(opts)
 
       # the `#send` is here so that we can keep this method private
@@ -420,8 +439,8 @@ module Stripe
       added = Set.new(values.keys - @values.keys)
 
       # Wipe old state before setting new.  This is useful for e.g. updating a
-      # customer, where there is no persistent card parameter.  Mark those values
-      # which don't persist as transient
+      # customer, where there is no persistent card parameter.  Mark those
+      # values which don't persist as transient
 
       remove_accessors(removed)
       add_accessors(added, values)
@@ -441,7 +460,8 @@ module Stripe
       self
     end
 
-    def serialize_params_value(value, original, unsaved, force, key: nil)
+    protected def serialize_params_value(value, original, unsaved, force,
+                                         key: nil)
       if value.nil?
         ""
 
@@ -516,11 +536,9 @@ module Stripe
       end
     end
 
-    private
-
     # Produces a deep copy of the given object including support for arrays,
     # hashes, and StripeObjects.
-    def self.deep_copy(obj)
+    private_class_method def self.deep_copy(obj)
       case obj
       when Array
         obj.map { |e| deep_copy(e) }
@@ -540,9 +558,8 @@ module Stripe
         obj
       end
     end
-    private_class_method :deep_copy
 
-    def dirty_value!(value)
+    private def dirty_value!(value)
       case value
       when Array
         value.map { |v| dirty_value!(v) }
@@ -553,12 +570,14 @@ module Stripe
 
     # Returns a hash of empty values for all the values that are in the given
     # StripeObject.
-    def empty_values(obj)
+    private def empty_values(obj)
       values = case obj
                when Hash         then obj
                when StripeObject then obj.instance_variable_get(:@values)
                else
-                 raise ArgumentError, "#empty_values got unexpected object type: #{obj.class.name}"
+                 raise ArgumentError,
+                       "#empty_values got unexpected object type: " \
+                       "#{obj.class.name}"
                end
 
       values.each_with_object({}) do |(k, _), update|

data/lib/stripe/stripe_response.rb

@@ -1,16 +1,54 @@
 # frozen_string_literal: true
 
 module Stripe
-  # StripeResponse encapsulates some vitals of a response that came back from
-  # the Stripe API.
-  class StripeResponse
-    # The data contained by the HTTP body of the response deserialized from
-    # JSON.
-    attr_accessor :data
+  # Headers provides an access wrapper to an API response's header data. It
+  # mainly exists so that we don't need to expose the entire
+  # `Net::HTTPResponse` object while still getting some of its benefits like
+  # case-insensitive access to header names and flattening of header values.
+  class StripeResponseHeaders
+    # Initializes a Headers object from a Net::HTTP::HTTPResponse object.
+    def self.from_net_http(resp)
+      new(resp.to_hash)
+    end
 
-    # The raw HTTP body of the response.
-    attr_accessor :http_body
+    # `hash` is expected to be a hash mapping header names to arrays of
+    # header values. This is the default format generated by calling
+    # `#to_hash` on a `Net::HTTPResponse` object because headers can be
+    # repeated multiple times. Using `#[]` will collapse values down to just
+    # the first.
+    def initialize(hash)
+      if !hash.is_a?(Hash) ||
+         !hash.keys.all? { |n| n.is_a?(String) } ||
+         !hash.values.all? { |a| a.is_a?(Array) } ||
+         !hash.values.all? { |a| a.all? { |v| v.is_a?(String) } }
+        raise ArgumentError,
+              "expect hash to be a map of string header names to arrays of " \
+              "header values"
+      end
 
+      @hash = {}
+
+      # This shouldn't be strictly necessary because `Net::HTTPResponse` will
+      # produce a hash with all headers downcased, but do it anyway just in
+      # case an object of this class was constructed manually.
+      #
+      # Also has the effect of duplicating the hash, which is desirable for a
+      # little extra object safety.
+      hash.each do |k, v|
+        @hash[k.downcase] = v
+      end
+    end
+
+    def [](name)
+      values = @hash[name.downcase]
+      if values && values.count > 1
+        warn("Duplicate header values for `#{name}`; returning only first")
+      end
+      values ? values.first : nil
+    end
+  end
+
+  module StripeResponseBase
     # A Hash of the HTTP headers of the response.
     attr_accessor :http_headers
 
@@ -20,30 +58,52 @@ module Stripe
     # The Stripe request ID of the response.
     attr_accessor :request_id
 
-    # Initializes a StripeResponse object from a Hash like the kind returned as
-    # part of a Faraday exception.
-    #
-    # This may throw JSON::ParserError if the response body is not valid JSON.
-    def self.from_faraday_hash(http_resp)
-      resp = StripeResponse.new
-      resp.data = JSON.parse(http_resp[:body], symbolize_names: true)
-      resp.http_body = http_resp[:body]
-      resp.http_headers = http_resp[:headers]
-      resp.http_status = http_resp[:status]
-      resp.request_id = http_resp[:headers]["Request-Id"]
-      resp
+    def self.populate_for_net_http(resp, http_resp)
+      resp.http_headers = StripeResponseHeaders.from_net_http(http_resp)
+      resp.http_status = http_resp.code.to_i
+      resp.request_id = http_resp["request-id"]
     end
+  end
 
-    # Initializes a StripeResponse object from a Faraday HTTP response object.
-    #
-    # This may throw JSON::ParserError if the response body is not valid JSON.
-    def self.from_faraday_response(http_resp)
+  # StripeResponse encapsulates some vitals of a response that came back from
+  # the Stripe API.
+  class StripeResponse
+    include StripeResponseBase
+    # The data contained by the HTTP body of the response deserialized from
+    # JSON.
+    attr_accessor :data
+
+    # The raw HTTP body of the response.
+    attr_accessor :http_body
+
+    # Initializes a StripeResponse object from a Net::HTTP::HTTPResponse
+    # object.
+    def self.from_net_http(http_resp)
       resp = StripeResponse.new
       resp.data = JSON.parse(http_resp.body, symbolize_names: true)
       resp.http_body = http_resp.body
-      resp.http_headers = http_resp.headers
-      resp.http_status = http_resp.status
-      resp.request_id = http_resp.headers["Request-Id"]
+      StripeResponseBase.populate_for_net_http(resp, http_resp)
+      resp
+    end
+  end
+
+  # We have to alias StripeResponseHeaders to StripeResponse::Headers, as this
+  # class used to be embedded within StripeResponse and we want to be backwards
+  # compatible.
+  StripeResponse::Headers = StripeResponseHeaders
+
+  # StripeHeadersOnlyResponse includes only header-related vitals of the
+  # response. This is used for streaming requests where the response was read
+  # directly in a block and we explicitly don't want to store the body of the
+  # response in memory.
+  class StripeHeadersOnlyResponse
+    include StripeResponseBase
+
+    # Initializes a StripeHeadersOnlyResponse object from a
+    # Net::HTTP::HTTPResponse object.
+    def self.from_net_http(http_resp)
+      resp = StripeHeadersOnlyResponse.new
+      StripeResponseBase.populate_for_net_http(resp, http_resp)
       resp
     end
   end