stripe 3.0.3 → 3.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 71ad66341e1b3896e85749e3f18870b734386a86
-  data.tar.gz: 67175bb4549ab20ca69f38016e9f7d96aedaa817
+  metadata.gz: 4e0d93e7805ba65b7f5dcfe753298a8be427fc1d
+  data.tar.gz: 3a59dcb60834e656c55f37368c8f957bb9d23486
 SHA512:
-  metadata.gz: f740ee89ea7c34c45944dc299ba346ad715c96b736a05dc6ad2f13337125656d049ff16a33671de454d5e2511e98e7431ae58caf275c934d957e3f608cb7df91
-  data.tar.gz: 04d28b541238aba0ce44820f5b1daf38a4a798892764d1d18e565d5d688b0d627895b037152ad976cbec982f1277dc6b7475bd5589ef152d6e7cbbebbb77b428
+  metadata.gz: 5a769766ed97097ae745300710ad092bc6646ec85d98f70686ffe71758159667e67f7758c6550a00ac74269978562a2dcf44162bc681960fb59c67ffbc04a525
+  data.tar.gz: 2c6782650e0069887f14fa28be69e135f2e4ccaeec68ce69422972cde7e8fc28e2310de86c903c88ade3017998cb9a11a68c5ffc921bf6098deb7877de5bd85e

data/.travis.yml

@@ -13,3 +13,26 @@ notifications:
     on_success: never
 
 sudo: false
+
+env:
+  global:
+    - STRIPE_MOCK_VERSION=0.1.12
+
+cache:
+  directories:
+    - stripe-mock
+
+before_install:
+  # Unpack and start stripe-mock so that the test suite can talk to it
+  - |
+    if [ ! -d "stripe-mock/stripe-mock_${STRIPE_MOCK_VERSION}" ]; then
+      mkdir -p stripe-mock/stripe-mock_${STRIPE_MOCK_VERSION}/
+      curl -L "https://github.com/stripe/stripe-mock/releases/download/v${STRIPE_MOCK_VERSION}/stripe-mock_${STRIPE_MOCK_VERSION}_linux_amd64.tar.gz" -o "stripe-mock/stripe-mock_${STRIPE_MOCK_VERSION}_linux_amd64.tar.gz"
+      tar -zxf "stripe-mock/stripe-mock_${STRIPE_MOCK_VERSION}_linux_amd64.tar.gz" -C "stripe-mock/stripe-mock_${STRIPE_MOCK_VERSION}/"
+    fi
+  - |
+    stripe-mock/stripe-mock_${STRIPE_MOCK_VERSION}/stripe-mock > /dev/null &
+    STRIPE_MOCK_PID=$!
+
+script:
+  - bundle exec rake

data/Gemfile

@@ -3,12 +3,11 @@ source "https://rubygems.org"
 gemspec
 
 group :development do
-  gem 'committee', '2.0.0.pre6'
   gem 'mocha', '~> 0.13.2'
   gem 'rake'
   gem 'shoulda-context'
-  gem 'sinatra'
   gem 'test-unit'
+  gem 'timecop'
   gem 'webmock'
 
   # Rack 2.0+ requires Ruby >= 2.2.2 which is problematic for the test suite on

data/History.txt

@@ -1,3 +1,7 @@
+=== 3.1.0 2017-08-03
+
+* Implement request logging with `Stripe.log_level` and `STRIPE_LOG`
+
 === 3.0.3 2017-07-28
 
 * Revert `nil` to empty string coercion from 3.0.2

data/README.md

@@ -135,6 +135,24 @@ Please take care to set conservative read timeouts. Some API requests can take
 some time, and a short timeout increases the likelihood of a problem within our
 servers.
 
+### Logging
+
+The library can be configured to emit logging that will give you better insight
+into what it's doing. The `info` logging level is usually most appropriate for
+production use, but `debug` is also available for more verbosity.
+
+There are a few options for enabling it:
+
+1. Set the environment variable `STRIPE_LOG` to the value `debug` or `info`:
+   ```
+   $ export STRIPE_LOG=info
+   ```
+
+2. Set `Stripe.log_level`:
+   ``` ruby
+   Stripe.log_level = "info"
+   ```
+
 ### Writing a Plugin
 
 If you're writing a plugin that uses the library, we'd appreciate it if you
@@ -147,6 +165,13 @@ API.
 
 ## Development
 
+The test suite depends on [stripe-mock], so make sure to fetch and run it from a
+background terminal ([stripe-mock's README][stripe-mock] also contains
+instructions for installing via Homebrew and other methods):
+
+    go get -u github.com/stripe/stripe-mock
+    stripe-mock
+
 Run all tests:
 
     bundle exec rake
@@ -163,15 +188,15 @@ Update bundled CA certificates from the [Mozilla cURL release][curl]:
 
     bundle exec rake update_certs
 
-Update bundled OpenAPI specification from the canonical repository:
-
-    bundle exec rake update_openapi
+Update the bundled [stripe-mock] by editing the version number found in
+`.travis.yml`.
 
 [api-keys]: https://dashboard.stripe.com/account/apikeys
 [connect]: https://stripe.com/connect
 [curl]: http://curl.haxx.se/docs/caextract.html
 [faraday]: https://github.com/lostisland/faraday
 [idempotency-keys]: https://stripe.com/docs/api/ruby#idempotent_requests
+[stripe-mock]: https://github.com/stripe/stripe-mock
 
 <!--
 # vim: set tw=79:

data/Rakefile

@@ -14,18 +14,6 @@ task :update_certs do
     File.expand_path("../lib/data/ca-certificates.crt", __FILE__)
 end
 
-desc "Update OpenAPI specification"
-task :update_openapi do
-  require "faraday"
-
-  ["fixtures.json", "fixtures.yaml", "spec2.json", "spec2.yaml"].map { |file|
-    Thread.new do
-      fetch_file "https://raw.githubusercontent.com/stripe/openapi/master/openapi/#{file}",
-        File.expand_path("../openapi/#{file}", __FILE__)
-    end
-  }.map { |t| t.join }
-end
-
 #
 # helpers
 #

data/VERSION

@@ -1 +1 @@
-3.0.3
+3.1.0

data/lib/stripe.rb

@@ -83,6 +83,8 @@ module Stripe
   @connect_base = 'https://connect.stripe.com'
   @uploads_base = 'https://uploads.stripe.com'
 
+  @log_level = nil
+
   @max_network_retries = 0
   @max_network_retry_delay = 2
   @initial_network_retry_delay = 0.5
@@ -142,6 +144,24 @@ module Stripe
     end
   end
 
+  LEVEL_DEBUG = "debug"
+  LEVEL_INFO = "info"
+
+  # When set prompts the library to log some extra information to $stdout 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.
+  def self.log_level
+    @log_level
+  end
+
+  def self.log_level=(val)
+    if val != nil && ![LEVEL_DEBUG, LEVEL_INFO].include?(val)
+      raise ArgumentError, "log_level should only be set to `nil`, `debug` or `info`"
+    end
+    @log_level = val
+  end
+
   def self.max_network_retries
     @max_network_retries
   end
@@ -174,3 +194,7 @@ module Stripe
     deprecate :uri_encode, "Stripe::Util#encode_parameters", 2016, 01
   end
 end
+
+unless ENV["STRIPE_LOG"].nil?
+  Stripe.log_level = ENV["STRIPE_LOG"]
+end

data/lib/stripe/stripe_client.rb

@@ -109,7 +109,7 @@ module Stripe
       end
     end
 
-    def execute_request(method, url,
+    def execute_request(method, path,
         api_base: nil, api_key: nil, headers: {}, params: {})
 
       api_base ||= Stripe.api_base
@@ -118,7 +118,7 @@ module Stripe
       check_api_key!(api_key)
 
       params = Util.objects_to_ids(params)
-      url = api_url(url, api_base)
+      url = api_url(path, api_base)
 
       case method.to_s.downcase.to_sym
       when :get, :head, :delete
@@ -133,14 +133,22 @@ module Stripe
         end
       end
 
-      http_resp = execute_request_with_rescues(api_base, 0) do
-        conn.run_request(
-          method,
-          url,
-          payload,
-          # TODO: Convert RestClient-style parameters.
-          request_headers(api_key, method).update(headers)
-        ) do |req|
+      headers = request_headers(api_key, method).
+        update(Util.normalize_headers(headers))
+
+      # 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(
+        api_key: api_key,
+        api_version: headers["Stripe-Version"] || Stripe.api_version,
+        idempotency_key: headers["Idempotency-Key"],
+        method: method,
+        path: path,
+        payload: payload,
+      )
+
+      http_resp = execute_request_with_rescues(api_base, context) do
+        conn.run_request(method, url, payload, headers) do |req|
           req.options.open_timeout = Stripe.open_timeout
           req.options.timeout = Stripe.read_timeout
         end
@@ -180,14 +188,31 @@ module Stripe
       end
     end
 
-    def execute_request_with_rescues(api_base, retry_count, &block)
+    def execute_request_with_rescues(api_base, context, &block)
+      retry_count = 0
       begin
+        request_start = Time.now
+        log_request(context)
         resp = block.call
+        context = context.dup_from_response(resp)
+        log_response(context, request_start, resp.status, resp.body)
 
       # 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 we modify context we copy it into a new variable so as not to
+        # taint the original on a retry.
+        error_context = context
+
+        if e.respond_to?(:response) && e.response
+          error_context = context.dup_from_response(e.response)
+          log_response(error_context, request_start,
+            e.response[:status], e.response[:body])
+        else
+          log_response_error(error_context, request_start, e)
+        end
+
         if self.class.should_retry?(e, retry_count)
           retry_count = retry_count + 1
           sleep self.class.sleep_time(retry_count)
@@ -197,9 +222,9 @@ module Stripe
         case e
         when Faraday::ClientError
           if e.response
-            handle_error_response(e.response)
+            handle_error_response(e.response, error_context)
           else
-            handle_network_error(e, retry_count, api_base)
+            handle_network_error(e, error_context, retry_count, api_base)
           end
 
         # Only handle errors when we know we can do so, and re-raise otherwise.
@@ -229,7 +254,7 @@ module Stripe
       str
     end
 
-    def handle_error_response(http_resp)
+    def handle_error_response(http_resp, context)
       begin
         resp = StripeResponse.from_faraday_hash(http_resp)
         error_data = resp.data[:error]
@@ -243,16 +268,26 @@ module Stripe
       end
 
       if error_data.is_a?(String)
-        error = specific_oauth_error(resp, error_data)
+        error = specific_oauth_error(resp, error_data, context)
       else
-        error = specific_api_error(resp, error_data)
+        error = specific_api_error(resp, error_data, context)
       end
 
       error.response = resp
       raise(error)
     end
 
-    def specific_api_error(resp, error_data)
+    def specific_api_error(resp, error_data, context)
+      Util.log_info('Stripe API error',
+        status: resp.http_status,
+        error_code: error_data['code'],
+        error_message: error_data['message'],
+        error_param: error_data['param'],
+        error_type: error_data['type'],
+        idempotency_key: context.idempotency_key,
+        request_id: context.request_id
+      )
+
       case resp.http_status
       when 400, 404
         error = InvalidRequestError.new(
@@ -297,9 +332,17 @@ module Stripe
 
     # Attempts to look at a response's error code and return an OAuth error if
     # one matches. Will return `nil` if the code isn't recognized.
-    def specific_oauth_error(resp, error_code)
+    def specific_oauth_error(resp, error_code, context)
       description = resp.data[:error_description] || error_code
 
+      Util.log_info('Stripe OAuth error',
+        status: resp.http_status,
+        error_code: error_code,
+        error_description: description,
+        idempotency_key: context.idempotency_key,
+        request_id: context.request_id
+      )
+
       args = [error_code, description, {
         http_status: resp.http_status, http_body: resp.http_body,
         json_body: resp.data, http_headers: resp.http_headers
@@ -319,7 +362,13 @@ module Stripe
       end
     end
 
-    def handle_network_error(e, retry_count, api_base=nil)
+    def handle_network_error(e, context, retry_count, api_base=nil)
+      Util.log_info('Stripe OAuth error',
+        error_message: e.message,
+        idempotency_key: context.idempotency_key,
+        request_id: context.request_id
+      )
+
       case e
       when Faraday::ConnectionFailed
         message = "Unexpected error communicating when trying to connect to Stripe. " \
@@ -388,6 +437,104 @@ module Stripe
       headers
     end
 
+    def log_request(context)
+      Util.log_info("Request to Stripe API",
+        api_version: context.api_version,
+        idempotency_key: context.idempotency_key,
+        method: context.method,
+        path: context.path
+      )
+      Util.log_debug("Request details",
+        body: context.payload,
+        idempotency_key: context.idempotency_key
+      )
+    end
+    private :log_request
+
+    def log_response(context, request_start, status, body)
+      Util.log_info("Response from Stripe API",
+        api_version: context.api_version,
+        elapsed: Time.now - request_start,
+        idempotency_key: context.idempotency_key,
+        method: context.method,
+        path: context.path,
+        request_id: context.request_id,
+        status: status
+      )
+      Util.log_debug("Response details",
+        body: body,
+        idempotency_key: context.idempotency_key,
+        request_id: context.request_id,
+      )
+      if context.request_id
+        Util.log_debug("Dashboard link for request",
+          idempotency_key: context.idempotency_key,
+          request_id: context.request_id,
+          url: Util.request_id_dashboard_url(context.request_id, context.api_key)
+        )
+      end
+    end
+    private :log_response
+
+    def log_response_error(context, request_start, e)
+      Util.log_info("Request error",
+        elapsed: Time.now - request_start,
+        error_message: e.message,
+        idempotency_key: context.idempotency_key,
+        method: context.method,
+        path: context.path,
+      )
+    end
+    private :log_response_error
+
+    # RequestLogContext stores information about a request that's begin made so
+    # that we can log certain information. It's useful because it means that we
+    # don't have to pass around as many parameters.
+    class RequestLogContext
+      attr_accessor :api_key
+      attr_accessor :api_version
+      attr_accessor :idempotency_key
+      attr_accessor :method
+      attr_accessor :path
+      attr_accessor :payload
+      attr_accessor :request_id
+
+      def initialize(api_key: nil, api_version: nil, idempotency_key: nil,
+          method: nil, path: nil, payload: nil)
+        self.api_key = api_key
+        self.api_version = api_version
+        self.idempotency_key = idempotency_key
+        self.method = method
+        self.path = path
+        self.payload = payload
+      end
+
+      # The idea with this method is that we might want to update some of
+      # context information because a response that we've received from the API
+      # contains information that's more authoritative than what we started
+      # with for a request. For example, we should trust whatever came back in
+      # a `Stripe-Version` header beyond what configuration information that we
+      # might have had available.
+      def dup_from_response(resp)
+        return self if resp.nil?
+
+        # Faraday's API is a little unusual. Normally it'll produce a response
+        # object with a `headers` method, but on error what it puts into
+        # `e.response` is an untyped `Hash`.
+        headers = if resp.is_a?(Faraday::Response)
+          resp.headers
+        else
+          resp[:headers]
+        end
+
+        context = self.dup
+        context.api_version = headers["Stripe-Version"]
+        context.idempotency_key = headers["Idempotency-Key"]
+        context.request_id = headers["Request-Id"]
+        context
+      end
+    end
+
     # SystemProfiler extracts information about the system that we're running
     # in so that we can generate a rich user agent header to help debug
     # integrations.