stripe 1.31.0 → 1.58.0

data/lib/stripe.rb

@@ -14,76 +14,144 @@ require 'stripe/version'
 
 # API operations
 require 'stripe/api_operations/create'
-require 'stripe/api_operations/update'
+require 'stripe/api_operations/save'
 require 'stripe/api_operations/delete'
 require 'stripe/api_operations/list'
 require 'stripe/api_operations/request'
 
-# Resources
+# API resource support classes
+require 'stripe/errors'
 require 'stripe/util'
 require 'stripe/stripe_object'
+require 'stripe/list_object'
 require 'stripe/api_resource'
 require 'stripe/singleton_api_resource'
-require 'stripe/list_object'
+
+# Named API resources
 require 'stripe/account'
+require 'stripe/alipay_account'
+require 'stripe/apple_pay_domain'
+require 'stripe/application_fee'
+require 'stripe/application_fee_refund'
 require 'stripe/balance'
 require 'stripe/balance_transaction'
+require 'stripe/bank_account'
+require 'stripe/bitcoin_receiver'
+require 'stripe/bitcoin_transaction'
+require 'stripe/card'
+require 'stripe/charge'
+require 'stripe/country_spec'
+require 'stripe/coupon'
 require 'stripe/customer'
+require 'stripe/dispute'
+require 'stripe/event'
+require 'stripe/file_upload'
 require 'stripe/invoice'
 require 'stripe/invoice_item'
-require 'stripe/charge'
+require 'stripe/order'
+require 'stripe/order_return'
 require 'stripe/plan'
-require 'stripe/file_upload'
-require 'stripe/coupon'
-require 'stripe/token'
-require 'stripe/event'
-require 'stripe/transfer'
+require 'stripe/product'
 require 'stripe/recipient'
-require 'stripe/bank_account'
-require 'stripe/card'
-require 'stripe/subscription'
-require 'stripe/application_fee'
 require 'stripe/refund'
 require 'stripe/reversal'
-require 'stripe/application_fee_refund'
-require 'stripe/bitcoin_receiver'
-require 'stripe/bitcoin_transaction'
-require 'stripe/dispute'
-require 'stripe/product'
 require 'stripe/sku'
-require 'stripe/order'
-
-# Errors
-require 'stripe/errors/stripe_error'
-require 'stripe/errors/api_error'
-require 'stripe/errors/api_connection_error'
-require 'stripe/errors/card_error'
-require 'stripe/errors/invalid_request_error'
-require 'stripe/errors/authentication_error'
-require 'stripe/errors/rate_limit_error'
+require 'stripe/source'
+require 'stripe/subscription'
+require 'stripe/subscription_item'
+require 'stripe/three_d_secure'
+require 'stripe/token'
+require 'stripe/transfer'
 
 module Stripe
   DEFAULT_CA_BUNDLE_PATH = File.dirname(__FILE__) + '/data/ca-certificates.crt'
 
+  # Exceptions which we'd like to retry. This includes both socket errors that
+  # may represent an intermittent problem and some special HTTP statuses.
+  RETRY_EXCEPTIONS = [
+    # Destination refused the connection. This could occur from a single
+    # saturated server, so retry in case it's intermittent.
+    Errno::ECONNREFUSED,
+
+    # Connection reset. This occasionally occurs on a server problem, and
+    # deserves a retry because the server should terminate all requests
+    # properly even if they were invalid.
+    Errno::ECONNRESET,
+
+    # Timed out making the connection. It's worth retrying under this
+    # circumstance.
+    Errno::ETIMEDOUT,
+
+    # A server may respond with a 409 to indicate that there is a concurrent
+    # request executing with the same idempotency key. In the case that a
+    # request failed due to a connection problem and the client has retried too
+    # early, but the server is still executing the old request, we would like
+    # the client to continue retrying until getting a "real" response status
+    # back.
+    RestClient::Conflict,
+
+    # Retry on timeout-related problems. This shouldn't be lumped in with HTTP
+    # exceptions, but with RestClient it is.
+    RestClient::RequestTimeout,
+  ].freeze
+
   @api_base = 'https://api.stripe.com'
   @connect_base = 'https://connect.stripe.com'
   @uploads_base = 'https://uploads.stripe.com'
 
-  @ssl_bundle_path  = DEFAULT_CA_BUNDLE_PATH
+  @max_network_retries = 0
+  @max_network_retry_delay = 2
+  @initial_network_retry_delay = 0.5
+
+  @ca_bundle_path  = DEFAULT_CA_BUNDLE_PATH
+  @ca_store = nil
   @verify_ssl_certs = true
 
   @open_timeout = 30
   @read_timeout = 80
 
   class << self
-    attr_accessor :api_key, :api_base, :verify_ssl_certs, :api_version, :connect_base, :uploads_base,
+    attr_accessor :stripe_account, :api_key, :api_base, :verify_ssl_certs, :api_version, :connect_base, :uploads_base,
                   :open_timeout, :read_timeout
+
+    attr_reader :max_network_retry_delay, :initial_network_retry_delay
   end
 
   def self.api_url(url='', api_base_url=nil)
     (api_base_url || @api_base) + url
   end
 
+  # 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.
+  def self.ca_bundle_path
+    @ca_bundle_path
+  end
+
+  def self.ca_bundle_path=(path)
+    @ca_bundle_path = path
+
+    # empty this field so a new store is initialized
+    @ca_store = nil
+  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 self.ca_store
+    @ca_store ||= begin
+      store = OpenSSL::X509::Store.new
+      store.add_file(ca_bundle_path)
+      store
+    end
+  end
+
   def self.request(method, url, api_key, params={}, headers={}, api_base_url=nil)
     api_base_url = api_base_url || @api_base
 
@@ -104,7 +172,7 @@ module Stripe
 
     if verify_ssl_certs
       request_opts = {:verify_ssl => OpenSSL::SSL::VERIFY_PEER,
-                      :ssl_ca_file => @ssl_bundle_path}
+                      :ssl_cert_store => ca_store}
     else
       request_opts = {:verify_ssl => false}
       unless @verify_ssl_warned
@@ -131,52 +199,84 @@ module Stripe
       end
     end
 
-    request_opts.update(:headers => request_headers(api_key).update(headers),
+    request_opts.update(:headers => request_headers(api_key, method).update(headers),
                         :method => method, :open_timeout => open_timeout,
                         :payload => payload, :url => url, :timeout => read_timeout)
 
+    response = execute_request_with_rescues(request_opts, api_base_url)
+
+    [parse(response), api_key]
+  end
+
+  def self.max_network_retries
+    @max_network_retries
+  end
+
+  def self.max_network_retries=(val)
+    @max_network_retries = val.to_i
+  end
+
+  private
+
+  def self.api_error(error, resp, error_obj)
+    APIError.new(error[:message], resp.code, resp.body, error_obj, resp.headers)
+  end
+
+  def self.authentication_error(error, resp, error_obj)
+    AuthenticationError.new(error[:message], resp.code, resp.body, error_obj,
+                            resp.headers)
+  end
+
+  def self.card_error(error, resp, error_obj)
+    CardError.new(error[:message], error[:param], error[:code],
+                  resp.code, resp.body, error_obj, resp.headers)
+  end
+
+  def self.execute_request(opts)
+    RestClient::Request.execute(opts)
+  end
+
+  def self.execute_request_with_rescues(request_opts, api_base_url, retry_count = 0)
     begin
       response = execute_request(request_opts)
-    rescue SocketError => e
-      handle_restclient_error(e, api_base_url)
-    rescue NoMethodError => e
-      # Work around RestClient bug
-      if e.message =~ /\WRequestFailed\W/
-        e = APIConnectionError.new('Unexpected HTTP response code')
-        handle_restclient_error(e, api_base_url)
-      else
-        raise
+
+    # We rescue all exceptions from a request so that we have an easy spot to
+    # implement our retry logic across the board. We'll re-raise if it's a type
+    # of exception that we didn't expect to handle.
+    rescue => e
+      if should_retry?(e, retry_count)
+        retry_count = retry_count + 1
+        sleep sleep_time(retry_count)
+        retry
       end
-    rescue RestClient::ExceptionWithResponse => e
-      if e.response
-        handle_api_error(e.response)
+
+      case e
+      when SocketError
+        response = handle_restclient_error(e, request_opts, retry_count, api_base_url)
+
+      when RestClient::ExceptionWithResponse
+        if e.response
+          handle_api_error(e.response)
+        else
+          response = handle_restclient_error(e, request_opts, retry_count, api_base_url)
+        end
+
+      when RestClient::Exception, Errno::ECONNREFUSED, OpenSSL::SSL::SSLError
+        response = handle_restclient_error(e, request_opts, retry_count, api_base_url)
+
+      # Only handle errors when we know we can do so, and re-raise otherwise.
+      # This should be pretty infrequent.
       else
-        handle_restclient_error(e, api_base_url)
+        raise
       end
-    rescue RestClient::Exception, Errno::ECONNREFUSED => e
-      handle_restclient_error(e, api_base_url)
     end
 
-    [parse(response), api_key]
+    response
   end
 
-  private
-
-  def self.user_agent
-    @uname ||= get_uname
-    lang_version = "#{RUBY_VERSION} p#{RUBY_PATCHLEVEL} (#{RUBY_RELEASE_DATE})"
-
-    {
-      :bindings_version => Stripe::VERSION,
-      :lang => 'ruby',
-      :lang_version => lang_version,
-      :platform => RUBY_PLATFORM,
-      :engine => defined?(RUBY_ENGINE) ? RUBY_ENGINE : '',
-      :publisher => 'stripe',
-      :uname => @uname,
-      :hostname => Socket.gethostname,
-    }
-
+  def self.general_api_error(rcode, rbody)
+    APIError.new("Invalid response object from API: #{rbody.inspect} " +
+                 "(HTTP response code was #{rcode})", rcode, rbody)
   end
 
   def self.get_uname
@@ -185,74 +285,31 @@ module Stripe
     else
       case RbConfig::CONFIG['host_os']
       when /linux|darwin|bsd|sunos|solaris|cygwin/i
-        _uname_uname
+        get_uname_from_system
       when /mswin|mingw/i
-        _uname_ver
+        get_uname_from_system_ver
       else
         "unknown platform"
       end
     end
   end
 
-  def self._uname_uname
+  def self.get_uname_from_system
     (`uname -a 2>/dev/null` || '').strip
+  rescue Errno::ENOENT
+    "uname executable not found"
   rescue Errno::ENOMEM # couldn't create subprocess
     "uname lookup failed"
   end
 
-  def self._uname_ver
+  def self.get_uname_from_system_ver
     (`ver` || '').strip
+  rescue Errno::ENOENT
+    "ver executable not found"
   rescue Errno::ENOMEM # couldn't create subprocess
     "uname lookup failed"
   end
 
-  # DEPRECATED. Use `Util#encode_parameters` instead.
-  def self.uri_encode(params)
-    Util.encode_parameters(params)
-  end
-  class << self
-    extend Gem::Deprecate
-    deprecate :uri_encode, "Stripe::Util#encode_parameters", 2016, 01
-  end
-
-  def self.request_headers(api_key)
-    headers = {
-      :user_agent => "Stripe/v1 RubyBindings/#{Stripe::VERSION}",
-      :authorization => "Bearer #{api_key}",
-      :content_type => 'application/x-www-form-urlencoded'
-    }
-
-    headers[:stripe_version] = api_version if api_version
-
-    begin
-      headers.update(:x_stripe_client_user_agent => JSON.generate(user_agent))
-    rescue => e
-      headers.update(:x_stripe_client_raw_user_agent => user_agent.inspect,
-                     :error => "#{e} (#{e.class})")
-    end
-  end
-
-  def self.execute_request(opts)
-    RestClient::Request.execute(opts)
-  end
-
-  def self.parse(response)
-    begin
-      # Would use :symbolize_names => true, but apparently there is
-      # some library out there that makes symbolize_names not work.
-      response = JSON.parse(response.body)
-    rescue JSON::ParserError
-      raise general_api_error(response.code, response.body)
-    end
-
-    Util.symbolize_names(response)
-  end
-
-  def self.general_api_error(rcode, rbody)
-    APIError.new("Invalid response object from API: #{rbody.inspect} " +
-                 "(HTTP response code was #{rcode})", rcode, rbody)
-  end
-
   def self.handle_api_error(resp)
     begin
       error_obj = JSON.parse(resp.body)
@@ -271,6 +328,8 @@ module Stripe
       raise authentication_error(error, resp, error_obj)
     when 402
       raise card_error(error, resp, error_obj)
+    when 403
+      raise permission_error(error, resp, error_obj)
     when 429
       raise rate_limit_error(error, resp, error_obj)
     else
@@ -279,31 +338,8 @@ module Stripe
 
   end
 
-  def self.invalid_request_error(error, resp, error_obj)
-    InvalidRequestError.new(error[:message], error[:param], resp.code,
-                            resp.body, error_obj, resp.headers)
-  end
-
-  def self.authentication_error(error, resp, error_obj)
-    AuthenticationError.new(error[:message], resp.code, resp.body, error_obj,
-                            resp.headers)
-  end
-
-  def self.rate_limit_error(error, resp, error_obj)
-    RateLimitError.new(error[:message], resp.code, resp.body, error_obj,
-                       resp.headers)
-  end
-
-  def self.card_error(error, resp, error_obj)
-    CardError.new(error[:message], error[:param], error[:code],
-                  resp.code, resp.body, error_obj, resp.headers)
-  end
-
-  def self.api_error(error, resp, error_obj)
-    APIError.new(error[:message], resp.code, resp.body, error_obj, resp.headers)
-  end
+  def self.handle_restclient_error(e, request_opts, retry_count, api_base_url=nil)
 
-  def self.handle_restclient_error(e, api_base_url=nil)
     api_base_url = @api_base unless api_base_url
     connection_message = "Please check your internet connection and try again. " \
         "If this problem persists, you should check Stripe's service status at " \
@@ -317,6 +353,12 @@ module Stripe
       message = "The connection to the server (#{api_base_url}) broke before the " \
         "request completed. #{connection_message}"
 
+    when OpenSSL::SSL::SSLError
+      message = "Could not establish a secure connection to Stripe, you may " \
+                "need to upgrade your OpenSSL version. To check, try running " \
+                "'openssl s_client -connect api.stripe.com:443' from the " \
+                "command line."
+
     when RestClient::SSLCertificateNotVerified
       message = "Could not verify Stripe's SSL certificate. " \
         "Please make sure that your network is not intercepting certificates. " \
@@ -334,6 +376,107 @@ module Stripe
 
     end
 
+    if retry_count > 0
+      message += " Request was retried #{retry_count} times."
+    end
+
     raise APIConnectionError.new(message + "\n\n(Network error: #{e.message})")
   end
+
+  def self.invalid_request_error(error, resp, error_obj)
+    InvalidRequestError.new(error[:message], error[:param], resp.code,
+                            resp.body, error_obj, resp.headers)
+  end
+
+  def self.parse(response)
+    begin
+      # Would use :symbolize_names => true, but apparently there is
+      # some library out there that makes symbolize_names not work.
+      response = JSON.parse(response.body)
+    rescue JSON::ParserError
+      raise general_api_error(response.code, response.body)
+    end
+
+    Util.symbolize_names(response)
+  end
+
+  def self.permission_error(error, resp, error_obj)
+    PermissionError.new(error[:message], resp.code, resp.body, error_obj, resp.headers)
+  end
+
+  def self.rate_limit_error(error, resp, error_obj)
+    RateLimitError.new(error[:message], resp.code, resp.body, error_obj,
+                       resp.headers)
+  end
+
+  def self.request_headers(api_key, method)
+    headers = {
+      'User-Agent' => "Stripe/v1 RubyBindings/#{Stripe::VERSION}",
+      'Authorization' => "Bearer #{api_key}",
+      'Content-Type' => 'application/x-www-form-urlencoded'
+    }
+
+    # It is only safe to retry network failures on post and delete
+    # requests if we add an Idempotency-Key header
+    if [:post, :delete].include?(method) && self.max_network_retries > 0
+      headers['Idempotency-Key'] ||= SecureRandom.uuid
+    end
+
+    headers['Stripe-Version'] = api_version if api_version
+    headers['Stripe-Account'] = stripe_account if stripe_account
+
+    begin
+      headers.update('X-Stripe-Client-User-Agent' => JSON.generate(user_agent))
+    rescue => e
+      headers.update('X-Stripe-Client-Raw-User-Agent' => user_agent.inspect,
+                     :error => "#{e} (#{e.class})")
+    end
+  end
+
+  def self.should_retry?(e, retry_count)
+    retry_count < self.max_network_retries &&
+      RETRY_EXCEPTIONS.any? { |klass| e.is_a?(klass) }
+  end
+
+  def self.sleep_time(retry_count)
+    # Apply exponential backoff with initial_network_retry_delay on the number
+    # of attempts so far as inputs. Do not allow the number to exceed
+    # max_network_retry_delay.
+    sleep_seconds = [initial_network_retry_delay * (2 ** (retry_count - 1)), max_network_retry_delay].min
+
+    # Apply some jitter by randomizing the value in the range of (sleep_seconds
+    # / 2) to (sleep_seconds).
+    sleep_seconds = sleep_seconds * (0.5 * (1 + rand()))
+
+    # But never sleep less than the base sleep seconds.
+    sleep_seconds = [initial_network_retry_delay, sleep_seconds].max
+
+    sleep_seconds
+  end
+
+  # DEPRECATED. Use `Util#encode_parameters` instead.
+  def self.uri_encode(params)
+    Util.encode_parameters(params)
+  end
+  class << self
+    extend Gem::Deprecate
+    deprecate :uri_encode, "Stripe::Util#encode_parameters", 2016, 01
+  end
+
+  def self.user_agent
+    @uname ||= get_uname
+    lang_version = "#{RUBY_VERSION} p#{RUBY_PATCHLEVEL} (#{RUBY_RELEASE_DATE})"
+
+    {
+      :bindings_version => Stripe::VERSION,
+      :lang => 'ruby',
+      :lang_version => lang_version,
+      :platform => RUBY_PLATFORM,
+      :engine => defined?(RUBY_ENGINE) ? RUBY_ENGINE : '',
+      :publisher => 'stripe',
+      :uname => @uname,
+      :hostname => Socket.gethostname,
+    }
+
+  end
 end

data/stripe.gemspec

@@ -5,28 +5,15 @@ require 'stripe/version'
 spec = Gem::Specification.new do |s|
   s.name = 'stripe'
   s.version = Stripe::VERSION
+  s.required_ruby_version = '>= 1.9.3'
   s.summary = 'Ruby bindings for the Stripe API'
   s.description = 'Stripe is the easiest way to accept payments online.  See https://stripe.com for details.'
-  s.authors = ['Ross Boucher', 'Greg Brockman']
-  s.email = ['boucher@stripe.com', 'gdb@stripe.com']
-  s.homepage = 'https://stripe.com/api'
+  s.author = 'Stripe'
+  s.email = 'support@stripe.com'
+  s.homepage = 'https://stripe.com/docs/api/ruby'
   s.license = 'MIT'
 
-  s.add_dependency('rest-client', '~> 1.4')
-  s.add_dependency('json', '~> 1.8.1')
-
-  s.add_development_dependency('mocha', '~> 0.13.2')
-  s.add_development_dependency('shoulda', '~> 3.4.0')
-  s.add_development_dependency('test-unit')
-  s.add_development_dependency('rake')
-
-  # to avoid problems, bring Byebug in on just versions of Ruby under which
-  # it's known to work well
-  if Gem::Version.new(RUBY_VERSION.dup) >= Gem::Version.new('2.0.0')
-    s.add_development_dependency("byebug")
-    s.add_development_dependency("pry")
-    s.add_development_dependency("pry-byebug")
-  end
+  s.add_dependency('rest-client', '>= 1.4', '< 4.0')
 
   s.files = `git ls-files`.split("\n")
   s.test_files    = `git ls-files -- test/*`.split("\n")