stripe 5.14.0 → 5.15.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 47a1fda0057d116729cd70477218913ecf097898f633952d287327ecfaf99133
-  data.tar.gz: ed37e7cb7f025d48a11d075bc507cb6e84f92a36fc542f8d8bcff1bc8729dc50
+  metadata.gz: 1b0ca3c982da5bfe967d889047eeadbc2a2ba7ef6807dc860639a844f706cf15
+  data.tar.gz: 450bc197cbfd02398b3103aa89a5447f28bf2dd0f74608f3f54953e48e7ba4fd
 SHA512:
-  metadata.gz: 84dda96e1a4da56d9643b13ae8bb6c6352f90baae770de860834461c73f3489501a81a03c3f98e4f0d0da9e6284c66111df743b9c907fbc82774979ab4f009d0
-  data.tar.gz: 4d166d7eded67674487f2f1e678e86d11a6cb54f88848e185a55a4bca93831307f2dca9f8cc2b8608f1305d7193715ddba48e3bbe3baa0e5245b582fe3bd9090
+  metadata.gz: 84c4915401aaf4a8e546763a17f44395df5ed284e36e721c6ba8d04612bbe4af9cc3d6bdeb235aba10abb82f5b001039f48ff0077e4d7477aed2f165a9f616a3
+  data.tar.gz: e4b3cacde2e92739ad543c2287cb06aa5041d2daa29780c83b3c670f97bdd395be7c537dc880cb452402575112b1498e10417244aada07653aec0fa52e551389

data/CHANGELOG.md

@@ -1,5 +1,8 @@
 # Changelog
 
+## 5.15.0 - 2020-02-10
+* [#902](https://github.com/stripe/stripe-ruby/pull/902) Add `request_begin` instrumentation callback
+
 ## 5.14.0 - 2020-01-14
 * [#896](https://github.com/stripe/stripe-ruby/pull/896) Add support for `CreditNoteLineItem`
 * [#894](https://github.com/stripe/stripe-ruby/pull/894) Clean up test output by capturing `$stderr` when we expect warnings

data/Gemfile

@@ -11,7 +11,10 @@ group :development do
   gem "rake"
   gem "shoulda-context"
   gem "test-unit"
-  gem "webmock"
+
+  # Version doesn't matter that much, but this one contains some fixes for Ruby
+  # 2.7 warnings that add noise to the test suite.
+  gem "webmock", ">= 3.8.0"
 
   # Rubocop changes pretty quickly: new cops get added and old cops change
   # names or go into new namespaces. This is a library and we don't have

data/README.md

@@ -14,8 +14,6 @@ The library also provides other features. For example:
 
 - Easy configuration path for fast setup and use.
 - Helpers for pagination.
-- Tracking of "fresh" values in API resources so that partial updates can be
-  executed.
 - Built-in mechanisms for the serialization of parameters according to the
   expectations of Stripe's API.
 
@@ -65,13 +63,11 @@ value:
 require "stripe"
 Stripe.api_key = "sk_test_..."
 
-# list charges
-Stripe::Charge.list()
+# list customers
+Stripe::Customer.list()
 
-# retrieve single charge
-Stripe::Charge.retrieve(
-  "ch_18atAXCdGbJFKhCuBAa4532Z",
-)
+# retrieve single customer
+Stripe::Customer.retrieve("cus_123456789")
 ```
 
 ### Per-request Configuration
@@ -83,7 +79,7 @@ per-request key and/or account:
 ```ruby
 require "stripe"
 
-Stripe::Charge.list(
+Stripe::Customer.list(
   {},
   {
     api_key: "sk_test_...",
@@ -92,8 +88,8 @@ Stripe::Charge.list(
   }
 )
 
-Stripe::Charge.retrieve(
-  "ch_18atAXCdGbJFKhCuBAa4532Z",
+Stripe::Customer.retrieve(
+  "cus_123456789",
   {
     api_key: "sk_test_...",
     stripe_account: "acct_...",
@@ -101,9 +97,9 @@ Stripe::Charge.retrieve(
   }
 )
 
-Stripe::Charge.retrieve(
+Stripe::Customer.retrieve(
   {
-    id: "ch_18atAXCdGbJFKhCuBAa4532Z",
+    id: "cus_123456789",
     expand: %w(balance_transaction)
   },
   {
@@ -112,8 +108,8 @@ Stripe::Charge.retrieve(
   }
 )
 
-Stripe::Charge.capture(
-  "ch_18atAXCdGbJFKhCuBAa4532Z",
+Stripe::Customer.capture(
+  "cus_123456789",
   {},
   {
     stripe_version: "2018-02-28",
@@ -123,6 +119,7 @@ Stripe::Charge.capture(
 ```
 
 Keep in mind that there are different method signatures depending on the action:
+
 - When operating on a collection (e.g. `.list`, `.create`) the method signature is
   `method(params, opts)`.
 - When operating on resource (e.g. `.capture`, `.update`) the method signature is
@@ -138,10 +135,8 @@ method:
 
 ```ruby
 client = Stripe::StripeClient.new
-charge, resp = client.request do
-  Stripe::Charge.retrieve(
-    "ch_18atAXCdGbJFKhCuBAa4532Z",
-  )
+customer, resp = client.request do
+  Stripe::Customer.retrieve("cus_123456789",)
 end
 puts resp.request_id
 ```
@@ -224,19 +219,43 @@ There are a few options for enabling it:
 
 ### 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`)
+The library has various hooks that user code can tie into by passing a block to
+`Stripe::Instrumentation.subscribe` to be notified about specific events.
+
+#### `request_begin`
+
+Invoked when an HTTP request starts. Receives `RequestBeginEvent` with the
+following properties:
+
+- `method`: HTTP method. (`Symbol`)
+- `num_retries`: The number of retries. (`Integer`)
+- `user_data`: A hash on which users can set arbitrary data, and which will be
+  passed through to `request_end` invocations. This could be used, for example,
+  to assign unique IDs to each request, and it'd work even if many requests are
+  running in parallel. All subscribers share the same object for any particular
+  request, so they must be careful to use unique keys that will not conflict
+  with other subscribers. (`Hash`)
+
+#### `request_end`
+
+Invoked when an HTTP request finishes, regardless of whether it terminated with
+a success or error. Receives `RequestEndEvent` with the following properties:
+
+- `duration`: Request duration in seconds. (`Float`)
+- `http_status`: HTTP response code (`Integer`) if available, or `nil` in case
+  of a lower level network error.
+- `method`: HTTP method. (`Symbol`)
+- `num_retries`: The number of retries. (`Integer`)
+- `path`: Request path. (`String`)
+- `user_data`: A hash on which users may have set arbitrary data in
+  `request_begin`. See above for more information. (`Hash`)
+
+#### Example
 
 For example:
+
 ```ruby
-Stripe::Instrumentation.subscribe(:request) do |request_event|
+Stripe::Instrumentation.subscribe(:request_end) do |request_event|
   tags = {
     method: request_event.method,
     resource: request_event.path.split("/")[2],

data/VERSION

@@ -1 +1 @@
-5.14.0
+5.15.0

data/lib/stripe/instrumentation.rb

@@ -2,23 +2,65 @@
 
 module Stripe
   class Instrumentation
-    class RequestEvent
+    # Event emitted on `request_begin` callback.
+    class RequestBeginEvent
+      attr_reader :method
+      attr_reader :path
+
+      # Arbitrary user-provided data in the form of a Ruby hash that's passed
+      # from subscribers on `request_begin` to subscribers on `request_end`.
+      # `request_begin` subscribers can set keys which will then be available
+      # in `request_end`.
+      #
+      # Note that all subscribers of `request_begin` share the same object, so
+      # they must be careful to set unique keys so as to not conflict with data
+      # set by other subscribers.
+      attr_reader :user_data
+
+      def initialize(method:, path:, user_data:)
+        @method = method
+        @path = path
+        @user_data = user_data
+        freeze
+      end
+    end
+
+    # Event emitted on `request_end` callback.
+    class RequestEndEvent
       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:)
+      # Arbitrary user-provided data in the form of a Ruby hash that's passed
+      # from subscribers on `request_begin` to subscribers on `request_end`.
+      # `request_begin` subscribers can set keys which will then be available
+      # in `request_end`.
+      attr_reader :user_data
+
+      def initialize(duration:, http_status:, method:, num_retries:, path:,
+                     user_data: nil)
         @duration = duration
         @http_status = http_status
         @method = method
         @num_retries = num_retries
         @path = path
+        @user_data = user_data
         freeze
       end
     end
 
+    # This class was renamed for consistency. This alias is here for backwards
+    # compatibility.
+    RequestEvent = RequestEndEvent
+
+    # Returns true if there are a non-zero number of subscribers on the given
+    # topic, and false otherwise.
+    def self.any_subscribers?(topic)
+      !subscribers[topic].empty?
+    end
+
     def self.subscribe(topic, name = rand, &block)
       subscribers[topic][name] = block
       name

data/lib/stripe/stripe_client.rb

@@ -450,19 +450,26 @@ module Stripe
 
     private def execute_request_with_rescues(method, api_base, context)
       num_retries = 0
+
       begin
-        request_start = Util.monotonic_time
+        request_start = nil
+        user_data = nil
+
         log_request(context, num_retries)
+        user_data = notify_request_begin(context)
+
+        request_start = Util.monotonic_time
         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 http_status >= 400
 
         log_response(context, request_start, http_status, resp.body)
-        notify_subscribers(request_duration, http_status, context,
-                           num_retries)
+        notify_request_end(context, request_duration, http_status,
+                           num_retries, user_data)
 
         if Stripe.enable_telemetry? && context.request_id
           request_duration_ms = (request_duration * 1000).to_i
@@ -477,8 +484,8 @@ 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
+        request_duration = Util.monotonic_time - request_start if request_start
 
         if e.is_a?(Stripe::StripeError)
           error_context = context.dup_from_response_headers(e.http_headers)
@@ -488,7 +495,8 @@ module Stripe
         else
           log_response_error(error_context, request_start, e)
         end
-        notify_subscribers(request_duration, http_status, context, num_retries)
+        notify_request_end(context, request_duration, http_status, num_retries,
+                           user_data)
 
         if self.class.should_retry?(e, method: method, num_retries: num_retries)
           num_retries += 1
@@ -512,15 +520,39 @@ module Stripe
       resp
     end
 
-    private def notify_subscribers(duration, http_status, context, num_retries)
-      request_event = Instrumentation::RequestEvent.new(
+    private def notify_request_begin(context)
+      return unless Instrumentation.any_subscribers?(:request_begin)
+
+      event = Instrumentation::RequestBeginEvent.new(
+        method: context.method,
+        path: context.path,
+        user_data: {}
+      )
+      Stripe::Instrumentation.notify(:request_begin, event)
+
+      # This field may be set in the `request_begin` callback. If so, we'll
+      # forward it onto `request_end`.
+      event.user_data
+    end
+
+    private def notify_request_end(context, duration, http_status, num_retries,
+                                   user_data)
+      return if !Instrumentation.any_subscribers?(:request_end) &&
+                !Instrumentation.any_subscribers?(:request)
+
+      event = Instrumentation::RequestEndEvent.new(
         duration: duration,
         http_status: http_status,
         method: context.method,
         num_retries: num_retries,
-        path: context.path
+        path: context.path,
+        user_data: user_data || {}
       )
-      Stripe::Instrumentation.notify(:request, request_event)
+      Stripe::Instrumentation.notify(:request_end, event)
+
+      # The name before `request_begin` was also added. Provided for backwards
+      # compatibility.
+      Stripe::Instrumentation.notify(:request, event)
     end
 
     private def general_api_error(status, body)
@@ -772,8 +804,9 @@ module Stripe
     end
 
     private def log_response_error(context, request_start, error)
+      elapsed = request_start ? Util.monotonic_time - request_start : nil
       Util.log_error("Request error",
-                     elapsed: Util.monotonic_time - request_start,
+                     elapsed: elapsed,
                      error_message: error.message,
                      idempotency_key: context.idempotency_key,
                      method: context.method,

data/lib/stripe/version.rb

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

data/test/stripe/instrumentation_test.rb

@@ -44,14 +44,27 @@ module Stripe
       end
     end
 
-    context "RequestEvent" do
+    context "RequestEventBegin" do
       should "return a frozen object" do
-        event = Stripe::Instrumentation::RequestEvent.new(
+        event = Stripe::Instrumentation::RequestBeginEvent.new(
+          method: :get,
+          path: "/v1/test",
+          user_data: nil
+        )
+
+        assert(event.frozen?)
+      end
+    end
+
+    context "RequestEventEnd" do
+      should "return a frozen object" do
+        event = Stripe::Instrumentation::RequestEndEvent.new(
           duration: 0.1,
           http_status: 200,
           method: :get,
           num_retries: 0,
-          path: "/v1/test"
+          path: "/v1/test",
+          user_data: nil
         )
 
         assert(event.frozen?)

data/test/stripe/stripe_client_test.rb

@@ -1150,9 +1150,23 @@ module Stripe
         Stripe::Instrumentation.unsubscribe(:request, :test)
       end
 
+      should "notify a subscribe on HTTP request start" do
+        events = []
+        Stripe::Instrumentation.subscribe(:request_end, :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)
+      end
+
       should "notify a subscriber of a successful HTTP request" do
         events = []
-        Stripe::Instrumentation.subscribe(:request, :test) { |event| events << event }
+        Stripe::Instrumentation.subscribe(:request_end, :test) { |event| events << event }
 
         stub_request(:get, "#{Stripe.api_base}/v1/charges")
           .to_return(body: JSON.generate(object: "charge"))
@@ -1169,7 +1183,7 @@ module Stripe
 
       should "notify a subscriber of a StripeError" do
         events = []
-        Stripe::Instrumentation.subscribe(:request, :test) { |event| events << event }
+        Stripe::Instrumentation.subscribe(:request_end, :test) { |event| events << event }
 
         error = {
           code: "code",
@@ -1197,7 +1211,7 @@ module Stripe
 
       should "notify a subscriber of a network error" do
         events = []
-        Stripe::Instrumentation.subscribe(:request, :test) { |event| events << event }
+        Stripe::Instrumentation.subscribe(:request_end, :test) { |event| events << event }
 
         stub_request(:get, "#{Stripe.api_base}/v1/charges")
           .to_raise(Net::OpenTimeout)
@@ -1213,6 +1227,40 @@ module Stripe
         assert(event.duration.positive?)
         assert_equal(0, event.num_retries)
       end
+
+      should "pass `user_data` from `request_begin` to `request_end`" do
+        actual_user_data = nil
+
+        Stripe::Instrumentation.subscribe(:request_begin) do |event|
+          event.user_data[:foo] = :bar
+        end
+        Stripe::Instrumentation.subscribe(:request_end) do |event|
+          actual_user_data = event.user_data
+        end
+
+        stub_request(:get, "#{Stripe.api_base}/v1/charges")
+          .to_return(body: JSON.generate(object: "charge"))
+        Stripe::Charge.list
+
+        assert_equal({ foo: :bar }, actual_user_data)
+      end
+
+      should "provide backward compatibility on `request` topic" 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
     end
   end
 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: stripe
 version: !ruby/object:Gem::Version
-  version: 5.14.0
+  version: 5.15.0
 platform: ruby
 authors:
 - Stripe
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2020-01-14 00:00:00.000000000 Z
+date: 2020-02-10 00:00:00.000000000 Z
 dependencies: []
 description: Stripe is the easiest way to accept payments online.  See https://stripe.com
   for details.