ruby_http_client 3.3.0 → 3.5.5

data/lib/ruby_http_client.rb

@@ -6,10 +6,54 @@ module SendGrid
 
   # Holds the response from an API call.
   class Response
+    # Provide useful functionality around API rate limiting.
+    class Ratelimit
+      attr_reader :limit, :remaining, :reset
+
+      # * *Args*    :
+      #   - +limit+ -> The total number of requests allowed within a rate limit window
+      #   - +remaining+ -> The number of requests that have been processed within this current rate limit window
+      #   - +reset+ -> The time (in seconds since Unix Epoch) when the rate limit will reset
+      def initialize(limit, remaining, reset)
+        @limit = limit.to_i
+        @remaining = remaining.to_i
+        @reset = Time.at reset.to_i
+      end
+
+      def exceeded?
+        remaining <= 0
+      end
+
+      # * *Returns* :
+      #   - The number of requests that have been used out of this
+      #     rate limit window
+      def used
+        limit - remaining
+      end
+
+      # Sleep until the reset time arrives. If given a block, it will
+      # be called after sleeping is finished.
+      #
+      # * *Returns* :
+      #   - The amount of time (in seconds) that the rate limit slept
+      #     for.
+      def wait!
+        now = Time.now.utc.to_i
+        duration = (reset.to_i - now) + 1
+
+        sleep duration if duration >= 0
+
+        yield if block_given?
+
+        duration
+      end
+    end
+
     # * *Args*    :
     #   - +response+ -> A NET::HTTP response object
     #
     attr_reader :status_code, :body, :headers
+
     def initialize(response)
       @status_code = response.code
       @body = response.body
@@ -21,6 +65,20 @@ module SendGrid
     def parsed_body
       @parsed_body ||= JSON.parse(@body, symbolize_names: true)
     end
+
+    def ratelimit
+      return @ratelimit unless @ratelimit.nil?
+
+      limit = headers['X-RateLimit-Limit']
+      remaining = headers['X-RateLimit-Remaining']
+      reset = headers['X-RateLimit-Reset']
+
+      # Guard against possibility that one (or probably, all) of the
+      # needed headers were not returned.
+      @ratelimit = Ratelimit.new(limit, remaining, reset) if limit && remaining && reset
+
+      @ratelimit
+    end
   end
 
   # A simple REST client.
@@ -35,15 +93,19 @@ module SendGrid
     #                  Or just pass the version as part of the URL
     #                  (e.g. client._("/v3"))
     #   - +url_path+ -> A list of the url path segments
+    #   - +proxy_options+ -> A hash of proxy settings.
+    #                        (e.g. { host: '127.0.0.1', port: 8080 })
     #
-    def initialize(host: nil, request_headers: nil, version: nil, url_path: nil)
+    def initialize(host: nil, request_headers: nil, version: nil, url_path: nil, http_options: {}, proxy_options: {}) # rubocop:disable Metrics/ParameterLists
       @host = host
       @request_headers = request_headers || {}
       @version = version
       @url_path = url_path || []
-      @methods = %w(delete get patch post put)
+      @methods = %w[delete get patch post put]
       @query_params = nil
       @request_body = nil
+      @http_options = http_options
+      @proxy_options = proxy_options
     end
 
     # Update the headers for the request
@@ -137,21 +199,10 @@ module SendGrid
     #
     def build_request(name, args)
       build_args(args) if args
-      uri = build_url(query_params: @query_params)
-      @http = add_ssl(Net::HTTP.new(uri.host, uri.port))
-      net_http = Kernel.const_get('Net::HTTP::' + name.to_s.capitalize)
-      @request = build_request_headers(net_http.new(uri.request_uri))
-      if (@request_body &&
-          (!@request_headers.has_key?('Content-Type') ||
-           @request_headers['Content-Type'] == 'application/json')
-      )
-        @request.body = @request_body.to_json
-        @request['Content-Type'] = 'application/json'
-      elsif !@request_body and (name.to_s == "post")
-        @request['Content-Type'] = ''
-      else
-        @request.body = @request_body
-      end
+      # build the request & http object
+      build_http_request(name)
+      # set the content type & request body
+      update_content_type(name)
       make_request(@http, @request)
     end
 
@@ -169,6 +220,18 @@ module SendGrid
       Response.new(response)
     end
 
+    # Build HTTP request object
+    #
+    # * *Returns* :
+    #   - Request object
+    def build_http(host, port)
+      params = [host, port]
+      params += @proxy_options.values_at(:host, :port, :user, :pass) unless @proxy_options.empty?
+      http = add_ssl(Net::HTTP.new(*params))
+      http = add_http_options(http) unless @http_options.empty?
+      http
+    end
+
     # Allow for https calls
     #
     # * *Args*    :
@@ -184,6 +247,20 @@ module SendGrid
       http
     end
 
+    # Add others http options to http object
+    #
+    # * *Args*    :
+    #   - +http+ -> HTTP::NET object
+    # * *Returns* :
+    #   - HTTP::NET object
+    #
+    def add_http_options(http)
+      @http_options.each do |attribute, value|
+        http.send("#{attribute}=", value)
+      end
+      http
+    end
+
     # Add variable values to the url.
     # (e.g. /your/api/{variable_value}/call)
     # Another example: if you have a ruby reserved word, such as true,
@@ -195,20 +272,22 @@ module SendGrid
     #   - Client object
     #
     def _(name = nil)
-      url_path = name ? @url_path.push(name) : @url_path
-      @url_path = []
+      url_path = name ? @url_path + [name] : @url_path
       Client.new(host: @host, request_headers: @request_headers,
-                 version: @version, url_path: url_path)
+                 version: @version, url_path: url_path,
+                 http_options: @http_options)
     end
 
     # Dynamically add segments to the url, then call a method.
     # (e.g. client.name.name.get())
     #
     # * *Args*    :
-    #   - The args are autmoatically passed in
+    #   - The args are automatically passed in
     # * *Returns* :
     #   - Client object or Response object
     #
+    # rubocop:disable Style/MethodMissingSuper
+    # rubocop:disable Style/MissingRespondToMissing
     def method_missing(name, *args, &_block)
       # Capture the version
       if name.to_s == 'version'
@@ -217,8 +296,42 @@ module SendGrid
       end
       # We have reached the end of the method chain, make the API call
       return build_request(name, args) if @methods.include?(name.to_s)
+
       # Add a segment to the URL
       _(name)
     end
+
+    private
+
+    def build_http_request(http_method)
+      uri = build_url(query_params: @query_params)
+      net_http = Kernel.const_get('Net::HTTP::' + http_method.to_s.capitalize)
+
+      @http = build_http(uri.host, uri.port)
+      @request = build_request_headers(net_http.new(uri.request_uri))
+    end
+
+    def update_content_type(http_method)
+      if @request_body && content_type_json?
+        # If body is a hash or array, encode it; else leave it alone
+        @request.body = if [Hash, Array].include?(@request_body.class)
+                          @request_body.to_json
+                        else
+                          @request_body
+                        end
+        @request['Content-Type'] = 'application/json'
+      elsif !@request_body && http_method.to_s == 'post'
+        @request['Content-Type'] = ''
+      else
+        @request.body = @request_body
+      end
+    end
+
+    def content_type_json?
+      !@request_headers.key?('Content-Type') ||
+        @request_headers['Content-Type'] == 'application/json'
+    end
+    # rubocop:enable Style/MethodMissingSuper
+    # rubocop:enable Style/MissingRespondToMissing
   end
 end

data/ruby_http_client.gemspec

@@ -1,20 +1,22 @@
-# coding: utf-8
-lib = File.expand_path('../lib', __FILE__)
+lib = File.expand_path('lib', __dir__)
 $LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
 
 Gem::Specification.new do |spec|
-  spec.name        = 'ruby_http_client'
-  spec.version     = '3.3.0'
-  spec.authors     = ['Elmer Thomas']
-  spec.email       = 'dx@sendgrid.com'
-  spec.summary     = 'A simple REST client'
+  spec.name = 'ruby_http_client'
+  spec.version = '3.5.5'
+  spec.authors = ['Elmer Thomas']
+  spec.email = 'help@twilio.com'
+  spec.summary = 'A simple REST client'
   spec.description = 'Quickly and easily access any REST or REST-like API.'
-  spec.homepage    = 'http://github.com/sendgrid/ruby-http-client'
-  spec.license     = 'MIT'
-  spec.files         = `git ls-files -z`.split("\x0")
-  spec.executables   = spec.files.grep(/^bin/) { |f| File.basename(f) }
-  spec.test_files    = spec.files.grep(/^(test|spec|features)/)
+  spec.homepage = 'http://github.com/sendgrid/ruby-http-client'
+  spec.license = 'MIT'
+  spec.files = `git ls-files -z`.split("\x0")
+  spec.executables = spec.files.grep(/^bin/) { |f| File.basename(f) }
+  spec.test_files = spec.files.grep(/^(test|spec|features)/)
   spec.require_paths = ['lib']
 
-  spec.add_development_dependency 'rake', '~> 0'
+  spec.add_development_dependency 'codecov'
+  spec.add_development_dependency 'minitest'
+  spec.add_development_dependency 'rake'
+  spec.add_development_dependency 'simplecov', '~> 0.18.5'
 end

data/test/test_helper.rb

@@ -0,0 +1,7 @@
+if RUBY_VERSION.equal?('2.7')
+  require 'simplecov'
+  SimpleCov.start
+
+  require 'codecov'
+  SimpleCov.formatter = SimpleCov::Formatter::Codecov
+end

data/test/test_ruby_http_client.rb

@@ -1,3 +1,4 @@
+require './test/test_helper'
 require 'ruby_http_client'
 require 'minitest/autorun'
 
@@ -11,6 +12,26 @@ class MockResponse
   end
 end
 
+class MockHttpResponse
+  attr_reader :code, :body, :headers
+
+  def initialize(code, body, headers)
+    @code = code
+    @body = body
+    @headers = headers
+  end
+
+  alias to_hash headers
+end
+
+class MockResponseWithRequestBody < MockResponse
+  attr_reader :request_body
+
+  def initialize(response)
+    @request_body = response['request_body']
+  end
+end
+
 class MockRequest < SendGrid::Client
   def make_request(_http, _request)
     response = {}
@@ -21,6 +42,17 @@ class MockRequest < SendGrid::Client
   end
 end
 
+class MockRequestWithRequestBody < SendGrid::Client
+  def make_request(_http, request)
+    response = {}
+    response['code'] = 200
+    response['body'] = { 'message' => 'success' }
+    response['headers'] = { 'headers' => 'test' }
+    response['request_body'] = request.body
+    MockResponseWithRequestBody.new(response)
+  end
+end
+
 class TestClient < Minitest::Test
   def setup
     @headers = JSON.parse('
@@ -31,9 +63,14 @@ class TestClient < Minitest::Test
         ')
     @host = 'http://localhost:4010'
     @version = 'v3'
+    @http_options = { open_timeout: 60, read_timeout: 60 }
     @client = MockRequest.new(host: @host,
                               request_headers: @headers,
                               version: @version)
+    @client_with_options = MockRequest.new(host: @host,
+                                           request_headers: @headers,
+                                           version: @version,
+                                           http_options: @http_options)
   end
 
   def test_init
@@ -61,7 +98,7 @@ class TestClient < Minitest::Test
 
   def test_build_query_params
     url = ''
-    query_params = { 'limit' => 100, 'offset' => 0, 'categories' => ['category1', 'category2'] }
+    query_params = { 'limit' => 100, 'offset' => 0, 'categories' => %w[category1 category2] }
     url = @client.build_query_params(url, query_params)
     assert_equal('?limit=100&offset=0&categories=category1&categories=category2', url)
   end
@@ -91,8 +128,8 @@ class TestClient < Minitest::Test
     args = nil
     response = @client.build_request(name, args)
     assert_equal(200, response.status_code)
-    assert_equal({'message' => 'success'}, response.body)
-    assert_equal({'headers' => 'test'}, response.headers)
+    assert_equal({ 'message' => 'success' }, response.body)
+    assert_equal({ 'headers' => 'test' }, response.headers)
   end
 
   def test_build_request_post_empty_content_type
@@ -103,7 +140,7 @@ class TestClient < Minitest::Test
       request_headers: headers,
       version: 'v3'
     )
-    args = [{'request_body' => {"hogekey" => "hogevalue"}}]
+    args = [{ 'request_body' => { 'hogekey' => 'hogevalue' } }]
     client.build_request('post', args)
     assert_equal('application/json', client.request['Content-Type'])
     assert_equal('{"hogekey":"hogevalue"}', client.request.body)
@@ -143,15 +180,71 @@ class TestClient < Minitest::Test
     }
     client = MockRequest.new(
       host: 'https://localhost',
-      request_headers: headers,
+      request_headers: headers
     )
     name = 'post'
-    args = [{'request_body' => 'hogebody'}]
+    args = [{ 'request_body' => 'hogebody' }]
     client.build_request(name, args)
     assert_equal('multipart/form-data; boundary=xYzZY', client.request['Content-Type'])
     assert_equal('hogebody', client.request.body)
   end
 
+  def test_json_body_encode_hash
+    headers = {
+      'Content-Type' => 'application/json'
+    }
+    client = MockRequestWithRequestBody.new(
+      host: 'https://localhost',
+      request_headers: headers
+    )
+    name = 'post'
+    args = [{ 'request_body' => { 'this_is' => 'json' } }]
+    response = client.build_request(name, args)
+    assert_equal('{"this_is":"json"}', response.request_body)
+  end
+
+  def test_json_body_encode_array
+    headers = {
+      'Content-Type' => 'application/json'
+    }
+    client = MockRequestWithRequestBody.new(
+      host: 'https://localhost',
+      request_headers: headers
+    )
+    name = 'post'
+    args = [{ 'request_body' => [{ 'this_is' => 'json' }] }]
+    response = client.build_request(name, args)
+    assert_equal('[{"this_is":"json"}]', response.request_body)
+  end
+
+  def test_json_body_do_not_reencode
+    headers = {
+      'Content-Type' => 'application/json'
+    }
+    client = MockRequestWithRequestBody.new(
+      host: 'https://localhost',
+      request_headers: headers
+    )
+    name = 'post'
+    args = [{ 'request_body' => '{"this_is":"json"}' }]
+    response = client.build_request(name, args)
+    assert_equal('{"this_is":"json"}', response.request_body)
+  end
+
+  def test_json_body_do_not_reencode_simplejson
+    headers = {
+      'Content-Type' => 'application/json'
+    }
+    client = MockRequestWithRequestBody.new(
+      host: 'https://localhost',
+      request_headers: headers
+    )
+    name = 'post'
+    args = [{ 'request_body' => 'true' }]
+    response = client.build_request(name, args)
+    assert_equal('true', response.request_body)
+  end
+
   def add_ssl
     uri = URI.parse('https://localhost:4010')
     http = Net::HTTP.new(uri.host, uri.port)
@@ -160,15 +253,152 @@ class TestClient < Minitest::Test
     assert_equal(http.verify_mode, OpenSSL::SSL::VERIFY_PEER)
   end
 
+  def test_add_http_options
+    uri = URI.parse('https://localhost:4010')
+    http = Net::HTTP.new(uri.host, uri.port)
+    http = @client_with_options.add_http_options(http)
+    assert_equal(http.open_timeout, 60)
+    assert_equal(http.read_timeout, 60)
+  end
+
   def test__
     url1 = @client._('test')
     assert_equal(['test'], url1.url_path)
   end
 
+  def test_ratelimit_core
+    expiry = Time.now.to_i + 1
+    rl = SendGrid::Response::Ratelimit.new(500, 100, expiry)
+    rl2 = SendGrid::Response::Ratelimit.new(500, 0, expiry)
+
+    refute rl.exceeded?
+    assert rl2.exceeded?
+
+    assert_equal(rl.used, 400)
+    assert_equal(rl2.used, 500)
+  end
+
+  def test_response_ratelimit_parsing
+    headers = {
+      'X-RateLimit-Limit' => '500',
+      'X-RateLimit-Remaining' => '300',
+      'X-RateLimit-Reset' => Time.now.to_i.to_s
+    }
+
+    body = ''
+    code = 204
+    http_response = MockHttpResponse.new(code, body, headers)
+    response = SendGrid::Response.new(http_response)
+
+    refute_nil response.ratelimit
+    refute response.ratelimit.exceeded?
+  end
+
   def test_method_missing
     response = @client.get
     assert_equal(200, response.status_code)
-    assert_equal({'message' => 'success'}, response.body)
-    assert_equal({'headers' => 'test'}, response.headers)
+    assert_equal({ 'message' => 'success' }, response.body)
+    assert_equal({ 'headers' => 'test' }, response.headers)
+  end
+
+  def test_http_options
+    url1 = @client_with_options._('test')
+    assert_equal(@host, @client_with_options.host)
+    assert_equal(@headers, @client_with_options.request_headers)
+    assert_equal(['test'], url1.url_path)
+  end
+
+  def test_proxy_options
+    proxy_options = {
+      host: '127.0.0.1', port: 8080, user: 'anonymous', pass: 'secret'
+    }
+    client = MockRequest.new(
+      host: 'https://api.sendgrid.com',
+      request_headers: { 'Authorization' => 'Bearer xxx' },
+      proxy_options: proxy_options
+    ).version('v3').api_keys
+
+    assert(client.proxy_address, '127.0.0.1')
+    assert(client.proxy_pass, 'secret')
+    assert(client.proxy_port, 8080)
+    assert(client.proxy_user, 'anonymous')
+  end
+
+  def test_proxy_from_http_proxy_environment_variable
+    ENV['http_proxy'] = 'anonymous:secret@127.0.0.1:8080'
+
+    client = MockRequest.new(
+      host: 'https://api.sendgrid.com',
+      request_headers: { 'Authorization' => 'Bearer xxx' }
+    ).version('v3').api_keys
+
+    assert(client.proxy_address, '127.0.0.1')
+    assert(client.proxy_pass, 'secret')
+    assert(client.proxy_port, 8080)
+    assert(client.proxy_user, 'anonymous')
+  ensure
+    ENV.delete('http_proxy')
+  end
+
+  # def test_docker_exists
+  #   assert(File.file?('./Dockerfile') || File.file?('./docker/Dockerfile'))
+  # end
+
+  # def test_docker_compose_exists
+  #   assert(File.file?('./docker-compose.yml') || File.file?('./docker/docker-compose.yml'))
+  # end
+
+  def test_env_sample_exists
+    assert(File.file?('./.env_sample'))
+  end
+
+  def test_gitignore_exists
+    assert(File.file?('./.gitignore'))
+  end
+
+  def test_gh_actions_exists
+    assert(File.file?('./.github/workflows/test-and-deploy.yml'))
+  end
+
+  def test_changelog_exists
+    assert(File.file?('./CHANGELOG.md'))
+  end
+
+  def test_code_of_conduct_exists
+    assert(File.file?('./CODE_OF_CONDUCT.md'))
+  end
+
+  def test_contributing_exists
+    assert(File.file?('./CONTRIBUTING.md'))
+  end
+
+  def test_issue_template_exists
+    assert(File.file?('./ISSUE_TEMPLATE.md'))
+  end
+
+  def test_license_exists
+    assert(File.file?('./LICENSE'))
+  end
+
+  def test_pull_request_template_exists
+    assert(File.file?('./PULL_REQUEST_TEMPLATE.md'))
+  end
+
+  def test_readme_exists
+    assert(File.file?('./README.md'))
+  end
+
+  def test_troubleshooting_exists
+    assert(File.file?('./TROUBLESHOOTING.md'))
+  end
+
+  def test_use_cases_exists
+    assert(File.file?('use_cases/README.md'))
+  end
+
+  def test_license_date_is_updated
+    license_end_year = IO.read('LICENSE').match(/Copyright \(C\) (\d{4}), Twilio SendGrid/)[1].to_i
+    current_year = Time.new.year
+    assert_equal(current_year, license_end_year)
   end
 end

data/use_cases/README.md

@@ -0,0 +1,3 @@
+This directory provides examples for specific use cases. Please [open an issue](https://github.com/sendgrid/ruby-http-client/issues) or make a pull request for any use cases you would like us to document here. Thank you!
+
+ # Table of Contents