stripe 3.3.1 → 5.38.0

data/lib/stripe/stripe_response.rb

@@ -1,14 +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
 
@@ -18,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

data/lib/stripe/util.rb

@@ -1,68 +1,50 @@
+# frozen_string_literal: true
+
 require "cgi"
 
 module Stripe
   module Util
-    def self.objects_to_ids(h)
-      case h
+    # Options that a user is allowed to specify.
+    OPTS_USER_SPECIFIED = Set[
+      :api_key,
+      :idempotency_key,
+      :stripe_account,
+      :stripe_version
+    ].freeze
+
+    # Options that should be copyable from one StripeObject to another
+    # including options that may be internal.
+    OPTS_COPYABLE = (
+      OPTS_USER_SPECIFIED + Set[:api_base]
+    ).freeze
+
+    # Options that should be persisted between API requests. This includes
+    # client, which is an object containing an HTTP client to reuse.
+    OPTS_PERSISTABLE = (
+      OPTS_USER_SPECIFIED + Set[:client] - Set[:idempotency_key]
+    ).freeze
+
+    def self.objects_to_ids(obj)
+      case obj
       when APIResource
-        h.id
+        obj.id
       when Hash
         res = {}
-        h.each { |k, v| res[k] = objects_to_ids(v) unless v.nil? }
+        obj.each { |k, v| res[k] = objects_to_ids(v) unless v.nil? }
         res
       when Array
-        h.map { |v| objects_to_ids(v) }
+        obj.map { |v| objects_to_ids(v) }
       else
-        h
+        obj
       end
     end
 
     def self.object_classes
-      @object_classes ||= {
-        # data structures
-        ListObject::OBJECT_NAME => ListObject,
-
-        # business objects
-        Account::OBJECT_NAME              => Account,
-        AlipayAccount::OBJECT_NAME        => AlipayAccount,
-        ApplePayDomain::OBJECT_NAME       => ApplePayDomain,
-        ApplicationFee::OBJECT_NAME       => ApplicationFee,
-        ApplicationFeeRefund::OBJECT_NAME => ApplicationFeeRefund,
-        Balance::OBJECT_NAME              => Balance,
-        BalanceTransaction::OBJECT_NAME   => BalanceTransaction,
-        BankAccount::OBJECT_NAME          => BankAccount,
-        BitcoinReceiver::OBJECT_NAME      => BitcoinReceiver,
-        BitcoinTransaction::OBJECT_NAME   => BitcoinTransaction,
-        Card::OBJECT_NAME                 => Card,
-        Charge::OBJECT_NAME               => Charge,
-        CountrySpec::OBJECT_NAME          => CountrySpec,
-        Coupon::OBJECT_NAME               => Coupon,
-        Customer::OBJECT_NAME             => Customer,
-        Dispute::OBJECT_NAME              => Dispute,
-        EphemeralKey::OBJECT_NAME         => EphemeralKey,
-        Event::OBJECT_NAME                => Event,
-        FileUpload::OBJECT_NAME           => FileUpload,
-        Invoice::OBJECT_NAME              => Invoice,
-        InvoiceItem::OBJECT_NAME          => InvoiceItem,
-        InvoiceLineItem::OBJECT_NAME      => InvoiceLineItem,
-        LoginLink::OBJECT_NAME            => LoginLink,
-        Order::OBJECT_NAME                => Order,
-        OrderReturn::OBJECT_NAME          => OrderReturn,
-        Payout::OBJECT_NAME               => Payout,
-        Plan::OBJECT_NAME                 => Plan,
-        Product::OBJECT_NAME              => Product,
-        Recipient::OBJECT_NAME            => Recipient,
-        RecipientTransfer::OBJECT_NAME    => RecipientTransfer,
-        Refund::OBJECT_NAME               => Refund,
-        Reversal::OBJECT_NAME             => Reversal,
-        SKU::OBJECT_NAME                  => SKU,
-        Source::OBJECT_NAME               => Source,
-        Subscription::OBJECT_NAME         => Subscription,
-        SubscriptionItem::OBJECT_NAME     => SubscriptionItem,
-        ThreeDSecure::OBJECT_NAME         => ThreeDSecure,
-        Token::OBJECT_NAME                => Token,
-        Transfer::OBJECT_NAME             => Transfer,
-      }
+      @object_classes ||= Stripe::ObjectTypes.object_names_to_classes
+    end
+
+    def self.object_name_matches_class?(object_name, klass)
+      Util.object_classes[object_name] == klass
     end
 
     # Converts a hash of fields or an array of hashes into a +StripeObject+ or
@@ -78,51 +60,48 @@ module Stripe
     # * +opts+ - Options for +StripeObject+ like an API key that will be reused
     #   on subsequent API calls.
     def self.convert_to_stripe_object(data, opts = {})
+      opts = normalize_opts(opts)
+
       case data
       when Array
         data.map { |i| convert_to_stripe_object(i, opts) }
       when Hash
-        # Try converting to a known object class.  If none available, fall back to generic StripeObject
-        object_classes.fetch(data[:object], StripeObject).construct_from(data, opts)
+        # Try converting to a known object class.  If none available, fall back
+        # to generic StripeObject
+        object_classes.fetch(data[:object], StripeObject)
+                      .construct_from(data, opts)
       else
         data
       end
     end
 
     def self.log_error(message, data = {})
-      if !Stripe.logger.nil? ||
-          !Stripe.log_level.nil? && Stripe.log_level <= Stripe::LEVEL_ERROR
-        log_internal(message, data, color: :cyan,
-          level: Stripe::LEVEL_ERROR, logger: Stripe.logger, out: $stderr)
+      config = data.delete(:config) || Stripe.config
+      logger = config.logger || Stripe.logger
+      if !logger.nil? ||
+         !config.log_level.nil? && config.log_level <= Stripe::LEVEL_ERROR
+        log_internal(message, data, color: :cyan, level: Stripe::LEVEL_ERROR,
+                                    logger: Stripe.logger, out: $stderr)
       end
     end
 
     def self.log_info(message, data = {})
-      if !Stripe.logger.nil? ||
-          !Stripe.log_level.nil? && Stripe.log_level <= Stripe::LEVEL_INFO
-        log_internal(message, data, color: :cyan,
-          level: Stripe::LEVEL_INFO, logger: Stripe.logger, out: $stdout)
+      config = data.delete(:config) || Stripe.config
+      logger = config.logger || Stripe.logger
+      if !logger.nil? ||
+         !config.log_level.nil? && config.log_level <= Stripe::LEVEL_INFO
+        log_internal(message, data, color: :cyan, level: Stripe::LEVEL_INFO,
+                                    logger: Stripe.logger, out: $stdout)
       end
     end
 
     def self.log_debug(message, data = {})
-      if !Stripe.logger.nil? ||
-          !Stripe.log_level.nil? && Stripe.log_level <= Stripe::LEVEL_DEBUG
-        log_internal(message, data, color: :blue,
-          level: Stripe::LEVEL_DEBUG, logger: Stripe.logger, out: $stdout)
-      end
-    end
-
-    def self.file_readable(file)
-      # This is nominally equivalent to File.readable?, but that can
-      # report incorrect results on some more oddball filesystems
-      # (such as AFS)
-      begin
-        File.open(file) { |f| }
-      rescue
-        false
-      else
-        true
+      config = data.delete(:config) || Stripe.config
+      logger = config.logger || Stripe.logger
+      if !logger.nil? ||
+         !config.log_level.nil? && config.log_level <= Stripe::LEVEL_DEBUG
+        log_internal(message, data, color: :blue, level: Stripe::LEVEL_DEBUG,
+                                    logger: Stripe.logger, out: $stdout)
       end
     end
 
@@ -131,7 +110,11 @@ module Stripe
       when Hash
         new_hash = {}
         object.each do |key, value|
-          key = (key.to_sym rescue key) || key
+          key = (begin
+                   key.to_sym
+                 rescue StandardError
+                   key
+                 end) || key
           new_hash[key] = symbolize_names(value)
         end
         new_hash
@@ -147,22 +130,8 @@ module Stripe
     # involves escaping special characters from parameter keys and values (e.g.
     # `&`).
     def self.encode_parameters(params)
-      Util.flatten_params(params).
-        map { |k,v| "#{url_encode(k)}=#{url_encode(v)}" }.join('&')
-    end
-
-    # Transforms an array into a hash with integer keys. Used for a small
-    # number of API endpoints. If the argument is not an Array, return it
-    # unchanged. Example: [{foo: 'bar'}] => {"0" => {foo: "bar"}}
-    def self.array_to_hash(array)
-      case array
-      when Array
-        hash = {}
-        array.each_with_index { |v,i| hash[i.to_s] = v }
-        hash
-      else
-        array
-      end
+      Util.flatten_params(params)
+          .map { |k, v| "#{url_encode(k)}=#{url_encode(v)}" }.join("&")
     end
 
     # Encodes a string in a way that makes it suitable for use in a set of
@@ -173,20 +142,19 @@ module Stripe
         # Don't use strict form encoding by changing the square bracket control
         # characters back to their literals. This is fine by the server, and
         # makes these parameter strings easier to read.
-        gsub('%5B', '[').gsub('%5D', ']')
+        gsub("%5B", "[").gsub("%5D", "]")
     end
 
-    def self.flatten_params(params, parent_key=nil)
+    def self.flatten_params(params, parent_key = nil)
       result = []
 
       # do not sort the final output because arrays (and arrays of hashes
       # especially) can be order sensitive, but do sort incoming parameters
       params.each do |key, value|
-        calculated_key = parent_key ? "#{parent_key}[#{key}]" : "#{key}"
+        calculated_key = parent_key ? "#{parent_key}[#{key}]" : key.to_s
         if value.is_a?(Hash)
           result += flatten_params(value, calculated_key)
         elsif value.is_a?(Array)
-          check_array_of_maps_start_keys!(value)
           result += flatten_params_array(value, calculated_key)
         else
           result << [calculated_key, value]
@@ -198,20 +166,32 @@ module Stripe
 
     def self.flatten_params_array(value, calculated_key)
       result = []
-      value.each do |elem|
+      value.each_with_index do |elem, i|
         if elem.is_a?(Hash)
-          result += flatten_params(elem, "#{calculated_key}[]")
+          result += flatten_params(elem, "#{calculated_key}[#{i}]")
         elsif elem.is_a?(Array)
           result += flatten_params_array(elem, calculated_key)
         else
-          result << ["#{calculated_key}[]", elem]
+          result << ["#{calculated_key}[#{i}]", elem]
         end
       end
       result
     end
 
+    # `Time.now` can be unstable in cases like an administrator manually
+    # updating its value or a reconcilation via NTP. For this reason, prefer
+    # the use of the system's monotonic clock especially where comparing times
+    # to calculate an elapsed duration.
+    #
+    # Shortcut for getting monotonic time, mostly for purposes of line length
+    # and test stubbing. Returns time in seconds since the event used for
+    # monotonic reference purposes by the platform (e.g. system boot time).
+    def self.monotonic_time
+      Process.clock_gettime(Process::CLOCK_MONOTONIC)
+    end
+
     def self.normalize_id(id)
-      if id.kind_of?(Hash) # overloaded id
+      if id.is_a?(Hash) # overloaded id
         params_hash = id.dup
         id = params_hash.delete(:id)
       else
@@ -225,22 +205,26 @@ module Stripe
     def self.normalize_opts(opts)
       case opts
       when String
-        {:api_key => opts}
+        { api_key: opts }
       when Hash
-        check_api_key!(opts.fetch(:api_key)) if opts.has_key?(:api_key)
-        opts.clone
+        check_api_key!(opts.fetch(:api_key)) if opts.key?(:api_key)
+        # Explicitly use dup here instead of clone to avoid preserving freeze
+        # state on input params.
+        opts.dup
       else
-        raise TypeError.new('normalize_opts expects a string or a hash')
+        raise TypeError, "normalize_opts expects a string or a hash"
       end
     end
 
     def self.check_string_argument!(key)
-      raise TypeError.new("argument must be a string") unless key.is_a?(String)
+      raise TypeError, "argument must be a string" unless key.is_a?(String)
+
       key
     end
 
     def self.check_api_key!(key)
-      raise TypeError.new("api_key must be a string") unless key.is_a?(String)
+      raise TypeError, "api_key must be a string" unless key.is_a?(String)
+
       key
     end
 
@@ -250,15 +234,11 @@ module Stripe
     # certain key values when the user could have set them with a variety of
     # diffent naming schemes.
     def self.normalize_headers(headers)
-      headers.inject({}) do |new_headers, (k, v)|
-        if k.is_a?(Symbol)
-          k = titlecase_parts(k.to_s.gsub("_", "-"))
-        elsif k.is_a?(String)
-          k = titlecase_parts(k)
-        end
+      headers.each_with_object({}) do |(k, v), new_headers|
+        k = k.to_s.tr("_", "-") if k.is_a?(Symbol)
+        k = k.split("-").reject(&:empty?).map(&:capitalize).join("-")
 
         new_headers[k] = v
-        new_headers
       end
     end
 
@@ -272,69 +252,33 @@ module Stripe
 
     # Constant time string comparison to prevent timing attacks
     # Code borrowed from ActiveSupport
-    def self.secure_compare(a, b)
-      return false unless a.bytesize == b.bytesize
+    def self.secure_compare(str_a, str_b)
+      return false unless str_a.bytesize == str_b.bytesize
 
-      l = a.unpack "C#{a.bytesize}"
+      l = str_a.unpack "C#{str_a.bytesize}"
 
       res = 0
-      b.each_byte { |byte| res |= byte ^ l.shift }
-      res == 0
+      str_b.each_byte { |byte| res |= byte ^ l.shift }
+      res.zero?
     end
 
-    private
+    #
+    # private
+    #
 
     COLOR_CODES = {
-      :black   => 0, :light_black    => 60,
-      :red     => 1, :light_red      => 61,
-      :green   => 2, :light_green    => 62,
-      :yellow  => 3, :light_yellow   => 63,
-      :blue    => 4, :light_blue     => 64,
-      :magenta => 5, :light_magenta  => 65,
-      :cyan    => 6, :light_cyan     => 66,
-      :white   => 7, :light_white    => 67,
-      :default => 9
-    }
+      black: 0, light_black: 60,
+      red: 1, light_red: 61,
+      green: 2, light_green: 62,
+      yellow: 3, light_yellow: 63,
+      blue: 4, light_blue: 64,
+      magenta: 5, light_magenta: 65,
+      cyan: 6, light_cyan: 66,
+      white: 7, light_white: 67,
+      default: 9,
+    }.freeze
     private_constant :COLOR_CODES
 
-    # We use a pretty janky version of form encoding (Rack's) that supports
-    # more complex data structures like maps and arrays through the use of
-    # specialized syntax. To encode an array of maps like:
-    #
-    #     [{a: 1, b: 2}, {a: 3, b: 4}]
-    #
-    # We have to produce something that looks like this:
-    #
-    #     arr[][a]=1&arr[][b]=2&arr[][a]=3&arr[][b]=4
-    #
-    # The only way for the server to recognize that this is a two item array is
-    # that it notices the repetition of element "a", so it's key that these
-    # repeated elements are encoded first.
-    #
-    # This method is invoked for any arrays being encoded and checks that if
-    # the array contains all non-empty maps, that each of those maps must start
-    # with the same key so that their boundaries can be properly encoded.
-    def self.check_array_of_maps_start_keys!(arr)
-      expected_key = nil
-      arr.each do |item|
-        return if !item.is_a?(Hash)
-        return if item.count == 0
-
-        first_key = item.first[0]
-
-        if expected_key
-          if expected_key != first_key
-            raise ArgumentError,
-              "All maps nested in an array should start with the same key " +
-              "(expected starting key '#{expected_key}', got '#{first_key}')"
-          end
-        else
-          expected_key = first_key
-        end
-      end
-    end
-    private_class_method :check_array_of_maps_start_keys!
-
     # Uses an ANSI escape code to colorize text if it's going to be sent to a
     # TTY.
     def self.colorize(val, color, isatty)
@@ -359,40 +303,36 @@ module Stripe
     end
     private_class_method :level_name
 
-    # TODO: Make these named required arguments when we drop support for Ruby
-    # 2.0.
-    def self.log_internal(message, data = {}, color: nil, level: nil, logger: nil, out: nil)
-      data_str = data.select { |k,v| !v.nil? }.
-        map { |(k,v)|
-          "%s=%s" % [
-            colorize(k, color, !out.nil? && out.isatty),
-            wrap_logfmt_value(v)
-          ]
-        }.join(" ")
+    def self.log_internal(message, data = {}, color:, level:, logger:, out:)
+      data_str = data.reject { |_k, v| v.nil? }
+                     .map do |(k, v)|
+        format("%<key>s=%<value>s",
+               key: colorize(k, color, logger.nil? && !out.nil? && out.isatty),
+               value: wrap_logfmt_value(v))
+      end.join(" ")
 
       if !logger.nil?
         # the library's log levels are mapped to the same values as the
         # standard library's logger
         logger.log(level,
-          "message=%s %s" % [wrap_logfmt_value(message), data_str])
+                   format("message=%<message>s %<data_str>s",
+                          message: wrap_logfmt_value(message),
+                          data_str: data_str))
       elsif out.isatty
-        out.puts "%s %s %s" %
-          [colorize(level_name(level)[0, 4].upcase, color, out.isatty), message, data_str]
+        out.puts format("%<level>s %<message>s %<data_str>s",
+                        level: colorize(level_name(level)[0, 4].upcase,
+                                        color, out.isatty),
+                        message: message,
+                        data_str: data_str)
       else
-        out.puts "message=%s level=%s %s" %
-          [wrap_logfmt_value(message), level_name(level), data_str]
+        out.puts format("message=%<message>s level=%<level>s %<data_str>s",
+                        message: wrap_logfmt_value(message),
+                        level: level_name(level),
+                        data_str: data_str)
       end
     end
     private_class_method :log_internal
 
-    def self.titlecase_parts(s)
-      s.split("-").
-        select { |p| p != "" }.
-        map { |p| p[0].upcase + p[1..-1].downcase }.
-        join("-")
-    end
-    private_class_method :titlecase_parts
-
     # Wraps a value in double quotes if it looks sufficiently complex so that
     # it can be read by logfmt parsers.
     def self.wrap_logfmt_value(val)
@@ -406,7 +346,7 @@ module Stripe
       if %r{[^\w\-/]} =~ val
         # If the string contains any special characters, escape any double
         # quotes it has, remove newlines, and wrap the whole thing in quotes.
-        %{"%s"} % val.gsub('"', '\"').gsub("\n", "")
+        format(%("%<value>s"), value: val.gsub('"', '\"').delete("\n"))
       else
         # Otherwise use the basic value if it looks like a standard set of
         # characters (and allow a few special characters like hyphens, and

data/lib/stripe/version.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module Stripe
-  VERSION = '3.3.1'
+  VERSION = "5.38.0"
 end