stripe 5.8.0 → 5.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a5a17039dd8609885e953ff5fd576a532f77d02b555d6a3f5d1b6c8437252a34
-  data.tar.gz: c9ae5618e79a97607fd55563ecca60a3a79de58b5f46f99977c8ed28441b35e8
+  metadata.gz: b59015578d0b75db3e8b02959010a9d3a7a3c4212823ad8b51790a869e32b92a
+  data.tar.gz: cc8dd57b285effb4814596431b8da59fe92d1a7e34a76d5dc738250a10673142
 SHA512:
-  metadata.gz: 6535270353329e05c49b0e3e7853cf096dd4e35ac1e677c781f9005c89a0432141176c5e68cde123381083237d9ff3d460a3fb82bb3373863950217c7496fc21
-  data.tar.gz: cfc98fa53ba0707c4ad798fc42a168a10eb4b62cb1e57cf6e08d17a9815d0a5c7bfd1057f6d2e40cc9a379210c12f11007c8ac3aafc307676a6e23445500a4ed
+  metadata.gz: 6154e0332f7b4c7d66c2238d4474ce904c0faa129dea9a1e1d03668a03d8b03796c593ddb7f04a76082251e6d08520996a28bd2427d897cb1dd769dfc1c3f8aa
+  data.tar.gz: 3d4bf185574c11c8c867b1998e4f07f1bce7b4dcaab166d475a5e2406e0cf2275e6d9890bf0df7f94523d36cc58c577819edaa9d301ba96b0d722d4806cbcdac

data/CHANGELOG.md

@@ -1,5 +1,8 @@
 # Changelog
 
+## 5.9.0 - 2019-11-07
+* [#870](https://github.com/stripe/stripe-ruby/pull/870) Add request instrumentation callback (see `README.md` for usage example)
+
 ## 5.8.0 - 2019-11-05
 * [#879](https://github.com/stripe/stripe-ruby/pull/879) Add support for `Mandate`
 * [#876](https://github.com/stripe/stripe-ruby/pull/876) Add additional per-request configuration documentation

data/README.md

@@ -1,5 +1,6 @@
 # Stripe Ruby Library
 
+[![Gem Version](https://badge.fury.io/rb/stripe.svg)](https://badge.fury.io/rb/stripe)
 [![Build Status](https://travis-ci.org/stripe/stripe-ruby.svg?branch=master)](https://travis-ci.org/stripe/stripe-ruby)
 [![Coverage Status](https://coveralls.io/repos/github/stripe/stripe-ruby/badge.svg?branch=master)](https://coveralls.io/github/stripe/stripe-ruby?branch=master)
 
@@ -221,6 +222,31 @@ There are a few options for enabling it:
    Stripe.log_level = Stripe::LEVEL_INFO
    ```
 
+### Instrumentation
+
+The library has a hook for when a HTTP call is made which can be used for
+monitoring. The callback receives a `RequestEvent` object with the following
+data:
+- HTTP method (`Symbol`)
+- request path (`String`)
+- HTTP response code (`Integer`) if available, or `nil` in case of a lower
+  level network error
+- request duration in seconds (`Float`)
+- the number of retries (`Integer`)
+
+For example:
+```ruby
+Stripe::Instrumentation.subscribe(:request) do |request_event|
+  tags = {
+    method: request_event.method,
+    resource: request_event.path.split("/")[2],
+    code: request_event.http_status,
+    retries: request_event.num_retries
+  }
+  StatsD.distribution('stripe_request', request_event.duration, tags: tags)
+end
+```
+
 ### Writing a Plugin
 
 If you're writing a plugin that uses the library, we'd appreciate it if you

data/VERSION

@@ -1 +1 @@
-5.8.0
+5.9.0

data/lib/stripe/instrumentation.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module Stripe
+  class Instrumentation
+    class RequestEvent
+      attr_reader :duration
+      attr_reader :http_status
+      attr_reader :method
+      attr_reader :num_retries
+      attr_reader :path
+
+      def initialize(duration:, http_status:, method:, num_retries:, path:)
+        @duration = duration
+        @http_status = http_status
+        @method = method
+        @num_retries = num_retries
+        @path = path
+        freeze
+      end
+    end
+
+    def self.subscribe(topic, name = rand, &block)
+      subscribers[topic][name] = block
+      name
+    end
+
+    def self.unsubscribe(topic, name)
+      subscribers[topic].delete(name)
+    end
+
+    def self.notify(topic, event)
+      subscribers[topic].each_value { |subscriber| subscriber.call(event) }
+    end
+
+    def self.subscribers
+      @subscribers ||= Hash.new { |hash, key| hash[key] = {} }
+    end
+    private_class_method :subscribers
+  end
+end

data/lib/stripe/stripe_client.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require "stripe/instrumentation"
+
 module Stripe
   # StripeClient executes requests against the Stripe API and allows a user to
   # recover both a resource a call returns as well as a response object that
@@ -452,15 +454,18 @@ module Stripe
         request_start = Util.monotonic_time
         log_request(context, num_retries)
         resp = yield
+        request_duration = Util.monotonic_time - request_start
+        http_status = resp.code.to_i
         context = context.dup_from_response_headers(resp)
 
-        handle_error_response(resp, context) if resp.code.to_i >= 400
+        handle_error_response(resp, context) if http_status >= 400
 
-        log_response(context, request_start, resp.code.to_i, resp.body)
+        log_response(context, request_start, http_status, resp.body)
+        notify_subscribers(request_duration, http_status, context,
+                           num_retries)
 
         if Stripe.enable_telemetry? && context.request_id
-          request_duration_ms =
-            ((Util.monotonic_time - request_start) * 1000).to_int
+          request_duration_ms = (request_duration * 1000).to_i
           @last_request_metrics =
             StripeRequestMetrics.new(context.request_id, request_duration_ms)
         end
@@ -472,14 +477,18 @@ module Stripe
         # If we modify context we copy it into a new variable so as not to
         # taint the original on a retry.
         error_context = context
+        request_duration = Util.monotonic_time - request_start
+        http_status = nil
 
         if e.is_a?(Stripe::StripeError)
           error_context = context.dup_from_response_headers(e.http_headers)
+          http_status = resp.code.to_i
           log_response(error_context, request_start,
                        e.http_status, e.http_body)
         else
           log_response_error(error_context, request_start, e)
         end
+        notify_subscribers(request_duration, http_status, context, num_retries)
 
         if self.class.should_retry?(e, method: method, num_retries: num_retries)
           num_retries += 1
@@ -503,6 +512,17 @@ module Stripe
       resp
     end
 
+    private def notify_subscribers(duration, http_status, context, num_retries)
+      request_event = Instrumentation::RequestEvent.new(
+        duration: duration,
+        http_status: http_status,
+        method: context.method,
+        num_retries: num_retries,
+        path: context.path
+      )
+      Stripe::Instrumentation.notify(:request, request_event)
+    end
+
     private def general_api_error(status, body)
       APIError.new("Invalid response object from API: #{body.inspect} " \
                    "(HTTP response code was #{status})",

data/lib/stripe/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Stripe
-  VERSION = "5.8.0"
+  VERSION = "5.9.0"
 end

data/test/stripe/instrumentation_test.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+require_relative "../test_helper"
+
+module Stripe
+  class InstrumentationTest < Test::Unit::TestCase
+    context ".notify" do
+      teardown do
+        Stripe::Instrumentation.send(:subscribers).clear
+      end
+
+      should "notify subscribers for the right topic" do
+        sub1_events = []
+        Stripe::Instrumentation.subscribe(:test1, :sub1) { |event| sub1_events << event }
+        sub2_events = []
+        Stripe::Instrumentation.subscribe(:test2, :sub2) { |event| sub2_events << event }
+
+        Stripe::Instrumentation.notify(:test1, "hello")
+        assert_equal(1, sub1_events.size)
+        assert_equal(0, sub2_events.size)
+      end
+
+      should "notify multiple subscribers of the same topic" do
+        sub1_events = []
+        Stripe::Instrumentation.subscribe(:test, :sub1) { |event| sub1_events << event }
+        sub2_events = []
+        Stripe::Instrumentation.subscribe(:test, :sub2) { |event| sub2_events << event }
+
+        Stripe::Instrumentation.notify(:test, "hello")
+        assert_equal(1, sub1_events.size)
+        assert_equal(1, sub2_events.size)
+      end
+
+      should "not notify a subscriber once it has unsubscribed" do
+        events = []
+        Stripe::Instrumentation.subscribe(:test, :sub) { |event| events << event }
+
+        Stripe::Instrumentation.notify(:test, "hello")
+        assert_equal(1, events.size)
+
+        Stripe::Instrumentation.unsubscribe(:test, :sub)
+        Stripe::Instrumentation.notify(:test, "hello")
+        assert_equal(1, events.size)
+      end
+    end
+
+    context "RequestEvent" do
+      should "return a frozen object" do
+        event = Stripe::Instrumentation::RequestEvent.new(
+          duration: 0.1,
+          http_status: 200,
+          method: :get,
+          num_retries: 0,
+          path: "/v1/test"
+        )
+
+        assert(event.frozen?)
+      end
+    end
+  end
+end

data/test/stripe/stripe_client_test.rb

@@ -1144,6 +1144,76 @@ module Stripe
         assert(!trace_payload["last_request_metrics"]["request_duration_ms"].nil?)
       end
     end
+
+    context "instrumentation" do
+      teardown do
+        Stripe::Instrumentation.unsubscribe(:request, :test)
+      end
+
+      should "notify a subscriber of a successful HTTP request" do
+        events = []
+        Stripe::Instrumentation.subscribe(:request, :test) { |event| events << event }
+
+        stub_request(:get, "#{Stripe.api_base}/v1/charges")
+          .to_return(body: JSON.generate(object: "charge"))
+        Stripe::Charge.list
+
+        assert_equal(1, events.size)
+        event = events.first
+        assert_equal(:get, event.method)
+        assert_equal("/v1/charges", event.path)
+        assert_equal(200, event.http_status)
+        assert(event.duration.positive?)
+        assert_equal(0, event.num_retries)
+      end
+
+      should "notify a subscriber of a StripeError" do
+        events = []
+        Stripe::Instrumentation.subscribe(:request, :test) { |event| events << event }
+
+        error = {
+          code: "code",
+          message: "message",
+          param: "param",
+          type: "type",
+        }
+        stub_request(:get, "#{Stripe.api_base}/v1/charges")
+          .to_return(
+            body: JSON.generate(error: error),
+            status: 500
+          )
+        assert_raises(Stripe::APIError) do
+          Stripe::Charge.list
+        end
+
+        assert_equal(1, events.size)
+        event = events.first
+        assert_equal(:get, event.method)
+        assert_equal("/v1/charges", event.path)
+        assert_equal(500, event.http_status)
+        assert(event.duration.positive?)
+        assert_equal(0, event.num_retries)
+      end
+
+      should "notify a subscriber of a network error" do
+        events = []
+        Stripe::Instrumentation.subscribe(:request, :test) { |event| events << event }
+
+        stub_request(:get, "#{Stripe.api_base}/v1/charges")
+          .to_raise(Net::OpenTimeout)
+        assert_raises(Stripe::APIConnectionError) do
+          Stripe::Charge.list
+        end
+
+        assert_equal(1, events.size)
+        event = events.first
+        assert_equal(:get, event.method)
+        assert_equal("/v1/charges", event.path)
+        assert_nil(event.http_status)
+        assert(event.duration.positive?)
+        assert_equal(0, event.num_retries)
+      end
+    end
   end
 
   class SystemProfilerTest < Test::Unit::TestCase

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: stripe
 version: !ruby/object:Gem::Version
-  version: 5.8.0
+  version: 5.9.0
 platform: ruby
 authors:
 - Stripe
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2019-11-06 00:00:00.000000000 Z
+date: 2019-11-07 00:00:00.000000000 Z
 dependencies: []
 description: Stripe is the easiest way to accept payments online.  See https://stripe.com
   for details.
@@ -49,6 +49,7 @@ files:
 - lib/stripe/connection_manager.rb
 - lib/stripe/error_object.rb
 - lib/stripe/errors.rb
+- lib/stripe/instrumentation.rb
 - lib/stripe/list_object.rb
 - lib/stripe/multipart_encoder.rb
 - lib/stripe/oauth.rb
@@ -167,6 +168,7 @@ files:
 - test/stripe/exchange_rate_test.rb
 - test/stripe/file_link_test.rb
 - test/stripe/file_test.rb
+- test/stripe/instrumentation_test.rb
 - test/stripe/invoice_item_test.rb
 - test/stripe/invoice_line_item_test.rb
 - test/stripe/invoice_test.rb
@@ -249,7 +251,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.0.3
+rubygems_version: 3.0.6
 signing_key: 
 specification_version: 4
 summary: Ruby bindings for the Stripe API
@@ -283,6 +285,7 @@ test_files:
 - test/stripe/exchange_rate_test.rb
 - test/stripe/file_link_test.rb
 - test/stripe/file_test.rb
+- test/stripe/instrumentation_test.rb
 - test/stripe/invoice_item_test.rb
 - test/stripe/invoice_line_item_test.rb
 - test/stripe/invoice_test.rb